testing.T.Context 传递到 HTTP 测试客户端的做法

我以前写 HTTP 客户端测试时，经常随手用 context.Background()。测试本身已经失败并准备退出，请求却可能仍在等待网络或服务端响应，最后只能再靠客户端超时兜底。Go 1.24 加入 testing.T.Context() 后，这个生命周期可以直接接到请求上。

最直接的做法是：用 http.NewRequestWithContext(t.Context(), ...) 创建出站请求，再交给 http.Client.Do。测试结束时，这个上下文会在已注册的 Cleanup 函数开始执行前被取消。

官方文档入口：https://pkg.go.dev/testing#T.Context、https://pkg.go.dev/net/http#NewRequestWithContext

为什么不再使用 context.Background

context.Background() 与当前测试没有生命周期关系。即使 t.Fatal 终止了测试 goroutine，已经发出的 HTTP 工作也不会因为这个背景上下文自动收到取消信号。t.Context() 的价值不是“让请求更快”，而是把请求归入测试边界：测试结束，依赖这个上下文的请求也应停止。

Go 官方对 T.Context 的定义很具体：它返回的上下文会在 Cleanup 函数执行前被取消。因此，如果 Cleanup 负责关闭测试服务器、释放连接或等待后台任务，相关任务可以先观察到 Done()，再进入资源清理。

把测试上下文传给 HTTP 客户端

下面的例子只保留关键链路。测试服务器故意模拟一个需要等待的处理器，客户端请求直接使用 t.Context()。正常返回时读取状态码；如果测试生命周期先结束，Client.Do 会沿请求上下文返回错误。

func TestHealth(t *testing.T) {
    srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 服务端同时观察请求取消，避免测试结束后继续等待。
        select {
        case 

这里的重点有两个。第一，传入的是当前 t 的上下文，而不是包级变量。第二，Context 取消不替代 resp.Body.Close()；只要 Do 成功返回了响应，响应体仍应由调用方关闭。

别把 httptest.NewRequestWithContext 用在客户端请求上

这是最容易混淆的一点。http.NewRequestWithContext 创建的是适合交给 Client.Do 或 Transport.RoundTrip 的出站请求。httptest.NewRequestWithContext 创建的是模拟进入服务器的请求，适合直接传给 http.Handler 测试。

func TestHandler(t *testing.T) {
    // 这是入站 Handler 测试，不会经过真实 HTTP 客户端。
    req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/health", nil)
    rec := httptest.NewRecorder()

    healthHandler(rec, req)

    // Recorder 保存 Handler 写出的状态，便于直接断言。
    if rec.Code != http.StatusNoContent {
        t.Fatalf("status = %d; want %d", rec.Code, http.StatusNoContent)
    }
}

如果你的目标是验证重定向、代理、TLS、连接复用或自定义 Transport，就使用真实客户端路径；如果只是验证 Handler 如何读取请求和写响应，才使用 httptest.NewRequestWithContext。

单次请求仍可以设置更短的超时

t.Context() 表示“测试还活着”，不等于“这次请求最多只能等 200 毫秒”。我更倾向于把它当父上下文，再针对单个调用派生更短期限。这样既保留测试结束时的取消，又让慢请求尽快暴露。

func getJSON(t *testing.T, client *http.Client, url string) (*http.Response, error) {
    t.Helper()

    // 单次请求的超时比整个测试生命周期更严格。
    ctx, cancel := context.WithTimeout(t.Context(), 200*time.Millisecond)
    defer cancel()

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return nil, err
    }

    // 返回值由调用方检查，并在成功时关闭 Body。
    return client.Do(req)
}

这里仍然需要调用 cancel()，因为派生上下文可能持有计时器。父上下文取消会传给子上下文，子上下文自己的超时也可以更早结束请求。

子测试和并行测试要使用自己的 t

表驱动测试里，每个 t.Run 都会收到自己的 *testing.T。请求应使用子测试参数的 t.Context()，不要在外层先缓存一个 Context 再让所有子测试共享。这样某个子测试结束时，它发起的工作不会继续拖到整个父测试结束。

for _, tc := range cases {
    tc := tc
    t.Run(tc.name, func(t *testing.T) {
        t.Parallel()

        // 使用当前子测试的上下文，保持取消边界独立。
        req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, tc.url, nil)
        if err != nil {
            t.Fatal(err)
        }

        resp, err := client.Do(req)
        if err != nil {
            t.Fatal(err)
        }
        defer resp.Body.Close()

        // 每个并行子测试只断言自己的结果。
        if resp.StatusCode != tc.wantStatus {
            t.Fatalf("status = %d; want %d", resp.StatusCode, tc.wantStatus)
        }
    })
}

并行测试还要避免共享可变请求对象。http.Request 携带 Context 和 Body 等状态，最稳妥的做法是在每个子测试中重新创建请求。

常见问题

Go 1.23 项目能调用 testing.T.Context 吗

不能。该方法从 Go 1.24 开始提供。旧版本可以显式创建 context.WithCancel，并用 t.Cleanup(cancel) 管理，但其取消时序与新方法的内建语义并不完全相同。

有了 t.Context 还需要设置 http.Client.Timeout 吗

两者用途不同。t.Context() 绑定测试生命周期，Client.Timeout 或派生的 context.WithTimeout 限制一次请求最多等待多久。测试套件通常仍应保留明确的请求超时。

测试取消后一定返回 context.Canceled 吗

不要只按字符串断言错误。HTTP 客户端可能把底层错误包装成 *url.Error；需要判断取消原因时，优先使用 errors.Is(err, context.Canceled) 或检查你设置的 deadline。

什么时候应该使用 httptest.NewRequestWithContext

当你直接调用 Handler、模拟入站请求时使用它；当请求要交给 http.Client.Do 时，使用 http.NewRequestWithContext。

结论

对 Go 1.24 及以上的 HTTP 客户端测试，默认把 t.Context() 传入 http.NewRequestWithContext 是更清晰的选择。需要更快失败时再派生短超时；进入子测试后改用子测试自己的 Context；只要成功得到响应，继续关闭 resp.Body。这几条把请求、断言和清理都放回同一个测试生命周期里。

参考：https://go.dev/doc/go1.24、https://pkg.go.dev/testing、https://pkg.go.dev/net/http、https://pkg.go.dev/net/http/httptest