Go 怎么生成测试覆盖率文件并定位未覆盖函数

Go 项目想知道测试到底覆盖了哪些代码，最小做法是执行 go test ./... -coverprofile=coverage.out，再用 go tool cover -func=coverage.out 看函数级百分比。报告里出现 0.0% 的函数，通常就是下一轮测试优先补齐的位置；再配合 HTML 报告，就能追到具体没有执行的语句。

先用 go test 生成一份可复用的覆盖率文件

假设项目根目录有 go.mod，业务代码在 internal/price，测试文件是 price_test.go。进入 module 根目录执行下面的命令：

# 清理旧报告，避免把上一次运行的结果误当成当前结果
rm -f coverage.out

# 运行当前 module 的测试，并把覆盖率写入文本文件
go test ./... -coverprofile=coverage.out

./... 会递归匹配 module 下的包。若只想看一个包，可以换成 ./internal/price。命令成功后，coverage.out 会记录文件区间、语句计数和命中次数；它不是漂亮的报表，但很适合提交给后续工具继续处理。

这里有一个容易忽略的判断：测试命令返回成功，只能说明测试通过，不等于覆盖率足够。先确认文件确实存在，再查看报告，能避免把“没有生成文件”和“生成了低覆盖率文件”混为一谈。

用 go tool cover -func 快速找出未覆盖函数

生成文件后，先看函数级摘要，不必马上打开浏览器：

# 按函数列出文件、行号和覆盖率，末尾会给出 total
go tool cover -func=coverage.out

输出通常包含函数名和百分比。优先处理 0.0% 的函数，再看那些只覆盖了主路径、但错误分支仍为空的函数。覆盖率是语句命中统计，不是业务正确性的证明；一个函数达到 100%，也可能没有验证返回值是否符合业务预期。

如果只关心某个包，可以在生成阶段缩小目标，例如 go test ./internal/price -coverprofile=price.out。这样报告更短，适合在排查一个局部模块时使用。团队流水线则可以保留 ./... 的全量文件，再把函数摘要作为审查入口。

用 HTML 报告把函数问题追到具体语句

函数摘要告诉你“哪里值得看”，HTML 报告负责回答“哪几行没有被执行”。执行：

# 生成本地 HTML 报告，浏览器打开后按文件查看覆盖颜色
go tool cover -html=coverage.out -o coverage.html

# macOS 下手动打开生成的文件；Linux 桌面环境可使用对应浏览器命令
open coverage.html

在报告里先点进低覆盖率文件，再沿着函数的分支查看空白区域。补测试时不要只追求总百分比，优先覆盖输入校验失败、依赖返回错误、空集合和边界值等真正会改变结果的路径。coverage.html 是展示产物，通常不需要提交进源码仓库；coverage.out 是否提交，则按团队 CI 约定决定。

多包和集成测试为什么要换用 covdata

普通单元测试已经足够时，不必为了新工具改流程。只有当测试需要启动真实二进制、跨多次运行收集数据时，才考虑 Go 1.20 引入的集成覆盖率流程：

# 构建带覆盖率插桩的应用；只写入主 module 的相关包
go build -cover -o demo-app ./cmd/demo

# 每次运行把二进制覆盖率数据写到这个文件夹
mkdir -p coverage-data
GOCOVERDIR=coverage-data ./demo-app

# 先看各包的语句覆盖率，再按需要转成传统文本格式
go tool covdata percent -i=coverage-data
go tool covdata textfmt -i=coverage-data -o=coverage.out
go tool cover -func=coverage.out

默认的 go build -cover 主要选择主 module 内的包；若确实需要纳入其他依赖，要显式使用 -coverpkg，并确认导入路径写对，不能把包名 main 当成 module 的导入路径。多个运行目录也可以交给 go tool covdata merge 合并。

还有两个边界要记住：二进制结束时才会写出完整数据，未恢复的 panic 或致命异常可能让本次运行的语句数据丢失；另外，覆盖率只说明代码是否被执行，不能替代断言、接口测试和业务验收。

常见问题

为什么执行 go test 后没有看到 coverage.out？

先检查命令是否真的带了 -coverprofile=coverage.out，以及当前目录是不是 module 根目录。测试失败时也应先看退出信息，不能只检查文件名。

函数显示 0.0% 就一定是无用代码吗？

不一定。它可能是错误分支、启动路径或仅由集成测试触达的函数。先确认它是否在当前测试范围内，再决定补单元测试还是加入集成测试。

怎么把多个包的结果合成一个报告？

单元测试可以按需要统一目标后生成一份 profile；集成测试则使用多个 GOCOVERDIR 数据目录，再用 go tool covdata merge 合并，最后转成文本报告。

一套稳定的排查顺序是：先生成 coverage.out，再用 -func 找函数，最后用 -html 看语句。只有测试对象变成真实二进制或跨多次运行时，才把流程升级到 GOCOVERDIR 和 covdata。