Go testing.T.ArtifactDir 怎样配合 -artifacts 保存测试产物

Go 1.26 的 testing.T.ArtifactDir 解决的是测试产物放在哪里的问题：测试函数可以把日志、JSON、调试转储等文件写入它返回的目录，同一个测试或子测试重复调用时会得到同一个目录。真正决定这些文件是否在测试结束后保留的是 go test 的 -artifacts 开关。

默认情况下，ArtifactDir 更适合临时排查，目录会在测试结束后清理；需要让 CI 或本地命令保留失败现场时，再使用 -artifacts，并通过 -outputdir 指定输出根目录。

官方文档地址：https://pkg.go.dev/testing#T.ArtifactDir

这个新接口解决了哪类测试问题

测试失败时，单靠断言文本往往不够。复杂输入、临时配置、请求样本或调试日志需要落盘，但测试代码不应该把文件写到固定的相对路径，也不应该自己猜测某个 CI runner 的临时目录。ArtifactDir 把“本次测试可以写入的产物目录”交给测试框架管理。

Go 1.26 的发布说明把它和 go test -artifacts 放在一起：前者提供目录，后者控制是否保存这些目录中的内容。两者是配套关系，不是两个互相替代的目录 API。

最小写法：先把产物写进 ArtifactDir

下面的例子为每次测试生成一个 JSON 结果文件。代码只关心“拿目录并写文件”，不依赖固定工作目录；如果创建或写入失败，直接让测试失败，避免留下一个没有完整内容的假产物。

package artifact_test

import (
    "encoding/json"
    "os"
    "path/filepath"
    "testing"
)

func TestOrder(t *testing.T) {
    // ArtifactDir 由 testing 管理，同一个测试中重复调用会得到同一路径。
    dir := t.ArtifactDir()
    report := map[string]any{
        "test":   t.Name(),
        "status": "failed-example",
    }

    data, err := json.MarshalIndent(report, "", "  ")
    if err != nil {
        t.Fatalf("encode report: %v", err)
    }

    // 文件名固定在测试自己的产物目录内，避免写入共享工作区。
    path := filepath.Join(dir, "report.json")
    if err := os.WriteFile(path, data, 0o600); err != nil {
        t.Fatalf("write artifact %q: %v", path, err)
    }
}

这里的目录是测试框架分配的边界，文件名仍由业务代码决定。建议使用简单、稳定、便于 CI 收集的文件名；如果一个测试会输出多种格式，可以在同一目录下按用途命名，而不是再创建一套与测试名重复的目录层级。

为什么要区分默认模式和 -artifacts

不带 -artifacts 时，ArtifactDir 返回的目录用于测试期间的临时文件，测试完成后会被移除。这样适合本地快速排查，也避免普通测试把大量调试文件长期堆在磁盘上。

当命令带上 -artifacts 时，测试产物会放在输出目录体系中，供失败收集、CI 上传或人工下载。可以用 -outputdir 指定根目录：

# 开启产物保留，并把输出根目录设为当前项目的 test-output。
go test -artifacts -outputdir ./test-output ./...

# 只运行一个测试，便于定位它生成的产物目录。
go test -artifacts -outputdir ./test-output -run '^TestOrder$' ./path/to/package

不要把“调用了 ArtifactDir”理解成“文件一定会永久保存”。是否保留由命令行模式决定，输出根目录也可能被 CI 任务在步骤结束时统一清理。文章中的目录关系是静态说明，实际保存位置应以当前 Go 工具链和运行命令为准。

父测试和子测试怎样划分目录

每个测试或子测试都有自己的产物目录。父测试调用一次得到父测试目录；子测试调用时得到属于自己的目录，同一个子测试重复调用仍保持稳定。这种划分可以避免并行子测试把同名文件写到一起。

func TestMatrix(t *testing.T) {
    // 父测试的目录用于记录整个矩阵的摘要。
    parentReport := filepath.Join(t.ArtifactDir(), "summary.json")
    if err := os.WriteFile(parentReport, []byte(`{"scope":"parent"}`), 0o600); err != nil {
        t.Fatal(err)
    }

    for _, name := range []string{"small", "large"} {
        name := name
        t.Run(name, func(t *testing.T) {
            t.Parallel()

            // 每个子测试写入自己的目录，避免并行运行时覆盖父测试或兄弟测试的文件。
            path := filepath.Join(t.ArtifactDir(), "case.txt")
            if err := os.WriteFile(path, []byte(name), 0o600); err != nil {
                t.Fatal(err)
            }
        })
    }
}

目录隔离解决的是文件命名冲突，不会自动解决测试数据、环境变量或外部服务的并发冲突。并行子测试仍然需要自己隔离数据库记录、端口和共享配置；ArtifactDir 只负责产物路径。

接入 CI 时怎样让失败现场可追踪

在持续集成中，推荐把“是否保留产物”作为测试任务的明确策略：普通快速检查可以不带 -artifacts，失败重跑或需要上传证据的任务则开启它，并把 -outputdir 指向 CI 约定的工作目录。

1. 测试代码只通过 t.ArtifactDir() 获取写入位置，不拼接 runner 私有路径。
2. 命令层统一设置 -artifacts 和 -outputdir，让不同测试包沿用同一收集根目录。
3. 失败任务结束前收集输出目录；成功任务可以不上传，减少制品体积。
4. 文件中只写脱敏后的请求样本、计时信息和诊断结果，不把 Token、Cookie 或个人数据直接落盘。

如果 CI 平台已经有独立的制品上传步骤，测试命令只需要负责生成目录，上传步骤负责保留周期和权限。这样测试代码不需要依赖某一家平台的环境变量，迁移到另一种 runner 时也更容易。

采用前需要留意的边界

• 版本边界。 ArtifactDir 属于 Go 1.26 的 testing API，项目若需要兼容更早工具链，应先用构建约束或旧的测试辅助函数隔离差异。
• 重复调用。 同一测试重复调用返回同一目录，不能把每次调用都当成新的临时空间；需要独立子目录时由业务代码自行命名。
• 清理语义。 未开启 -artifacts 时不要把目录当作长期缓存；测试完成后仍要把关键结果写入断言或日志。
• 路径与权限。 文件名应使用 filepath.Join，权限按产物敏感程度设置，不能因为目录由框架提供就忽略文件内容保护。
• 产物大小。 大型转储、重复日志和每轮循环输出会迅速放大 CI 制品，最好按失败路径采样并限制文件大小。

如何判断这项能力值得采用

可以从三个指标观察效果：失败测试是否能稳定找到对应目录、并行子测试是否还会发生文件覆盖、CI 制品体积是否处在可接受范围。如果第一项明显改善而第二项和第三项没有恶化，说明把产物路径交给 ArtifactDir 的收益已经体现。

它适合需要保存失败现场、测试矩阵较大或存在并行子测试的项目；对只输出一行断言文本的小测试，继续使用日志和断言即可。最终选择不在于 API 新不新，而在于测试产物的生命周期是否已经被团队明确管理。

相关问题

不加 -artifacts 还能在测试运行期间读取文件吗？

可以。目录在测试运行期间可用于写入和读取，但测试完成后不会按长期产物保留来设计。

ArtifactDir 会为每次调用创建新目录吗？

不会。同一个测试或子测试重复调用会返回同一个目录；不同子测试才有各自的目录边界。

开启 -artifacts 后还需要 -outputdir 吗？

不一定，但在 CI 中显式设置 -outputdir 更容易让上传步骤找到统一的输出根目录，也便于本地复现。