Go / 系统课时

使用 Golden File 验证输出

使用 Golden File 验证输出

当被测结果是较长文本、格式化报告或稳定的结构化内容时,逐字段断言会变得冗长。Golden File 把已确认的完整输出保存为基准文件,测试重新生成结果后做整体比较,并通过显式更新和代码审查控制基准变化。

学习目标

  • 判断哪些稳定输出适合使用 Golden File 验证
  • 实现比较、失败提示与显式更新机制
  • 通过差异审查避免错误输出被直接固化为新基准

什么时候适合 Golden File

Golden File 最适合输出内容较长,但整体格式本身就是契约的场景,例如代码生成结果、CLI 报告、模板渲染结果和序列化后的稳定文本。它能让测试只关注“当前输出是否与已批准输出一致”,避免维护大量细碎断言。

如果输出包含时间戳、随机 ID、绝对路径或不保证顺序的集合,应先归一化这些动态部分,否则基准文件会频繁产生无意义差异。对于只有两三个关键字段的业务判断,直接断言字段通常更清楚。

实现比较与显式更新

下面的 report_test.go 使用 testdata/user.golden 保存基准。正常测试只读取并比较;只有显式传入 -update 时才允许重写文件,从而避免测试失败时自动掩盖回归。

go
package report

import (
    "flag"
    "fmt"
    "os"
    "path/filepath"
    "testing"
)

var update = flag.Bool("update", false, "update golden files")

func renderUser(name string, active bool) string {
    return fmt.Sprintf("name: %s\nactive: %t\n", name, active)
}

func TestUserGolden(t *testing.T) {
    got := []byte(renderUser("Ada", true))
    path := filepath.Join("testdata", "user.golden")

    if *update {
        // 更新必须由调用者显式触发,不能在普通测试失败时自动发生。
        if err := os.WriteFile(path, got, 0o644); err != nil {
            t.Fatalf("update golden file: %v", err)
        }
    }

    want, err := os.ReadFile(path)
    if err != nil {
        t.Fatalf("read golden file: %v", err)
    }
    if string(got) != string(want) {
        t.Fatalf("golden mismatch\nwant:\n%s\ngot:\n%s", want, got)
    }
}

初始的 testdata/user.golden 内容如下:

text
name: Ada
active: true

执行普通测试:

bash
go test -run TestUserGolden

预期输出类似如下:

text
PASS
ok  <PATH>  <TIME>

把更新变成受控流程

Golden File 的关键不是“能自动更新”,而是更新后必须判断变化是否符合预期。推荐流程是先让普通测试暴露差异;确认行为变更属于需求后,再显式更新基准,并检查版本控制中的文本差异。

Golden File 更新与审查流程

确认变化是预期行为后执行:

bash
go test -run TestUserGolden -args -update
git diff -- testdata/user.golden

预期结果是测试通过,并由 git diff 展示本次基准文件真实发生的文本变化;如果内容没有改变,第二条命令不会输出差异:

text
PASS
ok  <PATH>  <TIME>
<DIFF_OR_EMPTY>

<PATH>、<TIME> 和 <DIFF_OR_EMPTY> 会随项目路径、运行耗时以及实际修改内容变化。

让失败差异容易阅读

简单文本可以像示例一样同时打印 want 与 got。如果 Golden File 很大,失败日志不应无节制输出整个文件,可以改为使用专门的 diff 库生成行级差异,或者在失败信息中给出基准文件路径,再让开发者通过版本控制工具检查变化。

CI 中应始终运行普通测试,而不是携带 -update。否则错误实现也可能把自己的输出写回基准,使测试立即恢复绿色。Golden File 应被当作需要代码审查的测试契约:只有确认行为变化正确后才更新,并让更新内容与对应实现一起提交。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

使用 Golden File 验证输出

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通