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

用 Forge 编写首个单元测试

用 Forge 编写首个单元测试

合约能够成功编译,并不代表状态变化符合预期。这一课使用 Foundry 的 Forge 为 Solidity 计数器编写单元测试,验证初始状态、递增操作和数值设置,并通过一次故意失败的断言学会读取测试报告、定位错误。

学习目标

  • 创建 Solidity 测试合约,理解 setUp()、test_ 命名约定和测试隔离机制。
  • 使用 assertEq 验证计数器的初始值与状态变化。
  • 运行 forge test,区分测试通过、断言失败和编译错误。

准备 Foundry 测试工程

Forge 是 Foundry 提供的 Solidity 编译与测试工具。它可以在本地执行测试合约,不需要先部署到公共测试网,也不需要单独启动 Anvil 节点。

前提是已经安装 Foundry,并且终端可以执行 forge 命令。在一个尚不存在 counter-lab 目录的位置执行:

bash
forge init counter-lab
cd counter-lab

预期结果:项目初始化成功,当前目录下具有以下文件和目录。这里列出的是项目结构检查结果,不是命令的逐字终端回显。

text
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,并保持功能简单,使测试结果能够直接对应到状态变化。

solidity
// 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 等断言方法。

solidity
// 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 文件已经保存,在项目根目录执行:

bash
forge test --match-path test/Counter.t.sol

预期输出的关键内容如下。编译信息、Gas 数值和执行耗时会随 Foundry 版本及运行环境变化,<GAS> 表示实际显示的 Gas 数字。

text
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。在项目根目录执行:

bash
forge test --match-test test_IncrementAddsOne -vv

预期结果:这个测试被标记为 [FAIL],测试套件显示 1 failed,命令以非零状态退出。详细断言信息会指出实际值 1 与预期值 2 不匹配;具体错误文本和 Gas 数值可能因版本不同而变化。

--match-test 按测试函数名称筛选,避免运行其他无关测试。-vv 可以显示更多测试日志和断言错误信息。如果仍然无法定位失败调用,可以改用 -vvv 查看失败测试的执行追踪。

排查时按以下顺序检查:

  1. 确认失败属于编译错误还是测试断言失败。编译错误需要先修正 Solidity 语法、导入路径或类型问题。
  2. 如果出现 [FAIL],先找到失败函数,例如 test_IncrementAddsOne。
  3. 检查断言中的实际值和预期值,确认操作是否执行,以及预期值是否写错。
  4. 核对 setUp() 是否准备了正确的初始状态,避免把错误的初始化结果误判为业务函数错误。

本例的根因是测试预期值故意写错,而不是 increment() 的实现有问题。将断言恢复为 assertEq(counter.number(), 1);,重新执行原来的测试命令,三个测试应当再次全部通过。

单元测试的价值可以通过这次正反验证直接观察:正确行为对应通过的断言,错误预期能够被明确报告。以后每增加一个合约函数,都可以沿用这种方式,为初始状态、一次操作后的状态和关键边界条件分别编写测试。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 Forge 编写首个单元测试

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

登录哪都通