利用 TestMain 管理共享资源又不污染单个用例

我以前给一组 HTTP 客户端测试加过假服务：每个用例都启动一次 httptest.Server，隔离性很好，但测试数量上来后，重复启动和关闭服务让套件越来越慢。后来把服务搬进 TestMain，速度问题解决了，却又遇到数据残留导致的偶发失败。真正有效的分工是：TestMain 只管理昂贵共享资源的包级生命周期，单个用例的可变数据仍由 testing.T 管理。

Go testing 包官方文档：https://pkg.go.dev/testing。官方说明中，测试包定义 func TestMain(m *testing.M) 后，生成的测试程序会调用它；TestMain 运行在主 goroutine，可以围绕 m.Run() 做初始化和收尾。这个能力很强，但官方也明确把它称为低层原语，普通测试不需要为了“统一”而全部搬进去。

数据来源：先判断什么值得共享

适合放进 TestMain 的通常是启动代价高、整个测试包只需要一份、并且能支持逻辑隔离的资源，例如本地假服务、数据库容器、消息代理连接、临时证书或大型只读测试数据。只创建一个普通结构体、一个临时目录，或只服务于单个测试的资源，直接在测试函数中创建更清楚。

我会用三个问题判断：资源启动是否明显昂贵；多个用例是否真的能安全共享；能否给每个用例分配独立数据范围。第三个问题最重要。如果服务只能靠“每次测试前清空全部数据”恢复，那么并行测试一开启就可能互相删除数据，这种资源不适合直接全局共享。

校验：进入 m.Run 前完成启动检查

m.Run() 才会运行这个包里的测试与基准测试。共享资源必须在它之前准备好；启动失败时，不要让几十个用例分别报“连接失败”，而应在包入口直接输出明确原因并返回非零退出码。

package client_test

import (
    "fmt"
    "net/http"
    "net/http/httptest"
    "os"
    "testing"
)

var sharedBaseURL string

func TestMain(m *testing.M) {
    // 包级资源只启动一次，并把可变实现封装在服务内部
    server := httptest.NewServer(newFakeHandler())
    if server.URL == "" {
        fmt.Fprintln(os.Stderr, "测试服务启动失败：URL 为空")
        os.Exit(1)
    }

    // 对测试只暴露初始化后不再修改的连接入口
    sharedBaseURL = server.URL

    code := m.Run()

    // os.Exit 不会运行 defer，因此必须在退出前显式关闭资源
    server.Close()
    os.Exit(code)
}

func newFakeHandler() http.Handler {
    // 处理器实现放在独立文件中，便于测试其隔离规则
    return http.NewServeMux()
}

m.Run() 返回适合传给 os.Exit 的退出码。当前官方文档也允许 TestMain 在调用 m.Run() 后直接返回，由测试包装器使用该结果退出。不过当需要明确处理关闭错误、调整最终退出码或保证旧版本风格一致时，显式保存 code 更容易看懂。关键不是“必须写 os.Exit”，而是如果写了，就不能把必要清理仅放在 defer 中。

存储模型：全局只保存不可变入口

污染通常不是因为出现了包级变量，而是因为包级变量承载了可变业务状态。把全局对象限制为服务地址、只读证书路径或配置快照；不要把“当前测试用户”“上一次响应”“共享请求体”放进去，也不要让测试随意改写全局客户端的超时和 Transport。

type fixture struct {
    baseURL string
    scope   string
    client  *http.Client
}

func newFixture(t *testing.T) *fixture {
    t.Helper()

    // 用测试名称生成独立命名空间，不修改包级共享入口
    scope := sanitizeScope(t.Name())
    f := &fixture{
        baseURL: sharedBaseURL,
        scope:   scope,
        client:  &http.Client{},
    }

    // 清理动作只绑定当前用例的数据范围
    t.Cleanup(func() {
        if err := f.deleteScope(); err != nil {
            t.Errorf("清理测试命名空间 %q 失败：%v", scope, err)
        }
    })

    return f
}

这里每个测试都会得到自己的 http.Client。这样某个用例修改超时、CookieJar 或 Transport 时，不会影响其他用例。共享的只有服务本身和一个字符串 URL，边界很容易审查。

查询路径：每个用例创建自己的命名空间

