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

初始化 Foundry 工程和测试目录

初始化 Foundry 工程和测试目录

本课将从零搭建一个可编译、可运行测试的 Foundry 工程。完成后,你将能够使用 Forge 管理 Solidity 合约,识别源码、测试、脚本与依赖目录,并通过实际编译和测试确认环境正常,为后续模糊测试准备可靠的工程基线。

学习目标

  • 安装并验证 Foundry 工具链,使用 Forge 初始化 Solidity 工程。
  • 理解 src、test、script、lib 和 foundry.toml 的职责。
  • 运行编译与测试命令,定位常见的工具链和依赖问题。

安装 Foundry 并确认工具链

Foundry 是面向以太坊智能合约开发的工具集,主要包含四个命令行工具:

工具 用途 常见命令
Forge 编译、测试和部署合约 forge build、forge test
Cast 调用合约、查询链上数据 cast --version
Anvil 启动本地以太坊开发节点 anvil --version
Chisel 交互式 Solidity 开发环境 chisel --version

以下操作适用于 macOS、Linux 和 Windows 的 WSL2 环境。Windows 用户建议在 WSL2 的 Ubuntu 终端中执行,不要直接将这些 Bash 安装命令复制到 PowerShell。

首先确认终端中可以使用 Git 和 curl:

bash
git --version
curl --version

预期结果:两条命令分别输出 Git 和 curl 的版本信息,具体版本号因环境而异。

接着安装官方的 Foundryup 安装器:

bash
# 下载并运行 Foundry 官方安装脚本
curl -L https://foundry.paradigm.xyz | bash

安装脚本通常会提示将 Foundry 的可执行文件目录加入 PATH。按照终端提示重新加载 Shell 配置,或者关闭终端后重新打开。

然后安装工具链并检查版本:

bash
# 下载并安装 Foundry 工具链
foundryup

# 检查核心工具是否已进入 PATH
forge --version
cast --version
anvil --version
chisel --version

预期结果:foundryup 完成安装,后续四条命令均能输出版本信息。版本号、提交标识和构建日期随安装版本变化,不需要与其他机器完全一致。

创建 Forge 工程

在准备存放代码的目录中执行初始化命令。以下示例使用 contract-lab 作为项目名称,要求同名目标目录尚不存在。

bash
# 创建包含示例合约、测试与脚本的工程
forge init contract-lab
cd contract-lab

# 查看当前工程使用的 Foundry 配置
forge config

预期结果:forge init 成功创建工程,forge config 输出当前生效的配置。默认模板通常包含 Counter.sol 合约、对应测试文件、部署脚本和 forge-std 依赖。

默认初始化通常还会创建 Git 仓库,并将 forge-std 作为项目依赖安装。因此初始化阶段需要 Git 可用,首次下载依赖时需要访问网络。

如果工程目录已经存在并希望直接在其中初始化,可以进入空目录后执行 forge init。不要直接对包含重要代码的非空目录使用强制初始化选项,以免造成文件冲突。

识别工程目录与依赖关系

Forge 默认使用明确的目录约定,编译器会根据配置读取 Solidity 源文件,并通过导入路径解析测试依赖。

路径 主要职责 默认示例
src/ 放置业务合约源码 Counter.sol
test/ 放置 Solidity 测试合约 Counter.t.sol
script/ 放置部署和交互脚本 Counter.s.sol
lib/ 保存项目依赖 forge-std/
foundry.toml 配置项目目录、编译和测试选项 [profile.default]
out/ 保存编译产物 编译时生成
cache/ 保存增量编译缓存 编译时生成

下面的结构图展示各目录在编译和测试过程中的关系。

Foundry 工程目录与编译测试依赖关系

其中,forge-std 是 Foundry 常用的 Solidity 测试标准库,提供 Test 基类、断言方法和测试辅助功能。默认测试通常会从 forge-std/Test.sol 导入 Test,不需要手动复制标准库源码。

打开根目录的 foundry.toml,典型配置如下:

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

这是配置文件示例,表示源码目录为 src,编译输出目录为 out,依赖搜索目录包含 lib。部分模板还会包含其他设置,以实际生成内容为准。

