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

把模糊测试接入 CI 工作流

把模糊测试接入 CI 工作流

本篇将 Foundry 模糊测试接入 GitHub Actions,让每次 Pull Request 自动完成依赖准备、合约编译和属性测试,并在测试失败时阻止代码合并。完成后,你将拥有一份可直接提交仓库的工作流配置,以及一套检查失败原因的方法。

学习目标

  • 配置 GitHub Actions,自动安装 Foundry 并准备 Solidity 项目依赖。
  • 为 CI 设置独立的模糊测试参数,确保测试失败会使工作流失败。
  • 验证分支保护规则,并定位依赖、编译和属性测试失败。

检查项目是否具备运行条件

以标准 Foundry 项目为例,仓库根目录应存在 foundry.toml、src/、test/,使用 Git 子模块管理依赖时,还应提交 .gitmodules 和依赖子模块的 Git 引用。

先在项目根目录执行:

bash
# 检查工具是否安装,并在本地运行完整测试集
forge --version
forge build
forge test -vvv

预期结果:forge --version 输出已安装的版本;编译成功,测试结果中出现 PASS,最后显示 Suite result: ok 等成功信息。版本号、测试数量和耗时以实际环境为准。

这里有三个必须提前确认的条件:

  • 测试函数遵循 Foundry 识别规则,例如 testFuzz_Transfer(uint256 amount),并包含实际断言。
  • 项目依赖能够从仓库配置恢复,不能只依赖开发者电脑上未提交的文件。
  • 关键测试不依赖个人钱包、交互式输入或未提供的环境变量。

如果测试需要主网分叉 RPC,应将访问凭据配置为 GitHub Actions Secrets。来自外部 Fork 的 Pull Request 通常无法读取仓库 Secrets,因此建议将必过的合并检查设计为不依赖私有 RPC 的本地属性测试,分叉测试另外运行。

配置独立的 CI 测试参数

创建或编辑仓库根目录的 foundry.toml。下面是完整的最小配置,已有项目需要保留自己的编译器、remappings 等设置,再合并 CI 参数。

toml
[profile.default]
src = "src"
test = "test"
out = "out"
libs = ["lib"]

# CI 使用独立的运行次数,避免影响开发者本地快速测试
[profile.ci.fuzz]
runs = 1024

[profile.ci.invariant]
runs = 128
depth = 100

这段配置在设置 FOUNDRY_PROFILE=ci 时生效:普通模糊测试每个测试执行 1024 次随机输入,Invariant 测试执行 128 轮、每轮最多 100 次目标调用。实际执行数量还会受到测试失败、拒绝输入和具体测试配置的影响。

这组参数适合作为中小型项目的起点。若 CI 执行时间超出预期,可以先分析耗时最大的测试,再调整运行次数;不要直接将所有属性测试关闭。

在本地验证 CI Profile:

bash
# 使用与 GitHub Actions 相同的测试配置
FOUNDRY_PROFILE=ci forge test -vv

预期结果:通过的模糊测试报告包含类似 [PASS] testFuzz_Transfer(uint256) (runs: 1024, ...) 的信息。函数名和其他统计值取决于项目实际测试。若没有对应模糊测试函数,则不会产生这条报告。

创建 GitHub Actions 工作流

在仓库中新建 .github/workflows/foundry.yml。以下配置适用于仓库根目录就是 Foundry 项目、依赖已通过 Git 子模块登记的场景。

yaml
name: Foundry Tests

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

jobs:
  forge-test:
    name: Forge Test
    runs-on: ubuntu-latest
    timeout-minutes: 20
    env:
      FOUNDRY_PROFILE: ci
    steps:
      # 递归检出项目及通过 Git 子模块登记的依赖
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          submodules: recursive
          persist-credentials: false

      # 使用官方 Foundry 安装 Action
      - name: Install Foundry
        uses: foundry-rs/foundry-toolchain@v1
        with:
          version: stable

      - name: Verify toolchain
        run: forge --version

      - name: Build contracts
        run: forge build

      # 任一测试失败都会使当前步骤返回非零退出码
      - name: Run fuzz and invariant tests
        run: forge test -vvv

配置的关键行为如下:

  • pull_request 在 PR 事件触发时检查改动,push 在提交进入 main 后再次验证,workflow_dispatch 支持手动运行。
  • actions/checkout@v4 的 submodules: recursive 会递归检出已登记的子模块;如果项目使用其他依赖管理方式,必须补充对应的安装步骤。
  • foundry-rs/foundry-toolchain@v1 安装 Foundry,stable 表示使用稳定版本。生产项目建议进一步固定经过验证的具体工具版本。
  • FOUNDRY_PROFILE: ci 让编译和测试使用 CI Profile。
  • forge test -vvv 运行匹配的 Foundry 测试,包括常规模糊测试和 Invariant 测试,并提供失败追踪信息。
  • timeout-minutes: 20 限制整个 Job 的执行时间,超时会导致检查失败。

