Go test 的 TestMain 为什么影响子测试退出码

TestMain 不会给每个子测试单独分配进程退出码，它控制的是整个包的测试程序入口。子测试失败会影响测试结果，m.Run 把这些结果汇总成退出码；如果 TestMain 随后错误地调用 os.Exit(0)，就可能覆盖这个失败状态。反过来，测试全部通过以后主动以非零码退出，也会让整个测试程序失败。

有一个常见说法需要纠正：TestMain 中调用 m.Run 后直接返回，并不等于丢掉失败码。当前 testing 文档明确说明，这种写法会由生成的测试包装器使用 m.Run 的结果退出。真正要检查的是显式退出、自定义启动失败处理、清理失败处理，以及调用测试的外层脚本。

Go 官方地址：https://go.dev/

目标和边界：分清三层结果

子测试 t.Run 返回的 bool、m.Run 返回的 int 和 shell 观察到的 go test 状态不是同一个值。t.Run 用于描述子测试是否成功；m.Run 管理测试集合；go test 命令还可能因为编译、包加载等问题失败。不要把某个子测试的名字和一个操作系统退出码直接绑定。

全流程总览：先让最小 TestMain 保持失败语义

在不需要改写退出码时，可以让 TestMain 正常返回。下面的示例故意保留一个失败子测试，用来帮助读者自行观察失败传播。它不是业务测试，也没有在文章生成过程中执行。

package exitdemo

import "testing"

func TestMain(m *testing.M) {
    // 正常返回时，测试包装器会用 m.Run 的结果退出。
    m.Run()
}

func TestExport(t *testing.T) {
    t.Run("empty-name", func(t *testing.T) {
        // 故意失败，用于观察包级结果，不代表真实业务断言。
        t.Error("示例：名称不能为空")
    })
}

在独立示例目录创建模块，将代码保存为 exit_test.go。项目已有 go.mod 时无需再次 init。每个包只保留一个 TestMain，避免把后面的替代写法同时粘贴进去。

# 仅在新示例目录初始化模块。
go mod init example.com/exitdemo
# 禁用测试结果复用，便于观察这次示例执行。
go test -count=1 -run TestExport -v .
# 紧跟命令查看状态，不能先执行其他命令覆盖它。
echo $?

依据 testing 规则，这个样例应显示子测试失败并让命令以非零状态结束。这里不给出伪造的 stdout 或具体平台状态数字。若 CI 仍显示成功，先检查外层命令是否用了忽略错误的写法，或流水线只保留了日志工具的退出状态。

阶段拆解：显式退出时，先完成清理再交出状态

如果必须把环境准备、测试执行和清理失败统一成最终状态，使用返回整数的辅助函数，把 os.Exit 留在最外层。这样辅助函数先返回，里面的 defer 才能运行；直接在同一层 defer 后调用 os.Exit，会跳过这些延迟调用。

package exitdemo

import (
    "fmt"
    "os"
    "testing"
)

func TestMain(m *testing.M) {
    // runSuite 返回后，其 defer 已完成，再退出测试进程。
    os.Exit(runSuite(m))
}

func runSuite(m *testing.M) (code int) {
    dir, err := os.MkdirTemp("", "exitdemo-*")
    if err != nil {
        fmt.Fprintln(os.Stderr, "准备测试目录:", err)
        return 1 // 环境未准备好，不把测试标成成功。
    }
    defer func() {
        if err := os.RemoveAll(dir); err != nil {
            fmt.Fprintln(os.Stderr, "清理测试目录:", err)
            if code == 0 {
                code = 1 // 保留已有失败，只把原成功改为清理失败。
            }
        }
    }()
    // 测试失败码不能被后面的成功常量覆盖。
    code = m.Run()
    return code
}

func TestExport(t *testing.T) {
    t.Run("empty-name", func(t *testing.T) {
        t.Error("示例：名称不能为空")
    })
}

这份完整代码替代前一个文件内容。目录是本例自己创建的临时目录，只清理这个目录。这里选择“清理失败也使测试任务失败”，属于明确的项目策略，并非 testing 强制所有项目如此。已有失败状态会被保留，便于识别主要失败来源。

推荐流程：优先用局部清理，确实共享才用 TestMain

只属于单个测试或子测试的资源，优先采用 t.Cleanup、t.TempDir 等测试级机制。包级 TestMain 更适合所有测试共享的准备和收尾，不必为每个小测试都增加一个进程入口控制层。

若 TestMain 的准备过程依赖命令行标志，应在使用之前显式调用 flag.Parse；进入普通测试函数时，测试框架已经解析了标志。不要把未解析的参数默认值当成 CI 传参失效，也不要为了读取标志跳过 m.Run。

常见误区：不是所有“结束”都等于测试成功

调用 m.Run 后无条件 os.Exit(0)，会主动丢掉失败码；启动失败后不运行测试并报告成功，则会制造“没有测但全绿”的结果。另一个极端是在普通子测试中调用 os.Exit，它会直接终止整个测试程序，破坏其他测试的运行和正常清理。断言失败应用 t.Error、t.Fatal 等测试方法表达。

panic、超时或被外部终止也不属于普通 m.Run 返回后的收尾路径。辅助函数的 defer 结构解决正常返回时的清理顺序，不能承诺任何异常退出都一定清理完成。外部服务等资源还需要独立的过期与回收方案。

并行子测试也不能按普通顺序子测试的 t.Run 返回时刻直接判断已经全部完成。t.Run 遇到 t.Parallel 时会有自己的调度语义；对于整个测试集合，交给 m.Run 管理完成与汇总，不要手写一个 bool 拼接成进程退出码。

速查：遇到状态不一致时查哪一层

选择自动返回或显式退出都可以，关键是保持测试失败状态、把清理责任放在正确层级，并让外层工具如实看到结果。本文示例用于理解契约，正式项目仍应根据自己的共享资源设计准备和收尾。

相关问题

TestMain 一定要写 os.Exit(m.Run()) 吗？

不一定。当前文档允许调用 m.Run 后正常返回，由测试包装器负责退出。显式退出适用于确实需要自己组合最终状态的情况。

t.Run 的 false 能直接当作退出码吗？

它是测试层面的布尔结果，不是进程状态；通常无需手动转换，m.Run 会汇总测试失败。

defer os.Exit(code) 能简化处理吗？

defer 的实参在注册时求值，code 后续变化可能不会体现在该调用里。辅助函数返回最终码的写法更直观，也减少延迟调用顺序的混淆。

参考：testing：TestMain、M.Run、os.Exit。