执行以下命令查看 Forge 实际解析到的导入映射:

bash
forge remappings

预期结果:输出包含以 forge-std/ 为前缀、指向 lib/forge-std/src/ 的映射。实际路径表示可能因工具链和项目配置不同而变化。

编译合约并运行基础测试

初始化成功不代表工程一定能够编译。还需要检查 Solidity 编译器、源码导入以及测试运行器是否正常。

在 contract-lab 根目录执行:

bash
# 编译工程中的 Solidity 合约
forge build

# 执行默认模板中的测试
forge test

预期结果:

  • forge build 成功完成编译,不出现 Solidity 编译错误。
  • forge test 显示测试执行结果,默认模板中的测试应通过。
  • 工程中生成或更新 out/ 与 cache/ 目录。

不同 Foundry 版本的控制台日志、编译文件数量、Gas 数值以及默认测试数量可能不同,应以编译成功和测试全部通过为验收标准。

可以进一步使用详细模式观察测试信息:

bash
# 输出更详细的测试执行结果
forge test -vv

预期结果:终端显示测试名称和执行状态;测试通过时显示成功统计。此命令不会主动部署合约到真实区块链,也不需要配置钱包私钥。

为了确认测试依赖确实可用,可以查看 test/Counter.t.sol,检查它是否导入 forge-std/Test.sol,以及测试合约是否继承 Test。若导入成功并能执行断言,说明基础测试依赖已正确接入。

处理初始化与编译失败

初次搭建时,最常见的问题集中在命令路径、Git 依赖、Solidity 编译器下载和导入解析。

现象 可能原因 排查与处理
foundryup: command not found Shell 尚未加载 PATH 重新打开终端,检查 Foundry 安装脚本给出的 PATH 配置提示
forge: command not found 工具链未安装完成 重新执行 foundryup 并检查 forge --version
初始化时依赖下载失败 Git 或网络访问异常 检查 git --version、网络代理和 GitHub 连通性
Source ... not found 依赖缺失或 remappings 错误 检查 lib/forge-std 并执行 forge remappings
无法下载 Solidity 编译器 编译器尚未缓存且网络不可用 恢复网络后重新执行 forge build
编译报 Solidity 版本不匹配 pragma 与编译器配置冲突 检查源码版本约束和 foundry.toml 的 solc_version 设置

当 forge-std 目录确实缺失时,可在工程根目录安装依赖:

bash
# 仅在依赖缺失时执行,避免重复安装
forge install foundry-rs/forge-std

# 重新检查导入映射并编译
forge remappings
forge build

预期结果:依赖成功安装到项目依赖目录,映射能够解析 forge-std/,编译不再因缺少 Test.sol 而失败。安装依赖需要能够访问相应的 Git 仓库。

如果修改配置后出现异常,先运行 forge config 确认实际生效值,而不是直接删除整个项目。需要清除编译缓存时,可以使用 forge clean,它会清理构建产物和缓存,但不会删除 src/、test/ 中的源码。

验收可用于模糊测试的工程基线

最后执行一次完整检查,将结果作为后续开发和排错的参照:

bash
# 确认编译、基础测试和依赖映射都正常
forge build
forge test
forge remappings

预期结果:编译成功、基础测试全部通过,且输出能够识别 forge-std 的导入映射。

验收时同时确认以下项目:

  1. src/Counter.sol 存在且可编译。
  2. test/Counter.t.sol 存在且其测试可以执行。
  3. script/ 包含初始化生成的脚本文件。
  4. lib/forge-std/ 包含标准库源码。
  5. foundry.toml 能被 Forge 正确读取。
  6. out/ 中存在编译产物,且测试结果没有失败项。

这套基线说明合约编译、依赖解析和测试执行链路已经接通。后续加入带随机参数的模糊测试时,如果出现失败,就可以优先检查新增测试逻辑和合约行为,而不必重新怀疑整个工程是否初始化成功。

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

目录与阅读设置

阅读设置

17

记录一个想法

初始化 Foundry 工程和测试目录

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

登录哪都通