智能合约与以太坊 / 系统课时
使用 Fuzz 检查输入边界
使用 Fuzz 检查输入边界
固定输入的单元测试容易遗漏极小金额、最大余额和不同账户状态的组合。本课使用 Foundry 编写参数化 Fuzz 测试,让 Forge 自动生成多组输入,通过 bound 与 vm.assume 控制测试范围,并验证 ETH 金库在存款、提款及非法调用后的账本一致性。
学习目标
- 编写接收随机参数的 Solidity Fuzz 测试,检查金额与状态组合。
- 正确选择
bound和vm.assume,避免无效输入消耗测试次数。 - 使用余额守恒性质、非法提款断言和失败反例定位边界缺陷。
定义要验证的金库性质
假设一个 ETH 金库为每个账户记录存款余额,并用 totalDeposits 记录所有账户的存款总额。存款增加账户余额和总额,提款减少两者,并把 ETH 转回调用者。
在没有外部强制转入 ETH、也没有其他收入来源的测试场景中,需要满足三个条件:
- 所有参与账户的记录余额之和等于
totalDeposits。 - 金库实际 ETH 余额等于
totalDeposits。 - 提款成功后,提款人实际收到的 ETH 等于本次扣除的账面金额。
例如,Alice 存入 4 ETH,Bob 存入 7 ETH,然后 Bob 提取 3 ETH。此时 Alice 账面余额为 4 ETH,Bob 为 4 ETH,金库总额和实际 ETH 余额均为 8 ETH。如果只修改 Bob 的余额而忘记减少总额,第二个条件就会失败。
在已安装 Foundry、包含 forge-std 的标准项目中,新建 src/BoundaryVault.sol:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
contract BoundaryVault {
error InvalidDeposit();
error InvalidWithdrawal();
error TransferFailed();
mapping(address => uint256) public balances;
uint256 public totalDeposits;
function deposit() external payable {
if (msg.value == 0) revert InvalidDeposit();
balances[msg.sender] += msg.value;
totalDeposits += msg.value;
}
function withdraw(uint256 amount) external {
if (amount == 0 || amount > balances[msg.sender]) {
revert InvalidWithdrawal();
}
// 先扣减账本;转账失败时整笔调用会回滚。
balances[msg.sender] -= amount;
totalDeposits -= amount;
(bool success, ) = payable(msg.sender).call{value: amount}("");
if (!success) revert TransferFailed();
}
}这里的 totalDeposits 是账本汇总字段,不是从 address(this).balance 临时计算得到的。因此测试能够检测汇总字段与实际 ETH 余额之间的偏差。金库只接受正数存款与有效提款,非法金额通过自定义错误回滚。
编写金额与状态组合的 Fuzz 测试
Forge 会将带参数的 testFuzz_ 函数识别为模糊测试,为 uint256、address、bool 等参数生成多组输入。每组输入会从测试初始化状态独立执行,不会继承上一组 Fuzz 调用产生的账本变化。
新建 test/BoundaryVault.t.sol,在一次测试中生成两笔存款金额、一笔提款金额和一个账户选择标记。第二个测试则随机生成没有存款记录的调用者,检查非法提款必须回滚。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
import {Test} from "forge-std/Test.sol";
import {BoundaryVault} from "../src/BoundaryVault.sol";
contract BoundaryVaultFuzzTest is Test {
BoundaryVault internal vault;
address internal constant ALICE = address(0xA11CE);
address internal constant BOB = address(0xB0B);
function setUp() public {
vault = new BoundaryVault();
}
function testFuzz_DepositWithdraw(
uint256 seedA,
uint256 seedB,
uint256 seedOut,
bool fromAlice
) public {
// 将任意随机金额映射到可执行的存款范围。
uint256 amountA = bound(seedA, 1, 10 ether);
uint256 amountB = bound(seedB, 1, 10 ether);
vm.deal(ALICE, amountA);
vm.deal(BOB, amountB);
vm.prank(ALICE);
vault.deposit{value: amountA}();
vm.prank(BOB);
vault.deposit{value: amountB}();
// 随机选择提款账户,提款金额不能超过其余额。
address receiver = fromAlice ? ALICE : BOB;
uint256 available = fromAlice ? amountA : amountB;
uint256 outAmount = bound(seedOut, 1, available);
uint256 ethBefore = receiver.balance;
vm.prank(receiver);
vault.withdraw(outAmount);
// 同时核对提款到账、账户汇总和实际金库资金。
assertEq(receiver.balance, ethBefore + outAmount);
assertEq(
vault.balances(ALICE) + vault.balances(BOB),
vault.totalDeposits()
);
assertEq(address(vault).balance, vault.totalDeposits());
assertEq(
vault.totalDeposits(),
amountA + amountB - outAmount
);
}
function testFuzz_RejectUnfunded(
address outsider,
uint256 rawAmount
) public {
// 排除不符合测试角色定义的调用者地址。
vm.assume(
outsider != address(0) &&
outsider != ALICE &&
outsider != BOB &&
outsider != address(vault)
);
vm.deal(ALICE, 1 ether);
vm.prank(ALICE);
vault.deposit{value: 1 ether}();
uint256 amount = bound(rawAmount, 1, 2 ether);
// 未存款的账户不能提走 Alice 的资金。
vm.expectRevert(BoundaryVault.InvalidWithdrawal.selector);
vm.prank(outsider);
vault.withdraw(amount);
assertEq(vault.balances(ALICE), 1 ether);
assertEq(address(vault).balance, 1 ether);
}
function test_ZeroWithdrawalReverts() public {
vm.expectRevert(BoundaryVault.InvalidWithdrawal.selector);
vault.withdraw(0);
}
}vm.deal 为测试账户设置 ETH 余额,vm.prank 让下一次合约调用使用指定的 msg.sender。fromAlice 的两个布尔取值覆盖了不同提款账户,seedOut 则覆盖从 1 wei 到当前账户全部余额的提款范围。

