Go coverage profile 怎样合并多个测试包的覆盖率

多个包一起测试时，先用一次 go test -coverprofile=coverage.out ./... 收集统一文本报告；如果手里是多次集成测试产生的二进制覆盖率目录，则用 go tool covdata merge 合并，再导出文本 profile。两种输入不能混用，也不要把各包的百分比直接求平均。

Go 官方地址：https://go.dev/

覆盖率合并解决什么问题

测试包数量多，并不等于必须手工合并文件。同一次 go test 可以指定多个包；更适合 covdata 的场景是同一份插桩程序经过不同用例、不同运行收集出多个目录，希望统一查看命中的代码区域。

本文将“合并”限定为数据汇总和报告输出，不讨论提高覆盖率，也不把覆盖率当作测试质量的充分条件。后面的命令是供项目采用的示例，没有预设任何实际覆盖率数值。

支持范围：先辨认文本文件与二进制目录

Go 1.20 起支持 go build -cover 的应用覆盖率采集。二进制目录中的 covmeta 描述插桩元数据，covcounters 记录运行计数；传统文本 profile 则包含 mode 头部及代码区间记录。改扩展名不会改变格式。

最小示例：一次收集多个测试包

在模块根目录运行下面的命令。示例按包自身测试的默认插桩范围收集，适合希望得到一份跨包报告的情况。

# 同一次测试指定模块内多个包；count=1 避免复用测试缓存
go test -count=1 -coverprofile=coverage.out ./...
# 函数报告可查看总计，HTML 保存为文件
go tool cover -func=coverage.out
go tool cover -html=coverage.out -o=coverage.html

如果问题是“某个包的测试调用了另一个包，但想统计被调用包”，应另外确定 -coverpkg 插桩范围；它与用于选择执行哪些测试的包参数承担不同作用。不要仅仅因为测试了 ./... 就推断每个测试二进制都对所有依赖插桩。

多次运行：合并完整覆盖率数据目录

假设当前工作区已有 run-a、run-b 两个完整二进制数据目录，来自同一源码版本、相同插桩范围的两组用例。每个目录均保留元数据和计数文件。选择一个尚不存在的输出目录，以免夹带以前运行的数据。

# 输入是包含 covmeta、covcounters 的目录，不是 coverage.out 文件
# 使用一个本轮尚不存在的目录名；mkdir 失败时不要继续向旧目录写
mkdir merged-current
# 逗号分隔目录，等号后的列表不要加入空格
go tool covdata merge -i=run-a,run-b -o=merged-current
# 查看合并后各包的语句覆盖比例
go tool covdata percent -i=merged-current

这里的目标是把不同用例命中的区域纳入同一统计，而不是平均两个报告上的百分比。按包输出的比例具有各自的语句分母，不能当成每个包等权的总分。

如果需要从头采集，可在项目中以 go build -cover 构建实际应用，再为各组运行设置不同的 GOCOVERDIR。应用入口和参数取决于项目，不要把不存在的演示目录直接照搬。默认应用插桩范围以主模块内包为主，外部依赖是否计入应显式决定。

兼容处理：把合并目录交给传统报告工具

需要函数明细或源码高亮时，将二进制目录转换成传统文本文件。textfmt 承担格式转换，cover 负责消费文本报告，两者职责不同。

# 把合并目录导出为传统文本 profile
go tool covdata textfmt -i=merged-current -o=merged.out
# 输出函数覆盖率，并将源码高亮页保存为静态文件
go tool cover -func=merged.out
go tool cover -html=merged.out -o=merged.html

生成源码高亮页时，应保留与采集版本相匹配的源码工作区。若只想了解目录包含哪些包，可使用 go tool covdata pkglist -i=merged-current；这个查询不代替对插桩范围的配置。

性能与使用注意：把统计口径固定下来

覆盖率插桩会增加工作量，报告运行的性能数据不要直接当作无插桩程序的基准。CI 中可将覆盖率任务和性能测量分开组织。

• 固定源码版本、构建条件和插桩范围。工具能够处理数据不等于不同构建的数字天然可比较。
• 保留完整采集目录。只拷贝 covcounters 而丢掉配套 covmeta，会失去解释计数所需的信息。
• 每轮使用独立目录。保留旧数据用于追溯，但不要无意混进当前报告。
• 检查测试或应用退出状态。异常终止可能影响计数落盘，不能把缺失数据解释成零覆盖。
• 发布报告前留意源码路径和内部包名。覆盖率文件属于开发产物，应按项目权限分发。

常见问题

可以直接 cat 多个 coverage.out 吗？

不建议。重复的 mode 头部以及相同代码区间的多份计数需要按格式语义处理，简单拼接无法可靠完成汇总。能统一采集时，优先一次 go test；二进制目录则走 covdata。

merge 会自动把旧文本报告转换为目录吗？

不会。其 -i 参数要求二进制覆盖率数据目录，textfmt 的作用方向是目录导出文本。

两个测试包都覆盖同一段代码，算两份覆盖率吗？

是否覆盖与计数值不同。汇总比例应根据代码区间和语句权重计算，不能把相同代码被多次命中解释为覆盖面积翻倍。

只要得到 HTML 就能确认所有用例成功吗？

不能。报告展示收集到的数据；测试是否成功以及采集是否完整仍应由任务退出状态和采集组织方式判断。

参考文档：Go 测试参数 https://pkg.go.dev/cmd/go#hdr-Testing_flags；应用覆盖率采集 https://go.dev/doc/build-cover；covdata 工具 https://pkg.go.dev/cmd/covdata。前者用于单元测试命令，后两者说明目录数据和报告操作。