writing-go-tests

Go 测试最佳实践

本技能提供可操作的测试指南。如需了解详细的实现模式、代码示例、理由及生产系统参考资料，请参阅 go-testing-best-practices.md。

编写 Go 测试时

始终遵循以下当前最佳实践：

1. 测试组织

• 将测试文件放在源代码旁边，并使用 *_test.go 命名
• 对未导出函数进行单元测试时，使用内部测试（相同包）
• 对集成测试和示例，使用外部测试（package foo_test）
• 测试文件超过 500-800 行时，按功能拆分（例如，handler_auth_test.go、handler_validation_test.go）

2. 表驱动测试

• 优先使用基于 map 的测试表，而非基于 slice 的测试表，以自动生成唯一的测试名称
• 使用描述性测试用例名称，使其显示在失败输出中
• 完整模式和示例请参阅详细指南

3. 并发测试

• 使用 testing/synctest 进行确定性并发测试（Go 1.24+）
• 这样可避免基于时间的测试出现不稳定，并将运行时间从数秒缩短至数微秒
• 对于传统的并行测试，务必在测试函数中首先调用 t.Parallel()

4. 断言和比较

• 复杂比较使用 google/go-cmp 中的 cmp.Diff()
• 简单测试使用标准库即可
• 需要更丰富的断言时，Testify 是主流的第三方框架

5. Mock 和测试替身

• 优先使用真实依赖进行集成测试，而非大量使用 Mock
• 使用 Testcontainers 进行数据库/服务集成测试
• 必须使用 Mock 时，优先使用简单的基于函数的测试替身，而非代码生成
• 采用基于接口的设计（“接受接口，返回结构体”）

6. 覆盖率目标

• 将 70-80% 的覆盖率作为实用目标
• 注重有意义的测试，而非覆盖率指标
• 使用 go test -cover 和 go tool cover -html 进行分析

7. 测试夹具

• 使用 testdata 目录存放测试夹具（Go 工具链会自动忽略该目录）
• 使用黄金文件测试验证复杂输出
• 对复杂测试数据使用函数式构建器模式

8. 辅助函数和清理

• 始终在辅助函数中标记 t.Helper()，以准确报告错误
• 使用 t.Cleanup() 清理资源（在测试中优于 defer）

9. 基准测试（Go 1.24+）

• 优先使用 B.Loop() 方法（可防止编译器优化）
• 配合 benchstat 进行统计分析
• 使用 -benchmem 进行内存分析

10. 命名约定

• 测试函数：Test*、Benchmark*、Fuzz*、Example*（前缀之后使用大写字母）
• 实际值和期望值分别使用 got 和 want
• 在表驱动测试中使用描述性测试用例名称

集成测试与单元测试

• 根据环境变量区分测试（优先于构建标签）
• 实现模式请参阅详细指南

补充参考资料

在以下情况下，请加载 go-testing-best-practices.md：

• 需要表驱动测试、Mock 模式、黄金文件、辅助函数或基准测试的完整代码示例
• 需要详细了解 testing/synctest 并发测试模式
• 需要了解为何优先采用特定模式而非其他方案
• 需要生产系统示例和统计数据（Kubernetes、Docker、Uber、Netflix、ByteDance）
• 需要了解测试框架的选择（Testify、GoMock、Testcontainers）
• 需要全面的覆盖率策略和工具详情
• 需要容器化集成测试模式

详细指南包含完整背景、带说明的示例以及经生产环境验证的模式。本 SKILL.md 提供可供应用的操作规则。

核心原则

注重验证行为而非实现的有意义测试。 务实卓越，胜过理论完美。