Go 1.25 testing/synctest 如何让并发测试不再依赖真实等待

如果并发测试里到处写 time.Sleep(100 * time.Millisecond)，通常是在用真实时间掩盖“后台 goroutine 什么时候稳定”的问题。Go 1.25 的 testing/synctest 把测试函数放进隔离的 bubble，提供虚拟时钟，并用 synctest.Wait 等待 bubble 内的 goroutine 进入稳定阻塞状态，因此测试可以围绕状态判断，而不是围绕一段拍脑袋的等待时长。

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

这套方法最适合定时器、context 超时、异步回调这类由 Go 时间包和 goroutine 驱动的代码；如果测试依赖真实网络、外部进程或不受 bubble 管理的阻塞资源，仍要先拆出边界，不能只把原来的 Sleep 替换成 Wait。

• 版本前提：Go 1.25 起正式使用 testing/synctest，不再需要 Go 1.24 的实验开关。
• 稳定判断：用 synctest.Wait 等待其他 goroutine 持久阻塞，再读取共享状态或上下文结果。
• 时间推进：在 bubble 内，time.Sleep 推进虚拟时钟，不必真的等待对应的墙上时间。
• 边界意识：网络 I/O、外部进程和 bubble 外的调用可能让测试无法稳定收敛，应改成可控替身。

先确认 Go 1.25 的使用边界

我第一次把这类测试从真实等待改掉时，最容易忽略的是版本差异。Go 1.24 的 testing/synctest 还是实验能力，需要设置 GOEXPERIMENT=synctest；Go 1.25 已经把它作为标准库能力正式提供。文章对应的导入路径是 testing/synctest，旧项目如果仍依赖实验 API，升级时要按当前文档调整。

# 确认工具链版本；只有 Go 1.25 及以上才按正式 API 编写
go version

# 在模块根目录查看 go 行，避免 CI 与本地工具链不一致
grep '^go ' go.mod

# 运行测试包；这里的命令由读者在自己的项目中执行
go test ./...

判断信号很简单：如果当前工具链低于 1.25，先不要把 testing/synctest 当作稳定依赖；如果已经是 Go 1.25，测试文件可以直接导入该包。Go 官方文档还说明，synctest.Test 会等待 bubble 内启动的 goroutine 退出，若 bubble 死锁，测试会失败。

把真实等待改成 bubble 内的稳定点

并发测试真正想知道的，通常不是“100 毫秒过去了吗”，而是“回调 goroutine 是否已经完成”。synctest.Test 建立隔离 bubble，测试逻辑、后台 goroutine 和时间包的虚拟时钟都在这个边界里；synctest.Wait 则让当前测试等到其他 goroutine 都进入持久阻塞，再检查状态。

package synctest_test

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

func TestAfterFuncRunsAfterCancel(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() {
			// 回调只修改测试状态，便于在稳定点后做断言。
			called = true
		})

		// 先等待当前 bubble 稳定，确认尚未取消时回调没有运行。
		synctest.Wait()
		if called {
			t.Fatal("回调在取消前执行")
		}

		// 取消上下文后再次等待，避免用真实 Sleep 猜回调的完成时机。
		cancel()
		synctest.Wait()
		if !called {
			t.Fatal("回调在取消后仍未执行")
		}
	})
}

这个例子里的两个 Wait 都有明确判断意义：第一个固定“取消前”的稳定状态，第二个固定“取消后”的稳定状态。和固定睡眠相比，测试不需要为慢机器预留更长时间，也不会因为某次调度恰好晚于 100 毫秒而偶发失败。

用虚拟时钟覆盖定时器与 context 超时

定时器场景是 synctest 最容易体现价值的地方。bubble 内的 time 包函数使用虚拟时钟；当 goroutine 都处于可判断的阻塞状态时，时间可以直接推进。测试可以把“超时前”和“超时后”拆成两个清晰的状态，而不是让 CI 真等几秒。

package synctest_test

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

func TestTimeoutWithoutWallClockWait(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		// 用短小的虚拟时间窗口表达业务超时，不让测试真的等待。
		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("超时前上下文错误：%v", err)
		}

		// 再推进最后一个纳秒，验证边界是否变成 DeadlineExceeded。
		time.Sleep(time.Nanosecond)
		synctest.Wait()
		if err := ctx.Err(); err != context.DeadlineExceeded {
			t.Fatalf("超时后错误：%v", err)
		}
	})
}

这里的关键不是把 5 秒改成 5 纳秒，而是让测试的时间跨度与断言边界分离：time.Sleep 推进的是 bubble 的虚拟时间，synctest.Wait 负责让由计时器触发的 goroutine 先稳定下来。这样可以精确覆盖“尚未超时”和“已经超时”两种条件。

遇到失败时先看阻塞资源，再决定回退

把所有并发测试都包进 synctest.Test 并不自动成功。官方 API 规定，Wait 必须在 bubble 内调用，且同一个 bubble 中不能由多个 goroutine 并发调用；Test 回调也不应调用 T.Run、T.Parallel 或 T.Deadline。这些约束不只是写法偏好，而是为了让 bubble 的调度和稳定判断有清晰边界。

如果测试卡在网络读写、外部进程、真实文件系统事件或其他不受 bubble 控制的资源上，不要继续加 Wait。先把依赖替换为内存实现、可控的 net.Pipe 或明确的测试桩；如果业务本来就要验证真实网络，再把这部分放到独立的集成测试中。Go 官方示例也展示了用可控连接替代 loopback 网络的思路，以免网络阻塞阻止 bubble 进入空闲状态。

上线前的运行与复盘清单

我会把这类改造的收尾分成三件事：第一，确保断言检查的是业务状态，而不是某个等待时长；第二，明确哪些 goroutine 应在 synctest.Test 返回前退出；第三，把不能虚拟化的网络、进程和系统资源记录为集成测试边界。这样即使 CI 的机器负载变化，单元测试也不会靠“多睡一会儿”维持稳定。

testing/synctest 能替代所有 time.Sleep 吗？不能。它解决的是 bubble 内可控并发和时间语义；真实外部资源仍需要隔离、桩或独立集成测试。

为什么 Wait 后还要检查状态？Wait 只帮助测试到达其他 goroutine 持久阻塞的稳定点，不替代业务断言。最终结果仍要由共享变量、channel 或 context 错误明确判断。

Go 1.24 项目能直接复制 Go 1.25 示例吗？不能直接假设。Go 1.24 的能力处于实验阶段，Go 1.25 才正式可用，应先核对工具链和现有实验开关，再安排迁移。

把真实等待改成 bubble、稳定点和虚拟时间后，并发测试的重点就从“这次有没有等够”回到了“状态是否满足预期”。这也是 testing/synctest 适合解决的问题边界。