测试临时目录在子测试结束后的清理边界

t.TempDir 的清理边界不由某一行 t.Run 是否返回决定，而由“调用它的那个 *testing.T 以及这个测试的全部子测试是否完成”决定。父测试调用 t.TempDir，目录会保留到所有普通、嵌套和并行子测试完成；子测试调用它，目录只保留到该子测试树结束。

清理边界只看 TempDir 的调用者

官方文档对 T.TempDir 的描述很明确：它返回当前测试使用的唯一临时目录，在测试及其全部子测试完成后自动删除。这里的“当前测试”就是接收方法调用的那个 T。每次调用都会得到独立目录，因此关键问题不是“目录在哪个代码块里”，而是“哪一个 T 创建了它”。

参考地址：https://pkg.go.dev/testing#T.TempDir

父测试共享目录：让子测试只使用自己的子目录

多个子测试需要共享同一个根目录时，可以在父测试创建目录。为了避免并行写同名文件，每个子测试再按名称建立自己的工作目录。父目录不会因为某个子测试先结束而被删除。

package filetest

import (
    "os"
    "path/filepath"
    "strings"
    "testing"
)

func TestIndexFiles(t *testing.T) {
    // 父 T 拥有这个目录，因此所有子测试完成前都会保留。
    sharedRoot := t.TempDir()

    for _, format := range []string{"json", "yaml"} {
        t.Run(format, func(t *testing.T) {
            t.Parallel()

            // 每个并行子测试使用不同子目录，避免互相覆盖文件。
            safeName := strings.ReplaceAll(t.Name(), "/", "_")
            caseDir := filepath.Join(sharedRoot, safeName)
            if err := os.MkdirAll(caseDir, 0o755); err != nil {
                t.Fatalf("创建用例目录失败: %v", err)
            }

            // 这里执行当前格式的写入与断言。
            _ = format
        })
    }
}

这种写法适合共享根目录或只读夹具，但“父目录活着”不等于“并发写安全”。子测试仍应避免写同一个文件；如果必须共享状态，要使用锁或改成非并行测试。

子测试独立目录：不要把路径泄漏给兄弟用例

在子测试内部调用 t.TempDir，目录的所有权就属于这个子测试。子测试及它继续创建的后代可以使用该目录，但兄弟子测试和父测试在 t.Run 之后不应继续使用它。

func TestParseConfig(t *testing.T) {
    t.Run("valid", func(t *testing.T) {
        // 目录只属于 valid 子测试树，其他兄弟用例不要复用。
        dir := t.TempDir()
        file := filepath.Join(dir, "app.yaml")
        if err := os.WriteFile(file, []byte("port: 8080\n"), 0o600); err != nil {
            t.Fatalf("写入测试配置失败: %v", err)
        }

        // 在这个子测试返回前完成读取和断言。
        _ = file
    })
}

最常见的错误是把子测试里的路径保存到外部变量，随后让父测试或兄弟测试读取。即使代码偶尔能跑通，也依赖了不该依赖的生命周期和调度顺序。真正需要跨子测试共享时，应把目录提升为父 T 的资源。

并行子测试最容易踩到的提前删除

t.Run 遇到子测试调用 t.Parallel 时，子测试会先暂停，父测试函数可以继续执行。整个父测试仍要等所有并行子测试完成才算完成，因此父 T 创建的 TempDir 仍然安全；但普通 Go 函数的 defer 只等当前函数返回，这两个边界并不相同。

func TestBadParallelCleanup(t *testing.T) {
    dir, err := os.MkdirTemp("", "bad-parallel-*")
    if err != nil {
        t.Fatal(err)
    }
    // 错误点：这个 defer 绑定父函数返回，不绑定测试树完成。
    defer os.RemoveAll(dir)

    t.Run("parallel", func(t *testing.T) {
        t.Parallel()

        // 子测试恢复执行时，父函数可能已经返回并删除了目录。
        if err := os.WriteFile(filepath.Join(dir, "result.txt"), []byte("ok"), 0o600); err != nil {
            t.Fatalf("写入失败: %v", err)
        }
    })
}

修复方式不是增加睡眠或重试，而是把第一行目录创建改成 dir := t.TempDir()，删除手工 defer。这样清理动作跟随父测试的生命周期，直到并行子测试全部结束。

后台资源要在目录删除前先停下来

目录本身没有被提前删除，但 watcher、HTTP 服务或 goroutine 在测试返回后仍继续访问目录，也会表现为“TempDir 清理太早”。T.Cleanup 按后进先出执行；在调用 t.TempDir 之后注册资源关闭函数，可以让资源先停止，再执行 TempDir 已登记的删除动作。

func TestWatcher(t *testing.T) {
    // TempDir 会为当前 T 注册目录清理动作。
    dir := t.TempDir()
    watcher := startWatcherForTest(dir)

    t.Cleanup(func() {
        // 后注册的 Cleanup 先执行，确保 watcher 不再访问目录。
        if err := watcher.Close(); err != nil {
            t.Errorf("关闭 watcher 失败: %v", err)
        }
    })

    // 这里完成会触发文件变化的测试逻辑。
}

不要让脱离测试控制的 goroutine 持有临时目录路径。理想做法是给后台任务提供关闭方法或可取消的上下文，并在 Cleanup 中等待它真正退出，而不是只发送停止信号。

复现与排查清单

如果错误只在 CI 或高并发环境出现，可以固定测试名反复执行，并启用竞态检测：

# 重复目标测试并开启竞态检测，放大并行清理和共享写入问题。
go test -run '^TestIndexFiles$' -count=100 -race ./...

• 报错是 no such file or directory：先确认目录由哪个 T 创建，再找父函数中的 defer RemoveAll。
• 只有并行子测试失败：检查子测试是否调用了 t.Parallel，以及父函数是否在它恢复前返回。
• 测试结束后仍有文件访问：检查后台 goroutine、watcher 和 server 是否在 Cleanup 中等待退出。
• 兄弟子测试互相污染：给每个子测试独立调用 t.TempDir，或在共享根目录下建立唯一子目录。
• 需要保留失败现场：不要破坏 TempDir 的清理语义，应在失败分支显式复制必要工件到测试输出位置。

一句话结论

判断 t.TempDir 何时清理，只要找到调用它的那个 testing.T：目录会活到这个测试和它的全部子测试完成。共享就由父 T 创建，隔离就由子 T 创建；遇到并行子测试，使用测试生命周期的 Cleanup，不要用父函数的 defer 代替。