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 ./... 看是否能列出目标包，再执行测试，能省掉一半排查时间。