智能合约与以太坊 / 系统课时
用 bound 生成合法数值区间
用 bound 生成合法数值区间
当金额只能在 1~1000 之间、购买数量只能在 1~20 之间时,直接模糊测试整个 uint256 范围会产生大量无效输入。本课使用 Foundry 的 bound 将随机值映射到合法区间,让测试真正执行合约业务,并比较这种方式与 vm.assume 的区别。
学习目标
- 掌握 bound 的参数、闭区间规则和返回值用法。
- 使用合法金额与数量完成可运行的 Foundry 模糊测试。
- 判断何时使用 bound、vm.assume 和明确的边界测试。
bound 如何约束输入
Foundry 的 forge-std 测试基类 Test 提供了 bound 辅助函数,常见用法如下:
amount = bound(amount, 1, 1000);这是片段示例,需放在继承 forge-std/Test.sol 中 Test 的测试合约函数内,且 amount 已声明为 uint256。
三个参数分别是原始输入 x、下界 min 和上界 max。返回值处于包含两个端点的闭区间内,即 1 <= amount <= 1000。上下界必须满足 min <= max,否则约束无效。
bound 并不是让模糊测试引擎直接只生成指定区间的随机数,而是在测试函数运行时将已有输入映射到该区间。对于不在目标区间内的常见输入,可以把映射理解为按区间宽度进行取模;已经处于合法区间的值通常保持不变。实际实现还处理完整 uint256 范围等特殊边界,不应自行用简单取模替代全部行为。
例如目标区间是 1~3:
| 原始输入 | 映射结果 | 说明 |
|---|---|---|
| 0 | 3 | 区间外输入映射回区间 |
| 1 | 1 | 已经合法,保持不变 |
| 2 | 2 | 已经合法,保持不变 |
| 3 | 3 | 上界包含在内 |
| 4 | 1 | 超过上界后映射 |
注意:bound 会改变传入的测试数据,而不是验证原始输入是否合法。因此它适合测试合法业务操作,不适合单独证明合约会拒绝非法金额。
用金额和数量完成一次业务测试
假设一个简化的商品购买合约规定:单价为 5 个计价单位,每次数量在 1~20 之间,支付总额不能超过 1000。这里使用纯整数计价,不涉及 Ether 转账,便于专注检查数量、金额及状态变化。
在已安装 Foundry 且包含 forge-std 的项目中,新建 test/BoundPurchase.t.sol,写入完整代码:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {Test} from "forge-std/Test.sol";
contract PurchaseBox {
uint256 public constant PRICE = 5;
uint256 public sold;
uint256 public revenue;
function buy(uint256 quantity, uint256 payment) external {
require(quantity >= 1 && quantity <= 20, "invalid quantity");
require(payment == quantity * PRICE, "invalid payment");
require(payment <= 1000, "payment too large");
sold += quantity;
revenue += payment;
}
}
contract BoundPurchaseTest is Test {
PurchaseBox internal box;
function setUp() public {
box = new PurchaseBox();
}
function testFuzz_Buy(uint256 rawQuantity) public {
// 映射数量,避免大部分随机输入被业务 require 拒绝。
uint256 quantity = bound(rawQuantity, 1, 20);
uint256 payment = quantity * box.PRICE();
uint256 soldBefore = box.sold();
uint256 revenueBefore = box.revenue();
box.buy(quantity, payment);
// 检查业务状态变化,而不只检查交易没有回滚。
assertEq(box.sold(), soldBefore + quantity);
assertEq(box.revenue(), revenueBefore + payment);
assertGe(quantity, 1);
assertLe(quantity, 20);
}
function test_BoundEndpoints() public {
assertEq(bound(1, 1, 20), 1);
assertEq(bound(20, 1, 20), 20);
}
}执行测试:
forge test --match-contract BoundPurchaseTest预期结果:编译成功,两个测试均通过,模糊测试会显示本次实际执行次数。下面只保留稳定的结果标识,具体运行次数及耗时随 Foundry 配置变化。
[PASS] test_BoundEndpoints()
[PASS] testFuzz_Buy(uint256)这个例子选择先约束数量、再根据单价计算金额,确保两个参数满足业务关联关系。如果分别执行 bound(quantity, 1, 20) 和 bound(payment, 1, 1000),虽然都得到合法范围内的数,却可能不满足 payment == quantity * 5,导致测试仍然回滚。
比较 bound 与 vm.assume 的执行效率
另一种约束写法是:
vm.assume(rawQuantity >= 1 && rawQuantity <= 20);
uint256 quantity = rawQuantity;这是片段示例,依赖继承 Test 的测试合约,以及已声明的 uint256 rawQuantity。
两者的处理方式存在实质差异:
| 比较项 | bound | vm.assume |
|---|---|---|
| 输入不符合条件 | 映射到目标区间 | 丢弃本次输入并重新尝试 |
| 合法业务调用机会 | 映射后通常可以继续执行 | 取决于能否生成满足条件的输入 |
| 适用约束 | 连续整数范围 | 排除特定值、地址关系等条件 |
| 对原始值的处理 | 可能改变原始值 | 保留满足条件的原始值 |
对于整个 uint256 空间而言,1~20 是极小的区间。虽然 Foundry 的模糊测试引擎会生成一些边界值,并非简单均匀随机采样,但用 vm.assume 进行如此狭窄的过滤仍可能出现大量丢弃,甚至达到允许的最大拒绝次数。
可以对同一业务测试分别采用两种约束方式,在相同的 fuzz.runs 配置下运行,再观察实际测试次数、拒绝情况和执行时间。不要预设某一种方式必然快多少倍,实际结果与约束范围、生成器策略和测试成本有关。
如果只想排除零地址,使用 vm.assume(user != address(0)) 通常比将地址强行转换成其他数值更符合测试意图,因为后者可能改变地址分布或身份语义。
避免区间映射掩盖边界缺陷
bound 提高合法交易的执行机会,但也会改变输入分布,不能保证每个业务端点都被充分覆盖。对于购买数量 1~20 的例子,至少还应单独检查以下情况:
| 测试输入 | 期望行为 |
|---|---|
| quantity = 1,payment = 5 | 购买成功 |
| quantity = 20,payment = 100 | 购买成功 |
| quantity = 0,payment = 0 | 回滚并提示 invalid quantity |
| quantity = 21,payment = 105 | 回滚并提示 invalid quantity |
| quantity = 2,payment = 9 | 回滚并提示 invalid payment |
可在前面的 BoundPurchaseTest 中补充一项固定边界测试:
function test_RejectQuantityAboveMaximum() public {
vm.expectRevert(bytes("invalid quantity"));
box.buy(21, 105);
}这是片段示例,放在已有的 BoundPurchaseTest 合约内部,复用 setUp 创建的 box。新增测试执行后,预期结果是 test_RejectQuantityAboveMaximum() 通过,因为合约按预期回滚并返回指定错误信息。
这里要区分两个测试目标:测试合法购买的状态不变量时,使用 bound(数量, 1, 20);测试数量限制是否生效时,直接提供 0、21 等非法值并使用 vm.expectRevert。不能先把 21 映射到合法区间,再声称已经验证了越界拒绝行为。
还要检查区间本身是否与业务一致。比如把数量错误地约束成 2~19,模糊测试依然可能全部通过,却遗漏真正的下界 1 和上界 20。对于资金合约,应把最小值、最大值、零值、最大值加一以及金额乘法边界纳入独立测试,尤其注意 uint256 乘法可能溢出时的回滚行为。
验证模糊测试确实执行了业务
仅看到测试通过还不够。可以增加执行次数,并查看详细的测试结果:
forge test --match-contract BoundPurchaseTest --fuzz-runs 1000 -vv预期结果:命中的测试全部通过,testFuzz_Buy(uint256) 的结果中显示 runs: 1000;固定测试则各执行一次。具体 gas 和耗时会因环境而异。如果使用前面新增的越界测试,它也应单独显示 PASS。
验收时重点检查三件事:一是输入约束确实覆盖业务合法范围;二是成功调用 buy 后,sold 和 revenue 都按预期增加;三是非法边界仍由独立测试验证回滚。
需要注意,1000 次模糊执行不等于覆盖了 1000 个互不相同的数量。对于只有 20 个合法整数值的区间,映射后的输入会重复。若测试需要严格覆盖每个数量,可以增加固定值循环测试,而不能仅依赖随机运行次数。
实际项目中可以把 bound 用于合法存款金额、订单数量、抵押率参数和手续费区间;对于非法输入拒绝、不同账户间的权限关系以及临界值精确覆盖,则应配合 vm.assume、固定边界用例和必要的状态不变量测试。