Go fuzz 测试如何保存和复现崩溃输入

Go fuzz 测试发现失败输入后，不需要自己把参数抄进新的测试函数。go test 会把失败样本最小化并写入 testdata/fuzz/；之后普通的 go test 会自动把这个文件当作种子再次执行。如果只想复现某一条输入，再从输出中的哈希拼出 go test -run=FuzzName/hash 即可。

官方地址：https://go.dev/doc/tutorial/fuzz

一、先把 FuzzXxx、种子和模糊目标接起来

一个可复现的 fuzz 测试通常包含三部分：以 Fuzz 开头的函数名、通过 f.Add 加入的初始样本，以及接收 *testing.T 和待 fuzz 参数的目标函数。下面的断言只表达一个可检查的性质：输入经过规范化后不应触发 panic。示例中的种子是固定输入，生成的输入由 Go 测试框架继续扩展。

func FuzzNormalize(f *testing.F) {
    // 固定样本用于基线覆盖，也方便团队先复查已知边界。
    f.Add("  Go\tFuzz  ")
    f.Add("普通文本")

    f.Fuzz(func(t *testing.T, input string) {
        // 目标函数应保持确定的失败信号；不要在这里吞掉 panic。
        got := strings.TrimSpace(input)
        if strings.ContainsRune(got, '\n') {
            t.Fatalf("规范化结果仍含换行: %q", got)
        }
    })
}

如果你只需要复放已有样本，仍然保留 f.Add，因为它与磁盘上的 corpus 文件一起构成基线。运行时可以先用短时长观察流程：

# 只运行名为 FuzzNormalize 的模糊测试，避免无限运行。
go test -fuzz=FuzzNormalize -fuzztime=30s

二、从失败输出找到真正可复用的输入

发生失败时，重点看两行：Failing input written to ... 给出保存位置，To re-run: 给出精确复现命令。路径通常是 testdata/fuzz/FuzzNormalize/ 下的一串哈希文件；这个哈希是测试框架为 corpus 条目生成的标识，不需要手工改名。

文件不是普通文本参数列表，而是 Go fuzz corpus 格式。第一行类似 go test fuzz v1，后续每一行对应 fuzz 目标的一个参数。字符串、整数等值会按照 corpus 格式编码，因此不要把它改成随意的 JSON 或命令行字符串。

# 下面是文件内容示意，不是需要执行的命令。
go test fuzz v1
string("  Go\tFuzz  ")

目录名中的测试函数和文件名中的哈希共同确定了输入归属。多个参数的 fuzz 目标会在同一个条目里按参数顺序记录多行内容，复现时也不需要把这些值重新拼成函数调用。

三、普通复放和定点复现分别怎么用

失败样本写入后，先执行一次不带 -fuzz 的 go test。它会运行固定种子，也会读取 testdata/fuzz/FuzzNormalize 中的条目；这适合确认修复是否覆盖所有已保存失败输入。

# 自动复放当前模块中已有的 fuzz corpus；退出码仍代表测试结果。
go test

# 只复现某个失败条目；把输出中的真实哈希替换到这里。
go test -run='FuzzNormalize/0123456789abcdef'

# 需要继续寻找新输入时才进入 fuzz 阶段，并限制本轮时间。
go test -fuzz=FuzzNormalize -fuzztime=30s

-run 接收测试名称匹配表达式，所以精确复现时应使用完整的 FuzzTestName/hash，不要只写 FuzzNormalize 后就认为只跑了一条 corpus。若项目还有其他测试，仍可以把包路径和其他常用参数按 CI 的原有方式补上。

四、修复后怎样把崩溃输入留下来

失败 corpus 的价值在于它把一次随机发现变成长期回归。提交代码时保留 testdata/fuzz/FuzzNormalize/ 下的文件；修复后先让普通 go test 复放，再视需要用有限时长的 go test -fuzz 继续探索。不要为了让流水线变绿而删除失败样本，也不要把 fuzz 运行时间当成测试通过的证明。

最后把“输入文件位置、复现命令、修复提交”放在同一条问题记录里。这样下次遇到同类崩溃时，团队面对的是一个可复放的 corpus 条目，而不是一段无法还原的终端日志。

相关问题

Q：失败输入一定会保存吗？
Go fuzz 测试发现失败后会把最小化输入写入对应的 testdata/fuzz/FuzzXxx 目录；如果命令在更早的构建阶段失败，则应先看编译或测试配置错误。

Q：为什么普通 go test 也会跑 fuzz 文件？
因为 corpus 文件会作为 seed corpus 参与 fuzz 测试的基线执行，保存后它就成为该测试的回归输入。

Q：可以直接编辑 corpus 文件吗？
应谨慎处理。它有固定编码格式，优先保留工具生成的原文件；若确实要维护样本，先确认首行版本和各参数的顺序。