Flutter 框架仓库测试体系全解：七大类测试清单、本地运行方式与 CI 编排机制

本文基于 Flutter 仓库官方的测试清单文档 Test-Types-Overview.md 展开，系统梳理 Flutter 代码库中 6000 余个测试文件的分类体系：框架测试、工具测试、DeviceLab 设备实验室测试、性能基准测试、分析 Lint 测试、包测试与引擎测试这七大类各自的存放位置、运行命令、速度量级与前置条件。读完本文，你能够按照文档给出的命令在本地复现任意一类测试，并理解 CI 中 dev/bots/test.dart 分片（shard）编排机制的工作原理。

测试体系总览：规模与运行时长分级

Flutter 代码库的测试规模庞大（官方统计超过 6000 个测试文件），因此官方文档将测试按"类别 + 位置"两个维度分组管理。在深入每一类之前，文档首先给出了统一的运行时长（Runtime Length）分级标准，这也是判断"某个测试在 CI 中属于哪个档位"的依据：

级别	耗时	典型代表
Sub-second	< 1 秒	简单单元测试，例如 dev/tools 中的测试
Fast	< 10 秒	大多数单元测试、简单 Widget 测试
Medium	10–60 秒	复杂 Widget 测试、部分工具测试
Slow	> 60 秒	集成测试、devicelab 任务、analyze 脚本

下面按文档的分组顺序，逐一介绍七大类测试的位置、命令与源码级细节。

一、框架测试（Framework Tests）

• 位置：packages/flutter/test/
• 语言：Dart
• 说明：针对 Flutter 框架本体的单元测试与 Widget 测试。
• 能否本地运行：可以。
• 速度：环境正常时单个测试通常在 10 秒以内（Fast）。
• 规模：文档标注约 1000+ 文件；当前仓库中 packages/flutter/test/ 下的 *_test.dart 实测为 924 个，与"千级"量级一致。

目录组织

从仓库实际结构看，packages/flutter/test/ 按框架内部模块划分一级目录，与 packages/flutter/lib/src/ 的模块布局一一对应：

packages/flutter/test/
├── animation/      # 动画系统
├── cupertino/      # Cupertino 组件
├── foundation/    # 基础库
├── gestures/       # 手势识别
├── material/       # Material 组件
├── painting/       # 绘制
├── physics/        # 物理（滚动弹簧模型等）
├── rendering/      # 渲染树
├── scheduler/      # 调度器
├── semantics/      # 语义（无障碍）
├── services/       # 平台服务
└── widgets/        # Widget 层

运行命令

文档给出的标准命令：

• 运行整个目录的测试：

  bin/flutter test packages/flutter/test/foundation
  

• 运行单个测试文件：

  bin/flutter test packages/flutter/test/foundation/assertions_test.dart
  

编写与进阶要点

• 测试文件统一使用 _test.dart 后缀，并放置在被测包的 test/ 子目录下；测试基于 flutter_test 包的 API 编写，详见 Running-and-writing-tests.md。

• Golden 文件（像素对比）测试：packages/flutter 的 golden 测试走 Flutter Gold 基线管理流程，在 Linux、Windows、macOS 与 Web 上对比像素差异，具体流程见 Writing-a-golden-file-test-for-package-flutter.md。

• 内存泄漏测试：本地开启 leak tracking 只需给 flutter test 追加参数：

  flutter test --dart-define LEAK_TRACKING=true
  

  详见 Leak-tracking.md。

• 测试标签（tags）：packages/flutter/dart_test.yaml 定义了两个常用标签——reduced-test-set（标识属于缩减测试集的文件）与 no-shuffle（禁止对带该标签的套件随机化执行顺序），用于 CI 中按需裁剪测试集合。

二、工具测试（Tool Tests）

