Go fuzz 测试发现解析器边界输入的写法

给文本解析器补 fuzz 测试时，关键不是让随机字符串“尽量多”，而是先定义结果契约：合法输入要得到可用记录，格式不完整的输入可以返回明确的输入错误，但不应该触发 panic、越界访问或返回半成品状态。Go 的原生 fuzz 测试把种子语料和持续变异放进 testing.F，很适合从几个有代表性的解析边界开始扩展。

官方资料：https://go.dev/doc/tutorial/fuzz

我会用一个逗号分隔的配置行作为例子：输入包含名称和端口，解析器返回结构化记录或可判断的错误。示例只聚焦种子、Fuzz 函数和错误分类，复杂语法仍应在真实项目中按业务契约补充。

先把解析器的成功契约写清楚

如果测试只写“返回值不为空”，fuzz 找到异常输入后很难判断问题在哪里。先约定三件事：输入有两个非空字段时返回记录；字段数量不足或端口不是数字时返回可识别的输入错误；无论输入是什么，函数都不能 panic，也不能在返回错误的同时交付一条看似有效的记录。

下面的类型和解析函数故意保持短小，方便把注意力放在测试边界上：

package parser

import (
    "errors"
    "strconv"
    "strings"
)

// ErrInvalid 表示输入格式不满足解析器契约，而不是实现崩溃。
var ErrInvalid = errors.New("invalid record")

type Record struct {
    Name string
    Port int
}

func Parse(line string) (Record, error) {
    // 只切一次字段，避免把名称中的后续逗号误当成更多配置项。
    parts := strings.SplitN(line, ",", 2)
    if len(parts) != 2 || strings.TrimSpace(parts[0]) == "" {
        return Record{}, ErrInvalid
    }

    // 端口先去空白，再转换；转换失败统一归类为输入错误。
    port, err := strconv.Atoi(strings.TrimSpace(parts[1]))
    if err != nil || port  65535 {
        return Record{}, ErrInvalid
    }
    return Record{Name: strings.TrimSpace(parts[0]), Port: port}, nil
}

这里的“不变量”是测试真正要保护的东西：成功时 Name 非空、Port 在合法范围内；失败时返回零值记录和 ErrInvalid。这比把每一个可能的随机字符串都列成表格更适合发现组合边界。

用种子语料覆盖正常与边界形态

种子不是随机输入的替代品，而是 fuzz 引擎开始探索时的方向提示。解析器至少可以放入一条正常记录、空输入、缺少逗号、端口越界和带空白的输入。种子应该代表不同结构，而不是只改变名称的拼写。

func FuzzParse(f *testing.F) {
    // 正常值让测试从可成功解析的路径开始探索。
    f.Add("api,8080")
    // 空值和缺字段覆盖最早的输入边界。
    f.Add("")
    f.Add("api")
    // 数值边界帮助 fuzz 更快到达转换和范围判断。
    f.Add("admin,0")
    f.Add("admin,65536")
    // Unicode 名称和首尾空白检查字符串处理路径。
    f.Add("支付, 443 ")

    f.Fuzz(func(t *testing.T, line string) {
        record, err := Parse(line)
        // 解析器对任意字符串都应返回结果或错误，不能让 panic 穿过测试。
        if err != nil {
            if !errors.Is(err, ErrInvalid) {
                t.Fatalf("unexpected parse error: %v", err)
            }
            if record != (Record{}) {
                t.Fatalf("invalid input returned a record: %#v", record)
            }
            return
        }
        // 成功结果必须满足结构化记录的不变量。
        if record.Name == "" || record.Port  65535 {
            t.Fatalf("invalid record: %#v", record)
        }
    })
}

Go 官方 fuzz 测试要求入口函数命名为 FuzzXxx，参数为 *testing.F；真正的 fuzz 目标由 f.Fuzz 注册。上面的种子会先按普通测试路径执行，之后才由 fuzz 运行器变异。

Fuzz 函数只接收能表达边界的参数

解析器的入口如果是字符串，就先把 fuzz 参数保持为字符串。不要为了“增加随机性”在测试函数里再拼接一层不可解释的随机字节，否则发现问题后很难还原输入。需要测试字节级协议时，再把入口改成 []byte，并在解析函数边界明确编码规则。

Fuzz 回调里适合放三类断言：

• 不会因为任意输入而 panic；
• 返回错误时，错误属于约定的输入错误集合，且结果保持零值；
• 返回成功时，记录满足字段范围、必填字段和互相一致等不变量。

不要在回调中断言“任意输入都必须成功”。对解析器来说，无效输入本来就是合法测试空间；真正需要失败的是解析器没有按契约分类，或者在拒绝输入时留下了错误状态。

把失败分成输入错误和实现缺陷

最容易误判的一点，是看到 err != nil 就直接调用 t.Fatal。这样会把 fuzz 找到的大量正常拒绝输入当成缺陷。更稳妥的做法是使用哨兵错误或错误类型，让测试知道哪些错误可以接受。

错误分类还应覆盖“错误和结果同时出现”的情况。比如解析器先填充了 Name，随后发现端口错误，却仍返回这个半成品记录；这不是普通输入错误，而是状态清理不完整。测试中把记录与错误一起检查，才能把这类问题留下来。

用短时运行和回归语料收口

日常开发可以先执行种子回归，确认新加入的种子没有破坏已有测试；需要探索时再指定单个 fuzz 函数和时间上限：

# 先跑普通测试，让种子语料成为稳定回归用例
go test ./...

# 只探索当前解析器，并限制本次本地试跑时间
go test -run=^$ -fuzz=FuzzParse -fuzztime=30s ./...

没有找到失败并不等于解析器被证明正确，短时运行只是一次受限探索。若 fuzz 发现失败，Go 会保留可复现的失败输入；修复后应把这个输入转成明确种子或普通回归用例，再继续运行。这样一次偶然发现才能沉淀成长期保护。

最后检查这四个边界

这套写法的重点不是准备一组漂亮的随机样本，而是让每个结果都能回到解析器契约。种子负责把重要入口交给 fuzz，Fuzz 函数负责表达不变量，错误分类负责区分“输入本来就不合法”和“实现真的坏了”。

相关问题

Go fuzz 测试必须有种子吗？不必须，但高价值种子能让探索更快覆盖成功路径、空值和格式边界。

解析器返回普通 error 怎么办？可以先用哨兵错误或自定义错误类型区分输入错误，测试再使用 errors.Is 或 errors.As。

短时间没有发现问题代表安全吗？不代表。fuzz 是探索工具，运行时间、覆盖路径和输入类型都会影响发现范围。