Go 1.25 testing/synctest 正式可用后怎么测试并发

Go 1.25 把 testing/synctest 从 Go 1.24 的实验能力带到了标准库。它适合测试“函数已经返回，但后台 goroutine 还会继续做事”的并发代码：测试在一个隔离的 bubble 中运行，bubble 内的时间使用虚拟时钟，所有 goroutine 都稳定阻塞时，时间可以瞬间推进。

官方地址：https://go.dev/doc/go1.25

实战中可以把 synctest.Test 当作并发测试的边界，把 synctest.Wait 当作“等到当前状态稳定”的判断点。这样，取消回调、定时器和异步收尾都不需要依赖脆弱的真实睡眠。

先理解 synctest bubble 解决什么问题

普通并发测试最容易写成“启动 goroutine，睡几十毫秒，再检查结果”。这种写法同时受机器负载、调度顺序和计时器精度影响：睡得短了可能误报，睡得长了又拖慢整套测试。synctest 的核心模式，是把被测 goroutine 和时间函数放进一个受控的 bubble。

在 bubble 中，time.Sleep、time.After 和基于它们的超时逻辑使用虚拟时间。synctest.Wait() 会等待 bubble 中除当前 goroutine 外的 goroutine 都进入“durably blocked”状态，再让测试继续判断。这里的重点不是等待某个固定毫秒数，而是等待当前并发状态不再自行变化。

用 synctest.Test 隔离并发测试

synctest.Test 接收外层测试对象和一个测试函数，并在新的 bubble 中执行这个函数。下面的场景是取消上下文后触发 context.AfterFunc：取消之前回调不应该执行，取消之后则应该执行。

package synctest_test

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

func TestAfterFuncAfterCancel(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        // 使用 bubble 关联的上下文，让取消逻辑留在同一测试边界内。
        ctx, cancel := context.WithCancel(t.Context())
        defer cancel()

        called := false
        context.AfterFunc(ctx, func() {
            // 回调在独立 goroutine 中执行，不能在 cancel 后立即断言。
            called = true
        })

        // 先等到当前 bubble 稳定，确认取消前回调没有提前执行。
        synctest.Wait()
        if called {
            t.Fatal("取消前不应执行 AfterFunc")
        }

        // 取消会触发回调，随后再次等待它完成，再检查最终状态。
        cancel()
        synctest.Wait()
        if !called {
            t.Fatal("取消后应执行 AfterFunc")
        }
    })
}

这个例子体现了一个可复用的判断习惯：触发动作和状态断言之间，用 synctest.Wait() 划出稳定点。第一次 Wait 不是“让回调执行”，而是确认在当前条件下 bubble 已经没有可自行推进的工作；第二次 Wait 才是在取消之后等待异步回调收敛。

用 synctest.Wait 判断并发状态

Wait 只能在 bubble 内调用，也不能被同一个 bubble 中的多个 goroutine 并发调用。它更适合由测试 goroutine 串行地放在几个关键观察点上，而不是塞进被测业务 goroutine 里。

还要区分“稳定阻塞”和“正在运行”：如果后台 goroutine 仍在执行 CPU 工作，Wait 会等它进入可识别的阻塞状态；如果代码在等待网络 I/O，网络操作本身不会因为虚拟时钟而自动完成。因此，网络边界通常要换成 bubble 能理解的本地可控依赖，不能把真实外部服务当成时间推进器。

用虚拟时间覆盖超时边界

超时测试是 synctest 最有价值的场景之一。测试可以先把虚拟时间推进到截止点之前，再推进最后一小段，直接覆盖“尚未超时”和“已经超时”两个状态。

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

func TestTimeoutBoundary(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        // 这个定时器使用 bubble 的虚拟时钟，不需要真实等待 5 秒。
        const timeout = 5 * time.Second
        ctx, cancel := context.WithTimeout(t.Context(), timeout)
        defer cancel()

        // 只推进到截止点前，验证上下文仍然没有结束。
        time.Sleep(timeout - time.Nanosecond)
        synctest.Wait()
        if err := ctx.Err(); err != nil {
            t.Fatalf("截止点前 ctx.Err() = %v，想要 nil", err)
        }

        // 再推进最后一纳秒，验证超时原因已经可观察。
        time.Sleep(time.Nanosecond)
        synctest.Wait()
        if err := ctx.Err(); err != context.DeadlineExceeded {
            t.Fatalf("截止点后 ctx.Err() = %v，想要 DeadlineExceeded", err)
        }
    })
}

这个模式比真实睡眠更容易表达业务边界：测试关心的是 deadline 前后状态，而不是墙上时钟实际走了多久。

哪些调用不能直接放进 bubble

使用前记住四条边界：

• synctest.Wait 不能在 bubble 外调用，普通测试函数不能直接把它当作全局等待器。
• synctest.Test 不能在另一个 bubble 内嵌套调用；一个测试场景应明确自己的 bubble 所有权。
• 传给 synctest.Test 的内部测试对象不适合调用 T.Run、T.Parallel 和 T.Deadline，应把场景拆在 bubble 外组织。
• 网络 I/O、外部进程或没有稳定阻塞语义的资源，不会因为虚拟时间自动完成，必要时要在测试边界处替换为可控依赖。

synctest.Test 返回前会等待 bubble 内的 goroutine 退出；如果 goroutine 在 bubble 中形成死锁，测试会失败。这既是资源收口能力，也是排查测试设计错误的信号：不要用无限后台任务证明“测试结束了”，而要让每个 goroutine 都有明确的退出条件。

用一张清单判断是否适合 synctest

一句话概括：Go 1.25 的 testing/synctest 不是把并发变成串行，而是把“等待多久”改成“等待到什么状态”。先用 synctest.Test 划出隔离范围，再用 synctest.Wait 固定观察点，最后用虚拟时间覆盖边界，测试才会既快又容易解释。

常见问题

Go 1.24 的 synctest 代码能直接迁移到 Go 1.25 吗？

需要对照 Go 1.25 的正式 API 调整。Go 1.25 的 testing/synctest 已经正式可用，Go 1.24 实验阶段的旧 API 在开启实验开关时仍保留，但官方说明旧 API 会在 Go 1.26 移除，迁移时不应继续依赖实验开关。

为什么调用 Wait 后时间没有继续前进？

虚拟时钟会在 bubble 内的 goroutine 都稳定阻塞时推进。如果仍有 goroutine 在运行，或代码卡在不受 bubble 控制的外部 I/O 上，测试就不能把它当作已经稳定的时间边界。

synctest 能替代所有并发压力测试吗？

不能。它解决的是异步逻辑、取消、定时器和可重复状态判断；它不等同于真实机器上的调度压力、网络抖动或资源竞争测试。两类测试关注的问题不同。