Go测试文件必须以_test.go结尾,函数名须为TestXxx(t *testing.T)格式;命名建议xxx_test.go与源文件对应,go test否则报“no test files”。

测试文件命名必须以 _test.go 结尾
Go 的 testing 包只识别这个后缀的文件,否则 go test 会直接跳过。命名建议采用 xxx_test.go,其中 xxx 与被测源文件名对应(如 user_handler.go → user_handler_test.go),便于 IDE 关联和团队理解。
常见错误现象:go test 输出 no test files,但文件明明存在 —— 很可能后缀写成了 .tests.go 或 test.go。
测试函数必须以 Test 开头且参数为 *testing.T
这是 Go 测试运行器的硬性约定。函数签名只能是 func TestXxx(t *testing.T),不能多参、不能少参、不能用 *testing.B 或 testing.F(那是 benchmark 和 fuzz 用的)。
实操建议:
- 函数名中的
Xxx应体现被测行为,比如TestUploadHandler_WithEmptyFile比Test1可读性强得多 - 避免在测试函数里启动真实 HTTP 服务(如
httptest.NewServer),它属于集成测试范畴;单元测试应使用httptest.NewRecorder+router.ServeHTTP - 若需复用 setup 逻辑,用
t.Cleanup()注册清理动作,而不是依赖defer在函数末尾写——后者在 panic 时可能不执行
Handler 测试必须调用 router.ServeHTTP(w, req)
直接调用 handler 函数(如 pingHandler(c))绕过了 Gin 的上下文初始化流程,c.Request、c.Params、c.MultipartForm 等都为 nil 或未解析状态,导致测试失真。
正确路径是构造完整请求链:
- 用
http.NewRequest创建*http.Request - 用
httptest.NewRecorder创建响应记录器w - 显式调用
router.ServeHTTP(w, req)触发 Gin 内部中间件和路由匹配 - 之后再断言
w.Code、w.Body.String()或检查c中挂载的数据(如通过c.MustGet("db"))
容易踩的坑:忘记设置 req.Header.Set("Content-Type", ...) 导致 c.ShouldBindJSON 或 c.FormFile 失败;或没调用 writer.Close() 就用于 multipart 请求体,造成 c.FormFile 返回 nil。
测试前必须设 gin.SetMode(gin.TestMode)
不设此模式,Gin 会在控制台打印大量 [GIN-debug] 日志,干扰测试输出;更严重的是,某些内部行为(如 panic 捕获策略、默认中间件启用)在 DebugMode 下与实际部署环境不一致。
推荐写法是在包级 TestMain 中统一设置:
func TestMain(m *testing.M) {
gin.SetMode(gin.TestMode)
os.Exit(m.Run())
}
注意:TestMain 是整个测试包的入口,只运行一次;不要在每个测试函数里重复调用 gin.SetMode,它不是线程安全的,且多次设置无意义。
真正难测的从来不是 happy path,而是中间件提前 abort、body 被中间件读取后不可重放、multipart boundary 不匹配这些隐性依赖。写测试时,先确认 c.MultipartForm() 或 c.GetRawData() 是否被其他逻辑干扰,比堆断言更重要。


















