testing.T.Context 管理测试子任务取消的实践示例

如果测试里启动了后台 goroutine，最容易遗漏的不是“怎么启动”，而是“测试结束时谁通知它退出”。Go 1.24 新增的 testing.T.Context() 返回一个绑定当前测试生命周期的上下文：测试完成后、注册的 Cleanup 函数执行前，它会被取消。

因此，测试子任务可以直接接收 t.Context()，在 ctx.Done() 上等待退出；再用 t.Cleanup 等待 worker 收尾。下面的例子只解决测试子任务取消和收尾，不把它扩展成通用并发框架。

t.Context 的取消时机是什么

t.Context() 返回的 context 会在当前测试完成、Cleanup 回调真正执行前被取消。这个顺序很关键：测试主体可以先返回，后台任务收到取消后执行最后的清理，而 Cleanup 还能负责等待这些任务退出。

它和 t.Deadline() 不是一回事。Deadline 告诉你测试进程的超时时间；Context 则提供了一个可以传入数据库调用、HTTP 请求或 worker 的取消信号。如果测试因为超时直接被测试进程终止，不能把 Context 当作强制杀死 goroutine 的机制。

把测试 context 传给子任务

先定义一个只在收到取消信号后退出的 worker。示例中用 sync.WaitGroup 记录子任务，使用原子计数保存已经收到取消的 worker 数量，避免把测试逻辑和具体业务对象耦合在一起。

package worker_test

import (
    "context"
    "sync"
    "sync/atomic"
    "testing"
)

func startWorker(ctx context.Context, wg *sync.WaitGroup, stopped *atomic.Int32) {
    wg.Add(1)
    go func() {
        defer wg.Done() // 无论哪条退出路径，都要归还 WaitGroup 计数

        for {
            select {
            case 

这里没有手动调用 cancel()。当测试主体结束时，测试框架会取消 ctx，两个 worker 从 ctx.Done() 分支退出，最后由 Cleanup 等待它们完成。

为什么 Cleanup 里还要 Wait

Context 只能发出取消信号，不能保证接收方已经退出。如果测试函数返回后立刻释放临时目录、关闭连接或修改共享状态，后台任务仍可能处于“收到取消但还没完成最后一步”的窗口。

把 wg.Wait() 放在 Cleanup 中，形成一个清晰的收尾顺序：

如果 worker 里调用的是数据库或 HTTP 客户端，也要把同一个 ctx 继续向下传递。只有任务链上的 API 真正支持 Context，取消信号才会继续生效；单纯在外层监听 Done，并不会中断一个不接受 context 的阻塞调用。

和手动 context.WithCancel 有什么区别

旧代码通常这样写：创建 context.WithCancel，测试末尾调用 cancel()，再等待 worker。它仍然适用于 Go 1.23 及更早版本，也适用于需要在测试中途主动取消、而不是等测试结束才取消的场景。

import (
    "context"
    "sync"
    "sync/atomic"
    "testing"
    "time"
)

func TestWorkersWithManualCancel(t *testing.T) {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel() // 即使断言提前失败，也要释放派生 context

    var wg sync.WaitGroup
    var stopped atomic.Int32
    startWorker(ctx, &wg, &stopped)

    cancel() // 这里可以在测试主体中途主动结束 worker
    done := make(chan struct{})
    go func() {
        defer close(done) // 通知测试等待 goroutine 已完成
        wg.Wait()
    }()

    select {
    case 

上面的兼容示例如果直接复制，还需要在 import 中加入 time。它和 t.Context() 的差别不在于谁更“强制”，而在于取消责任：前者由测试代码控制，后者把“测试结束时取消”交给 testing 框架。

使用时的四个边界

1. 需要 Go 1.24 或更高版本。 T.Context 是 Go 1.24 新增的方法；项目的 go.mod 或构建环境更低时，应继续使用 context.WithCancel。
2. 不要把它当成 goroutine 杀手。 goroutine 必须主动选择 ctx.Done()，并且长时间阻塞的调用要使用支持 context 的 API。
3. Cleanup 里只做可等待的收尾。 先让任务响应取消，再等待它们退出；不要在 Cleanup 里启动新的长期后台任务。
4. 测试中途取消仍需独立 cancel。 如果业务要求收到某个断言结果后立即终止子任务，t.Context() 不会替代一个局部的 WithCancel。

小结

使用 testing.T.Context() 管理测试子任务时，可以把它看成“测试生命周期提供的取消源”：测试主体负责启动并传递 Context，子任务负责监听 Done 并释放资源，Cleanup 负责等待最终退出。这样既减少了测试末尾手动 cancel 的样板，也保留了明确的 goroutine 收尾边界。

相关问题

t.Context 会在测试开始时就取消吗？

不会。它会在测试完成、Cleanup 回调执行前取消。测试主体运行期间，子任务可以正常使用该 Context。

Cleanup 能代替 WaitGroup 吗？

不能。Cleanup 只定义回调执行时机，不知道你的 goroutine 何时真正退出；需要用 WaitGroup、完成通道或其他明确的汇合信号等待任务收尾。

t.Context 能取消数据库查询吗？

只有查询 API 接收并使用 Context 时才可以，例如把它传入支持 context 的查询方法。否则只能通知你的 worker 停止继续发起工作，无法中断已经阻塞的调用。