Go testing/synctest.Wait 怎样等待虚拟并发环境稳定

我第一次把并发测试从“睡几毫秒再断言”改成 testing/synctest 时，最明显的变化不是代码更短，而是等待条件终于能写清楚：synctest.Wait() 等待当前虚拟测试环境中其它 goroutine 进入 durably blocked 状态。它不是无条件等待网络响应，也不是把一个可能死锁的测试强行推进到下一步。

官方文档：https://pkg.go.dev/testing/synctest

先把“稳定”理解成 bubble 内的可控停顿

synctest.Test 会创建一个隔离的 bubble，测试回调中启动的 goroutine 也属于这个 bubble。这里的“稳定”不是线程调度恰好停了一下，而是某个 goroutine 已经阻塞，并且只能由同一个 bubble 中的事件唤醒。这样，测试可以在一个确定的停顿点读取共享状态。

这也是 Wait 和普通 time.Sleep 的关键区别：前者表达“其它 goroutine 已经没有可继续推进的内部工作”，后者只表达“当前 goroutine 暂停了一段时间”。我现在写这类测试时，先画出 bubble 边界，再决定断言前的等待点；如果等待对象在边界外，单纯加 Wait 并不会让它变得可控。

最小用法：让 goroutine 先完成，再读取状态

最小场景不需要人为猜一个等待时长。工作 goroutine 只要在 bubble 内结束，Wait 就会等到它不再有可执行工作，然后再执行断言：

package synctestdemo

import (
    "testing"
    "testing/synctest"
)

func TestWaitForState(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        ready := false

        go func() {
            // 工作 goroutine 只在当前 bubble 内更新测试状态。
            ready = true
        }()

        synctest.Wait()
        if !ready {
            // Wait 返回后仍未完成，说明测试条件或协程边界写错了。
            t.Fatal("worker has not reached the stable state")
        }
    })
}

这里的要点不是把 Wait 当作万能屏障，而是把并发工作放进同一 bubble。若工作 goroutine 依赖一个 bubble 外部才能触发的事件，它就不满足 durably blocked 的定义，测试也不能靠 Wait 获得同样的确定性。

取消 context 后，再用 Wait 等待回调收敛

我在测试取消逻辑时，通常会把“取消前不应执行”和“取消后应执行”拆成两个等待点。官方示例使用 context.AfterFunc 表达这一点：注册回调后先等待一次，确认它没有被提前调用；执行取消后再等待一次，确认回调已经完成。

func TestCancelCallback(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        // 使用 bubble 提供的 context，让取消信号留在测试边界内。
        ctx, cancel := context.WithCancel(t.Context())
        defer cancel()

        called := false
        context.AfterFunc(ctx, func() {
            // 回调运行在取消信号触发后的 goroutine 中。
            called = true
        })

        synctest.Wait()
        if called {
            t.Fatal("callback ran before cancellation")
        }

        cancel()
        synctest.Wait()
        if !called {
            // 第二次 Wait 用来等回调完成，而不是延长固定睡眠时间。
            t.Fatal("callback did not run after cancellation")
        }
    })
}

示例中的 defer cancel() 负责清理 context；真正让断言可预测的是取消动作和第二次 Wait 之间的因果关系。这个模式适合验证回调、取消传播和内部 channel 通知，但不适合把外部网络响应伪装成 bubble 内事件。

Wait 不推进时间：超时测试要分开写时间动作

synctest bubble 内的 time 使用虚拟时钟，只有当 bubble 中的 goroutine 都处于可稳定阻塞状态时，时间才会向下一个能够唤醒 goroutine 的时间点推进。Wait 只负责等待其它 goroutine 稳定阻塞；它本身不是“快进五秒”的命令。

因此，测试超时边界时，要先用 time.Sleep 把虚拟时钟移动到边界，再用 Wait 等待相关回调稳定：

func TestTimeoutBoundary(t *testing.T) {
    synctest.Test(t, func(t *testing.T) {
        const timeout = 5 * time.Second

        // 让 context 在 bubble 的虚拟时钟中拥有明确的超时时间。
        ctx, cancel := context.WithTimeout(t.Context(), 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 {
            // 时间跨过边界后，再判断 DeadlineExceeded。
            t.Fatalf("after timeout: %v", err)
        }
    })
}

这个写法把两个责任分开：Sleep 推动虚拟时间，Wait 等待其它 goroutine 处理完当前内部工作。若把两者混成“随便等一下”，测试就很难说明自己究竟验证了时间边界，还是仅仅碰巧赶上了调度。

哪些阻塞算稳定，哪些情况不能交给 Wait

下面这张边界图是我写测试前最常看的部分。它不是 API 调用顺序，而是判断一个 goroutine 是否属于 Wait 能观察的稳定集合：

还有三个容易忽略的边界：第一，Wait 不能在 bubble 外调用；第二，同一个 bubble 不要让多个 goroutine 并发调用 Wait；第三，如果内部 goroutine 彼此等待且没有任何未来事件能解除阻塞，synctest.Test 会把它识别为死锁并使测试失败。遇到这种情况，应该修正测试拓扑或补齐触发条件，而不是继续增加等待次数。

我的判断清单：先画边界，再放 Wait

现在我会用下面四个问题判断一个 Wait 是否放对了位置：

• 被等待的 goroutine 是否由当前 synctest.Test 启动，并且所有依赖都在同一 bubble 内？
• 它的阻塞是否只能被 bubble 内事件解除，而不是依赖网络、文件、系统调用或外部 goroutine？
• 当前断言是在“工作已稳定”之后读取状态，还是误把 Wait 当成时间推进器？
• 如果 Wait 一直不返回，是否存在循环等待、没有发送者的 channel 或根 goroutine提前退出？

满足这些条件时，synctest.Wait 能把并发测试从“猜一个足够长的 sleep”变成“等待一个明确的内部稳定状态”。它的价值不在于替你解决所有异步问题，而在于把可控并发、虚拟时间和测试断言放进同一个可解释的边界里。

常见问题

Wait 能不能等待网络请求返回？

不能把网络 I/O 当作 durably blocked。synctest 文档把网络 I/O 和系统调用列为可能受 bubble 外事件唤醒的阻塞；测试应使用 fake 网络或把外部依赖隔离开。

Wait 和 time.Sleep 是替代关系吗？

不是。Wait 等待其它 goroutine 稳定阻塞，Sleep 负责在 bubble 的虚拟时钟中等待时间推进；超时测试经常需要先 Sleep，再 Wait。

为什么 Wait 不返回反而测试失败？

通常是 bubble 内出现死锁、没有内部事件可以解除阻塞，或测试把外部依赖放进了需要稳定收敛的路径。先检查 goroutine、channel 和 WaitGroup 的拓扑，再决定是否需要 fake 依赖。