testing/synctest 隔离时间驱动并发测试

时间驱动的并发测试最容易卡在两个地方：真实 time.Sleep 让测试变慢，后台 goroutine 又让断言依赖调度运气。Go 1.25 起，testing/synctest 已进入标准库，可以把测试放进隔离的 bubble，在其中使用虚拟时钟，并用 synctest.Wait() 等待 bubble 内的后台活动稳定下来。

先把并发测试放进 synctest.Test

Go 1.25 的 API 是 synctest.Test(t, func(t *testing.T){...})。它给回调提供一个新的测试对象，并把回调及其内部启动的 goroutine 放进同一个 bubble。代码里的时间仍然使用标准 time 包，不需要为生产代码额外注入 fake clock。

func TestBackgroundWork(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        done := false
        go func() {
            // 后台任务只修改 bubble 内的测试状态。
            done = true
        }()

        synctest.Wait()
        if !done {
            // Wait 返回后，内部 goroutine 已经达到稳定状态。
            t.Fatal("background work has not completed")
        }
    })
}

Wait 不是“睡一小段时间再试一次”，而是等待当前 bubble 中的 goroutine 都阻塞在 bubble 内部可判断的同步点。这样断言针对的是状态，而不是某次调度恰好给了多少毫秒。

用虚拟时间覆盖超时前后的两个边界

时间测试的关键不是把睡眠删掉，而是让测试明确检查边界。下面以 context.WithTimeout 为例：先推进到截止时间前，确认上下文仍未取消；再推进最后一个纳秒，确认错误变成 context.DeadlineExceeded。

func TestWithTimeout(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        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: %v", err)
        }

        time.Sleep(time.Nanosecond)
        synctest.Wait() // 推进到超时点，再观察取消结果。
        if err := ctx.Err(); err != context.DeadlineExceeded {
            t.Fatalf("after timeout: %v", err)
        }
    })
}

这里的 Sleep 是 bubble 的虚拟时间操作，测试不会实际等待五秒。每次推进后调用 Wait 很重要，它让计时器触发的取消动作有机会完成；只改变时间、不等待后台动作，断言仍可能读到旧状态。

用生命周期清理避免 bubble 残留

synctest.Test 返回前，bubble 内的 goroutine 应该全部退出。对有循环、定时器或通道等待的任务，要让测试持有取消入口，并在退出前关闭它。否则测试可能在最后阶段暴露死锁或残留，而不是给出真正的业务断言。

把外部 I/O 和版本迁移边界分开

文件、网络连接和外部进程不一定属于 bubble 的可控阻塞集合。官方建议测试网络代码时提供 fake network，例如使用 net.Pipe；不要把真实网络读操作放进同步判断。bubble 外启动的 goroutine 也不能被 Wait 代为管理。

还要留意版本差异：Go 1.24 的实验 API 使用 synctest.Run(func())，需要设置 GOEXPERIMENT=synctest；Go 1.25 的正式 API 改为带 *testing.T 的 Test。迁移旧测试时，应先确认 go.mod 和 CI 的 Go 版本，再替换调用方式，不要把实验版示例直接复制到新项目。

常见问题

synctest.Wait 会等待真实网络请求完成吗？

不会。外部 I/O 可能被 bubble 外的事件唤醒，不能作为 durable blocking 判断。应注入 fake 网络或把网络联调用普通测试策略单独覆盖。

为什么调用 Test 后测试仍然卡住？

优先检查 bubble 内是否有永不退出的 goroutine、未关闭的通道或缺少取消路径。Test 只有在 bubble 中的 goroutine 都退出后才返回。

Go 1.24 的 Run 能继续使用吗？

它属于实验版 API。新代码按 Go 1.25 的 synctest.Test 编写；维护旧项目时再按版本约束安排迁移。

实践中可以把 synctest 看成“隔离调度和时间”的测试工具，而不是通用的并发消毒器：先让测试自包含，再用 Wait 表达稳定点，用虚拟时间覆盖边界，最后为每个后台任务提供明确的退出路径。