Go t.Parallel 导致共享状态偶发失败的隔离方案

如果一个 Go 测试单独运行总能通过，加入 t.Parallel() 或提高并行度后却偶发失败，先不要把问题归咎于断言。更常见的根因是多个测试同时修改了进程级环境变量、同一个临时文件、全局配置或可变测试夹具。解决思路是把并行测试限制在只读输入上，把可变状态改成每个测试独有的副本。

结论：t.Parallel() 只负责调度，不会替测试隔离共享状态。配置优先通过参数传入，文件使用 t.TempDir()，环境变量测试保持串行；确实需要共享的夹具必须在并行阶段保持只读。

• 影响面：环境变量、工作目录、全局变量和固定文件名会跨测试相互覆盖。
• 触发条件：测试的执行顺序或并行时机变化后，先写入的状态被另一个测试观察到。
• 修复目标：每个测试拥有自己的可变输入，或者明确把共享夹具封装为只读资源。

影响面：为什么单测通过，并行后才偶发失败

单独运行时，测试拥有完整的进程时间线：它设置环境变量、写文件、调用被测函数，再执行清理。加入 t.Parallel() 后，多个测试的主体可能交错执行。Go 官方文档明确说明，Parallel 会让测试暂停，直到非并行测试结束，然后与其它并行测试一起运行；它并不会复制进程、环境变量或包级变量。

因此，下面这类代码的风险不在断言，而在共享的 APP_MODE。两个测试都写入同一个进程环境，读取时看到的值取决于当时谁最后一次修改了它：

func TestConfig(t *testing.T) {
    t.Parallel()

    // 环境变量属于整个进程，不能让并行测试各自拥有一份。
    _ = os.Setenv("APP_MODE", "test")
    defer os.Unsetenv("APP_MODE")

    if got := LoadMode(); got != "test" {
        t.Fatalf("模式不正确：got %q", got)
    }
}

固定的 ./testdata/output.json、会被重置的包级缓存、复用的数据库种子对象也有同样问题。若失败只在重复运行或改变测试顺序后出现，可以先按“进程级状态、文件系统状态、内存状态”三层排查。

时间线：t.Parallel 到底改变了什么

一次典型故障可以按四个时刻复盘。首先，父测试创建多个子测试；其次，子测试调用 t.Parallel() 并暂停；然后父测试继续创建其它子测试并返回；最后这些并行子测试在允许的并行度内恢复执行。非并行测试不会和并行测试主体同时运行，但已经完成的父级初始化仍可能被所有子测试共享。

-parallel 只限制同时运行的并行测试数量，不改变共享变量的归属。把它调成 1 有时会让现象暂时消失，却不能证明代码已经安全，因为测试仍然依赖隐含的全局状态。

func TestParser(t *testing.T) {
    cases := []struct {
        name string
        mode string
        input string
    }{
        {name: "strict", mode: "strict", input: "a=1"},
        {name: "loose", mode: "loose", input: "a=1;comment"},
    }

    for _, tc := range cases {
        tc := tc // 每个闭包绑定自己的用例值，避免共享循环变量。
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()

            // 配置作为输入传入，被测函数不再读取包级可变配置。
            cfg := Config{Mode: tc.mode}
            if err := ParseWithConfig(tc.input, cfg); err != nil {
                t.Fatalf("解析失败：%v", err)
            }
        })
    }
}

根因：把可变状态从并行测试中拿出来

第一种修复是依赖注入。不要让测试先修改全局配置再调用函数，而是让函数接收配置、时钟、文件系统或客户端等依赖。并行测试可以共享配置的只读模板，但每个用例都应创建自己的派生值；如果函数内部仍然写回全局缓存，单纯复制结构体也不够，还需要把缓存本身改成实例字段。

