Go testing.T Cleanup把失败位置指向测试调用方的诊断方法

公共测试辅助函数一多，失败日志很容易停在 testutil.go，读者还要沿着调用栈倒推是哪一个测试传入了坏状态。处理这类问题时，t.Cleanup 和 t.Helper 要配合使用：前者负责把恢复动作绑定到测试生命周期，后者负责让 testing 包跳过辅助函数栈帧。两者不是同一个开关。

官方文档：https://pkg.go.dev/testing

先把 Cleanup 和 Helper 分工说清楚

Cleanup 接收一个无参数函数。当前测试函数和它的所有子测试都返回后，testing 才调用这个函数；同一层注册的回调按最后注册、最先执行的顺序收尾。它解决的是“什么时候释放”。

Helper 标记调用它的函数为测试辅助函数。之后 testing 打印文件和行号时，会跳过这层辅助函数。它解决的是“失败显示在哪里”。因此，仅把关闭连接放进 Cleanup，并不会自动让报错跳到测试调用方；还要给注册清理动作的辅助函数加上 t.Helper()。

用一个带 Helper 的注册函数包住清理动作

下面的辅助函数模拟切换全局配置：测试拿到旧值后立即注册恢复动作，恢复失败通过同一个 *testing.T 报告。

package configtest

import "testing"

var currentMode = "safe"

func registerMode(t *testing.T, next string) {
	// 隐藏公共辅助函数这一层，让失败位置更接近调用它的测试。
	t.Helper()
	previous := currentMode
	currentMode = next
	t.Cleanup(func() {
		// 清理回调只负责恢复资源，不再创建新的测试生命周期。
		currentMode = previous
		if currentMode == "" {
			// 示例中的检查代表真实资源恢复失败。
			t.Errorf("restore mode: empty value")
		}
	})
}

func TestMode(t *testing.T) {
	// 调用方就是日志中希望看到的诊断位置。
	registerMode(t, "debug")
	if currentMode != "debug" {
		t.Fatalf("mode = %q; want debug", currentMode)
	}
}

这段代码里，Cleanup 闭包捕获了旧值，测试函数无需手写 defer。真正项目中如果恢复动作可能返回错误，应在回调内把错误内容写进 Errorf，同时保留资源关闭顺序。不要把 t.Fatal 放进由其他 goroutine 触发的清理逻辑；FailNow 类操作必须运行在测试 goroutine 中。

子测试边界决定清理动作何时发生

把 t 传给辅助函数，就等于把资源的所有权交给这一层测试。父测试注册的清理会等所有子测试完成；子测试注册的清理则在该子测试及其子测试结束后执行。如果辅助函数错误地保存父级 *testing.T 给子测试使用，日志位置和释放时机都会变得难以判断。

func TestGroups(t *testing.T) {
	// 父级资源会等所有子测试返回后再释放。
	registerMode(t, "suite")
	t.Run("case-a", func(t *testing.T) {
		// 子测试资源绑定到子测试，结束边界更小。
		registerMode(t, "case-a")
	})
}

还要记住两条顺序规则：同一个 T 上后注册的清理先执行；子测试自己的收尾先于父测试收尾。需要并行子测试时，避免在 Cleanup 中修改进程级环境变量、工作目录或共享全局变量；这类状态会让并行用例互相影响，应改成显式隔离或取消并行。

一份调用方导向的排查清单

先确认辅助函数收到的 *testing.T 就是当前测试参数，而不是包级变量或父测试引用；再确认 t.Helper() 位于辅助函数入口，而不是 Cleanup 执行之后。若失败来自闭包内部，检查闭包是否只做清理和错误报告，必要时在辅助层继续标记 Helper，但不要把真实业务断言吞掉。最后检查资源的创建、注册、释放是否属于同一个测试层，并用 go test -run TestGroups -v 观察子测试名称和失败位置。

常见问题

Cleanup 能替代所有 defer 吗？

不能。Cleanup 适合绑定测试生命周期的资源，尤其是子测试也使用的资源；只在当前函数内有效且不需要测试对象的局部收尾，普通 defer 更直接。

只调用 t.Helper 就会改变清理顺序吗？

不会。Helper 只影响 testing 输出的调用位置，Cleanup 的执行时机和逆序规则仍由注册到哪个 T 以及注册先后决定。

Cleanup 回调里还能调用 t.Errorf 吗？

可以用它报告恢复失败，但应保证回调在测试生命周期内执行、不要从其他 goroutine 调用终止测试的方法，并让错误信息包含资源名和恢复动作。

把“释放时机”和“报错位置”拆开设计，测试辅助层就能既复用清理逻辑，又把诊断信息留给真正写断言的测试调用方。