Solidity 单元测试工程化：Foundry 测试框架的 Fuzzing 与不变式验证

一、当 Happy Path 测试覆盖不了闪电贷攻击

大多数 Solidity 测试的现状是这样的：为每个函数写两三个手写用例 —— Alice 转账给 Bob、Bob approve 给合约、正常赎回成功 —— 跑通即止。这种 Happy Path 测试在 2023 年以前或许够用，但目前 DeFi 攻击已进化到高度组合化的阶段：攻击者在一个交易里嵌套 5-8 次跨协议调用，利用瞬时价格快照、MEV 捆绑和重入包装来构造攻击序列。手写用例几乎不可能穷举这种组合空间。

Foundry 的 fuzzing 测试是应对这种复杂度的实用方案。它的核心思路很简单：你不用手动枚举边界条件，而是定义"输入空间"和"预期行为"，让框架用随机输入去砸。搭配不变式测试（Invariant Testing），你还可以让框架在整个合约生命周期中持续验证某些"无论如何都不能违背"的规则。

flowchart LR A[定义测试合约] --> B{测试类型} B -->|Fuzz Test| C[随机输入生成器] B -->|Invariant Test| D[状态序列生成器] C --> E[执行函数调用] D --> E E --> F{断言检查} F -->|失败| G[记录最小复现用例] F -->|通过| H[继续下一轮] G --> I[输出 calldata]

在 Foundry 的生态中，fuzzing 已经不再是一个可选的高级技巧。它是构建复杂 DeFi 协议时的工程底线 —— 你可以少写一些单测，但关键的状态转换和处理外部输入的路径，fuzzing 应该成为默认选项。

二、Fuzzing 与不变式测试的原理差异

很多开发者把 Fuzzing 和 Invariant Testing 混为一谈，但它们在 Foundry 中的实现机制有本质区别。理解这个区别直接关系到你能发现什么类型的 bug。

Fuzz Test（模糊测试）：Foundry 随机生成函数参数，对同一个函数反复调用，每次调用之间是独立的。它的搜索空间是函数输入的类型空间。对于function deposit(uint256 amount)来说，Foundry 会生成各种uint256值 —— 0、1、max、以及各种中间值。如果某个值导致了 revert 或 assert 失败，Foundry 会尝试缩小范围找到最小复现值。

Invariant Test（不变式验证）：不变式测试的视角完全不同。它关注合约状态在函数调用序列下的守恒。Framework 随机生成函数调用序列（可能是任意公开函数的任意组合顺序），并在每次调用后检查预定义的不变量。如果某个序列打破了不变量，Foundry 会反向裁剪这个序列，找到触发问题的最短调用链。

sequenceDiagram participant Fuzz as Fuzzer 引擎 participant Target as 被测试合约 participant Invariant as 不变式检查器 loop 256 runs Fuzz->>Target: 生成随机参数 f(args) Target-->>Fuzz: 返回结果 Fuzz->>Fuzz: assert 单次调用结果 end Note over Fuzz,Invariant: 不变式测试更进一步 loop 任意函数序列 Fuzz->>Target: 随机选择函数 + 参数 Target-->>Fuzz: 状态变更 Fuzz->>Invariant: 检查所有不变量 Invariant-->>Fuzz: 通过 / 失败 alt 不变量被打破 Fuzz->>Fuzz: 裁剪调用序列 end end

两者的关系是互补的：Fuzzing 覆盖单函数边界行为，Invariant Testing 覆盖跨函数的状态一致性。一个典型的例子是代币合约：Fuzzing 确保transfer在各种参数下不报错；Invariant Testing 确保所有transfer+mint+burn操作序列结束后，totalSupply依然等于所有地址余额之和。

三、生产级代码实践

3.1 ERC20 代币的完整 Fuzzing 测试

