Go synctest.Test 怎样让并发测试在虚拟时钟下收敛

并发测试最容易陷入两个取舍：为了确认事件“还没有发生”而等待真实时间，测试就会变慢；等待时间太短，又会在繁忙的 CI 机器上偶发失败。Go 1.25 的 testing/synctest 把并发测试放进隔离的 bubble，并在 bubble 内使用虚拟时钟。核心写法是用 synctest.Test 包住测试，用 synctest.Wait 对齐 goroutine 状态。

把“等 5 秒让定时器自然触发”改成“推进 bubble 的虚拟时间，再等待所有 goroutine 稳定阻塞”，测试就能同时保持快速和可重复；但外部网络和未清理的后台 goroutine 仍然需要单独处理。

从真实等待切换到 synctest.Test

synctest.Test(t, fn) 会在独立的测试 bubble 中运行 fn，从 bubble 内启动的 goroutine 也属于这个边界。bubble 有自己的时钟，初始时间是 2000 年 1 月 1 日 UTC；测试不需要为了覆盖定时器而真的消耗墙上时间。

旧式测试通常用 time.After 加一个经验等待窗口。窗口既不能证明未来不会发生事件，也会把 CI 的调度抖动带进测试。迁移时先保留业务代码，只改变测试的外层执行环境：

package cache_test

import (
    "context"
    "testing"
    "testing/synctest"
    "time"
)

func TestRefreshDeadline(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        // 用独立上下文承载取消信号，避免测试依赖外部 goroutine。
        ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()

        done := make(chan struct{})
        go func() {
            // 后台任务只在上下文结束后退出，便于 Test 收拢 bubble。
            

用 synctest.Wait 对齐并发状态

Wait 不是“再睡一小段时间”，而是等待当前 bubble 中的 goroutine 都进入可判定的阻塞状态。这样，断言读取的就是一个已经收敛的状态，而不是碰运气地抢在后台 goroutine 之前或之后执行。

实际使用时，把它放在“改变条件之后”和“读取结果之前”：取消 context 后调用一次，推进定时器后调用一次，启动后台任务后如果要判断它的初始状态也调用一次。不要把 Wait 当作外部网络请求的完成通知；网络 I/O 可能被 bubble 外的事件唤醒，不属于同样的确定性阻塞。

用虚拟时间覆盖定时器边界

bubble 中的 time.Sleep、time.After、time.NewTimer 和基于它们的 context 超时都使用该 bubble 的虚拟时钟。时钟只会在 bubble 内 goroutine 都处于“持久阻塞”时向前推进，所以测试要在时间操作后配合 synctest.Wait。

边界测试建议拆成“差一点”和“刚好到期”两次判断。例如超时是 5 秒，可以先推进到 5*time.Second-time.Nanosecond，确认 context 仍未结束，再推进最后 1 纳秒并等待。这个写法表达的是业务边界，不依赖操作系统调度速度。

func TestTimeoutBoundary(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        // 用一个可控的 deadline 观察到期前后的两个状态。
        const timeout = 5 * time.Second
        ctx, cancel := context.WithTimeout(context.Background(), timeout)
        defer cancel()

        time.Sleep(timeout - time.Nanosecond)
        synctest.Wait()
        if err := ctx.Err(); err != nil {
            t.Fatalf("before timeout: got %v", err)
        }

        // 只推进剩余的 1 纳秒，避免用模糊的等待窗口表达边界。
        time.Sleep(time.Nanosecond)
        synctest.Wait()
        if err := ctx.Err(); err != context.DeadlineExceeded {
            t.Fatalf("after timeout: got %v", err)
        }
    })
}

让后台 goroutine 在 Test 返回前退出

synctest.Test 返回前，bubble 中的 goroutine 必须已经退出。一个常见误区是：主断言通过了，就认为测试结束；但后台 goroutine 可能仍在等待 channel、timer 或 context。如果它永远没有退出，bubble 会因死锁或泄漏而失败。

因此，后台任务需要清晰的结束信号：用 context 取消、关闭输入 channel、停止 timer，并在测试尾部用 Wait 或明确的 done channel 等到它退出。只把 goroutine 丢到后台、不保存停止入口的写法，不适合放进 synctest bubble。

同步原语也要放在正确边界内。bubble 内创建的 channel 可以用于 bubble 内 goroutine 之间通信；不要让测试依赖一个由 bubble 外部 goroutine 写入的 channel，否则“什么时候会被唤醒”就不再由测试自己控制。

处理 HTTP 测试的网络边界

如果目标只是验证 handler 的定时器和响应状态，优先直接调用 handler，配合 httptest.NewRequest 和 httptest.NewRecorder。这样不需要真实监听端口，测试重点仍然是 handler 内的并发状态：

func delayedHandler(w http.ResponseWriter, r *http.Request) {
    // timer 只模拟 handler 的延迟逻辑，结束后立刻释放资源。
    timer := time.NewTimer(2 * time.Second)
    defer timer.Stop()
    

若一定要验证客户端和服务端之间的读写协作，httptest.NewTestServer 会引入 loopback 网络，而网络读写不一定被 synctest 判定为 bubble 内的持久阻塞。此时应考虑把传输层替换为 net.Pipe 这样的内存连接，或把网络边界移到 synctest 之外，只在 bubble 内测试可控的 handler 和协议状态。

迁移时的取舍

从 Go 1.24 的实验 API 迁移到 Go 1.25 时，重点是把旧的 synctest.Run 外壳改为 synctest.Test(t, func(t *testing.T) { ... })，并继续使用 synctest.Wait。同时检查老测试里是否遗留了真实等待、未停止的 timer 或没有退出路径的 goroutine。

常见问题

synctest.Test 会把真实网络也变成虚拟网络吗？

不会。虚拟时钟和 bubble 只解决测试边界内的时间与并发调度；网络 I/O 可能受 bubble 外的事件影响，需要 fake network 或拆分测试边界。

为什么 time.Sleep 后还要调用 synctest.Wait？

Sleep 负责推进可观察的时间点，Wait 负责等待 timer、context 或后台 goroutine 把结果处理完。两者解决的是不同问题。

后台 goroutine 已经不影响断言，还需要清理吗？

需要。Test 返回前 bubble 内 goroutine 应该退出，否则测试可能因为无法收拢而失败，也会把资源泄漏隐藏到下一次测试。