• 位置：packages/flutter_tools/test/
• 语言：Dart
• 说明：flutter 命令行工具（flutter_tools）自身的测试所在地。
• 能否本地运行：可以。
• 速度：general shard 测试为 Fast（< 10 秒）；integration shard 为 Medium 到 Slow。
• 规模：文档标注约 500+ 文件；当前仓库实测 *_test.dart 为 477 个。

shard 结构

从源码结构看，packages/flutter_tools/test/ 按执行环境拆分为多个 shard，这种拆分与 CI 的并行分片策略直接对应：

packages/flutter_tools/test/
├── general.shard/          # 通用单元测试（纯 Dart，无需设备）
├── integration.shard/      # 集成测试（需要 FLUTTER_ROOT 环境变量）
├── commands.shard/         # flutter 命令行为测试
├── web.shard/              # Web 相关测试
├── android_java17_integration.shard/
├── android_preview_integration.shard/
└── src/                    # 共享的测试工具代码

运行命令

• 通用单元测试：

  bin/flutter test packages/flutter_tools/test/general.shard
  

• 单个测试文件：

  bin/flutter test packages/flutter_tools/test/general.shard/base_utils_test.dart
  

• 集成测试（需要设置 FLUTTER_ROOT 环境变量）：

  bin/flutter test packages/flutter_tools/test/integration.shard
  

工具包的更多说明见 packages/flutter_tools/README.md。

三、DeviceLab 测试（设备实验室）

• 位置：dev/devicelab/
• 语言：Dart
• 说明：在 Flutter DeviceLab 中运行的性能与集成测试。任务定义位于 dev/devicelab/lib/tasks/（实测 311 个 Dart 任务文件），被测应用大多位于 dev/integration_tests/。
• 能否本地运行：部分可以。通常需要连接物理设备、模拟器或仿真器，并配置相应环境（如 ANDROID_SDK_ROOT）。
• 速度：Slow（> 60 秒）。
• 规模：文档标注约 100+ 文件。

本地运行命令

文档给出的运行方式为（在 dev/devicelab 目录下执行）：

../../bin/cache/dart-sdk/bin/dart bin/test_runner.dart test -t {NAME_OF_TEST}

例如运行复杂布局启动耗时任务：

../../bin/cache/dart-sdk/bin/dart bin/test_runner.dart test -t complex_layout__start_up

从源码看，dev/devicelab/bin/test_runner.dart 基于 package:args 的 CommandRunner 构建，注册了 TestCommand（执行测试任务）与 UploadMetricsCommand（上传性能指标）两个子命令；任务名 {NAME_OF_TEST} 即 .ci.yaml 中定义的任务标识。

此外，Running-and-writing-tests.md 提供了当前推荐的本地复现流程：

1. 终端进入 dev/devicelab 目录；

2. 确认已连接物理设备、仿真器或模拟器；

3. 确认当前 locale 为 en_US：export LANG=en_US.UTF-8；

4. 执行：

   ../../bin/dart bin/run.dart -t [task_name]
   

   其中 [task_name] 同样是 .ci.yaml 中定义的任务名。入口文件为 dev/devicelab/bin/run.dart。

使用本地编译的引擎运行

当 DeviceLab 测试因你修改的引擎代码而失败时，可以携带本地引擎参数运行（见 Running-and-writing-tests.md）：

../../bin/dart bin/run.dart \
  --local-engine-src-path=[path_to_src] \
  --local-engine=[engine_build_for_your_device] \
  --local-engine-host=[host_engine_build_for_your_device] \
  -t [task_name]

如果本地 engine 目录与 flutter/ 目录同级，--local-engine-src-path 可省略，会自动解析。注意：部分测试需要 profile 模式而非 debug 模式的本地引擎构建，需按实际场景传入正确的引擎构建名。

DeviceLab 的整体介绍见 dev/devicelab/README.md。

四、基准测试（Benchmarks）

