智能合约与以太坊 / 系统课时
把模糊测试接入 CI 工作流
把模糊测试接入 CI 工作流
本篇将 Foundry 模糊测试接入 GitHub Actions,让每次 Pull Request 自动完成依赖准备、合约编译和属性测试,并在测试失败时阻止代码合并。完成后,你将拥有一份可直接提交仓库的工作流配置,以及一套检查失败原因的方法。
学习目标
- 配置 GitHub Actions,自动安装 Foundry 并准备 Solidity 项目依赖。
- 为 CI 设置独立的模糊测试参数,确保测试失败会使工作流失败。
- 验证分支保护规则,并定位依赖、编译和属性测试失败。
检查项目是否具备运行条件
以标准 Foundry 项目为例,仓库根目录应存在 foundry.toml、src/、test/,使用 Git 子模块管理依赖时,还应提交 .gitmodules 和依赖子模块的 Git 引用。
先在项目根目录执行:
# 检查工具是否安装,并在本地运行完整测试集
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 参数。
[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:
# 使用与 GitHub Actions 相同的测试配置
FOUNDRY_PROFILE=ci forge test -vv预期结果:通过的模糊测试报告包含类似 [PASS] testFuzz_Transfer(uint256) (runs: 1024, ...) 的信息。函数名和其他统计值取决于项目实际测试。若没有对应模糊测试函数,则不会产生这条报告。
创建 GitHub Actions 工作流
在仓库中新建 .github/workflows/foundry.yml。以下配置适用于仓库根目录就是 Foundry 项目、依赖已通过 Git 子模块登记的场景。
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 仓库中按以下顺序设置:
- 将工作流提交并推送到远程仓库,创建一个测试用 Pull Request。
- 进入仓库的
Actions页面,找到Foundry Tests,确认Forge TestJob 至少运行过一次。 - 进入
Settings → Branches,为main创建或编辑 Branch protection rule;使用 Rulesets 的仓库可在Settings → Rules → Rulesets配置等效规则。 - 启用
Require status checks to pass before merging,选择工作流产生的Forge Test检查。 - 保存规则,然后在 PR 页面确认必需检查的状态。
GitHub 页面入口会因仓库权限、组织策略和界面版本不同而略有差异。必须先运行一次工作流,相关状态检查才更容易出现在可选择列表中。
以下验收行为应当成立:
| 场景 | Actions 结果 | 配置门禁后的合并行为 |
|---|---|---|
| 编译通过且所有测试通过 | Success | 满足该检查要求 |
| 属性断言失败 | Failure | 阻止合并 |
| 依赖下载或编译失败 | Failure | 阻止合并 |
| Job 超时 | Failure | 阻止合并 |
| 必需检查尚未完成 | Pending | 等待检查完成 |
这里假定分支保护规则正确生效,且操作者没有绕过规则的权限。通过状态检查只是满足合并条件之一,并不代表代码已经完成安全审计。
制造一次可验证的失败
要验证失败是否真的阻断合并,可以在测试分支暂时创建 test/CiGate.t.sol。这个测试不依赖外部测试库,能够直接展示断言失败的退出行为。
// 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 执行该模糊测试时会发生断言失败。这个测试应当只存在于临时验收分支中。
执行:
FOUNDRY_PROFILE=ci forge test --match-test testFuzz_CiMustRejectFailure -vvv预期结果:控制台出现 FAIL,测试结果为失败,命令返回非零退出码。失败详情通常包含反例输入;具体输出取决于 Foundry 版本。
把测试文件提交并推送到 PR 后,检查以下结果:
Actions中的Run fuzz and invariant tests显示失败。- PR 的
Forge Test必需检查显示未通过。 - 合并操作被分支保护规则阻止。
- 删除故意失败的测试文件,再次推送提交,确认检查恢复成功。
如果第一项失败但第三项仍允许合并,应检查分支规则是否覆盖目标分支,以及选定的必需检查名称是否与实际 Job 一致。
排查 CI 中常见的不稳定失败
接入 CI 后,常见问题并非都来自合约逻辑。建议先按日志中最早出现的错误步骤定位,不要一看到测试红灯就重复点击 Re-run。
| 现象 | 常见原因 | 对应处理 |
|---|---|---|
| Solidity import 找不到 | 子模块未检出或依赖未提交 | 检查 .gitmodules、lib/ 和 remappings |
| 本地通过,CI 编译失败 | Foundry 或 solc 版本不一致 | 固定工具版本并核对 foundry.toml |
| 同一模糊测试偶尔失败 | 随机输入触及真实边界缺陷 | 保存反例与 seed,复现并修复断言或逻辑 |
vm.assume 相关测试失败 |
输入过滤过多,超过拒绝阈值 | 使用 bound 或改进输入生成范围 |
| Fork 测试失败 | RPC 不可用、权限不足或链状态变化 | 检查 Secrets 和固定区块高度 |
| Job 被超时取消 | 测试运行量或外部调用耗时过大 | 拆分长耗时测试并分析执行时间 |
调试随机失败时,优先使用日志中记录的反例和 seed。不要简单地把随机运行次数调小来隐藏问题。对于依赖外部区块链状态的测试,应固定分叉区块,避免同一份代码在不同链状态下得到不同结果。
还可以使用以下命令区分编译问题与具体模糊测试问题:
# 先确认编译,再单独执行目标测试函数
forge build
FOUNDRY_PROFILE=ci forge test --match-test testFuzz_Transfer -vvvv预期结果:若编译正常且项目存在 testFuzz_Transfer,控制台会显示该测试的通过或失败状态;失败时 -vvvv 提供更详细的执行追踪。实际函数名需要替换为项目中的测试名称。
当工作流能够自动运行、故意失败的属性断言会导致非零退出码、必需状态检查确实阻止合并,并且修复后检查能够恢复成功时,这套 Foundry CI 门禁才算完成验收。