编写生产级 Go 测试：表驱动、并行、goleak…

在编写或审查 Go 测试、搭建测试 CI、排查 flaky/慢测试时，用一套惯用做法写出可维护、快、可靠的测试。

适用场景

解决思路

1. 表驱动测试必须用具名子测试：每个用例都要有 `name` 字段并传给 `t.Run`。
2. 集成测试必须用 build tag（`//go:build integration`）与单元测试分离，用 `go test -tags=integration ./...` 单独运行。
3. 测试不得依赖执行顺序，每个测试必须能独立运行。
4. 独立测试尽量加 `t.Parallel()`；若在子测试里用并行，每个子测试内部自建 assert 实例。
5. 测试必须断言可观察行为与公开 API 契约，不要耦合实现细节——耦合内部的测试会让每次重构都变成重写测试，却证明不了契约。
6. 含 goroutine 的包在 `TestMain` 中使用 `goleak.VerifyTestMain(m)` 检测 goroutine 泄漏；需排除已知栈时传 `goleak.IgnoreCurrent()`；也可在单个测试里 `defer goleak.VerifyNone(t)`。
7. 把 testify 当辅助工具，不要用来替代标准库。
8. Mock 接口而不是具体类型：在消费方定义接口，再写 mock 实现。
9. 单元测试保持快（< 1ms）、隔离（无外部依赖）、确定性；集成测试用 build tag 分开。
10. CI 中带 race 检测运行测试（`go test -race ./...`）。
11. 包含 `ExampleXxx` 作为可执行文档：`go test` 会把 stdout 与 `// Output:` 注释对比，示例漂移会直接让构建失败。
12. 测试文件按被测的源文件命名，而不是按被测的函数/方法命名（`foo.go` -> `foo_test.go`），因为 `go test`、覆盖率报告、IDE 跳转、`gotests` 都按源文件解析测试。
13. 例外：超大源文件可按关注点拆成多个 `_test.go`（如 `foo_test.go` + `foo_edgecases_test.go`），但每个拆分文件名仍须派生自源文件名，绝不能来自单个函数名；优先保持每个源文件一个 `_test.go`。
14. 测试文件内，测试函数的顺序应与源文件中被测函数/方法的出现顺序一致，方便按位置定位。
15. 按约定命名：`TestAdd`（函数）、`TestMyStruct_MyMethod`（方法）、`BenchmarkAdd`、`ExampleAdd`、`FuzzAdd`。
16. 选择测试包形式：同包（白盒，可访问未导出符号）用 `package mypackage`；测试包（黑盒，仅公开 API）用 `package mypackage_test`。
17. 避免 assert 作用域泄漏到子测试：不要在父测试里创建 testify 的 `assert`/`require` 实例并在 `t.Run` 闭包里复用，因为 `assert.New(t)` 绑定的是父级 `*testing.T`，子测试失败会被归到父测试、子测试仍显示 PASS；应在每个 `t.Run` 内用该子测试的 `t` 新建实例。
18. 用故意写坏的用例验证 assert 作用域：若 `go test -v -run TestName` 显示 `--- FAIL: TestName` 但每个 `--- PASS: TestName/subtest_name` 仍为 PASS，说明 assert 作用域泄漏。
19. 用 `httptest` 配合表驱动模式测试 HTTP handler，覆盖请求/响应体、查询参数、header 和状态码断言。
20. 对时间敏感的并发代码（`time.Sleep`、`time.After`、`time.Ticker`）、需要可复现的竞态、或时序导致的 flaky 测试，使用 `testing/synctest`：`synctest.Test(t, func(t *testing.T){...})`，在时间推进点调用 `synctest.Wait()`；Go 1.25+ 用 `synctest.Test`，不要在 Go 1.25+ 代码里用 Go 1.24 的实验性 `synctest.Run`（仅当模块显式面向 Go 1.24 并开启 `GOEXPERIMENT=synctest` 时作为兼容回退）。
21. Go 1.27+ 可用 `synctest.Sleep(d)` 直接推进 bubble 的假时钟（等价于 `time.Sleep(d)` 加 `synctest.Wait()`，但不需要真实 goroutine 阻塞）；Go 1.27+ 的 `httptest.NewTestServer()` 是在内存假网络版 `httptest.NewServer`，可与 `synctest` 组合，服务端测试无需真实 socket 即可跑在 `synctest.Test` bubble 里。
22. 对可能挂起的测试，使用带调用位置的 panic 超时辅助函数。
23. 写基准测试必须用子基准测试（`b.Run` 覆盖每个变体），让每个变体在输出中有独立名字供对比工具 diff；Go 1.24+ 用 `b.Loop()` 而不是 `b.N` 循环。
24. 测试/基准/fuzz 需要持久化文件供检查时，Go 1.26+ 用 `t.ArtifactDir()`（`*testing.T`、`*testing.B`、`*testing.F` 均可用）代替临时路径或仓库内输出目录，写文件后用 `t.Logf` 打印路径。
25. Go 1.27+ 的 `go test` 默认运行 `stdversion` vet 检查，使用高于模块 `go` 指令的 API 会失败：应升级 `go` 指令或改用旧 API，不要静默该检查。
26. 用模糊测试找边界与 bug：先 `f.Add(...)` 添加种子（如 "hello"、""、"a"），再在 `f.Fuzz(func(t *testing.T, input string){...})` 中断言不变量（如 `Reverse(Reverse(s)) == s`）。
27. 用 `go test -coverprofile=coverage.out ./...` 生成覆盖率，再用 `go tool cover -html=coverage.out` 查看未覆盖行；把覆盖率当作定位未测路径的缺口发现器，而不是目标——它不衡量断言质量。
28. 用 linter 自动强制测试最佳实践：`thelper`、`paralleltest`、`testifylint`。
29. 按模式组织工作：Write 模式顺序处理被测代码，用 `gotests` 生成表驱动测试骨架后再补边界与错误路径；Review 模式聚焦 PR diff，检查新行为的覆盖、断言质量、表驱动结构与 flaky 模式；Audit 模式按关注点拆分最多 3 个并行子代理（单测质量与覆盖缺口、集成测试隔离与 build tag、goroutine 泄漏与竞态）并合并成一份缺口报告；Debug 模式顺序执行：稳定复现、隔离失败断言、在生产代码或测试 setup 中追溯根因。
30. 安装依赖：`go install github.com/cweill/gotests/gotests@latest`。
31. 常用命令速查：`go test ./...`；`go test -run TestName ./...`；`go test -run TestName/subtest ./...`；`go test -run 'Test(Add|Sub)' ./...`；`go test -run 'Test[A-Z]' ./...`；`go test -run 'TestUser.*' ./...`；`go test -run '.*Validation.*' ./...`；`go test -run TestName/. ./...`；`go test -run '/(unit|integration)' ./...`；`go test -race ./...`；`go test -cover ./...`；`go test -bench=. -benchmem ./...`；`go test -fuzz=FuzzName ./...`；`go test -tags=integration ./...`。

适用边界 · 注意事项

• 不适用于非 Go 项目。
• `testing/synctest` 需要 Go 1.25+（`synctest.Sleep`、`httptest.NewTestServer` 需要 Go 1.27+），低版本只能用兼容回退，不能直接套用。
• 不要把覆盖率百分比当作目标，它只能用来发现未测路径，不能衡量断言质量。