正常情况下,forge build 或 forge test 返回非零退出码后,GitHub Actions 会将对应步骤标记为失败,后续普通步骤不再执行,Job 最终失败。这里无需人为增加 exit 1,也不要设置 continue-on-error: true。

理解测试失败如何阻止合并

GitHub Actions 执行失败并不自动等于 PR 无法合并。必须同时配置仓库的分支保护规则,才能把测试结果变成合并门禁。

GitHub Actions 模糊测试与分支保护门禁流程图

在 GitHub 仓库中按以下顺序设置:

  1. 将工作流提交并推送到远程仓库,创建一个测试用 Pull Request。
  2. 进入仓库的 Actions 页面,找到 Foundry Tests,确认 Forge Test Job 至少运行过一次。
  3. 进入 Settings → Branches,为 main 创建或编辑 Branch protection rule;使用 Rulesets 的仓库可在 Settings → Rules → Rulesets 配置等效规则。
  4. 启用 Require status checks to pass before merging,选择工作流产生的 Forge Test 检查。
  5. 保存规则,然后在 PR 页面确认必需检查的状态。

GitHub 页面入口会因仓库权限、组织策略和界面版本不同而略有差异。必须先运行一次工作流,相关状态检查才更容易出现在可选择列表中。

以下验收行为应当成立:

场景 Actions 结果 配置门禁后的合并行为
编译通过且所有测试通过 Success 满足该检查要求
属性断言失败 Failure 阻止合并
依赖下载或编译失败 Failure 阻止合并
Job 超时 Failure 阻止合并
必需检查尚未完成 Pending 等待检查完成

这里假定分支保护规则正确生效,且操作者没有绕过规则的权限。通过状态检查只是满足合并条件之一,并不代表代码已经完成安全审计。

制造一次可验证的失败

要验证失败是否真的阻断合并,可以在测试分支暂时创建 test/CiGate.t.sol。这个测试不依赖外部测试库,能够直接展示断言失败的退出行为。

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

contract CiGateTest {
    // 故意让属性检查失败,只用于验证 CI 门禁
    function testFuzz_CiMustRejectFailure(uint256 value) public pure {
        assert(value < 0);
    }
}

由于 Solidity 的 uint256 不可能小于零,Foundry 执行该模糊测试时会发生断言失败。这个测试应当只存在于临时验收分支中。

执行:

bash
FOUNDRY_PROFILE=ci forge test --match-test testFuzz_CiMustRejectFailure -vvv

预期结果:控制台出现 FAIL,测试结果为失败,命令返回非零退出码。失败详情通常包含反例输入;具体输出取决于 Foundry 版本。

把测试文件提交并推送到 PR 后,检查以下结果:

  1. Actions 中的 Run fuzz and invariant tests 显示失败。
  2. PR 的 Forge Test 必需检查显示未通过。
  3. 合并操作被分支保护规则阻止。
  4. 删除故意失败的测试文件,再次推送提交,确认检查恢复成功。

如果第一项失败但第三项仍允许合并,应检查分支规则是否覆盖目标分支,以及选定的必需检查名称是否与实际 Job 一致。

排查 CI 中常见的不稳定失败

接入 CI 后,常见问题并非都来自合约逻辑。建议先按日志中最早出现的错误步骤定位,不要一看到测试红灯就重复点击 Re-run。

现象 常见原因 对应处理
Solidity import 找不到 子模块未检出或依赖未提交 检查 .gitmodules、lib/ 和 remappings
本地通过,CI 编译失败 Foundry 或 solc 版本不一致 固定工具版本并核对 foundry.toml
同一模糊测试偶尔失败 随机输入触及真实边界缺陷 保存反例与 seed,复现并修复断言或逻辑
vm.assume 相关测试失败 输入过滤过多,超过拒绝阈值 使用 bound 或改进输入生成范围
Fork 测试失败 RPC 不可用、权限不足或链状态变化 检查 Secrets 和固定区块高度
Job 被超时取消 测试运行量或外部调用耗时过大 拆分长耗时测试并分析执行时间

调试随机失败时,优先使用日志中记录的反例和 seed。不要简单地把随机运行次数调小来隐藏问题。对于依赖外部区块链状态的测试,应固定分叉区块,避免同一份代码在不同链状态下得到不同结果。

还可以使用以下命令区分编译问题与具体模糊测试问题:

bash
# 先确认编译,再单独执行目标测试函数
forge build
FOUNDRY_PROFILE=ci forge test --match-test testFuzz_Transfer -vvvv

预期结果:若编译正常且项目存在 testFuzz_Transfer,控制台会显示该测试的通过或失败状态;失败时 -vvvv 提供更详细的执行追踪。实际函数名需要替换为项目中的测试名称。

当工作流能够自动运行、故意失败的属性断言会导致非零退出码、必需状态检查确实阻止合并,并且修复后检查能够恢复成功时,这套 Foundry CI 门禁才算完成验收。

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

目录与阅读设置

阅读设置

17

记录一个想法

把模糊测试接入 CI 工作流

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

登录哪都通