testing/synctest 替代真实睡眠的测试迁移清单

Go 测试如果靠 time.Sleep 等后台 goroutine 完成，迁移重点是把“等现实时间”改成“等待 bubble 内活动达到可观察状态”。testing/synctest 提供虚拟时钟和 synctest.Wait，适合把慢、抖动的异步测试改成快速且可重复的测试。Go 1.25 起它进入标准库；Go 1.24 的实验版 API 不能直接照搬。

一、先盘点真实睡眠和异步完成点

把等待分成三类：定时器或超时回调，后台 goroutine 写入结果，真实 socket 或文件描述符。前两类适合迁移；第三类依赖 bubble 外的调度。

二、用 synctest.Test 包住真正需要的测试

Go 1.25 及以后使用 synctest.Test(t, func(t *testing.T) { ... })。回调里的 goroutine 和标准 time 包会受 bubble 时钟影响；不要把整个测试套件盲目包进去，synctest.Test 不能嵌套，回调中也不要调用 t.Parallel。

func TestRefresh(t *testing.T) {
	// Sleep 推进 bubble 虚拟时间，不等待真实时钟。
	synctest.Test(t, func(t *testing.T) {
		ready := make(chan struct{})
		go func() { time.Sleep(200 * time.Millisecond); close(ready) }()
		synctest.Wait() // 等待 bubble 内活动稳定
		select { case 

三、用虚拟时间和 Wait 替换固定等待

synctest.Wait 等待其他 goroutine 进入 durable blocked，并不等于任意业务任务都完成。测试 deadline 时可以这样写：

func TestDeadline(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		// 使用 bubble 当前时间，避免依赖真实时钟。
		deadline := time.Now().Add(time.Second)
		ctx, cancel := context.WithDeadline(t.Context(), deadline)
		defer cancel() // 失败时也释放 context 资源
		time.Sleep(time.Until(deadline))
		synctest.Wait() // 等待取消传播到 bubble 内 goroutine
		if ctx.Err() != context.DeadlineExceeded {
			t.Fatalf("context.Err() = %v", ctx.Err())
		}
	})
}

Go 1.27 起可用 synctest.Sleep，它相当于推进时间后再等待活动稳定；兼容旧版本时，用 time.Sleep 加 synctest.Wait。不要只把 Sleep 数值调小。

四、复核网络与外部调用边界

真实网络读写、文件系统、系统调用和 cgo 不会自动变成确定性 fake。网络协议单元测试可以用 net.Pipe，但它的同步写入语义不同于真实 socket，连接调度仍应由集成测试覆盖。

五、迁移完成前的收口检查

1. 确认 Go 版本：Go 1.24 实验版的 synctest.Run 与 Go 1.25 的 synctest.Test 不是同一 API。
2. 确认 bubble 内 goroutine 都有退出路径，避免死锁或测试结束后仍存活。
3. 把固定等待改成完成信号、虚拟时间和 Wait，而不是继续加大 Sleep。
4. 把真实 I/O 单独标为集成测试，明确 fake 与真实实现的差异。

分工很清楚：虚拟时间负责时间行为，Wait 负责 bubble 内并发收敛，fake 负责隔离外部 I/O。

相关问题

testing/synctest 能替代所有 time.Sleep 吗？

不能。它适合 bubble 内的时间和并发协调，外部 I/O 仍需 fake 或集成测试。

为什么 Wait 后仍可能没有结果？

Wait 只处理 bubble 内的 durable blocked，不替代业务完成信号，也不保证外部网络已完成。