Go testing/synctest.Sleep 怎样测试时间驱动代码

测试“等待 10 秒后才发送信号”的代码时，最容易踩到两个坑：真实等待让测试变慢，而直接调用 time.Sleep 又不能保证被测协程已经完成。Go 的 testing/synctest.Sleep 正好把这两个动作合在一起：推进当前测试气泡的虚拟时钟，并等待气泡里的其它协程达到稳定状态。

官方地址：https://pkg.go.dev/testing/synctest

把时间驱动逻辑放进 synctest.Test，再用 synctest.Sleep(d) 替代测试里的 time.Sleep(d)。这样测试不会真的等待 d，且在同样的等待时长下，不会因为测试协程和被测协程谁先醒来而产生偶发失败。

为什么 synctest.Sleep 能让时间驱动测试稳定

synctest.Test 会创建一个隔离的测试气泡。气泡中的 goroutine 属于同一个并发测试环境，time 使用气泡自己的时钟；只有当相关 goroutine 都进入可稳定判断的阻塞状态时，虚拟时间才会继续推进。

synctest.Sleep(d) 的关键不是“把机器时间调快”，而是组合了两个语义：先让气泡时钟前进 d，再等待其它协程完成当前可完成的工作。官方文档把它描述为 time.Sleep(d) 与 synctest.Wait() 的等价组合。

这也解释了它为什么适合时间驱动代码：业务协程可以继续写普通的 time.Sleep，测试协程则使用 synctest.Sleep，把“经过一段时间”和“让被测逻辑稳定下来”表达在同一个测试动作中。

先写一个等待后发信号的被测函数

先把业务行为缩成一个容易观察的完成信号：启动 goroutine，等待指定时长，再关闭 channel。示例只展示测试结构，不需要真的等待 10 秒。

package delay

import "time"

// StartAfter 在指定时长后关闭完成信号，供调用方等待任务结束。
func StartAfter(d time.Duration) 

这里的返回值是只读 channel，调用方只能接收完成信号。生产代码不需要为了测试专门暴露时钟对象；只要测试在 synctest.Test 内运行，包内的 time.Sleep 就会参与同一个虚拟时间环境。

用 synctest.Sleep 推进时间并断言结果

测试时把业务调用包进 synctest.Test，然后调用同样时长的 synctest.Sleep。它返回时，气泡内的时间驱动协程已经有机会完成，断言也就不再依赖真实调度顺序。

package delay_test

import (
	"testing"
	"testing/synctest"
	"time"

	"example.com/delay"
)

func TestStartAfter(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		// 在气泡中启动被测协程，10 秒不会变成真实等待。
		done := delay.StartAfter(10 * time.Second)

		// Sleep 同时推进虚拟时间，并等待气泡内其它协程稳定。
		synctest.Sleep(10 * time.Second)

		select {
		case 

这个测试的判断点很明确：如果 synctest.Sleep 返回后 done 仍未关闭，就说明“经过 10 秒后完成”的契约没有兑现。测试没有采集墙上时钟，也没有依赖实际等待时长，因此适合放进频繁运行的单元测试。

不要用同样时长的 time.Sleep 代替它

下面的写法看起来相近，但测试协程和被测协程都睡眠 1 秒时，谁先被调度并没有稳定保证。测试协程可能先从 time.Sleep 返回，于是立即检查 channel；也可能被测协程先关闭 channel。偶发失败正是由这个先后关系造成的。

func TestStartAfterWithPlainSleep(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		// 被测协程和测试协程使用相同的虚拟时长。
		done := delay.StartAfter(time.Second)
		time.Sleep(time.Second)

		select {
		case 

这里的问题不是 time.Sleep 在 synctest 中失效，而是它只表达“当前协程睡够了”，不表达“其它协程也已经稳定”。如果测试关心的是被测任务完成，应使用 synctest.Sleep；如果关心的是某个事件本身，则也可以直接接收 channel，让业务信号成为断言依据。

几个边界要在测试里说清楚

• 调用位置：synctest.Sleep 应在 synctest.Test 创建的气泡内使用。不要把它当作普通生产代码里的延时函数。
• 零时长：零时长适合检查当前已经可运行的工作，但它不等于“任意异步任务都完成”。仍然要根据 channel、context 或其它业务信号断言。
• 时长不匹配：测试等待时间短于业务延迟时，断言失败是合理结果；不要通过无限等待掩盖错误。
• 气泡外依赖：网络、外部进程或气泡外启动的 goroutine 不属于这套虚拟时间的完整控制范围，测试应优先使用自包含的替身。
• 协程泄漏：测试退出前仍未结束的气泡协程会让问题暴露出来，业务代码应提供取消或结束路径。

什么时候用 Sleep，什么时候用 Wait

如果测试目标是“经过某个持续时间后，时间驱动逻辑应当完成”，用 synctest.Sleep(d) 最直观。如果目标只是“让当前已经启动的 goroutine 运行到稳定点”，可以用 synctest.Wait()。前者改变观察到的虚拟时间，后者只等待当前气泡中的其它 goroutine 达到可判断状态。

常见问题

synctest.Sleep 会让生产代码里的 time.Sleep 失效吗？

不会。它只是在测试气泡中提供虚拟时间环境；生产代码仍然调用 time.Sleep，只是测试时不必真的等待墙上时间。

已经调用 time.Sleep，为什么还要调用 synctest.Wait？

time.Sleep 只保证当前 goroutine 睡眠结束；synctest.Wait 才负责等待其它气泡协程达到稳定。synctest.Sleep 是把这两个意图合成一个更适合测试的调用。

能不能在测试气泡外直接调用 synctest.Sleep？

不建议。它依赖当前气泡的时钟与协程集合，调用前应先进入 synctest.Test 或底层气泡环境。

测试还是偶尔失败怎么办？

先检查断言是否在等待明确的业务信号，而不是猜测 goroutine 调度顺序；再确认延迟时长、取消路径和气泡外依赖。不要简单增加真实 time.Sleep。