// test/Token.fuzz.t.sol // SPDX-License-Identifier: MIT pragma solidity ^0.8.26; import {Test, console} from "forge-std/Test.sol"; import {MyToken} from "../src/MyToken.sol"; /** * @title TokenFuzzTest * @notice 对 ERC20 代币进行 Fuzzing 测试 * 设计考量： * - 使用 forge-std 的 bound() 限制输入范围，避免 fuzzer 生成极端值导致无意义的 revert * - 每个 fuzz 函数独立，确保状态隔离 —— Foundry 会在每次 fuzz 调用前自动 fork 状态 * - 为 fuzzer 提供结构化的断言集，而非单个 assert，提高 bug 发现密度 */ contract TokenFuzzTest is Test { MyToken public token; address public owner; address public alice; address public bob; // Fuzzer 每次执行的 runs 数量，默认 256 // 设置为更高的值可以在 CI 中以 --fuzz-runs 参数覆盖 function setUp() public { owner = makeAddr("owner"); alice = makeAddr("alice"); bob = makeAddr("bob"); vm.startPrank(owner); token = new MyToken("TestToken", "TST"); token.mint(alice, 1_000_000 ether); token.mint(bob, 1_000_000 ether); vm.stopPrank(); } /** * Fuzz 测试：transfer 不应在合法输入下 revert * bound(amount, 1, max) 避免 amount=0 或溢出 */ function testFuzz_TransferShouldNotRevert(uint256 amount) public { amount = bound(amount, 1, token.balanceOf(alice)); vm.prank(alice); token.transfer(bob, amount); // 静默通过即表示无 revert } /** * Fuzz 测试：转账后余额守恒 * 这是核心业务不变量的 fuzz 化验证 */ function testFuzz_TransferPreservesTotalSupply(uint256 amount) public { amount = bound(amount, 1, token.balanceOf(alice)); uint256 aliceBefore = token.balanceOf(alice); uint256 bobBefore = token.balanceOf(bob); vm.prank(alice); token.transfer(bob, amount); assertEq(token.balanceOf(alice), aliceBefore - amount); assertEq(token.balanceOf(bob), bobBefore + amount); } /** * Fuzz 测试：approve 后 allowance 必须精确等于设定值 * 很多 ERC20 实现会因为 approve 非零值再改为零值时存在 race condition */ function testFuzz_ApproveSetsCorrectAllowance(uint256 amount) public { vm.prank(alice); token.approve(bob, amount); assertEq(token.allowance(alice, bob), amount); } /** * Fuzz 测试：transferFrom 的权限边界 * 如果 allowance 不足，必须 revert */ function testFuzz_TransferFromRevertsWhenAllowanceTooLow( uint256 approveAmount, uint256 transferAmount ) public { approveAmount = bound(approveAmount, 0, type(uint256).max - 1); // 确保 transferAmount > approveAmount transferAmount = bound(transferAmount, approveAmount + 1, type(uint256).max); vm.prank(alice); token.approve(bob, approveAmount); vm.prank(bob); vm.expectRevert(); token.transferFrom(alice, bob, transferAmount); } }

3.2 不变式测试：代币总供给守恒

// test/Token.invariant.t.sol // SPDX-License-Identifier: MIT pragma solidity ^0.8.26; import {Test, console} from "forge-std/Test.sol"; import {StdInvariant} from "forge-std/StdInvariant.sol"; import {MyToken} from "../src/MyToken.sol"; /** * @title TokenInvariantTest * @notice 验证 ERC20 代币在任意操作序列下的不变式 * 设计考量： * - 继承 StdInvariant 获取 targetContract / targetSelector 等辅助方法 * - 使用 excludeArtifacts 排除不需要的合约路径 * - ghost 变量用于跨调用追踪状态，避免 EVM storage slot 混淆 */ contract TokenInvariantTest is StdInvariant, Test { MyToken public token; address public alice; address public bob; function setUp() public { alice = makeAddr("alice"); bob = makeAddr("bob"); token = new MyToken("TestToken", "TST"); token.mint(alice, 1_000_000 ether); token.mint(bob, 1_000_000 ether); // 将合约注册为 fuzzer 目标 targetContract(address(token)); // 排除 view 函数和非公开函数，避免无意义的 fuzzer 调用 bytes4[] memory excludedSelectors = new bytes4[](3); excludedSelectors[0] = bytes4(keccak256("name()")); excludedSelectors[1] = bytes4(keccak256("symbol()")); excludedSelectors[2] = bytes4(keccak256("decimals()")); targetSelector(FuzzSelector({ addr: address(token), selectors: excludedSelectors }).exclude(); } /** * 不变式 1：总供给在所有操作后等于所有持币地址余额之和 * 这是 ERC20 最根本的不变式 */ function invariant_TotalSupplyEqualsSumOfBalances() public { assertEq( token.totalSupply(), token.balanceOf(alice) + token.balanceOf(bob) ); } /** * 不变式 2：任意地址的余额不能超过总供给 */ function invariant_BalanceNeverExceedsTotalSupply() public { assertLe(token.balanceOf(alice), token.totalSupply()); assertLe(token.balanceOf(bob), token.totalSupply()); } /** * 不变式 3：allowance 不影响余额，仅影响 transferFrom 的授权额度 */ function invariant_AllowanceDoesNotAffectBalance() public { // 无需显式断言 —— 如果 allowance 实现有 bug 影响了余额 // 前两个 invariants 必然会捕获 } }

