Go testing/synctest 怎样测试带定时器的 HTTP handler

带定时器的 HTTP handler，最稳的测试方式是把 handler、timer、goroutine 和断言都放进同一个 synctest.Test 气泡，再用虚拟时钟推进等待时间。不要先启动真实网络服务再靠固定的现实时间睡眠；那会把“定时器是否触发”和“网络 I/O 是否结束”混成一个不稳定问题。

把 handler 和定时器放进同一个测试气泡

先把例子缩小成一个“延迟响应”handler：请求进入后创建定时器，定时器触发才写响应。测试不启动端口，而是在气泡里创建 request、recorder 和 goroutine。这样 timer 使用气泡自己的虚拟时钟，测试不会真的等待 5 秒。

func delayedHandler(delay time.Duration) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        timer := time.NewTimer(delay)
        defer timer.Stop() // 无论请求如何结束，都释放未触发的定时器

        

测试的关键不是“睡眠后立刻读 recorder”，而是先让并发状态收敛。第一次 synctest.Wait 只确认 handler 仍在等待 timer；第二个时间边界推进完成后，再等待 goroutine 写完响应。

func TestDelayedHandler(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        const delay = 5 * time.Second
        handler := delayedHandler(delay)
        req := httptest.NewRequest(http.MethodGet, "/ready", nil)
        rec := httptest.NewRecorder()
        done := make(chan struct{})

        go func() {
            defer close(done) // 让测试能确认 ServeHTTP 已返回
            handler.ServeHTTP(rec, req)
        }()

        time.Sleep(delay - time.Second) // 推进到触发前，时间是虚拟的
        synctest.Wait()                  // 等待 timer 之前的状态稳定
        if got := rec.Body.String(); got != "" {
            t.Fatalf("before timer: body = %q", got)
        }

        time.Sleep(time.Second) // 推进剩余 1 秒，让 timer 到期
        synctest.Wait()         // 等 handler 写完 recorder
        if got := rec.Body.String(); got != "ready" {
            t.Fatalf("after timer: body = %q, want ready", got)
        }
        if rec.Code != http.StatusOK {
            t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
        }
        if got := rec.Header().Get("Content-Type"); got == "" {
            t.Fatal("Content-Type header is empty")
        }

        synctest.Wait() // 观察 done，确保后台 goroutine 已退出
        select {
        case 

这里的 time.Sleep 不是现实中的阻塞。气泡内的时间只有在 goroutine 都进入可持久阻塞状态时才会向前推进，因此一次测试可以立即跨过 4 秒和 1 秒两个边界。Wait 也不是“多等一会儿”，而是把断言放在同一气泡的稳定点上。

为什么要直接调用 ServeHTTP

httptest.NewRecorder 适合验证 handler 的状态码、响应头和响应体；它没有真实 socket，正好把问题限定在 timer 与 handler 协作上。反过来，httptest.NewServer 会加入网络读写，网络 I/O 不属于 synctest 能可靠判断的 durable blocked 状态，测试可能无法按预期收敛。

如果必须验证客户端、传输层或连接复用，再把网络问题拆成独立测试：可以使用 fake network，让连接行为可控；不要在一个既要验证 timer 又要验证真实端口的测试里同时追两类时序。

三种测试入口怎么选

判断标准很简单：如果断言对象是“5 秒后 handler 写了什么”，选择直接调用；如果断言对象是“客户端如何经过 HTTP 传输拿到结果”，再单独覆盖 server 或 fake network。测试越早把边界切开，越不需要靠重试掩盖时序问题。

定时器测试的三个排查点

• goroutine 是否在气泡内创建：气泡外启动的后台 goroutine 不会自动纳入等待范围，测试也不应依赖它。
• 时间推进后是否调用 Wait：Sleep 只推进时钟，Wait 才把 handler 的写入完成变成可断言状态。
• 是否混入真实 I/O：锁、socket 和系统调用的阻塞语义不同；把网络验证与虚拟时间验证拆开。

常见问题

为什么不是直接在测试里 Sleep 5 秒？

因为气泡中的 time 使用虚拟时钟，测试可以立即推进 5 秒；现实 Sleep 会拖慢测试，还无法保证 goroutine 已完成写响应。

synctest.Wait 能等待网络请求返回吗？

不能把它当作通用网络等待器。网络 I/O 可能由气泡外事件解除，优先使用无网络 handler 测试或 fake network。

为什么还要关闭 timer？

handler 可能在 timer 触发前因取消、错误或上游结束而返回，defer timer.Stop() 明确了未触发 timer 的清理边界。

Go 1.24 的写法能直接照搬吗？

不能完全照搬。Go 1.24 是实验 API，Go 1.25 的正式 API 使用 synctest.Test，并把测试用的 *testing.T 传入气泡。

把 timer、handler 和 goroutine 放在同一气泡，用时间边界配合 Wait 做断言，通常就能把“偶尔超时”的 HTTP 测试改成确定性的单元测试；真正的传输层问题则留给单独的网络测试。