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 服务运行测试

运行测试时，在退出时暂停 isolate，并在特定端口（例如，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
  }
}