智能合约与以太坊 / 系统课时
复现随机失败并缩小反例
复现随机失败并缩小反例
Forge 的模糊测试发现失败后,需要把随机输入转化为可重复、可定位的缺陷。本课通过一个整数边界错误,演示如何读取失败反例、固定随机种子、缩小触发条件,并将最小失败输入写成长期保留的回归测试。
学习目标
- 识别 Forge 输出中的失败输入、反例和执行轨迹。
- 使用固定种子与显式输入重复触发缺陷,缩小失败边界。
- 将随机发现转化为确定性回归用例,并验证修复效果。
构造一个可复现的边界缺陷
准备已安装 Foundry、可执行 forge --version 的开发环境。以下示例适用于支持 Solidity 0.8.20 的 Foundry 版本,新建一个标准项目:
forge init fuzz-repro
cd fuzz-repro
forge --version预期结果:项目创建成功,版本命令显示本机 Forge 版本号,实际版本号因安装环境而异。
在 test/Boundary.t.sol 中编写完整测试。示例中的合约本应把超过 100 的输入限制为 100,却错误地把 100 本身也限制为 99。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {Test} from "forge-std/Test.sol";
contract Boundary {
function normalize(uint256 amount) external pure returns (uint256) {
// 故意保留边界缺陷:100 被错误地变成 99。
if (amount >= 100) return 99;
return amount;
}
}
contract BoundaryTest is Test {
Boundary internal target;
function setUp() public {
target = new Boundary();
}
function testFuzz_Normalize(uint256 amount) public view {
// 规范要求:超过 100 的输入被限制为 100。
uint256 expected = amount > 100 ? 100 : amount;
assertEq(target.normalize(amount), expected);
}
function test_Regression_AtBoundary() public view {
assertEq(target.normalize(100), 100);
}
}执行模糊测试时,先筛选 testFuzz_Normalize,避免固定回归测试干扰对随机结果的观察。
forge test --match-test testFuzz_Normalize --fuzz-runs 1000 -vvv预期结果:模糊测试失败,Forge 报告断言错误,并展示触发失败的输入或反例信息。随机输入未必是 100,也可能是大于 100 的其他整数;不同版本的输出格式和统计信息可能不同。
读取失败输入与执行轨迹
Forge 的失败报告通常包含测试名称、失败原因、反例及运行统计。定位时应优先看具体断言,而不是只关注最后的测试汇总。
本例可以根据输入范围判断失败机制:
| 输入范围 | 规范期望 | 实际行为 | 结果 |
|---|---|---|---|
| 0~99 | 原值 | 原值 | 通过 |
| 100 | 100 | 99 | 失败 |
| 101 及以上 | 100 | 99 | 失败 |
如果 Forge 报告 amount = 101,这只是一个有效反例,并不意味着 101 是最小失败值。对于本例,100 才是满足失败条件的最小非负整数。
为了观察具体调用,执行:
forge test --match-test test_Regression_AtBoundary -vvvv预期结果:回归测试失败,执行轨迹中可观察到 normalize(100) 返回 99,随后 assertEq 检查失败。具体 Gas 数字、轨迹缩进和断言文字依版本而异。
分析轨迹时依次确认调用参数、返回值、断言期望值以及失败发生的位置。不要把测试断言写错、合约主动回退和返回值错误混为一谈。
固定随机种子并重复失败
要重复随机输入搜索过程,可以给 Forge 指定固定种子,同时保留测试代码、编译配置和模糊测试运行次数。
forge test --match-test testFuzz_Normalize --fuzz-seed 0x1234 --fuzz-runs 1000 -vvv预期结果:该测试仍然失败;在相同 Foundry 版本、配置和初始状态下,固定种子有助于重复输入生成过程。由于本例大量输入都能触发失败,命中概率很高,但不能假设每个种子下报告的反例完全相同。
也可以在 foundry.toml 中设置固定种子:
[profile.default.fuzz]
runs = 1000
seed = "0x1234"这段配置控制默认 Profile 下的模糊测试运行次数和随机种子。通过 forge config 检查合并后的有效配置,再执行对应测试验证设置是否生效。
要区分三种复现方式:
- 固定种子:重放相近的随机搜索过程,适合调查最初如何发现问题。
- 已保存反例:Forge 可以从失败缓存中重放既有反例,适合快速重现。
- 固定输入回归测试:直接执行确定的边界输入,最适合长期防止缺陷重新出现。
forge test --rerun 可以筛选上一次记录为失败的测试,但它不等价于重新生成完全相同的一批随机数据。对于已经明确的缺陷,优先保留固定输入回归测试。
缩小反例并确认失败边界
反例缩小的目标是找到容易理解、足以证明问题的输入,而不是简单追求数值越小越好。对于一个整数参数,可以通过边界二分、相邻值检查和业务规则分析来缩小范围。
假设某次运行报告失败输入为 1000,可以按以下顺序检查:
- 测试 500,确认仍然失败。
- 测试 250,确认仍然失败。
- 测试 125,确认仍然失败。
- 测试 99,确认通过。
- 测试 100,确认失败。
这组观察把触发条件锁定为 amount >= 100。二分成立的前提是当前区间具有可利用的单调失败性质;对哈希碰撞、特定字节组合或多个参数之间的关联错误,不能直接套用二分法。

进一步检查 0、1、99、100、101 和 type(uint256).max,可以覆盖正常输入、边界相邻值和极大输入。这里采用显式边界判断,避免为了计算期望值而产生额外的算术溢出。
固化回归测试并验证修复
前面的 test_Regression_AtBoundary 已把最小失败输入 100 固定下来。修复合约时只修改 normalize 的边界逻辑,其余测试保持不变:
// 片段示例:替换 Boundary 合约原有的 normalize 函数。
function normalize(uint256 amount) external pure returns (uint256) {
// 只有超过上限时才进行截断。
if (amount > 100) return 100;
return amount;
}该片段依赖前面完整示例中的 Boundary 合约。修复后,输入 99、100、101 分别得到 99、100、100,满足最初的规范。
执行固定回归测试和原始模糊测试:
forge test --match-test test_Regression_AtBoundary -vv
forge test --match-test testFuzz_Normalize --fuzz-seed 0x1234 --fuzz-runs 1000 -vv预期结果:两条命令均显示对应测试 [PASS],退出码为 0。模糊测试会显示运行次数和 Gas 统计,具体数字取决于 Foundry 版本与执行环境。
实际项目还应保存三类信息:失败函数与输入、失败时使用的 Forge 版本和配置、修复对应的回归测试名称。如果测试依赖主网分叉,还需要固定区块号和外部状态,单纯固定随机种子不足以保证结果一致。
最终验收标准是:原始反例在修复前可以稳定触发失败;修复后固定回归测试通过;再次运行模糊测试也不再发现相同问题。这样,随机搜索得到的一次性发现就转化成了可持续执行的边界验证。