testing.T.Context 绑定测试清理任务的生命周期

如果测试启动了后台 goroutine，Go 1.24 及以上可以直接把 t.Context() 传给它。测试及其子测试完成时，这个 Context 会在所有 t.Cleanup 回调执行前被取消；因此 Cleanup 可以安全等待后台任务收到 Done 信号并退出。这正是它与随手使用 context.Background() 的核心区别。

官方文档：https://pkg.go.dev/testing#T.Context

Context 和 Cleanup 到底谁先发生

我第一次使用这个 API 时，最担心的是清理回调里等待 worker 会不会死锁。官方给出的顺序消除了这个疑问：T.Context 返回的 Context 会在 Cleanup 回调被调用之前取消。Cleanup 回调因此能等待所有依赖 ctx.Done() 的资源关闭。

T.Cleanup 本身仍按后注册先执行的顺序调用，但无论某个 Cleanup 排在第几个，进入 Cleanup 阶段时 t.Context() 都已经取消。不要把“Context 取消”和“Cleanup 回调之间的 LIFO 顺序”混成一件事。

为什么不再手写 Background 加 CancelFunc

以前我常在测试里手动创建 WithCancel(context.Background())，再把 cancel 塞进 Cleanup。代码表面上没问题，但很容易只发取消信号、不等待任务退出，或者因为多个 Cleanup 的注册顺序不同而把关闭逻辑拆散。

func TestOldStyle(t *testing.T) {
    // 旧写法需要自己维护取消函数，并且还要另外等待 goroutine 退出。
    ctx, cancel := context.WithCancel(context.Background())
    t.Cleanup(cancel)

    go runPollingWorker(ctx)

    // 测试断言写在这里，但后台任务何时真正退出并不清楚。
}

t.Context() 把取消动作绑定到测试框架自己的完成边界。它不会自动等待 goroutine，因此完整模式仍然是“传递 Context + 暴露完成信号 + Cleanup 等待”。

正确做法：让 Cleanup 等待 workerDone

下面这个例子启动一个轮询任务。worker 始终监听测试 Context，退出前关闭 done；Cleanup 在 Context 已取消的前提下等待完成信号，并设置一个本地保护时间，避免错误实现让整套测试永久卡住。

package worker_test

import (
    "context"
    "testing"
    "time"
)

func startTestWorker(t *testing.T) 

这个模式对文件监听器、内存队列消费者、测试 HTTP 客户端和模拟调度器都适用。关键不是 goroutine 数量，而是每个后台任务必须有明确的停止信号与完成信号。

父测试和子测试应该用哪个 Context

我会用一句很实际的判断：资源在哪个测试结束时就该消失，就使用哪个 T 的 Context。子测试自己的 t.Context() 会在该子测试及其后代完成后进入取消和 Cleanup；父测试的 Context 则覆盖父测试及全部子测试的完成边界。

func TestService(t *testing.T) {
    // 服务供所有子测试共享，因此绑定父 T 的生命周期。
    serviceDone := startServiceForTest(t, t.Context())
    t.Cleanup(func() {
        // 父 Context 已取消，等待共享服务退出。
        

如果子测试中的任务误用了父 Context，那么子测试结束后它还可能继续运行，直到整个父测试完成。反过来，共享服务若绑定某个子测试 Context，则第一个子测试结束时就会被取消，兄弟用例随后可能访问到已经关闭的资源。

几个容易误解的边界

t.Context 会跟随 go test -timeout 提前取消吗

不要把它当成测试超时 API。t.Context() 主要表达测试完成与清理之间的生命周期。需要限制某次调用时，应从它派生带超时的 Context，并及时调用返回的 cancel。

func TestRemoteCall(t *testing.T) {
    // 业务调用有独立的 500ms 上限，同时仍受测试生命周期控制。
    ctx, cancel := context.WithTimeout(t.Context(), 500*time.Millisecond)
    defer cancel()

    if err := callDependency(ctx); err != nil {
        t.Fatalf("依赖调用失败: %v", err)
    }
}

Cleanup 里还能把 t.Context 传给关闭接口吗

通常不行，因为 Cleanup 开始时它已经取消。如果关闭接口需要一个仍可用的 Context，应在 Cleanup 内创建独立、短时、可取消的上下文，明确限制清理请求最长执行多久。

func registerShutdown(t *testing.T, srv *Server) {
    t.Helper()
    t.Cleanup(func() {
        // t.Context 已取消；为主动关闭请求创建独立且有上限的 Context。
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
        defer cancel()

        if err := srv.Shutdown(shutdownCtx); err != nil {
            t.Errorf("关闭测试服务失败: %v", err)
        }
    })
}

Go 1.23 及以下怎么办

T.Context 从 Go 1.24 加入。旧版本可以继续使用 context.WithCancel，但要把“先 cancel、再等待 done”的顺序集中在一个 Cleanup 中，不要分散到多个依赖 LIFO 的回调里。

func legacyTestContext(t *testing.T) context.Context {
    t.Helper()
    ctx, cancel := context.WithCancel(context.Background())

    // 旧版本至少把取消动作固定绑定到当前 T 的 Cleanup。
    t.Cleanup(cancel)
    return ctx
}

最后怎么检查有没有绑对生命周期

• 后台函数是否接收并监听了 context.Context。
• 是否存在可等待的 done、Wait 或 Close 完成信号。
• Cleanup 是否等待资源真正停止，而不只是发送取消。
• 共享资源是否绑定父 T，子测试私有资源是否绑定子 T。
• Cleanup 中的新网络操作是否使用独立的限时 Context。
• 模块的 go.mod 是否至少要求 Go 1.24。

# 只运行目标测试并重复执行，观察是否仍有偶发退出或泄漏问题。
go test -run '^TestWorker$' -count=50 -race ./...

对我来说，t.Context() 最大的价值不是少写一个 cancel，而是把后台任务的停止时刻交还给测试框架。只要继续保留“Cleanup 等待完成”的习惯，测试资源的结束边界就会比手工拼装更清楚，也更不容易留下 goroutine。