increase-coverage

代码覆盖率执行与最大化指南

本开发者技能将分步介绍执行代码覆盖率工具、找出未测试的路径（覆盖缺口），以及编写高保真单元测试的最佳实践，从而推动整个单体仓库的覆盖率达到 100%。

---

1. 执行并汇总单体仓库覆盖率

我们的单体仓库使用 Melos 协调多个软件包的测试。按照以下命令流程生成并合并覆盖率数据：

A. 运行带覆盖率统计的软件包测试

执行单体仓库测试运行器。它会在所有软件包中运行 flutter test --coverage（或 dart test --coverage）：

melos run test

B. 合并软件包覆盖率文件

运行合并脚本，将各软件包的 coverage/lcov.info 文件合并为统一的根目录 lcov.info 文件：

melos run coverage

说明

汇总脚本（scripts/combine_coverage.sh）会动态地将路径根目录改写为绝对路径，并删除临时的软件包 coverage 目录，以保持工作区整洁。

C. 生成 HTML 覆盖率报告

使用 genhtml（lcov 工具包的一部分）将统一的 lcov.info 文件转换成交互式 HTML 可视化报告：

genhtml lcov.info -o coverage/html

---

2. 定位未覆盖的代码行（覆盖缺口分析）

若要快速定位未测试的代码行，而不必浏览整份 HTML 报告，请在根目录的 lcov.info 文件上运行以下 grep 和 awk 管道命令：

grep -E "SF:|DA:" lcov.info | awk -F: '/SF/ {file=$2} /DA/ {split($2,a,","); if(a[2]==0) print file, a[1]}'

此输出会显示绝对文件路径，后接每条未覆盖语句的确切行号，例如：

/workspace/packages/preact_signals/lib/src/model.dart 21
/workspace/packages/preact_signals/lib/src/model.dart 25

---

3. 达到 100% 覆盖率的策略

找到未覆盖的代码行后，请采用以下针对性测试策略编写有意义的测试：

A. 测试模型与选项基础功能

确保充分测试值模型、选项和参数：

• copyWith 方法：分别使用 null（断言回退到当前值）和显式值进行测试。
• 相等性（==）与 hashCode：
  • 测试比较相同的引用（identical(this, other)）。
  • 测试比较属性相同的不同实例（预期相等）。
  • 测试比较属性不同的不同实例（预期不相等）。
  • 测试与 null 或完全不同类的实例进行比较。

B. 覆盖复杂分支与条件逻辑

检查每个嵌套的 if、else 和三元运算符（? :）语句：

• 构造能使路径判定为 true 的测试输入。
• 构造能使路径判定为 false 的测试输入。
• 确保明确触发边界检查、空集合和空安全回退逻辑。

C. 模拟并断言异常与捕获路径

若要覆盖恢复逻辑或诊断断言：

• catch 块：传入不兼容的类型，或构造会导致运行时 TypeError 或 AssertionError 的场景，以验证回退分支。
• 释放与生命周期错误：对信号或原语调用 .dispose()，然后尝试读取或写入，以断言会抛出 SignalsReadAfterDisposeError 或 SignalsWriteAfterDisposeError。

D. 深层递归集合

验证自定义深层集合断言（例如列表、映射、集合或嵌套对象）在每一层都能判断配置匹配与不匹配的情况。

---

4. 仓库清理与版本安全

完成覆盖率最大化运行前，请确认仓库整洁：

1. 格式化测试文件：

   dart format .
   

2. 运行 Lint 和静态分析：

   melos run analyze
   

3. 清理 Git 状态： 切勿将覆盖率文件（lcov.info 或 coverage/）提交到 Git 历史记录中。若它们意外进入暂存区，请将其移除：

   git rm -r --cached coverage/
   git rm lcov.info