• 位置：dev/benchmarks/
• 语言：Dart
• 说明：性能基准测试。基准测试以 DeviceLab 任务的形式运行，因此运行方式与第三节的 DeviceLab 测试相同（bin/run.dart -t <task_name>），前置条件也相同。
• 速度：Slow（> 60 秒）。
• 规模：文档标注约 160+ 文件；当前仓库实测 dev/benchmarks/ 下共有 224 个 Dart 文件（含被测应用与驱动代码）。

目录组织

dev/benchmarks/
├── complex_layout/          # 复杂布局（含 test_driver/ 驱动脚本）
├── macrobenchmarks/         # 宏观基准（启动、帧率、内存等）
├── microbenchmarks/         # 微观基准
├── platform_channels_benchmarks/   # 平台通道开销
├── platform_views_layout/          # 平台视图布局
├── platform_views_layout_hybrid_composition/
├── imitation_game_flutter/  # 模仿游戏基准
├── multiple_flutters/
└── test_apps/               # 配套被测应用

编写特定类型的基准测试有专门的指南：

• 内存测试：How-to-write-a-memory-test-for-Flutter.md
• 渲染速度测试：How-to-write-a-render-speed-test-for-Flutter.md

五、分析与 Lint 测试（Analysis and Lint Tests）

• 关键文件：

  • dev/bots/analyze.dart：强制代码风格与结构规则。
  • dev/bots/test.dart：主测试编排器（详见下文"CI 级编排"一节）。

• 能否本地运行：可以。

• 运行命令：

  bin/cache/dart-sdk/bin/dart --enable-asserts dev/bots/analyze.dart
  

  注意必须启用 --enable-asserts；文档说明本地完整运行一次需要 60 秒以上（Slow）。

analyze.dart 内部依赖 dev/bots/allowlist.dart 管理豁免名单，并内置 30 秒心跳输出（_kHeartbeatInterval），防止长任务"看起来像挂死"。

六、其他包测试（Package Tests）