正确选择 bound 与 vm.assume
这两种方法都能让测试聚焦有效场景,但处理输入的方式不同。
| 方法 | 实际行为 | 适合场景 |
|---|---|---|
bound(value, min, max) |
把输入映射到包含上下界的整数范围,保留该次测试 | 金额、数量、比例、时间窗口 |
vm.assume(condition) |
条件为假时丢弃当前候选输入并重新生成 | 排除零地址、相同角色或少量不合法组合 |
例如,金库允许 1 wei 到 10 ETH 的存款。直接使用 vm.assume(amount >= 1 && amount <= 10 ether) 过滤整个 uint256 输入空间,会让绝大多数候选值被丢弃,容易耗尽允许的拒绝次数。使用 bound(amount, 1, 10 ether) 则不需要反复等待随机值落入狭窄区间。
相反,随机地址测试只需要排除零地址、Alice、Bob 和金库本身。这些排除条件在地址空间中只占极小部分,使用 vm.assume 更符合语义,也不必把随机地址强行映射到另一段数值范围。
还要区分有效输入与非法输入:testFuzz_DepositWithdraw 只检查合法提款是否满足账本性质,不能因此认定零金额或超额提款处理正确。test_ZeroWithdrawalReverts 和 testFuzz_RejectUnfunded 分别覆盖这两类拒绝行为的一部分。
运行测试并定位失败输入
在项目根目录的 foundry.toml 中添加以下配置;如果文件已有其他配置,只追加对应的 Fuzz 配置节,避免重复定义相同 TOML 表。
[profile.default.fuzz]
runs = 256这表示每个 Fuzz 测试目标运行 256 组有效样本。对于本例,两个带参数的测试分别执行 Fuzz,固定输入测试只执行一次。可使用 forge config 核对配置是否生效。
执行命令:
forge test --match-contract BoundaryVaultFuzzTest -vv预期输出的关键部分如下。Gas 统计和耗时因环境而异,示例中的占位符代表动态数值:
[PASS] testFuzz_DepositWithdraw(uint256,uint256,uint256,bool) (runs: 256, μ: <GAS>, ~: <GAS>)
[PASS] testFuzz_RejectUnfunded(address,uint256) (runs: 256, μ: <GAS>, ~: <GAS>)
[PASS] test_ZeroWithdrawalReverts() (gas: <GAS>)
Suite result: ok. 3 passed; 0 failed; 0 skipped; finished in <TIME> (<TIME> CPU time)若测试失败,Forge 会显示失败测试、反例或失败执行轨迹。Fuzz 引擎通常会尝试缩小触发失败的输入,使问题更容易复现。需要进一步检查调用与断言时,运行:
forge test --match-test testFuzz_DepositWithdraw -vvvv预期结果:如果测试通过,显示该测试的 PASS 状态和详细调用轨迹;如果存在失败反例,则显示 FAIL、相关输入或调用数据及失败位置。实际数值取决于当前合约和随机样本,不能预先固定。
可以尝试把金库 withdraw 中的 totalDeposits -= amount; 暂时删除,再运行第一条测试命令。由于提款后总额没有同步减少,只要成功提款,账本汇总与实际金库余额就不相等,assertEq(address(vault).balance, vault.totalDeposits()) 应报告失败。恢复该语句后重新运行,三个测试应再次通过。
如果出现过多输入被拒绝的错误,应先查看 vm.assume 是否限制了极小的数值区间,而不是直接增大拒绝次数上限。对于金额优先使用 bound,对于少量无效角色使用 vm.assume。
补齐随机测试无法保证覆盖的边界
Fuzz 可以高效搜索输入组合,但 256 次通过并不能证明合约对全部输入绝对正确,也不意味着执行过每一个边界。交付前应单独核对以下输入:
| 场景 | 输入 | 应有结果 |
|---|---|---|
| 零金额存款 | msg.value = 0 |
InvalidDeposit 回滚 |
| 最小有效存款 | msg.value = 1 wei |
成功记账 1 wei |
| 零金额提款 | amount = 0 |
InvalidWithdrawal 回滚 |
| 全额提款 | 余额 4 ETH,提取 4 ETH | 账户余额和金库余额均减少 4 ETH |
| 超额提款 | 余额 4 ETH,提取 4 ETH + 1 wei | 回滚且原有账本不变 |
| 无余额账户提款 | Alice 存 1 ETH,陌生账户提 1 ETH | 回滚,Alice 余额仍为 1 ETH |
对于提款接收方拒收 ETH 的情况,还应使用专门的拒收合约测试 TransferFailed,并核对失败后扣减的余额全部回滚。本篇测试的普通账户均能接收 ETH,不覆盖这条失败路径。
最后需要区分两种测试层级:这里的 Fuzz 测试验证的是每次生成输入后执行一段固定的“存款、存款、提款”操作序列。Foundry 的状态不变量测试则可以通过 invariant_ 测试和 Handler 随机组合多次调用,寻找更复杂的跨操作状态缺陷。当前示例已经能证明这段操作序列在本次覆盖的输入范围内满足断言,但不能替代任意调用序列的状态不变量验证。