Go httptest.NewRequestWithContext 怎样测试请求上下文取消

如果一个 HTTP handler 只有在请求被取消后才会停止数据库查询、退出循环或返回特殊响应，直接依赖真实网络超时会让测试变慢，而且很难稳定复现。更合适的做法是先用 context.WithCancel 或 context.WithTimeout 准备测试上下文，再把它交给 httptest.NewRequestWithContext 构造服务端请求。

测试 handler 的取消分支时，关键不是启动真实服务器，而是保证取消发生在调用 handler 之前，并在 handler 内通过 r.Context().Done() 或 r.Context().Err() 观察结果。

先把测试边界分清楚

httptest.NewRequestWithContext 返回的是适合传给 http.Handler 测试的服务端请求。官方文档说明它接收 context、方法、目标地址和请求体；空方法按 GET 处理，目标地址可以是路径或绝对 URL，构造失败时会 panic，这些行为适合测试代码快速准备请求。

本文只测试“handler 收到的请求上下文已经取消”这一条边界，不测试客户端如何因为网络、连接或真实截止时间而停止请求。也就是说，测试对象是 handler 的判断逻辑，而不是传输层。

用 WithCancel 稳定构造已取消请求

最容易复现的分支是 context.Canceled。先创建可取消上下文，调用取消函数，再把这个已经结束的上下文传给 NewRequestWithContext。handler 一开始检查时就能看到取消状态。

package canceltest

import (
    "context"
    "net/http"
    "net/http/httptest"
    "testing"
)

func cancelAwareHandler(w http.ResponseWriter, r *http.Request) {
    // 先读取错误原因，便于区分主动取消和截止时间到期。
    if err := r.Context().Err(); err != nil {
        http.Error(w, err.Error(), http.StatusRequestTimeout)
        return
    }

    // 没有取消信号时才进入正常处理分支。
    w.WriteHeader(http.StatusOK)
}

func TestHandlerSeesCanceledContext(t *testing.T) {
    ctx, cancel := context.WithCancel(context.Background())
    cancel() // 在构造请求前结束上下文，稳定复现取消分支。

    req := httptest.NewRequestWithContext(ctx, http.MethodGet, "/jobs/42", nil)
    rec := httptest.NewRecorder()

    cancelAwareHandler(rec, req)

    // Recorder 只观察 handler 生成的响应，不需要启动真实 HTTP 服务。
    if rec.Code != http.StatusRequestTimeout {
        t.Fatalf("unexpected status: %d", rec.Code)
    }
}

这个测试的重点是取消时机：如果先调用 handler、再调用 cancel，handler 可能已经走过正常分支，测试就不能证明取消路径有效。NewRequestWithContext 负责把 context 放入请求，NewRecorder 负责记录 handler 对 ResponseWriter 的写入。

用 Err 区分 Canceled 和 DeadlineExceeded

取消不是只有一种原因。主动调用取消函数通常得到 context.Canceled；截止时间或超时到达后，通常得到 context.DeadlineExceeded。如果业务动作需要区分重试、日志级别或响应内容，就应该分别构造这两类输入，而不是只断言“Done channel 被关闭”。

func TestHandlerDistinguishesCancelReasons(t *testing.T) {
    tests := []struct {
        name string
        makeContext func() (context.Context, func())
        want error
    }{
        {
            name: "主动取消",
            makeContext: func() (context.Context, func()) {
                ctx, cancel := context.WithCancel(context.Background())
                cancel() // 立即结束，期待 context.Canceled。
                return ctx, func() {}
            },
            want: context.Canceled,
        },
        {
            name: "截止时间",
            makeContext: func() (context.Context, func()) {
                ctx, cancel := context.WithTimeout(context.Background(), 0)
                return ctx, cancel // 零时长让截止时间分支可控地结束。
            },
            want: context.DeadlineExceeded,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            ctx, cleanup := tt.makeContext()
            defer cleanup() // 即使上下文已结束，也保持测试资源成对释放。

            req := httptest.NewRequestWithContext(ctx, http.MethodGet, "/work", nil)
            got := req.Context().Err()
            if got != tt.want {
                t.Fatalf("context error = %v, want %v", got, tt.want)
            }
        })
    }
}

这里的断言直接针对 req.Context().Err()，目的是验证构造出来的请求确实携带了预期状态。若测试的是 handler 的业务响应，则应把请求交给 handler，再用 recorder 检查状态码、响应体或错误提示；不要把上下文错误和 HTTP 状态码混为同一个断言。

Done 适合控制流程，Err 适合判断原因

Done() 返回的 channel 适合放进工作循环或 select，它回答的是“是否已经结束”；Err() 适合在分支处判断结束原因，它回答的是“为什么结束”。handler 如果要停止一个阻塞中的工作，应监听 Done()；如果已经回到可执行代码并需要决定响应，则读取 Err()。

func processUntilCanceled(ctx context.Context, step func() error) error {
    for {
        select {
        case 

实际 handler 中还要注意竞态：如果取消和业务完成几乎同时发生，代码必须明确哪一个结果优先。测试可以分别覆盖“进入 handler 前已取消”和“处理过程中收到取消”，但不要把单次测试结果扩大成对所有并发时序的保证。

几个容易让测试失真的检查点

• 取消发生得太晚：先调用 handler 再取消，不能稳定覆盖入口取消分支。
• 只检查 Done：Done 关闭无法区分主动取消和截止时间到期；需要原因时读取 Err。
• 把请求上下文当客户端超时：本文构造的是服务端测试请求，不会替代真实客户端和网络链路测试。
• 忽略清理函数：即便测试上下文已结束，也保留 defer cancel() 或成对清理的习惯，后续改成非零超时后不容易泄漏。
• 把 recorder 当成完整服务器：它只记录 handler 对响应写入器的操作，不会模拟代理、连接复用或真实传输。

最后用一张清单确认测试方向

1. 测试目标是 handler 的取消分支，而不是客户端网络超时。
2. 使用 WithCancel 或 WithTimeout 生成明确的 context。
3. 在调用 NewRequestWithContext 前确定取消时机。
4. 用 Err() 区分 context.Canceled 与 context.DeadlineExceeded。
5. 用 httptest.NewRecorder 观察响应，并把上下文原因与 HTTP 响应断言分开。

这样写出来的测试短、稳定，而且每个失败都能回答一个具体问题：请求是否带入了正确的 context，handler 是否看到了取消，以及它是否返回了约定的响应。等到需要验证真实客户端断开、代理超时或连接行为时，再另写端到端测试，不要让 NewRequestWithContext 的单元测试承担超出边界的职责。

相关问题

NewRequestWithContext 和 NewRequest 有什么区别？NewRequest 使用后台上下文；需要测试取消或截止时间时，应显式传入自己的 context。

一定要启动 httptest.Server 吗？只测试 handler 时不需要。直接构造请求并使用 ResponseRecorder 就能覆盖上下文判断；只有需要验证客户端、路由或真实传输时才考虑测试服务器。

为什么不直接比较响应体？响应体是业务协议的一部分，上下文错误是控制信号。分别断言能让失败信息更准确，也避免某个文案调整掩盖取消逻辑问题。