第二种修复是隔离文件。不要拼接固定文件名或复用仓库里的输出目录，使用 t.TempDir() 为每个测试申请目录。该目录会在测试及其子测试结束后清理，路径也不需要由测试自行猜测。对需要多个并行子测试读取的基线文件，可以在父级一次生成后只读；对会被修改的文件，则在子测试内重新复制。

func TestWriter(t *testing.T) {
    t.Parallel()

    dir := t.TempDir() // 每个测试得到独立目录，避免固定路径互相覆盖。
    output := filepath.Join(dir, "result.json")

    if err := WriteResult(output, Result{Value: 42}); err != nil {
        t.Fatalf("写入结果失败：%v", err)
    }
    if _, err := os.Stat(output); err != nil {
        t.Fatalf("结果文件不存在：%v", err)
    }
}

第三种修复是夹具生命周期隔离。可变夹具应该在子测试中创建，并用 t.Cleanup() 注册释放动作；不要因为父测试创建一次很方便，就让所有并行子测试共同修改它。共享夹具只有在“初始化一次、并行期间只读、所有子测试结束后再清理”三个条件同时满足时才适合放在父级。

修复动作：环境变量测试必须明确串行边界

t.Setenv() 会自动注册清理，把环境变量恢复为原值，但官方文档同时规定它不能用于并行测试，也不能用于拥有并行祖先的测试。这不是 API 使用技巧问题，而是因为环境变量影响整个进程。需要验证环境变量的测试应当保持串行，并把并行测试放在另一个没有并行祖先的分组中。

func TestEnvConfig(t *testing.T) {
    t.Run("environment", func(t *testing.T) {
        // 这里故意不调用 t.Parallel，保证 Setenv 不和其它并行测试重叠。
        t.Setenv("APP_MODE", "test")
        if got := LoadMode(); got != "test" {
            t.Fatalf("模式不正确：got %q", got)
        }
    })
}

func TestPureConfig(t *testing.T) {
    t.Parallel()

    // 纯函数式配置不碰进程环境，适合与其它测试并行。
    cfg := Config{Mode: "test"}
    if got := LoadWithConfig(cfg); got != "test" {
        t.Fatalf("模式不正确：got %q", got)
    }
}

如果旧代码只能读取环境变量，可以先把读取动作收敛到一个小适配层，再让核心逻辑接受普通配置对象。这样只有适配层测试需要串行，解析、校验和业务规则测试就可以并行。

防复发：如何确认修复的是共享状态

回归检查要覆盖不同调度条件，而不是只把 -parallel 调小。可以先使用 go test ./... -count=1 关闭缓存，再用 go test ./... -count=20 -shuffle=on 重复并打乱测试顺序，最后对涉及共享内存的包运行 go test -race ./...。这些命令是排查手段，不是用更长等待替代隔离设计。

• 环境变量测试：确认没有 t.Setenv 与 t.Parallel 同时出现，也没有并行祖先。
• 文件测试：确认路径来自 t.TempDir 或每个用例独立的目录，不写固定输出文件。
• 夹具测试：确认并行阶段只读；有写操作的对象在子测试中创建，并由对应的 t.Cleanup 释放。
• 参数化测试：确认闭包捕获的是当前用例副本，函数不再偷偷读取包级可变配置。

修复后的判断标准不是“这次没有失败”，而是即使改变并行度、顺序和重复次数，测试仍然只依赖显式输入与自己的生命周期。

常见问题：Go 并行测试隔离怎么做

把 -parallel 设置为 1 能彻底解决问题吗？

不能。它只降低并行调度数量，无法改变环境变量、包级变量和固定文件属于共享资源的事实；应修复资源边界。

共享只读夹具可以放在父测试里吗？

可以，但要保证并行子测试只读，并在所有子测试完成后再清理。只要有一个子测试会修改它，就应为子测试创建独立副本。

为什么用了 t.Setenv 还不能调用 t.Parallel？

因为环境变量属于整个进程。Setenv 能帮你恢复原值，却不能把环境复制给每个并行测试，所以这类测试必须保持串行。