Go 测试为什么包内全局变量互相污染

Go 测试中出现“单独运行能通过，整包运行却失败”，常见原因不是断言本身，而是同一个测试进程里的包级可变变量被前一个测试改写了。普通 go test 会把同一包的测试组织到一个测试程序中；同包测试还能直接访问包内未导出标识符，所以全局配置、注册表、缓存和默认客户端都可能成为共享状态。

官方参考：https://pkg.go.dev/testing

测试需要的是“每个用例都能从已知状态开始”。如果变量必须是包级状态，就在测试边界保存并恢复；如果可以改变设计，优先让函数接收依赖或由工厂创建新对象。

先看清全局变量为什么会留下痕迹

包级变量在包初始化时创建，测试函数返回后不会自动重置。下面的示例里，第二个测试读到的不是默认配置，而是第一个测试写进去的值：

package settings

import "testing"

// currentMode 是包内共享状态，测试修改后不会随测试函数返回自动恢复。
var currentMode = "safe"

func TestEnableFastMode(t *testing.T) {
	// 这个测试改变包级变量，影响仍在同一进程中的后续测试。
	currentMode = "fast"
}

func TestDefaultMode(t *testing.T) {
	// 这里的失败说明测试依赖了执行前的隐含状态。
	if currentMode != "safe" {
		t.Fatalf("mode = %q, want %q", currentMode, "safe")
	}
}

测试文件放在被测包内时，可以访问未导出变量；放在 settings_test 这样的外部测试包时，只能通过公开 API 观察状态，但公开 API 背后仍可能持有同一个全局对象。不要用“换成黑盒测试”代替状态隔离，它只能改变可见性。

普通顺序依赖和并行竞态不是一回事

如果测试没有调用 t.Parallel()，前一个测试修改全局变量，后一个测试仍可能读到它，形成顺序依赖。测试顺序不应成为隐含契约；即使当前看起来按文件顺序执行，新增测试或重构后也可能改变暴露方式。

调用 t.Parallel() 后，问题更严重：多个测试可能同时读写同一变量，既有错误结果，也可能出现数据竞争。下面的写法把并行标记和全局写入放在一起，必须改掉：

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

	// 并行测试共享 currentMode，写入彼此不可预测，也可能触发竞态检测。
	currentMode = "fast"
	if currentMode != "fast" {
		t.Fatal("mode was changed by another test")
	}
}

父测试调用 t.Parallel() 后，子测试和其他并行测试的调度关系也要谨慎处理。不要靠 time.Sleep“等别人写完”，这只是把竞态藏起来。若必须测试并发安全性，应把共享对象设计成明确受锁或消息同步保护的对象，并用 -race 辅助发现数据竞争。

用保存恢复把污染关在一个测试里

对已有包级配置，最小修复是进入测试时保存旧值，退出时用 t.Cleanup 恢复。清理函数会在当前测试及其子测试结束后执行，适合把修改范围封装成一个助手：

func withMode(t *testing.T, next string) {
	t.Helper()
	old := currentMode
	// 无论断言成功还是失败，都恢复进入测试前的值。
	t.Cleanup(func() {
		currentMode = old
	})
	currentMode = next
}

func TestFastMode(t *testing.T) {
	withMode(t, "fast")
	if currentMode != "fast" {
		t.Fatalf("mode = %q, want fast", currentMode)
	}
}

func TestSafeMode(t *testing.T) {
	withMode(t, "safe")
	if currentMode != "safe" {
		t.Fatalf("mode = %q, want safe", currentMode)
	}
}

如果全局变量是 map、slice 或指针，不能只复制一个引用。应复制需要恢复的字段，或让生产代码提供明确的 reset/构造函数；否则清理时把同一个底层对象放回去，污染仍然存在。

TestMain 适合全包准备，不是每测一次重置

需要一次性准备临时目录、测试数据库或公共资源时，可以在测试包中定义 TestMain(m *testing.M)，在调用 m.Run() 前初始化，在返回后统一清理。官方文档说明，TestMain 运行在测试主 goroutine 中，适合包级 setup/teardown。

func TestMain(m *testing.M) {
	// 这里只做整个测试包只需一次的准备。
	prepareTestStore()

	code := m.Run()
	// m.Run 返回后再释放包级资源，避免测试中途提前关闭。
	closeTestStore()
	os.Exit(code)
}

示例需要导入 os。注意，TestMain 不会在每个测试前自动恢复全局变量；如果每个用例需要干净状态，仍要使用保存恢复、独立工厂或显式 reset。若 TestMain 依赖 testing 的命令行参数，还应按官方说明在读取前调用 flag.Parse()。

最后排除测试缓存造成的错觉

测试缓存可能让你误以为“刚改的状态已经重新跑过”。排查时先用 go test -count=1 ./... 禁用缓存，再根据需要加 -race 检查并发读写。缓存只影响是否复用已有结果，不会把一次 go test 进程里的全局变量带到另一次新进程；真正的污染仍要回到代码里的共享状态。

可以按下面的顺序收敛问题：

1. 搜索包级可变变量、init 注册逻辑和测试中的直接赋值。
2. 暂时去掉 t.Parallel()，看失败是否从竞态变成稳定的顺序依赖。
3. 为修改全局状态的测试加快照恢复；复杂对象改用工厂创建。
4. 用 go test -count=1 -race ./... 做一次针对性复查。

常见追问

为什么单独运行某个测试却通过？它可能没有遇到前置测试留下的状态，也可能被测试缓存直接复用了结果。先禁用缓存，再运行整个包。

把测试改到外部包就能解决吗？不能保证。外部包测试减少了对未导出变量的直接访问，但生产包里的单例、注册表和缓存仍然可能共享。

TestMain 能不能每次清空变量？它只在测试程序级别运行一次。每个测试的隔离应放在测试边界或生产代码的对象生命周期里。