智能合约与以太坊 / 系统课时
运行第一条 Forge 断言用例
运行第一条 Forge 断言用例
本课将创建一个最小 Solidity 测试合约,通过 forge test 验证状态变化,再故意制造一次断言失败,使用详细日志与调用轨迹定位问题。完成后,你将掌握从编写用例、执行测试到阅读失败轨迹的完整操作方法,并获得后续开展模糊测试所需的测试基线。
学习目标
- 编写继承
Test的 Forge 测试合约,使用assertEq验证状态。 - 通过
forge test和测试过滤参数运行指定用例。 - 使用
-vvv、-vvvv查看失败原因及合约调用轨迹。
检查项目与测试环境
Forge 是 Foundry 工具链中的 Solidity 构建与测试工具。它可以编译合约、部署测试实例并在本地 EVM 中执行测试,不需要预先启动 Anvil,也不需要连接公共区块链。
先在终端检查 Forge 是否可用:
forge --version预期结果:终端显示 Forge 版本信息,具体版本号、构建提交和时间随安装版本变化。如果提示 command not found,需要先安装 Foundry 并确认可执行文件已加入 PATH。
如果尚未创建项目,可以执行:
forge init first-forge-test
cd first-forge-test预期结果:当前目录成为包含 foundry.toml、src/、test/ 和 lib/ 的 Foundry 项目。初始化过程可能需要访问网络下载测试依赖。
本课使用 Foundry 标准项目结构。forge-std 提供 Test.sol、断言函数及测试辅助能力。初始化模板中可能已经存在 Counter.sol 和 Counter.t.sol,它们可以保留,本课通过筛选测试合约单独运行新增用例。
编写最小合约与断言
创建 src/SimpleCounter.sol。合约只保存一个计数值,increment 每次调用使其增加 1。使用 Solidity ^0.8.20,需要项目使用兼容的编译器版本。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract SimpleCounter {
uint256 public count;
// 每次调用只增加一次,便于验证状态变化
function increment() external {
count += 1;
}
}然后创建 test/SimpleCounter.t.sol:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {Test} from "forge-std/Test.sol";
import {SimpleCounter} from "../src/SimpleCounter.sol";
contract SimpleCounterTest is Test {
SimpleCounter counter;
// 每条测试开始前重新部署,避免用例互相污染
function setUp() public {
counter = new SimpleCounter();
}
function test_Increment() public {
assertEq(counter.count(), 0);
counter.increment();
assertEq(counter.count(), 1);
}
}这里的 Test 是 forge-std 提供的基类。Forge 自动识别以 test 开头的测试函数,setUp() 会在每条测试执行前运行。
assertEq(actual, expected) 比较实际值与期望值:第一次验证初始状态为 0,第二次验证调用后状态为 1。如果任意断言失败,测试就会被标记为失败。
运行用例并读取成功结果
在包含 foundry.toml 的项目根目录执行:
forge test --match-contract SimpleCounterTest预期输出(摘录,Gas 和耗时因环境而异):
Ran 1 test for test/SimpleCounter.t.sol:SimpleCounterTest
[PASS] test_Increment() (gas: <GAS>)
Suite result: ok. 1 passed; 0 failed; 0 skipped其中 <GAS> 代表实际输出中的 Gas 数值,并不是 Forge 的固定输出字段。编译信息、执行耗时和完整汇总可能因 Foundry 版本不同而变化。
[PASS] 表示断言全部通过;1 passed 表示当前筛选范围内成功执行一条测试。未指定筛选条件时,forge test 会运行项目中发现的全部测试,包括模板自带的测试。
需要进一步限定单个函数时,可以执行:
forge test --match-contract SimpleCounterTest --match-test test_Increment预期结果:只执行 SimpleCounterTest 中名称匹配 test_Increment 的测试函数,结果仍为 [PASS]。--match-contract 用于匹配测试合约名称,--match-test 用于匹配测试函数名称。
制造失败并查看调用轨迹
接下来故意将第二个断言中的期望值从 1 改成 2,保留第一次断言和 increment() 调用不变。
修改后的测试函数如下,属于片段示例,需替换现有 SimpleCounterTest 合约中的同名函数:
function test_Increment() public {
assertEq(counter.count(), 0);
counter.increment();
// 故意设置错误期望值,验证失败定位能力
assertEq(counter.count(), 2);
}执行失败测试并启用三级详细输出:
forge test --match-contract SimpleCounterTest -vvv预期输出(关键内容摘录):
[FAIL: assertion failed: 1 != 2] test_Increment()
Suite result: FAILED. 0 passed; 1 failed; 0 skipped不同版本可能采用不同的断言错误格式,但失败信息应能表明实际值为 1、期望值为 2。命令执行状态为失败,通常返回非零退出码,这也是 CI 能识别测试失败的依据。
查看日志时重点区分三个层次:
[FAIL]:哪条测试失败。- 断言错误:实际值与期望值有什么差异。
Traces:测试期间调用了哪些函数,调用或断言在哪一步出错。
Forge 的详细等级可以按问题复杂度逐步增加:
| 命令参数 | 主要用途 |
|---|---|
-vv |
显示测试日志与断言相关信息 |
-vvv |
显示失败测试的执行轨迹 |
-vvvv |
显示所有测试的执行轨迹,并显示失败测试的初始化轨迹 |
-vvvvv |
更完整地显示执行与初始化轨迹,适合深入排查 |
要查看成功路径与失败路径的调用关系,可以使用:
forge test --match-contract SimpleCounterTest -vvvv预期结果:失败测试下出现 Traces 区域,可以观察到 SimpleCounter::count() 的读取、SimpleCounter::increment() 的调用,以及最后的断言失败。轨迹中的 Gas 数值、内部调用细节和展示格式取决于当前 Foundry 版本。

阅读轨迹时,从测试函数入口向下检查调用顺序,再检查返回值与失败位置。这里 increment() 已经正常执行,计数也确实增加到 1,因此问题出在测试预期,而不是合约状态更新逻辑。
修复断言并建立测试基线
将错误断言恢复为 assertEq(counter.count(), 1);,然后执行:
forge test --match-contract SimpleCounterTest -vvvv预期输出(调用轨迹摘录):
[PASS] test_Increment() (gas: <GAS>)
Traces:在 Traces 下方应能看到计数器的调用及正常返回;测试汇总应显示 1 passed; 0 failed。其中 <GAS> 为实际 Gas 数值,具体轨迹行数可能随版本变化。
如果结果仍然失败,依次检查:
src/SimpleCounter.sol中的increment()是否执行count += 1。test/SimpleCounter.t.sol的期望值是否恢复为 1。setUp()是否为每条测试创建新的SimpleCounter实例。- 终端是否处于正确项目根目录,是否修改了本课实际执行的测试文件。
最后运行 forge test 检查整个项目,确保新增用例没有破坏其他已有测试。默认模板可能包含额外用例,因此此时总测试数量不一定为 1。
一条可靠的测试基线至少应满足三个条件:测试可以重复执行、修改错误期望值能稳定触发失败、恢复正确期望值后能重新通过。具备这三个条件后,才能进一步增加边界值断言和模糊测试输入,而不必先猜测测试框架是否正常工作。