Go fuzz 测试发现输入后怎么保存成稳定回归用例

Go fuzz 测试发现问题后，不需要手工把随机输入抄进测试代码。go test -fuzz 会把失败输入缩小并写入 testdata/fuzz/FuzzXxx 目录；把这个 corpus 文件提交到版本库，普通的 go test 也会再次执行它，于是一次随机发现就变成了稳定回归用例。

发现失败后，Go 会把最小输入放在哪里

一个典型的 fuzz 测试以 Fuzz 开头，参数是 *testing.F。f.Add 提供少量种子，f.Fuzz 接收真正的 fuzz target。运行期间如果断言失败，Go 会尝试最小化输入，终端通常会给出类似 testdata/fuzz/FuzzDecode/9f... 的文件路径，以及可复制的 go test -run=FuzzDecode/9f... 命令。

func FuzzDecode(f *testing.F) {
	// 只放少量可读边界，避免用 f.Add 代替自动发现。
	f.Add([]byte("ok"))
	f.Add([]byte{0x00, 0xff})

	f.Fuzz(func(t *testing.T, data []byte) {
		// fuzz target 应尽量确定，不保存可变输入的引用。
		value, err := Decode(data)
		if err != nil {
			return
		}
		if !value.Valid() {
			t.Fatalf("decoded value is invalid")
		}
	})
}

这里的关键不是记住某个 hash，而是保留目录中的文件。文件首行会记录 corpus 格式版本，后面按 fuzz target 的参数类型保存值。只要文件还在，Go 就能在下一次测试中把它当作种子重新执行。

让发现样例进入稳定回归

拿到失败路径后，先只复现这一条：go test -run=FuzzDecode/9f...。这样可以把问题和其他测试、其他随机输入分开。确认修复后，再执行 go test -run=FuzzDecode，它会同时覆盖 f.Add 的种子和 testdata/fuzz/FuzzDecode 中已经保存的失败样例。

# 先复现输出中那一条最小失败样例
go test -run=FuzzDecode/9f...

# 修复后执行该 fuzz 测试的全部种子与回归 corpus
go test -run=FuzzDecode

# 需要继续探索时限制本轮时间，避免把 CI 变成无限 fuzz
go test -fuzz=FuzzDecode -fuzztime=30s

修复提交应同时包含代码和 testdata/fuzz/FuzzDecode 文件。只保存终端日志不够，因为日志没有被 go test 自动加载；只把输入改写成一个普通 TestDecode 也会丢掉 fuzz corpus 的格式和原始边界。若团队需要更醒目的业务说明，可以在测试附近补一句注释，但不要删掉机器生成的样例文件。

什么时候用 f.Add，什么时候保留 corpus 文件

f.Add 适合表达读者一眼能看懂的基础边界，例如空输入、最短合法值和一个典型编码。自动发现的失败样例则更适合保留在 corpus 文件中：它可能包含控制字节、组合参数或不值得塞进源码的长输入。两者都属于 seed corpus，但维护目的不同。

不要为了“看起来整齐”把每个 corpus 文件重新编码成字符串常量，也不要在 fuzz target 中修改输入切片或把它的引用保存到下一轮。测试函数应快速、确定，并把业务断言放在 *testing.T 上；*testing.F 只负责注册种子和启动 fuzz。

常见坑与速查

• 目录写错：必须是当前包下的 testdata/fuzz/FuzzXxx，大小写和 fuzz 函数名保持一致。
• 只跑 fuzz 不跑普通测试：发现问题后先用 -run 单条复现，再用普通 go test 做回归。
• 误删最小样例：修复后保留 corpus，它就是防止同一输入再次破坏行为的证据。
• 类型不匹配：f.Add 的参数必须对应 fuzz target 支持的参数类型，不能随意塞入结构体。

相关问题

失败输入一定会变成最小文件吗？

Go 会尝试最小化失败输入，但最终文件仍应由测试人员确认是否代表真实边界；不要把最小化误解为业务上最短的输入。

修复后还要继续执行 -fuzz 吗？

先用普通 go test 确认已保存样例通过，再按风险安排限时 fuzz；回归与探索是两件不同的事。

可以只提交 hash 不提交文件吗？

不建议。hash 只是定位信息，真正能被 Go 自动加载并重放的是 testdata/fuzz/FuzzXxx 中的 corpus 文件。