Go go test -shuffle 结果不稳定怎么办

我第一次把 go test -shuffle=on 放进 CI 时，看到的不是“随机功能有问题”，而是同一组测试有时通过、有时失败。真正需要处理的是测试之间隐藏的顺序依赖：某个测试留下了环境变量、包级变量、临时文件或外部资源，换一个执行顺序后，后面的测试就读到了不该看到的状态。

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

排查时不要直接反复执行 go test -shuffle=on。先把失败时打印的种子记下来，用固定整数种子复现；再分别排查共享状态、t.Parallel() 带来的并行调度，以及测试缓存。三条线混在一起，通常会让修复变成“多跑几次看看”。

先把随机失败变成固定案例

Go 官方的 -shuffle 支持关闭、按系统时钟随机，以及使用整数种子。on 适合主动发现顺序依赖，固定整数则适合复现同一条执行路径。第一步是保留失败日志中的种子，随后用同一个种子再跑一次。

# 先用系统时钟打乱测试顺序，观察是否能暴露顺序依赖
go test -v -shuffle=on ./...

# 把失败时记录的整数种子替换到这里，复现同一组测试顺序
go test -v -shuffle=184735 ./...

# 固定种子后再跑几轮，确认失败是否稳定出现
go test -v -shuffle=184735 -count=5 ./path/to/pkg

这里的整数只是示例，不能把它当成“正确种子”。每次失败都应记录实际输出中的种子、包路径和失败测试名。固定种子复现后，问题就从“偶发”变成了可以逐步缩小的工程案例。

先查测试之间有没有共享状态

固定顺序后，我通常先看测试是否修改了其他测试也能看到的东西。重点包括包级变量、os.Setenv、当前工作目录、临时目录中的固定文件名、全局单例、数据库表和共享缓存。单个测试在自己的顺序里没问题，不代表它把状态恢复干净了。

func TestFeature(t *testing.T) {
	// 用唯一临时目录承载本测试文件，避免固定路径被其他测试复用
	workDir := t.TempDir()
	configPath := filepath.Join(workDir, "config.json")

	// 写入本测试专属配置，测试结束后目录由 testing 自动清理
	if err := os.WriteFile(configPath, []byte(\`{"mode":"test"}\`), 0o600); err != nil {
		t.Fatalf("write config: %v", err)
	}

	// 通过显式参数传入路径，避免被包级全局配置或环境变量污染
	got, err := LoadConfig(configPath)
	if err != nil {
		t.Fatalf("load config: %v", err)
	}
	if got.Mode != "test" {
		t.Fatalf("mode = %q, want test", got.Mode)
	}
}

如果必须修改环境变量，使用测试对象提供的清理机制，并确认该测试没有进入并行执行。testing.T.Setenv 会在测试结束时恢复原值，但因为环境变量影响整个进程，它不能和并行测试或并行祖先一起使用。

func TestWithEndpoint(t *testing.T) {
	// Setenv 会在本测试结束时恢复原值，但不能与 t.Parallel 同时使用
	t.Setenv("APP_ENDPOINT", "http://127.0.0.1:18080")

	// 从当前测试读取环境变量，避免把固定值复制到业务代码中
	if got := os.Getenv("APP_ENDPOINT"); got == "" {
		t.Fatal("APP_ENDPOINT is empty")
	}
}

不要把顺序打乱和并行调度混为一谈

-shuffle 改变的是测试或基准的执行顺序；t.Parallel() 则允许测试进入并行调度。两者可能同时存在，但证据不同。先用固定种子、暂时不改代码的方式复现，确认问题是否只依赖顺序；再单独检查并行测试之间是否读写了同一资源。

func TestUserCache(t *testing.T) {
	// 只有确认测试完全独立后才启用并行，否则先保留串行执行
	t.Parallel()

	// 每个测试使用唯一键，避免并行测试互相覆盖缓存数据
	key := "user-cache-" + t.Name()
	if err := cache.Set(key, "ready"); err != nil {
		t.Fatalf("set cache: %v", err)
	}
	if got := cache.Get(key); got != "ready" {
		t.Fatalf("cache value = %q, want ready", got)
	}
}

常见误区是看到固定种子仍然失败，就立刻断定是随机数或 Go 测试框架的问题。更有价值的判断是：关闭 t.Parallel() 后是否还失败；把外部资源换成每个测试独占的资源后是否还失败。这样才能区分顺序依赖和真正的数据竞争。

用 -count=1 排除测试缓存假象

显式包列表模式下，go test 会缓存成功的测试结果。缓存命中时，终端通常会显示 (cached)，这不等于测试二进制刚刚重新执行。如果你正在验证清理逻辑或顺序修复，最好加上 -count=1，确保拿到新鲜结果。

# 固定顺序并关闭缓存，适合验证刚改过的清理逻辑
go test -v -shuffle=184735 -count=1 ./path/to/pkg

# 如果怀疑存在数据竞争，再单独运行 race 检查
go test -race -shuffle=184735 -count=1 ./path/to/pkg

-count=1 解决的是缓存问题，不会自动修复共享状态；-race 也不能替代顺序复现。它们是不同维度的工具，应该在固定种子已经把问题缩小后分别使用。

修复后用同一条证据回归

修复动作应当对应根因：包级状态改为测试内局部状态，固定文件名改为 t.TempDir()，环境变量用 t.Setenv 并避免并行，数据库或缓存使用唯一键并在结束时清理。不要只把 CI 改成串行或关闭 -shuffle，那只是把缺陷藏起来。

# 第一轮：用原始种子和新鲜运行确认原失败已消失
go test -v -shuffle=184735 -count=1 ./path/to/pkg

# 第二轮：重复固定顺序，观察是否仍有间歇性失败
go test -shuffle=184735 -count=20 ./path/to/pkg

# 第三轮：在同一范围内检查并行读写冲突
go test -race -shuffle=184735 -count=5 ./path/to/pkg

小结

Go go test -shuffle 的价值不在于制造随机失败，而在于把隐藏的测试耦合暴露出来。排查顺序可以固定为：记录失败种子，用整数种子复现；检查共享状态；单独判断 t.Parallel() 和数据竞争；用 -count=1 排除缓存；最后用同一个种子、重复次数和必要的 -race 做回归。这样修复的是测试隔离问题，而不是把探测开关关掉。

相关问题

-shuffle=on 失败时为什么要保存种子？

因为 on 使用系统时钟生成随机顺序，失败时的整数种子能把这次执行路径固定下来，便于在本地或 CI 中重复观察。

固定种子通过了，能说明测试已经稳定吗？

不能。它只说明这一条顺序通过。还应使用多个种子或继续运行 -shuffle=on，并检查测试是否真正清理了共享状态。

为什么加了 -count=1 还是会失败？

-count=1 只关闭测试缓存，不改变测试逻辑、顺序依赖或并行冲突。它能让你看到新鲜运行结果，但根因仍需按固定种子和资源隔离继续定位。