Go 模糊测试发现失败输入后怎么固定成回归用例

Go 模糊测试发现失败输入后，不需要手工把随机值改写成普通测试。go test -fuzz 会把缩减后的失败输入写入 testdata/fuzz//；保留这个文件并提交到版本库，后续普通 go test 就会自动重放它。真正稳定的做法是：先用输出中的子测试名单独复现，再把种子文件作为回归资产提交，修复后先跑回归，最后按需要继续模糊探索。

官方资料：https://pkg.go.dev/testing#F

失败输入不是一次性的 fuzz 日志，而是一条已经被 Go 最小化的测试样本。目录、文件内容和回归命令都应保留下来；不要只复制终端里显示的字符串。

• 落盘位置：testdata/fuzz//哈希文件名。
• 单独复现：使用输出里的 go test -run=FuzzTestName/子测试标识。
• 日常回归：直接执行 go test，它会加载种子语料。
• 继续探索：修复并确认回归通过后，再执行带 -fuzz 的命令。

失败输入为什么会变成可提交的种子

模糊测试函数通常接收 *testing.F，先用 f.Add 放入已知种子，再通过 f.Fuzz 声明真正的测试目标。Go 运行时会在这些种子和生成输入上寻找使断言失败的值；发现失败后，它会尽量缩短输入，并将结果放进以 fuzz 测试名命名的目录。

func FuzzDecode(f *testing.F) {
    // 这些输入用于建立基线，也会参与普通 go test 回归。
    f.Add([]byte("name=go"))
    f.Fuzz(func(t *testing.T, data []byte) {
        // 这里放待验证的属性，不要依赖某个随机值的出现顺序。
        if err := checkRecord(data); err != nil {
            t.Fatalf("record rejected: %v", err)
        }
    })
}

输出中常见的关键信息是 Failing input written to testdata/fuzz/FuzzDecode/...。这条路径比日志中的展示值更重要，因为文件里保存的是 Go fuzz corpus 格式，第一行是版本标记，后面按参数类型记录实际值。多参数 fuzz 目标也应完整保留整个文件。

先用 -run 固定复现同一个问题

不要一看到失败就再次启动长时间 fuzz。输出通常会给出一个可复制的子测试标识，例如：

# 只重放这一个已经保存的失败样本
go test -run='FuzzDecode/af69258a12129d6cbba438df5d5f25ba0ec050461c116f777e77ea7c9a0d217a'

# 只运行该 fuzz 测试的全部种子，不继续生成随机输入
go test -run='FuzzDecode$'

第一条命令适合定位根因：它把问题缩小到单个输入。第二条命令适合确认目录里的历史种子是否都能正常执行。这里的单引号只是为了保护 shell 中的特殊字符；子测试名应以本次 fuzz 输出为准，不要手写一个看起来相似的哈希。

把 testdata/fuzz 当作回归代码的一部分

确认失败文件确实位于当前包的 testdata/fuzz/ 下后，直接纳入版本控制。不要把它移动到任意 fixtures 目录，也不要只把内容复制到 f.Add：前者会让 Go 测试框架找不到语料，后者会让仓库失去“这次失败由 fuzz 自动缩减得到”的清晰边界。

# 查看当前包里将被普通 go test 自动加载的种子目录
find testdata/fuzz -type f -maxdepth 2 -print

# 提交前先执行固定回归；失败时保留完整测试输出
go test ./...

语料文件可以与测试代码一起评审：代码解释“什么性质必须成立”，种子文件解释“哪个边界曾经打破过这个性质”。如果文件内容包含敏感业务数据，应先用可公开的等价输入重现问题，再提交替代样本；不能把真实凭据或用户数据带入 corpus。

修复后如何安排回归和下一轮 fuzz

修复顺序建议固定下来：先运行失败样本的 -run 命令，再运行包级或仓库级 go test，确认所有历史种子通过后才重新启动 fuzz。这样能区分“已知问题没有回归”和“探索阶段发现了新的输入”。

# 修复后先重放单条边界样本，再覆盖整个仓库
go test -run='FuzzDecode/af69258a12129d6cbba438df5d5f25ba0ec050461c116f777e77ea7c9a0d217a'
go test ./...

# 需要继续找新边界时再限制探索时间，避免命令无限运行
go test -fuzz='FuzzDecode' -fuzztime=30s

-fuzztime 只是探索时长，不会替代已有种子的回归职责。工程上可以把 testdata/fuzz 的新增文件当成普通测试变更评审：看目录是否对应正确的 FuzzXxx，看失败样本是否能解释一个真实边界，并确认修复没有通过删除语料来“消除”失败。

常见问题

失败文件需要改名吗？

通常不需要。哈希文件名由 Go 生成，用于标识该 corpus entry；优先保留原名和原始格式。

普通 go test 会不会继续随机生成输入？

不会。普通 go test 会执行种子语料；只有显式使用 -fuzz 才进入持续生成输入的探索模式。

修复后还要保留已经通过的失败样本吗？

要保留。它现在就是回归用例，能防止同一边界在后续重构中再次失守。