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

用覆盖率识别未触达分支

用覆盖率识别未触达分支

模糊测试全部通过,并不代表智能合约的关键路径都被执行过。本课使用 Forge 生成覆盖率报告,定位未触达的函数与条件分支,再结合 Handler 调用指标判断测试输入是否真正改变了合约状态,最终形成一份可以用于补测和持续集成的覆盖缺口清单。

学习目标

  • 使用 forge coverage 生成并解读行、语句、分支和函数覆盖率。
  • 结合 Handler 调用量、回滚量与丢弃量识别无效测试路径。
  • 将覆盖缺口转化为可验证的补测案例,并理解覆盖率的安全边界。

运行 Forge 覆盖率分析

在包含 foundry.toml、src/ 和 test/ 的 Foundry 项目根目录执行。以下命令适用于支持 forge coverage 的 Foundry 版本;具体选项可通过 forge coverage --help 确认。

bash
# 检查安装版本并确认测试基线
forge --version
forge test

# 输出终端汇总和机器可读取的 LCOV 报告
forge coverage --report summary --report lcov

预期结果:测试通过后,终端出现覆盖率汇总表,项目根目录通常生成 lcov.info。具体覆盖率数值取决于项目,不应把某个示例百分比当成固定结果。forge --version 的版本信息同样因环境而异。

汇总报告主要包含四项指标:

指标 含义 首要检查点
Lines 被执行的源码行比例 是否有整段业务逻辑未运行
Statements 被执行的语句比例 是否遗漏状态更新或错误处理
Branches 已触达的条件分支比例 if 的不同结果是否均出现
Funcs 被调用的函数比例 管理入口、提现入口是否未触达

例如,一个合约有 20 个统计分支,仅命中 12 个,则分支覆盖率为 60%。即使行覆盖率达到 95%,剩余的 8 个分支仍然需要检查。

覆盖率通常会包含测试代码、辅助合约或依赖代码。审查时应优先关注 src/ 中真正部署的业务合约,并保持不同测试批次的统计范围一致。不要把包含大量测试辅助代码的全项目总覆盖率直接当成生产合约的覆盖率。

定位没有执行的业务分支

假设一个金库合约允许用户存入和取出 ETH,但账户余额不足时必须拒绝提现。下面是一个可以独立编译的 Solidity 合约示例,适用于 Solidity 0.8.20 及兼容编译器。

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

contract Vault {
    mapping(address => uint256) public balances;

    function deposit() external payable {
        require(msg.value > 0, "ZERO_DEPOSIT");
        balances[msg.sender] += msg.value;
    }

    function withdraw(uint256 amount) external {
        // 必须先扣减内部余额,再进行外部转账
        require(amount <= balances[msg.sender], "INSUFFICIENT");
        balances[msg.sender] -= amount;
        (bool ok, ) = payable(msg.sender).call{value: amount}("");
        require(ok, "TRANSFER_FAILED");
    }
}

这是完整合约示例,可保存为 src/Vault.sol。其中 INSUFFICIENT 是余额不足分支,TRANSFER_FAILED 是外部转账失败分支,两者需要不同的测试条件才能触达。

假设现有测试仅执行正常存款和正常提现,那么可能出现以下覆盖缺口:

代码位置 已有场景 尚需补测
deposit() 存入 1 ETH 存入 0 ETH
withdraw() 存入 1 ETH 后取出 0.5 ETH 申请取出 2 ETH
withdraw() 向普通外部账户转账成功 接收 ETH 时主动拒绝的合约账户

这些是需要检查的业务场景,不代表 Forge 一定为每条 require 生成完全相同的分支统计条目。实际定位时,应同时查看源码条件和报告中的命中记录。

对需要更细粒度分析的项目,可以执行:

bash
# 生成可供逐条检查的调试覆盖率报告
forge coverage --report debug

预期结果:Forge 输出调试覆盖率信息,用于进一步查看覆盖项及命中情况;具体展示内容随 Foundry 版本而变化。如果希望在网页中逐行查看,可使用前面生成的 lcov.info 配合支持 LCOV 的可视化工具。

补测优先级建议依次考虑:资金转移、访问控制、清算与偿付、价格边界、暂停与恢复,最后才是普通查询函数。未触达的只读辅助函数通常不应比资金相关的未触达分支获得更高优先级。

结合 Handler 指标判断测试是否有效

有状态模糊测试通常由 Handler 接收随机输入,再调用目标合约。一个 Handler 函数被调用,并不意味着目标合约的业务分支已经被成功执行。

Forge 覆盖率与 Handler 调用指标关联示意图

在 foundry.toml 中可以为不变量测试启用调用指标。以下为独立配置片段;已有配置文件应合并对应表段,避免重复定义。