3.3 不变式 Handler：控制 fuzzer 的行为边界

对于更复杂的协议，直接 targetContract 会导致 fuzzer 生成不真实的操作序列。比如一个借贷协议，fuzzer 可能反复调用deposit而不调用borrow，这样的序列找不到真实 bug。通过 Handler 合约，可以引导 fuzzer 的行为模式：

// test/handlers/LendingHandler.sol contract LendingHandler is Test { LendingPool public pool; MockERC20 public token; constructor(LendingPool _pool, MockERC20 _token) { pool = _pool; token = _token; } /** * Handler 方法：deposit * 每次被 fuzzer 随机选中时，使用 ghost 变量记录 deposit 总量 * 这种设计让 fuzzer 的调用更接近真实用户行为 */ function deposit(uint256 amount) public { amount = bound(amount, 1, token.balanceOf(address(this))); token.approve(address(pool), amount); pool.deposit(amount); } function borrow(uint256 amount) public { // 限制借款量不超过可用流动性的 80%，避免 fuzzer 反复触发无意义的 revert uint256 available = pool.getAvailableLiquidity(); amount = bound(amount, 1, (available * 80) / 100); pool.borrow(amount); } function repay(uint256 amount) public { uint256 debt = pool.getDebt(address(this)); amount = bound(amount, 1, debt); token.approve(address(pool), amount); pool.repay(amount); } }

3.4 Foundry 配置调优

# foundry.toml [profile.default] src = "src" out = "out" libs = ["lib"] # Fuzzing 配置 fuzz = { runs = 5000, max_test_rejects = 500_000 } # runs: 每个 fuzz 测试执行的随机输入组数，5000 是复杂 DeFi 协议的合理起点 # max_test_rejects: 允许 fuzzer 抛弃的无效输入数，默认 65536 # 提高这个值是必要的：如果 bound() 频繁排除了大量输入范围，fuzzer 需要更多重试才能找到有效输入 invariant = { runs = 256, depth = 15, fail_on_revert = false } # runs: 不变式测试的跑数 # depth: 函数调用序列的最大长度，15 表示 fuzzer 会生成 1-15 个随机函数调用组成的序列 # fail_on_revert = false: 不变式测试中允许函数调用 revert（正常业务逻辑） # 设置为 true 会让 fuzzer 把所有 revert 视为失败，适用于"任何操作都不应该 revert"的严格场景 [profile.ci] fuzz = { runs = 10000, max_test_rejects = 1_000_000 } invariant = { runs = 512, depth = 20 } # CI 环境下提高运行次数，利用 CI Runner 的高性能 CPU 做深度搜索

四、边界分析

Fuzzing 的覆盖率不等于合约安全性。Foundry fuzzer 基于随机输入生成，它不能保证覆盖所有代码路径。一个只在block.timestamp == 某个特定值时触发的 bug，fuzzer 几乎不可能命中。覆盖率报告应该作为最低标准而不是完美目标。

不变式设计的质量决定了测试价值。如果你定义的不变式本身就有漏洞（比如"总借款量不超过存款量"忽略利息累积），那么测试无论跑多少轮都是自我欺骗。不变式的推导需要与合约的数学规范对齐。

Gas 消耗不可忽视。在 CI 中运行 10000 次 fuzz 测试，对于包含多个复杂操作的合约，单次运行可能消耗大量 RPC 调用和 CPU 时间。建议将高 runs 值的配置放在 nightly CI 中，日常 PR 使用较低的 runs 值做快速门禁。

不适用场景：

• 合约依赖外部 oracle 价格：fuzzer 无法模拟链下价格波动的分布
• 需要跨区块状态（如时间锁）：Foundry fuzzer 默认在单区块内运行
• 依赖复杂 MEV 场景：需要搭配forge-std的vm.roll()和vm.warp()手动构造

五、总结