dart-test-coverage

Dart 测试覆盖率

在 Dart 包中运行和解读测试覆盖率的指南。

何时使用此技能

• 当被要求“检查测试覆盖率”或“提高覆盖率”时。
• 当需要找出库中哪些部分未经测试时。

何时不使用（弃用防护规则）

不要收集或要求提供以下内容的测试覆盖率：

• 生成的代码：由构建器生成的代码（*.g.dart、*.freezed.dart、 protobuf）。
• 特定平台的 FFI / OS 入口点：需要执行环境中无法使用的特定物理硬件或 OS 服务的底层平台绑定或入口点。
• 示例应用和工具脚本：example/ 下的独立示例代码或 tool/ 下的开发维护脚本，除非该包明确要求整个代码仓库的覆盖率达到 100%。
• 失败的测试套件：如果现有测试在 dart test 下运行失败，请先修复失败的测试，再收集或报告覆盖率。

发现

查找测试覆盖不足的部分：

运行覆盖率分析

按照工作流生成并解读覆盖率数据：

1. 运行带覆盖率收集的测试：dart test --coverage=.dart_tool/coverage
2. 解读结果：使用脚本或 format_coverage，按照解读结果一节中的说明找出具体文件和未覆盖的行。

如何使用此技能（工作流）

1. 运行 dart test，确保测试通过。
2. 运行 dart test --coverage=.dart_tool/coverage，收集覆盖率数据。
3. 使用提供的脚本或标准工具解读结果。
4. 添加测试以覆盖未覆盖的行。

运行覆盖率分析

运行以下命令，以 JSON 格式收集覆盖率数据：

dart test --coverage=.dart_tool/coverage

说明

我们使用 .dart_tool/coverage 作为输出目录，因为 .dart_tool 通常已在 .gitignore 文件中被忽略。

提示

对于条件逻辑复杂的项目，可以向 dart test 传入 --branch-coverage 标志，以收集分支级覆盖率。

解读结果

选项 1：使用自定义解读脚本

此代码仓库包含一个零依赖脚本，用于解析原始 JSON 输出，并汇总覆盖率百分比和未覆盖的行。

从项目根目录运行该脚本（按需调整脚本路径）：

dart run skills/dart-test-coverage/scripts/interpret_coverage.dart .dart_tool/coverage <package_name>

将 <package_name> 替换为 pubspec.yaml 中的名称。

输出示例：

package:my_pkg/src/file.dart: 50.0% (2/4 lines)
  Missed lines: 3, 4

选项 2：使用 package:coverage

如果已安装 package:test，那么 package:coverage 很可能作为传递依赖可用。你可以使用其中的 format_coverage 工具。

要以便于阅读的形式“美化打印”覆盖率数据：

dart run coverage:format_coverage --in=.dart_tool/coverage --out=stdout --pretty-print --report-on=lib

此命令会输出文件内容，并在左侧显示命中次数（例如，0| 表示未覆盖的行）。

报告结果的最佳实践

向用户呈现覆盖率结果时，请遵循以下指南：

1. 先说明总体覆盖率百分比，让用户立即了解情况。
2. 清晰指出具体文件和未覆盖的行。
3. 将行号对应到代码：不要只说“第 3 到 6 行未覆盖”。查看源文件，并告诉用户哪些函数或代码块未经测试（例如：“divide 函数缺少覆盖率”）。
4. 提出具体的修复方案：提供用户可以立即采用的示例测试代码，以覆盖未覆盖的行。
5. 多文件汇总时使用表格：报告多个文件时，使用包含文件、覆盖率 % 和未覆盖行等列的 Markdown 表格，让摘要一目了然。

约束

• 收集覆盖率前，始终确认测试通过。
• 不要提交 .dart_tool/coverage 目录。
• 提高覆盖率时，重点关注 lib/ 文件，而非 test/ 或生成的文件。