智能合约与以太坊 / 系统课时
创建 invariant 函数和测试目标
创建 invariant 函数和测试目标
普通模糊测试主要检验单次函数调用,而资金池、账本等合约的缺陷可能需要多次存取操作才能触发。本课使用 Foundry 创建可运行的状态不变量测试,配置目标合约、调用次数与随机序列深度,并通过运行结果确认属性确实受到检查。
学习目标
- 使用
invariant_命名规则声明状态不变量,并通过targetContract指定测试对象。 - 理解
runs、depth和每次调用后的属性检查机制。 - 运行完整测试,识别通过、断言失败和调用回滚之间的区别。
确定要持续成立的属性
假设一个简化资金账本只提供存入和取出操作,并记录累计存入量、累计取出量以及当前余额。
无论用户按什么顺序操作,都应该满足:
例如,依次存入 100、取出 30、再存入 20,最后累计存入为 120、累计取出为 30、余额为 90,等式仍然成立。
这就是状态不变量:它并不要求余额保持不变,而是要求不同状态变量之间的关系始终成立。
普通单元测试可以手工检查这三次操作;不变量测试则由 Foundry 随机生成大量操作序列,在每次调用后检查关系是否被破坏。
创建合约与 invariant 测试
前置条件是已经安装 Foundry,并拥有包含 forge-std 依赖的标准 Forge 项目。可以通过 forge --version 检查安装状态。
在项目的 test/CounterInvariant.t.sol 中放入以下完整示例。为了方便直接运行,这里把待测合约和测试合约写在同一文件,实际项目可以把业务合约放在 src/ 下。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {Test} from "forge-std/Test.sol";
contract Ledger {
uint256 public totalIn;
uint256 public totalOut;
uint256 public balance;
function deposit(uint256 amount) external {
// 限定单次金额,避免极大随机值干扰状态探索。
amount = amount % 1001;
totalIn += amount;
balance += amount;
}
function withdraw(uint256 amount) external {
if (balance == 0) return;
// 保证取出金额不超过现有余额。
amount = amount % (balance + 1);
totalOut += amount;
balance -= amount;
}
}
contract CounterInvariantTest is Test {
Ledger internal ledger;
function setUp() public {
ledger = new Ledger();
// 只对账本合约的外部函数生成随机调用。
targetContract(address(ledger));
}
function invariant_accounting() public view {
assertEq(
ledger.totalIn(),
ledger.totalOut() + ledger.balance()
);
}
}这里有三个关键位置。
setUp()在测试序列开始前部署待测账本并注册目标地址。targetContract(address(ledger))将随机调用限制在该合约,避免误将测试辅助合约加入测试范围。invariant_accounting()通过assertEq声明必须持续成立的账务关系。
Foundry 使用以 invariant_ 开头的函数名识别不变量测试。测试函数不需要随机参数,因为随机参数由引擎传递给目标合约的函数,而不是直接传递给不变量函数。
targetContract 是继承 forge-std/Test.sol 后可用的测试辅助方法,不能直接写进普通生产合约。
配置 runs 和 depth
在项目根目录的 foundry.toml 中添加以下配置;如果已有 [invariant] 段,应合并字段,而不是重复声明同名表。
[invariant]
runs = 20
depth = 32
fail_on_revert = true各参数的含义如下。
| 参数 | 示例值 | 实际作用 |
|---|---|---|
runs |
20 | 生成并执行 20 轮随机调用序列 |
depth |
32 | 每轮最多执行 32 次目标函数调用 |
fail_on_revert |
true | 目标调用发生未被容许的回滚时使测试失败 |
这组设置的计划调用量是 20 × 32 = 640 次,并不代表 640 种唯一状态,也不代表所有可能调用顺序都已覆盖。
runs 增加随机序列数量,适合扩大不同输入和初始操作组合的探索;depth 增加单条序列的长度,更适合寻找需要多次连续操作才能触发的状态缺陷。
例如,一个缺陷只有连续取款五次后才出现,那么将 depth 设置为 3 就无法覆盖该触发链,即使增加 runs 也不能弥补序列长度不足。
理解每次调用后的检查过程
Foundry 的不变量测试并不是完成整条随机序列后才做一次断言,而是在序列执行过程中持续检查属性。

上图用三次调用说明一轮测试的基本行为。实际配置为 depth = 32 时,Foundry 会继续产生更多调用,并反复执行不变量检查。
需要特别注意以下边界:
- 每轮随机序列在隔离的测试状态中执行,不会把上一轮结束的余额当成下一轮初始余额。
- 如果没有开启
fail_on_revert,目标调用回滚通常不会直接导致整轮不变量测试失败,但仍会消耗一次调用深度。 - 即使断言一直通过,如果所有目标函数都回滚,测试也可能没有覆盖真正的业务状态变化。
- 多个独立的
invariant_测试通常使用各自的执行状态;要求同时检查的一组属性可以写进同一个不变量函数。
本例显式使用 fail_on_revert = true,并通过金额约束保证正常随机调用不会因为余额不足而回滚,便于观察真正的状态缺陷。
运行并检查结果
在 Forge 项目根目录执行:
forge test --match-contract CounterInvariantTest -vv预期结果是测试通过,控制台会出现类似以下摘要;耗时和完整日志会随环境变化。
[PASS] invariant_accounting() (runs: 20, calls: 640, reverts: 0)这里的 calls: 640 对应 20 轮、每轮 32 次调用;reverts: 0 表示此次示例运行没有目标调用回滚。最终成功还应以 Forge 给出的测试通过状态为准。
为了确认断言不是摆设,可以做一次故障注入:暂时将 withdraw() 中的 totalOut += amount; 删除,其余逻辑保持不变。只要产生非零取款,累计存入量就不再等于累计取出量加余额。
重新执行同一条测试命令。
预期结果:invariant_accounting() 报告失败,Forge 输出触发问题的调用信息或反例序列。具体金额和调用顺序由随机探索决定,不应预设为固定值。随后恢复被删除的代码,再次运行并确认测试通过。
如果测试意外显示通过,先检查三件事:函数名是否以 invariant_ 开头,targetContract 是否指向真正的业务合约,以及运行摘要中的 calls、reverts 是否表明有效状态操作已经发生。
对于需要授权、代币余额或复杂操作前置条件的真实协议,通常还要增加 Handler 合约来生成有效调用。单纯调大 runs 和 depth,无法修复大量随机调用因前置条件不满足而回滚的问题。