Go fuzz 测试怎么保存可复现的失败输入

Go fuzz 找到一个会 panic 或断言失败的输入后，最可靠的保存方式不是复制终端日志，而是保留它生成的语料文件：放在 testdata/fuzz/FuzzXxx 下。修复代码后，普通 go test 会再次执行这条失败语料；需要单独定位时，再使用输出里的 go test -run=FuzzXxx/。

先把种子和失败输入放到正确的语料边界

一个 fuzz 测试通常有两类输入来源。简单种子可以直接写在 FuzzXxx 中；需要长期保留的失败样本则落到与测试包同级的 testdata/fuzz/FuzzXxx。两者都会在启用 fuzz 前先被执行，但职责不同：前者描述测试起点，后者记录已经发现、修复后仍要防回归的具体样本。

func FuzzParse(f *testing.F) {
    // 小种子覆盖空输入、普通输入和边界字节。
    f.Add([]byte{})
    f.Add([]byte("id=42"))

    f.Fuzz(func(t *testing.T, input []byte) {
        // 这里放待验证的解析不变量，而不是修改全局状态。
        _, err := Parse(input)
        if err != nil {
            t.Skip() // 示例只关心可解析输入的后续不变量。
        }
    })
}

如果 fuzz 目标只有一个 []byte 参数，失败文件会保存一个 []byte 值；如果目标是 string, int64，文件中也必须按这个顺序保存同样的两种类型。不能把“看起来相同”的整数或字符串随意换成另一种类型。

用有限时长运行并定位失败文件

开发机上建议先给 fuzz 设置一个明确的时间窗口，避免把“本轮没有找到失败”误解为永久安全。下面的命令只限制本次探索时长；发现失败时，Go 会先尝试最小化输入，再打印文件位置和可复现命令。

# 将探索窗口限制为 30 秒，避免命令无限运行。
go test -run '^$' -fuzz '^FuzzParse$' -fuzztime 30s

# 只回归某个失败语料；hash 从 fuzz 输出中原样复制。
go test -run='^FuzzParse/af69258a12129d6cbba438df5d5f25ba0ec050461c116f777e77ea7c9a0d217a$'

这里的 -run '^$' 用来跳过普通测试，减少进入 fuzz 前的无关耗时；如果包里的其他测试本来就是前置检查，也可以去掉它。失败样本的文件名由 Go 生成，不要为了“好看”改成普通文本文件名，否则工具可能无法识别其语料格式。

修复后用普通 go test 固化回归

失败文件写入后，先不要急着删除。打开它可以看到类似下面的结构：第一行声明 fuzz 语料格式，后面的每一行对应一个 fuzz 参数。提交代码时，将它和测试一起纳入版本控制，修复完成后执行普通 go test。

go test fuzz v1
[]byte("id=42")

普通测试模式会执行 f.Add 提供的输入，也会执行 testdata/fuzz/FuzzParse 中的文件。因此“修复后 go test 通过”才是回归闭环；单独的 fuzz 长跑只是继续寻找新路径，并不能替代这一步。

注意，fuzz 运行时还会在 $GOCACHE/fuzz 保存能扩大覆盖率的生成语料。这部分是本机缓存，不是团队共享的失败样本。持续运行后缓存可能变大，可以按团队的清理策略处理，但不要把它误提交进项目。

保存失败时先查这张迁移清单

最小可执行的迁移清单是：保留生成的文件；确认目录和 FuzzXxx 名称一致；核对每个参数的类型；修复根因；运行普通 go test；最后再决定是否补充一条更易读的 f.Add 种子。不要用改标题、改 hash 或删除样本来“解决”重复失败。

常见问题

失败输入一定会保存到 testdata/fuzz 吗？

优先写入该目录；如果目录不可写，Go 会把它写到 build cache 的 fuzz 缓存目录，需根据输出定位并恢复可提交的仓库样本。

f.Add 的种子需要提交吗？

测试代码本身随项目提交。少量稳定种子适合用 f.Add 表达；较大的二进制或失败样本更适合使用语料文件。

只运行 go test -fuzz 就能验证修复吗？

不能替代普通回归。修复后先运行普通 go test，确认仓库中的失败语料已经通过，再按需要继续 fuzz。

GOCACHE/fuzz 里的文件要加入 Git 吗？

通常不要。它是 fuzz 引擎维护的覆盖缓存；应提交的是测试包下能稳定复现问题的语料文件。