Flutter 框架 package:flutter 测试覆盖率查看与本地重算指南

本篇指南围绕 Flutter 官方仓库中的测试覆盖率文档 Test-coverage-for-package-flutter.md 展开，教你如何在 VS Code、Emacs 等编辑器中直观查看 package:flutter 的逐行覆盖率（lcov 数据），以及如何使用 flutter test --merge-coverage 与 flutter test --coverage 两种姿势快速/完整重算覆盖率。读完后，你将掌握：覆盖率数据从哪里来、本地文件布局、编辑器展示配置，以及 lcov 工具在覆盖率合并中的底层调用链。

覆盖率数据从哪来：flutter update-packages 的下载机制

在本地查看 package:flutter 的测试覆盖率之前，首先要理解数据的来源。运行 flutter update-packages 后，工具会从云端下载 package:flutter 最新的覆盖率数据，写入本地两个文件：

• packages/flutter/coverage/lcov.info：当前覆盖率视图数据，编辑器插件直接读取它；
• packages/flutter/coverage/lcov.base.info：云端基线数据，用于 --merge-coverage 的合并基准。

需要特别注意的一点：这份覆盖率数据与你的 git 修订版本不同步。云端数据对应的是 CI 机器人最近一次全量测试的结果，而你的本地 checkout 可能是另一个 commit，因此两者之间天然存在版本偏差（version skew）。文档明确指出，这种偏差通常危害不大，但在解读“未覆盖行”时应意识到它可能存在——你看到的“红色未覆盖行”，有可能在云端版本里已被覆盖，或者反过来。

从源码看这一机制：flutter update-packages 命令的实现位于 update_packages.dart，其中 _downloadCoverageData() 方法从 flutter_infra_release/flutter/coverage/lcov.info 拉取数据（可通过环境变量 FLUTTER_STORAGE_BASE_URL 覆盖存储基址，默认指向 Google 存储），拉取成功后同时写入 lcov.base.info 与 lcov.info 两份内容相同的文件。也就是说，初始状态下“当前视图”就是“云端基线”，本地任何合并操作都是在这个基线之上叠加的。

该命令在仓库中属于面向 CI 和仓库维护者的命令（其 description 明确写着“Normal Flutter developers should not have to use this command”），但在需要查看覆盖率时，它又是获取基线数据的入口。

在 Visual Studio Code 中查看逐行覆盖率

VS Code 是文档中推荐的查看方式，步骤如下：

1. 安装 Coverage Gutters 扩展；
2. 打开 packages/flutter/lib/src 下的任意 dart 文件。

此时行号旁的 gutter 区域会出现绿色和红色高亮：

• 绿色行：该行在测试中被执行过；
• 红色行：该行是“可执行候选”（candidate for execution）但未被任何测试执行。

状态栏底部还会显示当前文件的代码覆盖率百分比。

排查技巧：如果高亮不出现或数据异常，查看 VS Code 的 Output 面板中 coverage-gutters 输出流里的报错信息。

在 Emacs 中用 coverlay 查看覆盖率

Emacs 用户可以使用 coverlay 包，配置要点：

• 使用 coverlay-load-file 指定 .../packages/flutter/coverage/lcov.info 文件；
• 将 coverlay:base-path 配置为指向 .../packages/flutter 目录，这样 lcov 中的路径前缀才能正确映射到本地源码树；
• 其余 coverlay 行为可按个人习惯配置。

原文档中还提到 Atom 编辑器的 lcov-info 包（需直接打开 packages/flutter 目录、打开 Dart 文件后用 Packages > Lcov Info > Toggle 激活）。该编辑器生态相对小众，配置步骤较多且 UI 有已知怪癖，本文不再展开；其核心原理与 VS Code 方案一致，即读取同一份 lcov.info。

快速重算：flutter test --merge-coverage

当你为 package:flutter 新增或修改了某个测试文件（例如 test/material/dialog_test.dart），不必等 CI 全量重跑，可以在 Linux 机器上用 --merge-coverage 选项快速看到覆盖率变化：

flutter test --merge-coverage test/material/dialog_test.dart

这条命令只运行你指定的那一个测试文件，然后把该次运行的覆盖率数据合并进你的本地视图。合并的具体机制是：

