智能合约与以太坊 / 系统课时

运行第一条 Forge 断言用例

运行第一条 Forge 断言用例

本课将创建一个最小 Solidity 测试合约,通过 forge test 验证状态变化,再故意制造一次断言失败,使用详细日志与调用轨迹定位问题。完成后,你将掌握从编写用例、执行测试到阅读失败轨迹的完整操作方法,并获得后续开展模糊测试所需的测试基线。

学习目标

  • 编写继承 Test 的 Forge 测试合约,使用 assertEq 验证状态。
  • 通过 forge test 和测试过滤参数运行指定用例。
  • 使用 -vvv、-vvvv 查看失败原因及合约调用轨迹。

检查项目与测试环境

Forge 是 Foundry 工具链中的 Solidity 构建与测试工具。它可以编译合约、部署测试实例并在本地 EVM 中执行测试,不需要预先启动 Anvil,也不需要连接公共区块链。

先在终端检查 Forge 是否可用:

bash
forge --version

预期结果:终端显示 Forge 版本信息,具体版本号、构建提交和时间随安装版本变化。如果提示 command not found,需要先安装 Foundry 并确认可执行文件已加入 PATH。

如果尚未创建项目,可以执行:

bash
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,需要项目使用兼容的编译器版本。

solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract SimpleCounter {
    uint256 public count;

    // 每次调用只增加一次,便于验证状态变化
    function increment() external {
        count += 1;
    }
}

然后创建 test/SimpleCounter.t.sol:

solidity
// 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 的项目根目录执行:

bash
forge test --match-contract SimpleCounterTest

预期输出(摘录,Gas 和耗时因环境而异):

text
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 会运行项目中发现的全部测试,包括模板自带的测试。

需要进一步限定单个函数时,可以执行:

bash
forge test --match-contract SimpleCounterTest --match-test test_Increment

预期结果:只执行 SimpleCounterTest 中名称匹配 test_Increment 的测试函数,结果仍为 [PASS]。--match-contract 用于匹配测试合约名称,--match-test 用于匹配测试函数名称。

制造失败并查看调用轨迹

接下来故意将第二个断言中的期望值从 1 改成 2,保留第一次断言和 increment() 调用不变。

修改后的测试函数如下,属于片段示例,需替换现有 SimpleCounterTest 合约中的同名函数:

solidity
function test_Increment() public {
    assertEq(counter.count(), 0);
    counter.increment();
    // 故意设置错误期望值,验证失败定位能力
    assertEq(counter.count(), 2);
}

执行失败测试并启用三级详细输出:

bash
forge test --match-contract SimpleCounterTest -vvv

预期输出(关键内容摘录):

text
[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 更完整地显示执行与初始化轨迹,适合深入排查

要查看成功路径与失败路径的调用关系,可以使用:

bash
forge test --match-contract SimpleCounterTest -vvvv

预期结果:失败测试下出现 Traces 区域,可以观察到 SimpleCounter::count() 的读取、SimpleCounter::increment() 的调用,以及最后的断言失败。轨迹中的 Gas 数值、内部调用细节和展示格式取决于当前 Foundry 版本。

Forge 测试执行与失败定位流程

阅读轨迹时,从测试函数入口向下检查调用顺序,再检查返回值与失败位置。这里 increment() 已经正常执行,计数也确实增加到 1,因此问题出在测试预期,而不是合约状态更新逻辑。

修复断言并建立测试基线

将错误断言恢复为 assertEq(counter.count(), 1);,然后执行:

bash
forge test --match-contract SimpleCounterTest -vvvv

预期输出(调用轨迹摘录):

text
[PASS] test_Increment() (gas: <GAS>)
Traces:

在 Traces 下方应能看到计数器的调用及正常返回;测试汇总应显示 1 passed; 0 failed。其中 <GAS> 为实际 Gas 数值,具体轨迹行数可能随版本变化。

如果结果仍然失败,依次检查:

  1. src/SimpleCounter.sol 中的 increment() 是否执行 count += 1。
  2. test/SimpleCounter.t.sol 的期望值是否恢复为 1。
  3. setUp() 是否为每条测试创建新的 SimpleCounter 实例。
  4. 终端是否处于正确项目根目录,是否修改了本课实际执行的测试文件。

最后运行 forge test 检查整个项目,确保新增用例没有破坏其他已有测试。默认模板可能包含额外用例,因此此时总测试数量不一定为 1。

一条可靠的测试基线至少应满足三个条件:测试可以重复执行、修改错误期望值能稳定触发失败、恢复正确期望值后能重新通过。具备这三个条件后,才能进一步增加边界值断言和模糊测试输入,而不必先猜测测试框架是否正常工作。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

运行第一条 Forge 断言用例

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通