go test 是集成在 Go 构建工具链中的测试执行器，依赖包结构、_test.go 命名、TestXxx 函数签名及正确目录位置；错误常源于包不一致、函数名/参数不符或工作目录不当。
Go 的 go test 不是“运行测试文件”那么简单，它是一套集成在构建工具链里的测试执行器，依赖包结构、命名约定和命令参数协同工作。直接 go test 能跑起来，但多数人卡在「为什么没执行我的函数」「为什么覆盖率是 0%」「为什么 -run 没生效」——问题往往出在包路径、测试函数签名或当前目录上。
测试文件必须以 _test.go 结尾且放在被测包目录下
Go 强制要求测试代码与被测代码处于同一包（package xxx），且文件名必须匹配 *_test.go 模式。如果你把 utils_test.go 放在 ./test/ 子目录下，go test 默认不会扫描它；如果改名为 utils.go，即使内容是 func TestX(t *testing.T)，也不会被识别。
- ✅ 正确：项目根目录下有
math.go和math_test.go，两者都声明package math - ❌ 错误：把
math_test.go放进./internal/test/，或改成math_test.go但声明package test - ⚠️ 注意：
go test ./...会递归查找所有含*_test.go的子目录，但每个子目录仍需满足包一致性
测试函数必须是 TestXxx 形式且接收 *testing.T 参数
Go 测试发现机制只认函数名以 Test 开头、首字母大写的导出函数，并且参数列表必须是 (t *testing.T)（或 (t *testing.B) 用于基准测试）。写成 testAdd()、Test_add() 或 func TestAdd(t int) 都会被跳过。
func TestAdd(t *testing.T) {
got := Add(2, 3)
if got != 5 {
t.Errorf("Add(2, 3) = %d, want 5", got)
}
}
- ✅
TestAdd、TestHTTPHandler、TestValidate_Email（只要首字母大写） - ❌
testAdd、TEST_ADD、Testadd（小写 a）、Test_Add（下划线后小写） - ⚠️ 如果想临时禁用某个测试，加下划线前缀：如
Test_Add_disabled不会被执行
go test 命令的常用参数组合与典型场景
不加参数的 go test 只运行当前目录下的测试；加 -v 才能看到每个测试的输出；而 -run 是按正则匹配测试函数名，不是文件名。
-
go test：静默运行，仅报错时输出 -
go test -v：显示每个t.Log()和测试通过/失败详情 -
go test -run=^TestAdd$：精确匹配函数名（^和$防止匹配到TestAddWithNegative） -
go test -count=1：强制只运行一次（默认会缓存并跳过重复测试） -
go test -race：启用竞态检测（仅支持 Linux/macOS/Windows，会显著降速） -
go test -coverprofile=coverage.out && go tool cover -html=coverage.out：生成并打开 HTML 覆盖率报告
子测试（t.Run）和 setup/teardown 的惯用写法
Go 原生不提供 beforeEach，但可以用闭包 + t.Run 实现逻辑分组和资源隔离。注意：子测试名也必须是 TestXxx 风格，且不能在 t.Run 外部做全局状态修改。
func TestLogin(t *testing.T) {
t.Run("valid credentials", func(t *testing.T) {
// 每个子测试都有独立的 t，可单独标记失败或跳过
if os.Getenv("CI") == "true" {
t.Skip("skip login test in CI")
}
// ...实际测试逻辑
})
t.Run("empty password", func(t *testing.T) {
// 这里不会受上一个子测试影响
})
}
- 子测试名不用加
Test前缀，但建议保持驼峰风格便于阅读（如"EmptyPassword"） - 不要在
t.Run外部修改共享变量，否则子测试间可能互相污染 - 想复用 setup 逻辑？提取为私有函数，传入
*testing.T：比如setupDB(t)内部调用t.Cleanup()关闭连接
最容易被忽略的是当前工作目录和模块初始化状态：go test 默认按 go list 解析包路径，如果不在 module 根目录下运行，或 go.mod 缺失，可能报 no Go files in。先 go list ./... 看是否能列出目标包，再执行测试，能省掉一半排查时间。
