Fuzz 测试发现输入后如何固定回归种子

Fuzz 测试找到一个失败输入后，最稳妥的做法不是把终端里的字符串抄到注释里，而是把它纳入测试的 seed corpus。短小、稳定、能表达缺陷的输入可以写进 f.Add；Go 自动生成并保存到 testdata/fuzz/FuzzXxx 的语料文件也应保留在仓库中。这样，普通 go test 会先回归它，之后再次执行 Fuzz 时也会从这组输入开始。

固定回归种子的核心是“保留失败语料 + 用 f.Add 表达可读的最小案例”。文本输入优先写进 f.Add；不可读或包含特殊字节的输入保留 Go 生成的语料文件，不要手工改写其编码。

失败输入为什么会变成回归材料

Go 原生 Fuzz 测试有两类初始输入：测试代码里的 f.Add 种子，以及测试运行过程中积累的语料文件。Fuzz 发现失败后，会尽量缩小输入，并把可复现的输入保存到当前包的 testdata/fuzz/FuzzXxx 目录。这个文件不是装饰性的日志，而是下次测试要读取的回归材料。

因此，不要只复制一行失败日志。日志可能转义了换行、零字节或非 UTF-8 字节，而语料文件保存的是测试真正收到的参数。若输入很短且可读，再把同一个案例转成 f.Add，能让代码审查者直接看懂缺陷。

可读的时间输入直接写进 f.Add

下面用一个“布局必须能解析并得到 UTC 时间”的小函数演示固定种子。示例中的两个输入只是演示数据；真实项目应替换为 Fuzz 找到的最小失败案例。代码注释说明了为什么同时保留一个合法种子和一个带时区的边界种子。

package timeparse

import (
	"testing"
	"time"
)

const layout = "2006-01-02 15:04:05 -0700"

func parseEventTime(value string) (time.Time, error) {
	// Parse 只接受固定布局；错误必须交给调用方判断，不能静默使用本地时区。
	return time.Parse(layout, value)
}

func FuzzParseEventTime(f *testing.F) {
	// f.Add 把可读的回归案例放进初始种子语料，普通 go test 也会执行它们。
	f.Add("2026-01-02 03:04:05 +0800")
	f.Add("2026-01-02 03:04:05 -0700")

	f.Fuzz(func(t *testing.T, input string) {
		parsed, err := parseEventTime(input)
		if err == nil && parsed.Location() == time.Local {
			// 解析成功也要检查时区边界，避免把偏移输入误当成本地时间。
			t.Fatalf("unexpected local location for %q", input)
		}
	})
}

这里的重点不是让 Fuzz 对任意字符串都返回成功，而是把性质写清楚：能解析时不能丢掉输入中的时区偏移。固定种子应当是“曾经失败、以后必须持续覆盖”的输入，不要把大量随机样本全部手工搬进 f.Add。

生成的语料文件要不要提交

如果失败输入包含不可读字节、长字符串或特殊编码，保留 Go 自动生成的语料文件更可靠。常见路径形如 testdata/fuzz/FuzzParseEventTime/，文件名由工具生成，不应依赖文件名来表达业务含义。可以在旁边的测试注释或提交说明中解释它对应的缺陷。

如果失败输入很短、可读并且适合代码审查，就把它转成一条 f.Add，同时删除重复的语料文件，避免同一个案例维护两份来源。转换时要保持字节完全一致：换行、前后空格、时区符号和非 ASCII 字符都不能凭感觉重打。

用两种命令确认回归不会丢

先运行普通测试。它会执行 f.Add 提供的种子，也会读取包内已保存的 fuzz corpus；如果固定输入再次触发缺陷，应该在这一层就失败。

# 先执行包内测试，快速确认固定种子仍然可复现或已被修复
go test ./...

# 只跑这个 Fuzz 函数的种子阶段，避免其它测试干扰定位
go test -run='^FuzzParseEventTime$' ./...

修复代码后，再用受限时间运行 Fuzz，确认新的变体没有立即击穿同一性质。-fuzztime 只是运行预算，不是“测试通过”的证明；出现失败时应保留新的最小语料，并把问题缩小到一个明确断言。

# 在当前包内继续探索，时间到后正常退出；失败会提前返回
go test -fuzz='^FuzzParseEventTime$' -fuzztime=20s ./...

几个容易误判的边界

• f.Add 不是运行结果缓存。它是初始种子语料，Fuzz 仍会生成和变异新的输入。
• 错误返回也要有性质。时间解析遇到非法布局时，测试应断言错误类型或错误分支，而不是强行要求所有输入成功。
• 时区偏移不能靠机器环境兜底。测试不要把 time.Local 当成输入语义；明确要求偏移时，检查解析后的时区和时刻。
• 二进制语料不要手改。保留工具生成的原文件，避免转义或编码变化让回归案例失真。

相关问题

Q：发现的输入已经写进 f.Add，还需要保留 testdata 文件吗？
如果两者字节完全相同且输入适合代码阅读，通常保留一种来源即可；不可读或较长输入优先保留工具生成的语料文件。

Q：普通 go test 为什么能执行 Fuzz 函数？
它会执行种子语料阶段，但不会像 -fuzz 那样持续生成新输入。

Q：时间解析的回归种子应该优先覆盖什么？
优先覆盖真实缺陷的最小输入，例如偏移、边界日期、额外空格或非法布局；每条种子都应对应一个可解释的断言。

总结来说，固定回归种子不是复制失败日志，而是把最小失败输入纳入 Go 测试的种子语料体系。可读案例用 f.Add 表达，特殊字节案例保留 testdata/fuzz/FuzzXxx，再用普通测试和受限 Fuzz 共同守住时间解析的边界。