共享服务内部可以维护同一份受锁保护的存储，但所有数据读写都必须带 scope。数据库测试可以对应独立 schema、租户 ID 或事务；对象存储可以对应前缀；消息系统可以对应唯一 topic。不要依赖用例执行顺序，也不要把“测试后清空整库”当作隔离。

func TestCreateOrder(t *testing.T) {
    t.Parallel()
    fx := newFixture(t)

    // 订单只写入当前测试命名空间
    order, err := fx.createOrder("book")
    if err != nil {
        t.Fatalf("创建订单失败：%v", err)
    }
    if order.Scope != fx.scope {
        t.Fatalf("订单命名空间错误：got %q want %q", order.Scope, fx.scope)
    }
}

func TestListOrdersStartsEmpty(t *testing.T) {
    t.Parallel()
    fx := newFixture(t)

    // 新命名空间不应看见其他并行用例的数据
    orders, err := fx.listOrders()
    if err != nil {
        t.Fatalf("查询订单失败：%v", err)
    }
    if len(orders) != 0 {
        t.Fatalf("新命名空间存在残留数据：%d", len(orders))
    }
}

t.Parallel() 会让并行测试与其他并行测试一起运行，所以共享服务本身还必须是并发安全的。命名空间解决“数据归谁”，互斥锁、并发安全容器或数据库事务解决“同时访问是否安全”，两者不能互相替代。

异常处理：不要让一个用例关闭共享资源

单个测试只能清理自己的 scope，不能关闭包级服务。否则第一个结束的测试会让仍在运行的并行测试全部连接失败。反过来，TestMain 也不应逐个理解用例数据；它只需保证 m.Run() 结束后关闭共享资源。

如果局部清理失败，使用 t.Errorf 将问题记在对应测试上通常比在 TestMain 汇总更有定位价值。若资源关闭失败会泄漏进程或端口，则可以在 m.Run() 后检查关闭错误，并在原测试成功时把最终退出码改为非零。注意不要覆盖已经存在的测试失败码。

code := m.Run()

// 先执行包级清理，再决定最终退出码
if err := stopSharedResource(); err != nil {
    fmt.Fprintln(os.Stderr, "关闭共享测试资源失败：", err)
    if code == 0 {
        code = 1
    }
}
os.Exit(code)

若 TestMain 自己依赖命令行标志，还要记住官方文档指出：调用 TestMain 时 flag.Parse() 尚未执行。普通测试函数开始前标志已经解析，但 TestMain 读取自定义标志时应显式调用 flag.Parse()。

清理策略：包级资源和用例状态分别收尾

可以把整套设计压缩为两层生命周期。外层由 TestMain 负责“启动一次、验证一次、关闭一次”；内层由 testing.T 负责“创建独立状态、断言、清理当前状态”。这种结构不要求每个测试都无状态，而是要求可变状态有明确所有者。

• 共享服务只在 TestMain 中创建和关闭。
• 包级变量只保存初始化后不可变的入口。
• 每个用例获得独立 client、scope、事务或 schema。
• 局部资源使用 t.Cleanup，不依赖测试函数最后一行。
• 并行测试不清空全局数据，也不关闭共享服务。
• 调用 os.Exit 前显式完成所有必要的包级清理。

如果资源启动很快，优先让每个用例独占资源，简单性通常比几百毫秒更值钱。只有当启动成本确实成为瓶颈，并且资源支持可靠的逻辑隔离时，TestMain 才是合适的优化点。

常见问题

TestMain 是整个项目只运行一次吗？

不是。它属于测试包，运行 go test ./... 时，不同包会构建并运行各自的测试程序，因此需要各自的 TestMain 和资源策略。

能在 TestMain 里调用 t.Cleanup 吗？

不能，因为 TestMain 收到的是 *testing.M，不是 *testing.T。包级资源在 m.Run() 前后显式管理；用例级资源在测试或辅助函数中注册 t.Cleanup。

为什么不把共享数据库客户端直接放全局变量？

并发安全且配置固定的连接池可以共享，但测试不要改写它的配置，也不要共享事务。更稳妥的方式是全局保存不可变连接入口或受控池，每个用例创建自己的事务、schema 或租户范围。

测试调用 FailNow 后 cleanup 还会执行吗？

t.Cleanup 注册的函数会在测试及其子测试完成后按后进先出顺序调用，因此比把清理写在测试函数末尾更可靠。