dart-collect-coverage

实现 Dart 和 Flutter 测试覆盖率

目录

• 测试基础
• 覆盖率指令
• 工作流：配置并生成覆盖率报告
• 工作流：高级手动覆盖率收集
• 示例

测试基础

使用标准的 Dart 测试范式构建测试套件。Dart 项目使用 package:test，Flutter 项目使用 flutter_test。

• 单元测试： 验证单个函数、方法或类。
• 组件/Widget 测试： 使用模拟对象（package:mockito）验证组件行为、布局和交互。
• 集成测试： 在模拟或真实设备上验证整个应用流程。

覆盖率指令

使用内联注释排除特定行、代码块或整个文件。在格式化时传递 --check-ignore 标志以强制执行这些指令。

• 忽略单行：// coverage:ignore-line
• 忽略代码块：// coverage:ignore-start 和 // coverage:ignore-end
• 忽略整个文件：// coverage:ignore-file

工作流：配置并生成覆盖率报告

按照以下顺序工作流添加 coverage 包、执行测试并生成 LCOV 报告。

任务进度清单：

• [ ] 1. 将 coverage 添加为 dev_dependency。
• [ ] 2. 执行自动化覆盖率脚本。
• [ ] 3. 验证 LCOV 输出。

1. 添加依赖

将 coverage 包作为 dev_dependency 添加到项目中。不要将其添加到标准依赖中。

如果是标准 Dart 项目：

dart pub add dev:coverage

如果是 Flutter 项目：

flutter pub add dev:coverage

2. 收集覆盖率并生成 LCOV

使用内置的 test_with_coverage 脚本。该脚本会自动运行所有测试，从 Dart VM 收集 JSON 覆盖率数据，并将其格式化为 LCOV 报告。

dart run coverage:test_with_coverage

注意：如果在 Dart 工作区（monorepo）中工作，请明确指定测试目录（例如 dart run coverage:test_with_coverage -- pkgs/foo/test pkgs/bar/test）。

3. 反馈循环：验证输出

运行验证器 -> 检查错误 -> 修复：

1. 确认项目根目录下已创建 coverage/ 目录。
2. 确保 coverage/coverage.json（原始数据）和 coverage/lcov.info（格式化报告）存在。
3. 如果特定文件缺少覆盖率，请确保它们已被测试文件导入并执行，或者如果它们被有意排除，请添加 // coverage:ignore-file。

工作流：高级手动覆盖率收集

如果您需要对 VM 服务、隔离暂停或分支/函数级覆盖率进行精细控制，请使用手动收集工作流。

任务进度清单：

• [ ] 1. 启用 VM 服务运行测试。
• [ ] 2. 收集原始 JSON 覆盖率。
• [ ] 3. 将 JSON 格式化为 LCOV。

1. 启用 VM 服务运行测试

执行测试时，在退出时暂停隔离，并在特定端口（例如 8181）上暴露 VM 服务。

dart run --pause-isolates-on-exit --disable-service-auth-codes --enable-vm-service=8181 test &

2. 收集原始覆盖率

从运行的 VM 服务中提取覆盖率数据，并输出到 JSON 文件。

dart run coverage:collect_coverage --wait-paused --uri=http://127.0.0.1:8181/ -o coverage/coverage.json --resume-isolates

可选：追加 --function-coverage 和 --branch-coverage 以收集更深入的指标（需要 Dart VM 2.17.0+）。

3. 格式化为 LCOV

将原始 JSON 数据转换为标准 LCOV 格式。

dart run coverage:format_coverage --packages=.dart_tool/package_config.json --lcov -i coverage/coverage.json -o coverage/lcov.info --check-ignore

示例

示例：pubspec.yaml 配置

确保 pubspec.yaml 中 coverage 包严格位于 dev_dependencies 下。

name: my_dart_app
environment:
  sdk: ^3.0.0

dependencies:
  path: ^1.8.0

dev_dependencies:
  test: ^1.24.0
  coverage: ^1.15.0

示例：应用忽略指令

使用忽略指令防止生成的代码或不可测试的边缘情况降低覆盖率分数。

// coverage:ignore-file
import 'package:meta/meta.dart';

class SystemConfig {
  final String env;

  SystemConfig(this.env);

  // coverage:ignore-start
  void legacyInit() {
    print('Deprecated initialization');
  }
  // coverage:ignore-end

  bool isProduction() {
    if (env == 'prod') return true;
    return false; // coverage:ignore-line
  }
}