1. 以 packages/flutter/coverage/lcov.base.info（flutter update-packages 从云端下载的基线）为基础；
2. 叠加本次单个测试运行产生的覆盖率数据；
3. 合并结果写回 packages/flutter/coverage/lcov.info，供编辑器插件（如 Coverage Gutters、Emacs coverlay）直接读取。在 Emacs 中按 C-c C-l g 可刷新看到新数据。

源码层面，这一流程由 coverage_collector.dart 中的 collectCoverageData() 完成：当 mergeCoverageData 为 true 时，工具会先检查 coverage/lcov.base.info 是否存在（缺失则报错 "Unable to merge coverage data"），再检查系统是否安装了 lcov 工具（Linux 上提示 sudo apt-get install lcov，macOS 上提示 brew install lcov），最后调用：

lcov --add-tracefile coverage/lcov.base.info \
     --add-tracefile <本次运行数据> \
     --output-file coverage/lcov.info

这正是命令行帮助中 --merge-coverage 标注 “(Requires lcov.)” 的原因。

两个必须记住的使用约束（均出自原文档与源码逻辑）：

• 每次都从原始基线出发：每次运行 --merge-coverage，工具都会回到最初的 lcov.base.info 数据再叠加当前运行，而不是在上次合并结果上继续累加；
• 一次命令只看一次运行的增量：如果你想观察多个测试文件变化对覆盖率的综合影响，需要把所有测试文件名显式列在命令行上，例如 flutter test --merge-coverage test/material/dialog_test.dart test/material/app_bar_test.dart。

完整重算：flutter test --coverage

如果需要从零重算 package:flutter 的全部覆盖率数据，可以使用 --coverage 标志：

cd packages/flutter && flutter test --coverage

这会对整个包运行全量测试并重新生成覆盖率文件。但文档明确提示：lcov.base.info 由 CI 机器人自动生成，从零重算通常没有必要，日常开发中它会在你运行 flutter update-packages 时被拉取下来。因此推荐的工作流是——日常增量验证用 --merge-coverage，只有怀疑本地基线数据与当前代码严重不一致时，才考虑 --coverage 全量重算（注意全量重算耗时较长，且结果只反映你本地这一次运行的执行情况，未必能复现 CI 的完整测试矩阵）。

从 test.dart 的命令行定义可以看到 --coverage、--merge-coverage、--branch-coverage 三者都会触发覆盖率收集器（CoverageCollector）的初始化，并共用 --coverage-path（默认 coverage/lcov.info）与 --coverage-package（正则筛选要纳入报告的包名，默认匹配当前包）等参数，因此你也可以按需调整输出位置或包名范围。

Coveralls 的现状说明

原文档曾将 Coveralls（此处按规范不附外链）作为查看整体覆盖率的便捷入口，但文档同时明确指出：Coveralls 对 Flutter 的展示长期处于故障状态，官方未推进解决该问题。因此不要依赖外部覆盖率网站查看 package:flutter 的覆盖率，以本地 lcov.info + 编辑器插件作为事实来源。

为什么仓库强调覆盖率：与 Tree hygiene 的关联

查看和重算覆盖率在 Flutter 仓库不只是“锦上添花”。仓库的贡献规范文档 Tree-hygiene.md 要求每个变更都必须被测试覆盖，并建议用覆盖率工具确认新代码全部被测试覆盖；Style-guide-for-Flutter-repo.md 也要求“检查代码覆盖率，确保新增的每一行代码都被测试”，并给出原因：未被测试的代码很可能回归或“被优化掉”。本文档在测试系列教程中的位置可参见 Running-and-writing-tests.md 中对本指南的引用。

小结

场景	命令/工具	数据来源
获取云端基线	flutter update-packages	写入 lcov.base.info 与 lcov.info
逐行查看	VS Code Coverage Gutters / Emacs coverlay	读取 packages/flutter/coverage/lcov.info
增量验证单个测试	flutter test --merge-coverage <test>（Linux，需 lcov）	基线 + 本次运行，写回 lcov.info
全量重算	cd packages/flutter && flutter test --coverage	本地全量测试运行

掌握以上流程后，你在为 package:flutter 提交框架代码时，就能在本地即时验证“新代码是否被测试覆盖”，与 CI 的覆盖率口径保持一致，同时清楚每一份覆盖率数字背后的数据链路：云端基线 → lcov.base.info → lcov --add-tracefile 合并 → lcov.info → 编辑器高亮。