• 位置：packages/*/test/（不含 flutter 与 flutter_tools，后两者已单列）

• 语言：Dart

• 说明：packages/ 下其余各包的测试。判定规则是：任何包含 pubspec.yaml 的目录都视为一个包，可以有自己的 test/ 目录。当前仓库 packages/ 下包含 flutter_driver、flutter_test、flutter_goldens、flutter_localizations、flutter_web_plugins、fuchsia_remote_debug_protocol、integration_test 等包，均遵循这一结构。

• 能否本地运行：可以。

• 速度：单个测试为 Fast（< 10 秒）。

• 运行命令：

  bin/flutter test packages/<package_name>/test
  

编写规范同样遵循 Running-and-writing-tests.md 中的约定（_test.dart 后缀、test/ 目录、按功能拆分小文件而非堆积巨型测试文件）。

七、引擎测试（Engine Tests）

• 位置：engine/src（对应 flutter/engine 仓库，本仓库中已合并到 engine/ 目录，核心位于 engine/src/flutter）
• 语言：C++、Dart、Java、Kotlin 等
• 说明：Flutter 引擎本体的测试，是七大类中唯一跨多种语言的类别。
• 能否本地运行：可以，但需要完整的引擎开发环境（GN、Ninja、gclient 等）。
• 速度：单个单元测试为 Fast，完整测试套为 Slow。

方式一：run_tests.py

从 engine/src/flutter 目录执行 testing/run_tests.py：

testing/run_tests.py --type=engine   # C++ 测试
testing/run_tests.py --type=java    # Java 测试
testing/run_tests.py --type=dart    # Dart 测试

从源码看（engine/src/flutter/testing/run_tests.py#L1277-L1282），--type 参数默认值为 all（等价于运行全部测试类型），另有 --variant（默认 host_debug_unopt）指定引擎构建变体，以及 --engine-filter、--dart-filter、--java-filter 等按可执行文件/脚本名过滤的选项，方便只复跑失败子集。

方式二：et（Engine Tool）

• 运行某个测试目标：

  et test //flutter/impeller:impeller_unittests
  

• 查询所有测试目标：

  et query targets --testonly
  

引擎各语言测试体系（C++ Google Tests、Android 嵌入层的 Robolectric/JUnit、iOS 嵌入层的 XCTest、dart:ui 的 Dart 测试、Web 引擎测试）的完整说明见 Testing-the-engine.md。

CI 级编排：dev/bots/test.dart 的分片机制

前六类测试在 CI 中由 dev/bots/test.dart 统一编排。该脚本的文件头注释完整描述了其执行模型，值得逐条理解：

1. 默认过滤输出：默认只显示错误；若某个测试运行时间超过 utils.dart 中的 _quietTimeout，则连原始输出一起打印，以便发现"挂死"的测试。--verbose 可关闭输出过滤。

2. 错误默认非致命：所有测试都会跑完，最后汇总错误，退出码为 1；--abort-on-error 可在首个错误时立即退出。

3. shard / subshard 拆分：测试支持按 shard 和 subshard 拆分执行，可用 --dry-run 查看"本应执行"的测试列表。本地复现某个分片只需设置环境变量，例如运行全部框架测试：

   SHARD=framework_tests bin/dart dev/bots/test.dart
   

   部分 shard 支持命名 subshard（如 SHARD=framework_tests SUBSHARD=widgets），部分支持数字 subsharding（如 SHARD=build_tests SUBSHARD=1_2 表示"两分取一"，即运行前半）。

4. 随机化执行顺序：shard 内测试默认以随机顺序执行，用于暴露测试间的隐式依赖；--test-randomize-ordering-seed=<n> 可固定随机种子以复现某次乱序运行。带 no-shuffle 标签的套件则不随机化（见 packages/flutter/dart_test.yaml）。

5. 其余参数透传：脚本的其他参数会被原样传递给 flutter 工具，因此可以叠加 flutter test 的常用选项。

与 test.dart 配合的 analyze.dart 负责静态分析门禁，两者即 CI 中"分析与测试"这一档的完整入口。

七大类测试速查表

类别	位置	语言	本地运行	典型命令	速度	规模（仓库实测）
框架测试	packages/flutter/test/	Dart	可	bin/flutter test packages/flutter/test/foundation	Fast	924 个 *_test.dart
工具测试	packages/flutter_tools/test/	Dart	可（集成 shard 需 FLUTTER_ROOT）	bin/flutter test packages/flutter_tools/test/general.shard	Fast–Slow	477 个 *_test.dart
DeviceLab	dev/devicelab/	Dart	部分（需设备/模拟器）	../../bin/dart bin/run.dart -t <task>（在 dev/devicelab 下）	Slow	311 个任务文件
基准测试	dev/benchmarks/	Dart	部分（同 DeviceLab）	同 DeviceLab	Slow	224 个 Dart 文件
分析/Lint	dev/bots/analyze.dart	Dart	可	bin/cache/dart-sdk/bin/dart --enable-asserts dev/bots/analyze.dart	Slow	—
其他包	packages/*/test/	Dart	可	bin/flutter test packages/<name>/test	Fast	每包 test/ 目录
引擎	engine/src/flutter	C++/Dart/Java/Kotlin 等	可（需引擎开发环境）	testing/run_tests.py --type=engine / et test <target>	Fast–Slow	多语言混合

相关文档

• Running-and-writing-tests.md：单元测试编写与本地运行（含 --local-engine 用法）
• Writing-a-golden-file-test-for-package-flutter.md：packages/flutter 的 golden 文件测试流程
• Leak-tracking.md：内存泄漏追踪
• How-to-write-a-memory-test-for-Flutter.md：内存测试编写指南
• How-to-write-a-render-speed-test-for-Flutter.md：渲染速度测试编写指南
• Testing-the-engine.md：引擎各语言测试体系
• Test-coverage-for-package-flutter.md：package:flutter 的测试覆盖率统计方式