Go t.Parallel 为什么让测试不稳定

Go 测试加上 t.Parallel() 后偶尔失败，通常不是调度器“随机出错”，而是测试把会变化的状态放进了同一个进程边界。多个测试同时读写全局变量、环境变量、工作目录、固定临时文件或共享外部资源时，谁先改、谁后读就会影响结果。

排查的关键是先看生命周期，再看资源归属：t.Parallel() 只改变测试何时加入并行集合，并不会自动复制数据，也不会替你隔离进程级状态。官方文档对 Parallel、Run 的说明可直接查阅：

官方地址：https://pkg.go.dev/testing#T.Parallel

想让并行测试稳定，先保证每个测试拥有自己的输入、临时目录和外部资源；无法隔离的进程级状态就不要放进并行测试。

先确认 t.Parallel 改变了什么

t.Run 创建子测试后，子测试在调用 t.Parallel() 的位置暂停，等非并行测试完成，再与其他并行测试一起运行。父测试不会因为“提交了并行子测试”就提前完成：父测试函数返回后，测试框架才会继续收拢并行子测试。因此，真正需要画出来的是等待点和边界，而不是一条假想的线性执行流程。

一个常见的表驱动写法如下。这里的每个子测试只读取自己的输入，避免把“并行”误解为“共享数据也安全”。

func TestPrice(t *testing.T) {
	cases := []struct {
		name string
		in   int
		want int
	}{
		{name: "small", in: 10, want: 12},
		{name: "large", in: 100, want: 120},
	}

	for _, tc := range cases {
		tc := tc // 中文注释：把当前用例绑定到本轮闭包，避免读取变化中的循环变量。
		t.Run(tc.name, func(t *testing.T) {
			t.Parallel() // 中文注释：声明加入并行测试集合，不会复制外部共享状态。
			if got := tc.in + tc.in/5; got != tc.want {
				t.Fatalf("got %d, want %d", got, tc.want) // 中文注释：失败时同时打印期望值，便于定位用例。
			}
		})
	}
}

不稳定通常来自哪些共享资产

把失败现场按资产分级，定位会比反复重跑更快。第一类是测试代码里的全局切片、单例缓存和包级配置；第二类是进程级环境变量与当前工作目录；第三类是固定文件名、固定端口、共享数据库记录或同一个外部服务账号。它们的共同点是：测试函数看起来各自独立，但实际写入了同一处状态。

尤其要注意 t.Setenv 和 t.Chdir。它们改变整个进程的环境或工作目录，不能用于并行测试，也不能用于拥有并行祖先的测试。若一个测试需要这类设置，可以把它放在非并行边界；若只是准备输入，优先改成局部参数或测试专属目录。

还有一种容易漏掉的情况：测试本身没有写全局变量，却调用了会修改全局状态的辅助函数。例如初始化函数把结果缓存到包变量，清理函数又在另一个并行测试仍使用时重置它。这类问题要沿着辅助函数继续追踪，而不是只看测试函数的几行代码。

按测试边界做隔离

稳定方案不是给所有共享变量加锁。锁只能保证一次访问不同时发生，却不能保证测试之间语义隔离；一个测试写入的值仍可能成为另一个测试读到的值。更稳妥的顺序是：输入数据局部化，文件使用 t.TempDir()，资源用 t.Cleanup() 回收，确实无法隔离的状态放回非并行测试。

func TestConfigFile(t *testing.T) {
	dir := t.TempDir() // 中文注释：每个测试获得独立目录，避免固定路径互相覆盖。
	path := filepath.Join(dir, "config.json")

	t.Cleanup(func() {
		// 中文注释：登记测试专属资源的收尾动作，清理逻辑只作用于本测试。
		_ = os.Remove(path)
	})

	if err := os.WriteFile(path, []byte(`{"mode":"test"}`), 0o600); err != nil {
		t.Fatalf("write config: %v", err) // 中文注释：准备阶段失败就停止本用例，避免掩盖根因。
	}
	got, err := os.ReadFile(path)
	if err != nil {
		t.Fatalf("read config: %v", err) // 中文注释：读取错误要保留原始错误，便于区分路径和权限问题。
	}
	if string(got) != `{"mode":"test"}` {
		t.Fatalf("unexpected config: %s", got) // 中文注释：只比较本测试写入的内容，不依赖其他用例的文件。
	}
}

如果测试必须修改环境变量，可将该测试保留为非并行测试，并让其他并行测试不要依赖相同变量。对数据库、HTTP 服务或消息队列，则使用独立命名空间、唯一记录键或专属测试实例；只在连接对象本身安全并且数据键隔离时，才适合共享客户端。

用重复运行和 race 检测确认根因

先用重复运行放大调度差异，再用 race 检测判断是否存在未同步的内存访问。下面的命令是排查手段，输出需要结合失败用例和资源边界阅读；它们不是把偶发失败“压过去”的修复。

# 中文注释：重复执行测试，观察失败是否只在特定调度下出现。
go test ./path/to/pkg -run TestPrice -count=50

# 中文注释：开启竞态检测，重点关注并行用例访问共享内存的读写冲突。
go test -race ./path/to/pkg -run TestPrice -count=10

如果重复运行失败但 -race 没有提示，仍可能是共享文件、环境变量、端口或外部数据造成的逻辑竞争；如果 -race 报告冲突，应回到写入方和读取方，优先拆分状态，而不是只增加等待时间。每个修复后都要确认三件事：用例输入是否独立，清理是否属于当前测试，父测试返回前是否仍有共享资源被修改。

几个容易误判的问题

加了互斥锁是不是就稳定了？

不一定。锁可以消除数据竞争，却不能阻止测试按照错误的顺序观察到别的测试写入的业务状态。先做所有权隔离，再考虑锁保护真正需要共享的只读或协调资源。

为什么父测试里的清理代码会影响并行子测试？

并行子测试要等父测试函数返回后才继续，所以父函数返回前的准备状态会被它们看到；同时，清理的归属必须与资源的创建边界一致。将测试专属资源注册到对应的 t.Cleanup，比在外层手工猜测时机更清楚。

什么时候应该直接取消 t.Parallel？

当测试依赖无法隔离的进程级状态、共享外部系统或全局初始化，而且并行收益不明显时，取消并行是合理的工程取舍。稳定、可定位的测试比表面上的并发执行更重要。

最后可以把判断压缩成一句话：t.Parallel() 管的是调度，不管资源复制。只要每个测试都能说明“我拥有什么、谁负责清理、哪些状态不能并行修改”，偶发失败通常就能从随机现象还原成明确的边界问题。