toml
[invariant]
runs = 256
depth = 50
show_metrics = true

配置生效后执行:

bash
# 运行名称以 invariant_ 开头的测试并输出详细信息
forge test --match-test 'invariant_*' -vv

预期结果:已配置的不变量测试执行 256 轮,每轮设置最多 50 次目标调用;结果报告包含实际运行轮数、调用数与回滚数,并在支持该选项的版本中展示各 Handler 函数的调用指标。实际调用数可能受到测试失败、过滤条件及执行机制影响,不保证恒为 12800。

假设某次测试统计得到如下数据:

Handler 操作 调用次数 回滚或丢弃次数 诊断结论
deposit 4000 3200 大量输入未形成有效存款
withdraw 4200 3900 多数请求无法完成提现
transfer 3800 0 需进一步核实是否改变关键状态

这是用于分析的假设数据,不是 Forge 的固定输出格式。回滚和丢弃在工具报告中可能分别统计,不能不加区分地当成同一种业务失败。

以 withdraw 为例,若 4200 次调用中有 3900 次回滚或丢弃,剩余 300 次占比约为 7.1%。这个比例只是粗略的有效调用参考,并不能证明 300 次都触达了不同的提现路径。

应进一步检查 Handler 是否先完成存款、是否将提现金额限制到有效范围,以及是否覆盖余额不足、余额恰好相等和余额大于提现金额三种情况。对正常操作使用 bound 生成合理输入,对预期回滚场景单独设计测试,不要通过过滤条件把所有异常输入都排除。

把覆盖缺口变成具体测试

发现余额不足分支没有被触达后,应添加明确断言的测试,而不是单纯增加随机运行次数。

以下测试文件依赖前面的 src/Vault.sol 和项目已安装的 forge-std。保存为 test/VaultCoverage.t.sol,可以直接测试余额不足的回滚行为。

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

import {Test} from "forge-std/Test.sol";
import {Vault} from "../src/Vault.sol";

contract VaultCoverageTest is Test {
    Vault vault;
    address alice = address(0xA11CE);

    function setUp() public {
        vault = new Vault();
        vm.deal(alice, 3 ether);
    }

    function testWithdrawInsufficientBalance() public {
        vm.startPrank(alice);
        vault.deposit{value: 1 ether}();

        // 提现超过账户余额,必须按预期回滚
        vm.expectRevert(bytes("INSUFFICIENT"));
        vault.withdraw(2 ether);
        vm.stopPrank();

        assertEq(vault.balances(alice), 1 ether);
    }
}

执行测试并重新生成覆盖率:

bash
forge test --match-test testWithdrawInsufficientBalance
forge coverage --report summary

预期结果:单独测试显示 [PASS] testWithdrawInsufficientBalance(),重新运行覆盖率后,相应余额检查逻辑被执行。分支覆盖率是否上升以及上升多少,应以实际报告为准。

这项测试同时验证两个安全行为:超额提现会回滚,回滚后 Alice 的内部余额仍为 1 ETH。相比仅检查代码路径被执行,它增加了对错误处理和状态不变性的验证。

对于剩余的转账失败路径,可以使用拒绝接收 ETH 的测试合约作为提现调用者,并验证转账失败时内部余额恢复。由于这需要额外构造合约调用者,应作为独立补测任务,而不是假设普通 EOA 提现能够触发失败。

在持续集成中解释覆盖率变化

CI 中应固定 Foundry 版本、Solidity 编译配置、测试选择范围和关键随机测试参数,然后对同一批生产合约比较覆盖率。否则,依赖升级或测试范围改变可能造成百分比波动,却不代表业务分支真的增加或减少。

建议在代码评审中维护如下检查表:

检查项 可执行验收标准
关键函数 存款、提现、管理员操作均有测试入口
关键失败路径 余额不足、零金额、未授权调用均有明确断言
Handler 质量 关键操作调用数非零,回滚及丢弃比例经过解释
覆盖率变化 新增未覆盖分支逐条说明原因和风险
安全属性 余额守恒、权限约束等具有独立断言

例如,某次提交使分支覆盖率从 82% 下降至 78%,不能只凭下降 4 个百分点就判断存在漏洞。应检查新增的是资金释放分支还是无害的辅助判断;前者需要优先补测,后者可以结合风险评估安排处理。

实际交付时,应同时保留覆盖率报告、Handler 指标、失败用例和不变量断言。覆盖率用于发现测试没有走到哪里,Handler 指标用于判断随机测试是否有效进入业务逻辑,而安全属性测试用于判断走到这些路径后,合约是否仍满足资金和权限约束。

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

目录与阅读设置

阅读设置

17

记录一个想法

用覆盖率识别未触达分支

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

登录哪都通