Go 模糊测试失败后怎样保留回归语料

Go 模糊测试失败后，最有价值的产物不是终端里那一行错误，而是 Go 已经最小化并保存下来的失败输入文件。不要删除这个 crash artifact，也不要把它移到普通 fixtures 目录；保留在 testdata/fuzz/ 下，先用 go test -run 单独复现，修复后再让默认 go test 自动把它当作回归用例。

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

先准备一个能长期复现的 FuzzParse

模糊测试的回归语料属于测试包的一部分。下面的示例把输入看成一个简单的 key=value 对，重点不在解析规则本身，而在于让读者看清 FuzzParse、参数类型和语料目录之间的关系。

package parser

import (
	"errors"
	"strings"
	"testing"
)

// ParsePair 只接受一个非空 key 和任意 value，返回可供模糊测试检查的结果。
func ParsePair(input string) (string, string, error) {
	parts := strings.SplitN(input, "=", 2)
	if len(parts) != 2 || strings.TrimSpace(parts[0]) == "" {
		return "", "", errors.New("invalid key=value input")
	}
	return strings.TrimSpace(parts[0]), parts[1], nil
}

func FuzzParse(f *testing.F) {
	f.Add("name=go") // 先放入一个稳定种子，帮助测试快速进入有效路径。
	f.Fuzz(func(t *testing.T, input string) {
		key, _, err := ParsePair(input)
		if err == nil && key == "" {
			t.Fatalf("parser returned an empty key for %q", input)
		}
	})
}

这里的模糊测试参数是一个 string。因此，后面由 Go 生成的 corpus 文件也必须描述一个 string 值；如果把测试函数改成接收 []byte 或多个参数，旧语料就不能直接照搬。

从失败输出中保留三项关键信息

运行模糊测试后，失败输出一般会给出文件路径和一条精确的 -run 命令。真正需要保留的是 Fuzz 函数名、文件 hash 和文件路径，三者缺一会让后续复现变得含糊。

# 让模糊测试运行一小段时间，示例只关注失败产物的来源。
go test -fuzz=FuzzParse -fuzztime=30s

# 失败后先查看语料目录，不要把文件复制到临时目录后再调试。
find testdata/fuzz/FuzzParse -type f -maxdepth 1 -print

# 使用输出中的真实 hash，只重放这一条失败语料。
go test -run=FuzzParse/

Go 会先尝试把导致失败的输入缩小到更容易阅读和复现的形式，然后将它写入 testdata/fuzz/FuzzParse/。这个文件不是普通日志：它属于该 fuzz test 的 seed corpus，后续运行普通 go test 时也会被执行。

用 -run 单独重放，不要一上来重新长时间 fuzz

定位阶段应先运行单条 corpus。这样可以区分“某个固定输入必现”与“随机探索过程中偶尔出现”，也能把调试器、日志或断点集中到同一个输入上。

func FuzzParse(f *testing.F) {
	f.Add("name=go")
	f.Fuzz(func(t *testing.T, input string) {
		key, value, err := ParsePair(input)
		if err != nil {
			return // 非法输入是预期分支，不把它误报成回归失败。
		}
		if strings.TrimSpace(key) == "" {
			t.Fatalf("empty key, input=%q value=%q", input, value)
		}
	})
}

如果单条重放仍然失败，就在这一步检查输入如何经过解析函数；如果单条重放已经通过，再检查是不是改动了 fuzz 函数名、测试包路径或构建条件。不要因为一次重放通过就删除文件，它仍然记录着曾经触发过的边界。

修复后让默认 go test 继续执行这条语料

修复动作完成后，先运行默认测试。只要失败文件仍在对应目录中，Go 就会把它作为种子语料执行；这正是“失败输入转成回归用例”的关键，不需要把原始输入重新写进 f.Add。

# 先运行全部种子语料，确认修复没有破坏已有测试。
go test

# 若仍失败，继续用精确 hash 定位，不要删除 corpus 文件来让测试变绿。
go test -run=FuzzParse/

# 修复后的短时间探索，用来寻找同一缺陷的相邻输入。
go test -fuzz=FuzzParse -fuzztime=10s

普通 go test 通过，只能说明当前保存的语料已通过；它不等于新一轮 fuzz 探索没有发现更多问题。两者用途不同：-run 用来复现一个条目，默认测试用来守住已有条目，-fuzz 用来继续探索。

检查 corpus 格式和测试参数是否匹配

Go 的 corpus 文件第一行是编码版本，后面的每一行对应 fuzz target 的一个参数。例如测试函数接收 []byte 和 int64，文件就必须按同样的顺序保存这两个值：

func FuzzDecode(f *testing.F) {
	f.Add([]byte("hello"), int64(1)) // 文件语料也必须按 []byte、int64 的顺序编码。
	f.Fuzz(func(t *testing.T, data []byte, version int64) {
		if version 

go test fuzz v1
[]byte("hello")
int64(1)

常见问题是修改了 fuzz target 的参数顺序，却继续保留旧目录；这时不要手工改 hash 文件内容来“适配”。先确认新的函数签名，再决定把语料转换成新格式或建立新的 fuzz test，避免回归样本的含义被悄悄改变。

提交时保留修复代码和失败语料

一个可复查的提交至少应同时包含三类变化：修复代码、对应的测试逻辑、最小化后的 corpus 文件。这样以后任何人执行默认测试，都能重新触发曾经暴露问题的输入。

# 只查看本次修复和回归语料的变化。
git diff -- parser.go parser_test.go testdata/fuzz/FuzzParse

# 确认失败条目没有被忽略或误移出测试包。
git status --short -- testdata/fuzz/FuzzParse

# 修复和语料一起提交，提交信息写清它们的对应关系。
git add parser.go parser_test.go testdata/fuzz/FuzzParse
git commit -m "fix parser and keep fuzz regression corpus"

几个容易踩坑的地方

失败文件可以删掉吗？

不建议。除非它确认是误报、已经被更小且等价的语料替代，或者测试边界已经有明确迁移方案，否则删除会丢失一次真实回归证据。

为什么普通 go test 也会跑 fuzz 语料？

目录中的文件属于该 fuzz test 的 seed corpus。默认测试会执行这些已知输入；只有带 -fuzz 时才会继续生成和变异更多输入。

文件名 hash 能自己改吗？

不要把 hash 当业务标签手工重命名。调试时直接复制 Go 输出的路径和命令，目录中的文件名用于稳定定位。

什么时候把输入写成 f.Add？

适合少量、易读、对所有开发者都有价值的基础种子。模糊测试自动发现并最小化的失败输入，更适合保留为目录文件，避免测试代码被大段原始数据占满。