Go testing.TB.Cleanup 为什么测试结束前不执行：注册时机与子测试边界

一、最小例子：Cleanup 为什么不会在下一行执行

func TestConfig(t *testing.T) {
    t.Cleanup(func() {
        t.Log("restore config")
    })

    t.Log("test body")
}

运行这个测试时，restore config 会在测试主体返回后才出现。它不会插入到 t.Cleanup 调用的下一行，也不会在测试主体仍然执行时提前清理资源。

二、注册时机决定清理覆盖范围

把资源创建和 Cleanup 注册放在同一层，通常最容易推理。创建成功后立刻注册，后面的断言失败、子测试失败或测试提前返回，都不会跳过清理。

func TestWorkspace(t *testing.T) {
    dir := t.TempDir()
    old := os.Getenv("APP_CONFIG_DIR")
    if err := os.Setenv("APP_CONFIG_DIR", dir); err != nil {
        t.Fatal(err)
    }
    t.Cleanup(func() {
        _ = os.Setenv("APP_CONFIG_DIR", old)
    })

    t.Run("reads config", func(t *testing.T) {
        // 子测试读取同一个临时配置目录。
    })
}

如果在 Setenv 成功之前就注册恢复函数，恢复函数可能拿不到可靠的旧值；如果资源创建失败后仍注册清理，则清理函数还要处理“资源其实不存在”的情况。实际代码应先完成必要的创建，再立即登记对应的逆操作。

三、父测试与 t.Run：谁的 Cleanup 先执行

每个 t.Run 都会获得自己的测试上下文。子测试注册的 Cleanup 只负责子测试拥有的资源；父测试注册的 Cleanup 则要等整个父测试的子测试树结束。

func TestOrder(t *testing.T) {
    t.Cleanup(func() { t.Log("parent cleanup") })
    t.Run("child", func(t *testing.T) {
        t.Cleanup(func() { t.Log("child cleanup") })
        t.Log("child body")
    })
}

这个例子的可观察顺序是 child body、child cleanup，最后才是 parent cleanup。父清理不会打断子测试，也不应在子测试仍需要资源时关闭共享依赖。

四、并行子测试最容易误判的边界

调用 t.Parallel() 后，子测试会暂停到父测试主体返回；父测试主体返回后，多个子测试才可能并行继续。因此，父测试在调用 t.Run 后立刻观察某个子测试副作用，往往观察得太早。

func TestParallel(t *testing.T) {
    shared := newFakeStore()
    t.Cleanup(func() { shared.Close() })

    for _, name := range []string{"a", "b"} {
        name := name
        t.Run(name, func(t *testing.T) {
            t.Parallel()
            if err := shared.Put(name, "ok"); err != nil {
                t.Fatal(err)
            }
        })
    }
}

这里把共享存储的关闭动作放在父测试 Cleanup 是安全的生命周期表达：父 Cleanup 会等待两个并行子测试都结束。若把 shared.Close() 放在父测试主体的末尾，就可能在子测试真正恢复执行前关闭它。

五、Cleanup 看似没有执行的排查清单

• 确认是否调用了 go test，而不是只运行了不会进入测试生命周期的普通程序。
• 确认注册 Cleanup 的代码确实走到了；创建资源失败后直接 return，不会凭空产生清理回调。
• 确认日志查看位置。t.Log 在测试成功时通常需要配合 go test -v 才能看到。
• 确认清理函数没有被自己的错误处理吞掉；恢复环境变量、关闭连接等操作应记录必要错误。
• 确认没有在并行子测试仍运行时从父测试外部读取结果；等待测试框架完成后再检查最终状态。

六、把清理逻辑封装成可复用辅助函数

func withEnv(t testing.TB, key, value string) {
    t.Helper()
    old, existed := os.LookupEnv(key)
    if err := os.Setenv(key, value); err != nil {
        t.Fatalf("set %s: %v", key, err)
    }
    t.Cleanup(func() {
        var err error
        if existed {
            err = os.Setenv(key, old)
        } else {
            err = os.Unsetenv(key)
        }
        if err != nil {
            t.Errorf("restore %s: %v", key, err)
        }
    })
}

辅助函数接收 testing.TB，因此既能服务 *testing.T，也能服务 *testing.B 或 *testing.F。调用方只需要在状态改变后立即调用它，资源的归属和恢复顺序就会跟测试上下文绑定。

结语：先画出测试树，再决定清理挂载点

testing.TB.Cleanup 的核心不是“延迟执行”四个字，而是测试树上的生命周期归属。独立资源挂在创建它的测试上，共享父资源挂在父测试上；并行子测试尤其要避免在父测试主体末尾手动关闭资源。按这个原则检查注册时机、子测试边界和日志输出，绝大多数“Cleanup 没执行”的问题都能定位。

相关问题

• Cleanup 会按什么顺序执行？同一测试上下文内按后进先出执行，子测试的清理先于父测试清理。
• 失败测试还会执行 Cleanup 吗？只要回调已经注册，测试失败或通过都应进入清理阶段。
• 并行测试能否直接共享可变资源？可以，但必须同步访问，并把关闭动作放在能覆盖所有使用者的父级 Cleanup 中。