Go fuzz 测试怎么固定回归样本：种子语料、失败复现与 CI 验收

线上接口偶尔收到一段很短、却能让解析器走进异常分支的输入时，单元测试里往往没有留下它。Go 原生 fuzz 测试的价值，就是把这种“当时撞出来”的边界样本保存下来，下一次先回归已知问题，再继续探索未知输入。

先把一个可复现的解析任务交给 fuzz

示例选择一个边界清晰的十六进制解码函数。目标不是证明标准库永远正确，而是验证自己的输入约束：函数不应 panic，返回的字节序列重新编码后应保持规范形式。

package hexinput

import (
    "encoding/hex"
    "testing"
)

func Decode(s string) ([]byte, error) {
    return hex.DecodeString(s)
}

func FuzzDecode(f *testing.F) {
    f.Add("00ff")
    f.Add("")
    f.Add("f")

    f.Fuzz(func(t *testing.T, input string) {
        _, _ = Decode(input)
    })
}

文件名可以是 decode_fuzz_test.go，测试函数必须以 Fuzz 开头并接收 *testing.F。这里的三个 F.Add 是种子，不是限制 fuzz 只能测试三种输入；它们会作为探索的起点，也会在普通回归模式下被执行。

种子语料该放什么，怎么避免只测到“漂亮输入”

种子最值得保存的不是随机字符串，而是业务真实边界：空值、奇数长度、大小写混用、前后空白、刚好超过协议限制的长度，以及曾经在线上触发过 bug 的原始样本。每个种子都应该能解释“为什么留它”，否则几年后只会变成一串没人敢删的魔法值。

如果测试函数需要多个参数，F.Add 的参数顺序和类型必须与 fuzz 回调完全一致。例如测试长度前缀协议时，可以把 []byte 和 uint8 作为两个种子参数，但不要在回调里再把它们偷偷转换成另一套规则。

func FuzzFrame(f *testing.F) {
    f.Add([]byte{0x01, 0x02}, uint8(2))
    f.Fuzz(func(t *testing.T, payload []byte, declared uint8) {
        if int(declared) > len(payload) {
            t.Skip()
        }
        // 在这里验证解码器不会 panic，并检查结果边界。
    })
}

可见的验收点是：执行 fuzz 测试时，种子样本先被运行；如果参数类型不支持、顺序不符或回调签名不匹配，错误应在测试启动阶段暴露，而不是沉默地跳过。

失败样本如何变成永久回归用例

启动持续探索：

go test ./... -run=^$ -fuzz=FuzzDecode -fuzztime=30s

这里用 -run=^$ 避免同时跑普通测试，用 -fuzztime=30s 给本地实验设边界。若 fuzz 找到导致 panic 或断言失败的输入，Go 会在对应包的 testdata/fuzz/FuzzDecode/ 下保存语料文件。文件名由工具管理，内容不要手工改成另一种格式。

修复代码后，先不启动新的随机探索，直接回归失败语料：

go test ./... -run=^FuzzDecode$ -count=1

成功状态应是测试进程退出码为 0，且不再复现原来的 panic 或断言失败。确认后把新增的 testdata/fuzz 文件提交到仓库；它就是这次事故的最小可重复证据。

在 CI 里区分回归和探索

CI 的首要任务是稳定识别已知问题，因此通常先跑普通测试，让 testdata/fuzz 中的失败语料参与回归，再按项目预算决定是否开启短时 fuzz。持续探索不是越久越好：它会受机器性能、随机种子和输入空间影响，应该被当作额外的质量信号。

go test ./... -run=^FuzzDecode$ -count=1
go test ./... -run=^$ -fuzz=FuzzDecode -fuzztime=20s

第一条命令适合每次提交，第二条可以放在夜间或合并前任务。不要只看日志里的“执行了多少次”；真正的成功条件是进程退出码、失败语料是否被保存，以及修复后的回归命令是否通过。

常见问题：Go fuzz 测试的边界怎么判断

F.Add 的样本会限制随机输入范围吗？

不会。它们是初始语料，fuzz 引擎还会变异并探索其他输入。样本的作用是尽快把测试带到有意义的格式附近。

失败语料为什么要提交到仓库？

因为它记录了一个已经发生过的反例。提交后，普通测试可以稳定重放它，避免修复在后续重构中回退。

CI 是否应该一直运行 fuzz？

不建议无边界地运行。回归测试要稳定、快速；探索任务应设置明确的 -fuzztime，并把它当作补充检查。

只有 panic 才值得保留吗？

不是。违反业务不变量、产生非法长度、错误接受不该接受的编码，同样应通过断言让 fuzz 生成可回归的失败样本。

把偶发输入收进团队的测试资产

一套好用的 fuzz 流程不是“跑一次随机测试”，而是把种子、失败语料、修复验证和 CI 预算连成闭环：真实边界从 F.Add 开始，失败输入落到 testdata/fuzz，修复后用普通命令回归，持续探索则在明确时间内提供新的反例。这样偶发问题才不会只留在某台机器的终端里。