Go test -shuffle=on 如何帮助发现测试间共享状态

如果多个 Go 测试单独执行都能通过，合在一起却偶发失败，先别急着给测试加重试。更常见的原因是某个测试修改了包级变量、环境变量、临时文件或数据库记录，另一个测试碰巧读到了这份残留状态。go test -shuffle=on 会随机化测试和基准的执行顺序，并报告本次种子；拿着种子再运行一次，就能把“偶发”变成可定位的顺序依赖。

先分清 -shuffle 解决的是什么问题

Go 测试中的“顺序问题”通常不是命令要求测试必须按某个顺序执行，而是测试代码偷偷依赖了前一个测试留下的状态。比如下面两个测试共享一个包级 map：创建测试先写入数据，读取测试再断言数据存在。它们分别运行时没有问题，换一个顺序就可能失败。

var records = map[string]string{}

func TestCreate(t *testing.T) {
	// 这个写入发生在包级共享状态上，容易影响其他测试。
	records["order-1"] = "paid"
}

func TestRead(t *testing.T) {
	// 读取测试不应该假定 TestCreate 已经运行过。
	if records["order-1"] != "paid" {
		t.Fatalf("record was not prepared by this test")
	}
}

-shuffle 关注的是测试与基准的执行顺序；它没有把测试变成并行任务，也不会自动重置 map、环境变量或数据库。随机化的价值在于扩大“谁先运行”的尝试范围，让隐藏的共享状态更容易露出来。

用随机种子发现测试间的隐式依赖

排查时先从整个模块跑一轮，再根据日志缩小范围：

# -shuffle=on 随机化顺序，-count=1 关闭本次测试缓存
go test -shuffle=on -count=1 ./...

如果失败输出中出现类似 -test.shuffle 20260909 的信息，先把它保存下来。这个数字不是失败原因，而是复现同一随机顺序的入口。不要只跑失败的那个测试：顺序依赖往往藏在“准备数据的测试”和“读取数据的测试”之间。

接着用 -run 缩小包或测试名，并固定种子：

# 固定种子重放同一轮顺序，再逐步缩小匹配范围
go test -shuffle=20260909 -count=1 -run 'Test(Create|Read)' ./path/to/orders

如果固定种子稳定失败，说明已经抓到可复现线索；如果只在大范围失败，保留完整命令，先检查测试初始化、共享缓存和外部资源的清理边界。

用固定种子把偶发失败变成可复现

发现问题后，选择方案时要区分“找问题”和“复现问题”：on 使用系统时钟，每轮种子可能不同，适合主动扰动顺序；整数种子适合把失败锁定，便于本地修复和 CI 复查。

修复前可以连续使用几个不同整数种子，确认问题确实来自隔离，而不是某个测试的偶然超时。修复后也要保留一次固定种子回归，避免只在默认顺序下“看起来通过”。

按资源边界修复共享状态

修复方向不是永久关闭 -shuffle，而是让测试对运行顺序不敏感。每个测试先准备自己要读的数据，测试结束时通过 t.Cleanup 恢复环境变量、删除临时文件或清理数据库记录；包级变量尽量改成测试内局部变量。需要外部服务时，给每个测试使用唯一命名空间，并把删除动作注册为清理函数。

func TestRead(t *testing.T) {
	// 每个测试自己创建夹具，不依赖其他测试先写入。
	records := map[string]string{"order-1": "paid"}

	// 清理逻辑集中注册，失败路径也会执行。
	t.Cleanup(func() {
		for key := range records {
			delete(records, key)
		}
	})

	if records["order-1"] != "paid" {
		t.Fatalf("unexpected order state")
	}
}

如果资源由 TestMain 统一创建，仍要确认每个测试不会修改一份可变全局对象。全局初始化适合准备只读依赖，不适合把某个测试的业务状态偷偷传给下一个测试。

常见问题

为什么加了 -shuffle=on 还是复现不了？

先加 -count=1，再保存日志中的整数种子；同时确认失败是否依赖时间、网络或并发调度。种子只能固定测试顺序，不能固定所有外部时序。

-shuffle=on 会让测试并行执行吗？

不会。它改变测试和基准的顺序；t.Parallel 与 -parallel 才涉及并行测试的调度。

修复后还需要保留固定种子吗？

可以把触发过问题的种子放进回归命令或 CI 诊断记录，但不要只依赖它；日常仍应偶尔使用 on，持续检查新测试是否引入共享状态。