智能合约与以太坊 / 系统课时
用 Forge 编写首个单元测试
用 Forge 编写首个单元测试
合约能够成功编译,并不代表状态变化符合预期。这一课使用 Foundry 的 Forge 为 Solidity 计数器编写单元测试,验证初始状态、递增操作和数值设置,并通过一次故意失败的断言学会读取测试报告、定位错误。
学习目标
- 创建 Solidity 测试合约,理解
setUp()、test_命名约定和测试隔离机制。 - 使用
assertEq验证计数器的初始值与状态变化。 - 运行
forge test,区分测试通过、断言失败和编译错误。
准备 Foundry 测试工程
Forge 是 Foundry 提供的 Solidity 编译与测试工具。它可以在本地执行测试合约,不需要先部署到公共测试网,也不需要单独启动 Anvil 节点。
前提是已经安装 Foundry,并且终端可以执行 forge 命令。在一个尚不存在 counter-lab 目录的位置执行:
forge init counter-lab
cd counter-lab预期结果:项目初始化成功,当前目录下具有以下文件和目录。这里列出的是项目结构检查结果,不是命令的逐字终端回显。
foundry.toml
src/
test/
lib/forge-std/其中,src/ 存放业务合约,test/ 存放测试合约,lib/forge-std/ 提供测试断言和辅助工具,foundry.toml 保存工程配置。默认模板可能还包含 script/ 等目录。
Forge 通常使用以下约定识别测试:
| 项目 | 约定 | 本课示例 |
|---|---|---|
| 测试文件 | 通常以 .t.sol 结尾 |
Counter.t.sol |
| 测试合约 | 通常以 Test 结尾 |
CounterTest |
| 普通测试函数 | 名称以 test 开头 |
test_IncrementAddsOne |
| 初始化函数 | setUp() |
每次测试前部署计数器 |
| 断言 | 使用 assertEq 等方法 |
检查实际值等于预期值 |
文件和合约的命名属于常用约定,不能把所有约定都理解为强制语法。Forge 根据测试函数的命名规则发现测试,.t.sol 则方便开发者区分测试文件。
编写需要验证的计数器
将 src/Counter.sol 的内容完整替换为下面的合约。这里使用 Solidity ^0.8.20,并保持功能简单,使测试结果能够直接对应到状态变化。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract Counter {
// public 状态变量自动生成 number() 读取函数
uint256 public number;
function increment() external {
// 每次调用只增加一次,便于检查状态变化
number += 1;
}
function setNumber(uint256 newNumber) external {
number = newNumber;
}
}合约有三个明确的行为约束:部署后 number 默认等于 0;调用一次 increment() 后变为 1;调用 setNumber(42) 后变为 42。
number 是持久化状态变量,public 会让编译器生成同名读取函数 number()。测试通过它读取实际状态,而不是假设调用执行成功就代表数值正确。
这里不需要构造函数,因为 Solidity 会把未显式初始化的 uint256 状态变量初始化为 0。这些可观察行为就是接下来要验证的测试条件。
使用 setUp 和 assertEq 编写测试
将 test/Counter.t.sol 完整替换为以下代码。测试合约继承 Forge 标准库的 Test,从而获得 assertEq 等断言方法。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {Test} from "forge-std/Test.sol";
import {Counter} from "../src/Counter.sol";
contract CounterTest is Test {
Counter internal counter;
function setUp() public {
// 每个测试开始前重新部署,避免用例共享修改后的状态
counter = new Counter();
}
function test_InitialNumberIsZero() public {
assertEq(counter.number(), 0);
}
function test_IncrementAddsOne() public {
counter.increment();
assertEq(counter.number(), 1);
}
function test_SetNumberUpdatesValue() public {
counter.setNumber(42);
assertEq(counter.number(), 42);
}
}这个测试合约包含三个彼此独立的测试函数。每个函数只验证一项具体行为,因此测试失败时能够快速确定是哪项约束未被满足。
setUp() 是 Forge 识别的初始化函数,会在每个测试函数执行之前运行。这里每次都通过 new Counter() 创建新的计数器实例,所以三个测试不会因为共享修改后的合约状态而互相影响。
assertEq(actual, expected) 的第一个参数是实际值,第二个参数是预期值。两者相等时断言通过;不相等时断言失败,当前测试被标记为失败。
注意,测试中的 counter.increment() 并不会自动判断递增是否正确。真正检查业务结果的是后面的 assertEq(counter.number(), 1)。如果只调用函数而没有验证返回值、状态或事件,就可能出现代码正常执行但业务结果错误的情况。
Forge 也支持名称以 testFuzz 开头、带参数的模糊测试。本课的三个函数都不接收参数,属于使用固定输入和固定预期结果的普通单元测试。
运行测试并理解输出
确认两个 Solidity 文件已经保存,在项目根目录执行:
forge test --match-path test/Counter.t.sol预期输出的关键内容如下。编译信息、Gas 数值和执行耗时会随 Foundry 版本及运行环境变化,<GAS> 表示实际显示的 Gas 数字。
Ran 3 tests for test/Counter.t.sol:CounterTest
[PASS] test_IncrementAddsOne() (gas: <GAS>)
[PASS] test_InitialNumberIsZero() (gas: <GAS>)
[PASS] test_SetNumberUpdatesValue() (gas: <GAS>)
Suite result: ok. 3 passed; 0 failed; 0 skipped--match-path 用于筛选指定路径的测试文件。[PASS] 表示对应测试函数成功执行,并且所有断言均通过;3 passed 表示有三个测试通过,0 failed 表示没有失败的测试。
这里的 Gas 数值是测试执行时报告的消耗指标,不是判断测试正确性的依据。即使 Gas 使用量发生变化,只要业务断言成立,测试仍然可以通过。
如果项目中存在多个测试合约,不使用筛选参数直接运行 forge test,Forge 就会执行当前配置范围内发现的测试,而不只运行 CounterTest。
制造一次断言失败并定位原因
为了确认测试确实能发现错误,而不是始终返回成功,暂时修改 test_IncrementAddsOne() 中的断言,把预期值从 1 改为 2,保留前面的 counter.increment() 不变。
此时计数器的实际值仍然是 1,但测试要求它等于 2。在项目根目录执行:
forge test --match-test test_IncrementAddsOne -vv预期结果:这个测试被标记为 [FAIL],测试套件显示 1 failed,命令以非零状态退出。详细断言信息会指出实际值 1 与预期值 2 不匹配;具体错误文本和 Gas 数值可能因版本不同而变化。
--match-test 按测试函数名称筛选,避免运行其他无关测试。-vv 可以显示更多测试日志和断言错误信息。如果仍然无法定位失败调用,可以改用 -vvv 查看失败测试的执行追踪。
排查时按以下顺序检查:
- 确认失败属于编译错误还是测试断言失败。编译错误需要先修正 Solidity 语法、导入路径或类型问题。
- 如果出现
[FAIL],先找到失败函数,例如test_IncrementAddsOne。 - 检查断言中的实际值和预期值,确认操作是否执行,以及预期值是否写错。
- 核对
setUp()是否准备了正确的初始状态,避免把错误的初始化结果误判为业务函数错误。
本例的根因是测试预期值故意写错,而不是 increment() 的实现有问题。将断言恢复为 assertEq(counter.number(), 1);,重新执行原来的测试命令,三个测试应当再次全部通过。
单元测试的价值可以通过这次正反验证直接观察:正确行为对应通过的断言,错误预期能够被明确报告。以后每增加一个合约函数,都可以沿用这种方式,为初始状态、一次操作后的状态和关键边界条件分别编写测试。