Go test2json 的 testdata 黄金文件机制：test 输出如何被精确转换为 JSON 事件流

本文聚焦 Go 源码树中 test2json 测试数据目录说明 所定义的 <test>.src / <test>.test / <test>.json 三件套黄金文件约定，结合 TestGolden 测试实现 与 转换器源码，完整拆解 go test -json 背后的转换校验体系：读完后你能理解 test2json 的事件流格式如何在不同输入分片方式下被逐字节验证，以及如何在本地运行或再生成这些黄金文件。

test2json 在 Go 测试体系中的位置

go test -json 的机器可读输出并不是 testing 包直接打印的，而是由一个专门的转换层完成：cmd/internal/test2json 包实现"测试二进制输出 → JSON 事件流"的转换，被 cmd/test2json 命令行工具 和 cmd/go 共同使用（test2json.go 的包注释明确了这一职责）。

cmd/test2json/main.go 的文档给出了该工具的完整用法约定：

go tool test2json [-p pkg] [-t] [./pkg.test -test.v=test2json]

• -p pkg：在每个事件中报告被测包名；
• -t：在事件中加入时间戳（对应 Mode 常量中的 Timestamp 位）；
• 测试二进制建议以 -test.v=test2json 启动，该模式下测试框架会为"测试框架行"（=== RUN、--- PASS 等）加上 ^V（\x16）前缀、为 t.Error/t.Fatal 输出加上 ^O（\x0f）/^N（\x0e）包裹，其余位置的这些控制字符则用 ^[（\x1b）转义。仅用 -test.v 也能工作，但保真度较低；
• 若测试二进制是脱离 go test 单独运行的，才需要 go tool test2json；多包场景应始终使用 go test -json。

输出的 JSON 流是换行分隔的 TestEvent 序列，字段包括 Time、Action、Package、Test、Elapsed、Output、OutputType、FailedBuild；Action 取值限定为 start、run、pause、cont、pass、bench、fail、output、skip 等固定集合，且每条流必然以 start 事件开头。OutputType 则区分普通输出（空）、框架行 frame、错误输出 error 及其续行 error-continue——这套语义正是黄金文件验证的对象。

testdata 目录的三件套约定

README.md 是该目录的权威说明，全文定义了一套针对 TestGolden 的黄金文件组织规则。对于每一组以 <test> 为前缀的文件：

1. <test>.src（可选）：若存在，TestGolden 会把它当作脚本测试（script test）执行，并验证脚本的真实输出与 <test>.test 一致。这一层验证的是 testing 包本身产生的原始输出——即测试框架打印的内容确实是 test2json 预期的输入形态；
2. <test>.test（必需）：TestGolden 读取它，交给一个 Converter 处理，验证转换结果与 <test>.json 一致。这一层验证的是 test2json 把原始输出翻译成 JSON 事件流的行为。

也就是说，.src → .test → .json 形成一条两级校验链：第一级锚定"测试框架的输出长什么样"，第二级锚定"转换器对这些输出的解析结果长什么样"。

当前 testdata 目录 实际包含的黄金用例覆盖了多种典型场景（以下清单来自目录实际内容）：

用例前缀	覆盖的主题
frame、framebig、framefail、framefuzz	框架行（framing）识别、超长框架行、含框架行的失败/模糊输入
frameescape、ascii、unicode、smiley	控制字符转义、ASCII 全字节、Unicode 与表情符号
multiline-error（仅 .src）	多行错误输出的标记包裹
attr、bench、benchfail、benchshort、empty	=== ATTR 属性行、基准测试、空测试等
panic、timeout、vet	崩溃、超时、vet 失败等异常路径
issue23036、issue23920、issue29755	历史缺陷的回归用例

其中 frameescape 和 multiline-error 带有 .src 脚本输入。以 frameescape.src 为例，它是一个 txtar 归档，头部第一行指令 ! go test -v=test2json 声明要执行的命令，归档体内附带真实的测试源码：

func TestAscii(t *testing.T) {
	t.Run("Log", func(t *testing.T) {
		for i := rune(0); i < 0x80; i++ {
			t.Log(string(i))
		}
	})
	t.Run("Error", func(t *testing.T) {
		for i := rune(0); i < 0x80; i++ {
			t.Error(string(i))
		}
	})
}

这种"全字节遍历"的构造方式专门用来暴露转义标记（^V/^O/^N/^[）与测试输出中出现的任意控制字节之间的冲突。从目录结构看，multiline-error.src 目前没有配对的 .test 文件，而 TestGolden 只按 *.test 取用例，因此它目前是一份未被主测试流程直接消费的独立输入数据。

TestGolden 的完整校验流程

理解这套机制的核心是读 TestGolden。它的执行流程可以概括为以下步骤：

第 1 步：发现用例。 通过 filepath.Glob("testdata/*.test") 收集所有黄金用例，为每个 <test>.test 派生一个子测试，名称取文件主干（如 frame、bench）。

第 2 步（仅对含 .src 的用例）：执行脚本测试，锚定第一级。 runTest（test2json_test.go#L177-L247）借助 cmd/internal/script 引擎工作：

• 用 txtar.ParseFile 解析 .src 归档，把其中的文件（go.mod、x_test.go 等）解包到临时目录；
• 执行归档注释头中的脚本指令（即真实的 go test -v=test2json），拿到 stdout；
• 在返回前做一处裁剪：strings.LastIndex(stdout, "\n\x16=== NAME")，即 丢弃最后一个 ^V=== NAME 标记之后的内容。=== NAME 行是测试框架为了"让 test2json 把后续输出归因到正确的测试"而额外生成的辅助行（转换器源码中对它的注释是"本行只用于纠正 c.testName，不产生事件"，见 test2json.go#L366-L370），裁剪后剩下的输出才是稳定的、可进黄金文件的形态；
• 将脚本输出与 <test>.test 做原始字节比对，比对逻辑由 diffRaw 完成（见下文）。

第 3 步：逐行喂入，验证主路径。 无论是否执行过 .src，测试都会把 <test>.test 的内容按行写入一个 Converter（NewConverter(&buf, "", 0)），逐段调用 writeAndKill，最后 Close()，再与 <test>.json 比对。

这里有一个值得注意的防御性技巧——writeAndKill：

// writeAndKill writes b to w and then fills b with Zs.
func writeAndKill(w io.Writer, b []byte) {
	w.Write(b)
	for i := range b {
		b[i] = 'Z'
	}
}

每次写入后立刻把源缓冲区填成 'Z'。如果 Converter 内部错误地"持有"了调用方切片（而非拷贝），后续操作会看到一片 Z，测试立即失败。这是防止缓冲区复用类 bug 的常用手段。

第 4 步：多边界条件子测试。 主路径通过后，测试再用同一份输入以四种不同的"分片方式"重跑转换器，覆盖真实场景中管道读取的不确定性：

• bulk：整个输入一次性写入；
• crlf：把输入中的 \n 全部替换成 \r\n 后整体写入，验证 Windows 换行兼容（比对前再把输出的 \r\n 归一化回 \n）；
• even2 / odd2：每次只写 2 个字节，分别从偶数位和奇数位开始切分，制造 UTF-8 序列、行边界恰好落在两次 Write 中间的极端情形；
• tiny5…tiny8：把全局输出缓冲区 outBuffer（默认 1024）临时改小到 5～8 字节，专门验证"输出缓冲极小时 UTF-8 多字节序列不被拆断"。这正是 Converter 中 trimUTF8 的职责：在缓冲溢出处回退到最近的合法 UTF-8 边界（test2json.go#L661-L688），配套的单测 TestTrimUTF8 用 "hello α ☺ 😂 world"（分别覆盖 1/2/3/4 字节字符）逐切点验证。

第 5 步：-update 再生成黄金文件。 测试文件头部定义了 var update = flag.Bool("update", false, "rewrite testdata/*.json files")（test2json_test.go#L29）。加上 -update 运行时，脚本测试的输出会重写 <test>.test，Converter 的结果会重写 <test>.json，并直接返回（不再做比对）。修改转换器行为后，这是官方认可的再生成入口。

两级比对函数的设计

• diffRaw（test2json_test.go#L379-L412）用于 .src → .test 比对。它先用正则 \d*\.\d*s 把两侧的运行时长统一替换成 X.XXs 占位符（耗时本身不可复现），比对失败时再调用 escapeNonPrinting 把不可打印字符转义为 \xNN 形式，并在差异首次出现的行上用 » 标出，便于人工定位；
• diffJSON（test2json_test.go#L261-L377）用于 .test → .json 比对。它不是简单的字节相等，而是把两侧都解析成事件序列后做"容差匹配"：非 output 事件必须逐字段严格相等，而连续的 output 事件允许在同一 Test 名下合并文本后比较——因为 output 事件如何切分取决于写入分片，属于合法实现自由度。失败时会打印两侧当前游标附近的上下文行（标记 »），即源码注释所说的 "events out of sync" 报告。

一个具体用例的逐事件走查：frame

以最短的完整用例 frame.test 和 frame.json 为例（测试输出中框架行的 ^V 前缀在源文件中不可见，这里从 JSON 侧反推更清晰）：

=== RUN   TestAscii          <- 框架行（^V 前缀）
=== RUN   TestNotReally      <- 框架行（^V 前缀）
--- PASS: TestAscii          <- 结果报告行
    i can eat glass, ...    <- 缩进的普通输出
FAIL
PASS                         <- 框架行（^V 前缀）

转换结果是 10 个事件：

1. {"Action":"start"} —— 由 NewConverter 无条件首发（test2json.go#L143）；
2. {"Action":"run","Test":"TestAscii"} —— === RUN 行生成 run 事件；
3. {"Action":"output",...,"OutputType":"frame"} —— 框架行本身也会作为输出事件重放，类型为 frame，保证"所有 output 事件拼接 = 原始输出"这一不变量；
4. 第 4 行事件无 OutputType——普通输出（此时归因于最近 run 的 TestNotReally 尚未产生事件，testName 仍为 TestAscii）；
5. --- PASS: TestAscii 触发两个动作：先发 pass 事件（注意 PASS 报告是延迟发出的——flushReport 在更浅的更新行出现或流结束时才把挂起报告写出，见 test2json.go#L394-L402），再把该行本身作为 frame 输出事件；
6. 末尾 PASS 使转换器记录整体结果为 pass，Close() 时补上最终的 {"Action":"pass"}（无 Test 字段，代表包级结果）。

再看 bench.test → bench.json 则能看到基准测试的特殊规则：BenchmarkFoo-8 2000000000 0.00 ns/op 这种结果行没有 Test 字段（直接作为包级 output 事件），而 --- BENCH: 行触发的后续日志输出都带 Test:"BenchmarkFoo-8"，最终以 bench 事件收尾。这一行为与 main.go 文档中"benchmark 报告" 的描述一一对应。lineBuffer 中还有一个专门为此设计的分支：缓冲区尚未见到换行时，若已能识别出形如 Benchmark... 的合法基准名后跟 \t，会提前把该行切出走 part 回调（test2json.go#L561-L575），使基准结果行不必等换行符即可低延迟发出。

转换器内部：标记、状态机与缓冲

黄金文件之所以稳定，根源在于 Converter 的确定性状态机：

• 四个控制标记（test2json.go#L171-L176）：markFraming='V'&^'@'（^V，框架行前缀）、markErrBegin='O'&^'@'（^O，错误起始）、markErrEnd='N'&^'@'（^N，错误结束）、markEscape='['&^'@'（^[，转义）。writeOutputEvent（test2json.go#L425-L511）逐字节扫描输出，处理转义对跨 Write 调用被拆开的情况（markEscape 状态位），并把 ^O…^N 之间的内容标成 error/error-continue——这也解释了为什么 testing 包 中 strErrBegin = string(markErrBegin) 等常量与这里的值保持一致；
• 双 lineBuffer：input 缓冲负责把输入切成"整行"交给 handleInputLine，output 缓冲负责把行（或长行的分段）交给 writeOutputEvent。indexEOL 的判定比单纯找 \n 更细：行中出现的 ^V（非行首）同样算边界，以适配 -test.v=test2json 的框架行标记；
• handleInputLine 的分发逻辑（test2json.go#L221-L384）：识别 8 种 === 前缀（RUN/PAUSE/CONT/NAME/PASS/FAIL/SKIP/ATTR/ARTIFACTS）与 4 种缩进可变的 --- 报告前缀；普通行则按缩进深度在"当前子测试报告栈"中做输出归因；PASS/FAIL 终行结束整个报告栈并锁定包级结果。markFraming 字段记录"上一行是否带 ^V"，使转换器能兼容带标记与不带标记（仅 -test.v）两种输入——这正是 frame.test 里 FAIL 行无标记也能被正确当作输出处理的原因；
• 缓冲尺寸：inBuffer=4096 / outBuffer=1024，源码注释解释了取值理由：输入缓冲须能容纳单条最长的测试指令行（如极深的子测试名），输出缓冲须不小于 utf8.UTFMax 且其大小直接限制了单个 output 事件 Output 字段的最大长度。

如何运行与再生成

在完整检出本仓库后（即 Go 源码树），这些测试属于 cmd 模块：

# 运行 test2json 的全部测试（含 TestGolden 与各边界子测试）
go test cmd/internal/test2json

# 只看黄金文件比对，附带子测试名
go test cmd/internal/test2json -run TestGolden -v

# 修改 Converter 行为后，再生成 testdata 下的 .test / .json 黄金文件
go test cmd/internal/test2json -run TestGolden -update

适用前提：需具备能构建 Go 源码树自身的环境（源码树自举编译），因为含 .src 的用例（frameescape 等）会真实执行 go test -v=test2json。对照阅读路径建议：README.md（约定）→ test2json_test.go（校验流程）→ 任一对 .test/.json（如 frame）→ test2json.go（转换实现）→ cmd/test2json/main.go（对外格式契约）。

小结

testdata/README.md 用不到 10 行文字定义了 test2json 质量保障的核心骨架：.src 脚本测试锁定"测试框架原始输出"，.test/.json 黄金对锁定"JSON 事件流翻译"。围绕这一骨架，TestGolden 用逐行、整块、CRLF、奇偶 2 字节分片、极小输出缓冲五类输入方式交叉验证了转换器的分片鲁棒性，用 writeAndKill 堵住缓冲区持有问题，用 diffJSON 的事件级容差比对在"切分自由"与"内容确定"之间取得了平衡，再用 -update 标志提供了黄金文件的官方再生成通道。这套"两级锚定 + 多边界重放"的模式，对任何需要把文本流转换成结构化事件且要求逐字节可复现校验的项目，都有直接借鉴价值。