web3-testing

web3-testing skill 概览

web3-testing 能做什么

web3-testing skill 用来帮助 agent 设计并搭建基于 Hardhat 和 Foundry 的智能合约测试工作流。它面向的不是只想要一个泛泛的“写点 Solidity 测试”提示的团队，而是需要更完整测试方案的人：单元测试、集成覆盖、主网 fork、fuzzing、gas 检查，以及与验证相关的配置都在它的能力范围内。

谁适合使用 web3-testing

这个 web3-testing skill 特别适合：

• 正在从零开始建立或升级测试体系的 Solidity 开发者
• 转向 Web3 的 QA 和测试自动化工程师
• 需要用真实 fork 状态做验证的 DeFi 团队
• 希望快速获得结构化测试思路的审计人员或协议工程师

如果你只需要一个非常简单的一次性单元测试，或者你的技术栈并不用 Hardhat / Foundry，那它的价值就会小很多。

它真正解决的工作问题

大多数用户并不想看理论。他们真正想完成的是：从“我已经有合约和风险点”快速走到“我有一套可信、可运行的测试计划和起步测试代码”。web3-testing 的价值就在于，它会把对话推进到更具体的测试搭建和进阶模式上，而这些内容往往是普通提示词容易漏掉的，尤其是 fork 状态、fuzzing、gas 报告，以及分层测试策略。

web3-testing 的差异化优势

和通用编码提示相比，web3-testing 在这些方面给出的指导更强：

• 如何在 Hardhat 和 Foundry 工作流之间做选择
• 如何搭建更贴近真实环境的网络和运行配置
• 如何覆盖智能合约里常见的边界和异常情况
• 如何基于 fork 链上状态测试协议行为
• 如何补上 coverage、gas reporting 这类质量信号

安装前要知道什么

从仓库结构来看，它的信号很明确：这个 skill 主要就是一份 SKILL.md 操作手册，而不是一个附带脚本、工具或参考资源的大型工具包。好处是上手很轻，接入成本低；但也意味着你拿到的是方法指导和示例，不是自动化能力。如果你想要一个自带 helper、可以直接落地的强约束测试框架，那它更适合作为“思路 + 脚手架”辅助，而不是即装即用的 package。

如何使用 web3-testing skill

web3-testing 的安装方式

从上层仓库安装这个 skill：

npx skills add https://github.com/wshobson/agents --skill web3-testing

由于仓库路径是 plugins/blockchain-web3/skills/web3-testing，你安装的是一份聚焦的 skill 文档，而不是独立的 npm 测试库。

先看这个文件

从这里开始：

• SKILL.md

这就是这里真正的事实来源。该 skill 目录下没有有实际分量的配套子目录，所以不要预期别处还藏着什么 helper。

web3-testing 需要你提供哪些输入

当你提供下面这些信息时，web3-testing 的效果最好：

• 合约的用途
• 关键函数和访问控制方式
• 不变量或安全属性
• 你偏好的工具链：Hardhat、Foundry，或两者都用
• 外部依赖，比如预言机、池子、token、代理合约
• 你需要的是单元测试、集成测试、fork 测试、fuzzing，还是 gas 检查

弱输入示例：“Write tests for my contract.”

强输入示例：“Using Foundry, create unit and fuzz tests for an ERC20 staking contract with reward accrual, admin-only parameter updates, pause behavior, and emergency withdrawal. Include revert-path coverage and invariants around total staked balances.”

把模糊目标变成可用提示词

一个好用的 web3-testing usage 提示通常包含四部分：

1. 技术栈
2. 合约暴露面
3. 风险区域
4. 希望输出的格式

示例：

“Use the web3-testing skill to propose a test plan and starter files for a Hardhat project. Contract set: Vault.sol, Strategy.sol, OracleAdapter.sol. Focus on deposit/withdraw accounting, role restrictions, stale oracle handling, slippage boundaries, and upgrade safety. Include unit tests, one mainnet fork scenario, and gas reporter setup.”

这比一句“给我全面测试”要好得多，因为它明确告诉 agent：在你的场景里，“全面”具体指什么。

有意识地选择 Hardhat 还是 Foundry

源内容同时覆盖了这两个框架，所以你的提示里最好明确写出要优先优化哪个。

当你更需要下面这些能力时，优先用 `Hardhat``：

• 基于 JavaScript 或 TypeScript 的测试流程
• 更依赖插件生态的工作流
• 在熟悉的 Node 环境里做 coverage 和 gas reporter 配置
• 更容易和更广泛的应用侧工具链集成

当你更需要下面这些能力时，优先用 Foundry：

• 更快、原生面向 Solidity 的测试
• fuzzing 和 invariant 风格工作流
• 更紧凑、以智能合约为核心的开发反馈循环

如果你的团队两者都在用，要明确说出来，并让 skill 拆分各自职责，而不是含糊地混在一起。

面向测试自动化时，web3-testing 的最佳工作流

对于 web3-testing for Test Automation，效果最强的一套流程通常是：

1. 先让它给出测试矩阵
2. 审查有哪些失败场景遗漏了
3. 再让它生成 setup / config 文件
4. 然后生成起步测试
5. 再结合真实合约代码和 ABI 细化
6. 最后补 fork 和 fuzz 两层

这个顺序能避免一个很常见的失败模式：agent 生成了看起来能跑的测试，但实际并没有反映你的协议风险。

web3-testing 擅长产出什么

在实际使用里，web3-testing 最有用的产出通常是：

• 初始的 hardhat.config.js 测试配置
• 测试类别拆分
• 标准行为的起步单元测试
• 面向 DeFi 集成的 fork 测试思路
• fuzzing 目标和边界场景清单
• gas reporting 和 coverage 建议

它最强的用法，是把它当作“结构化测试指南 + 代码脚手架生成器”。

什么最容易挡住好结果

最大的阻碍通常不是安装问题，而是协议上下文不完整：

• 没有合约代码或函数列表
• 没有说明关键不变量
• 没有解释外部集成关系
• 只要求“full coverage”却不给优先级
• 在一个模糊请求里混用多个框架假设

如果这些信息缺失，输出很容易退化成通用的 ERC20 风格测试建议，而不是协议级、自动化可落地的测试设计。

能提升输出质量的实用提示结构

只要条件允许，尽量按这个结构来写：

• Repository context: framework, Solidity version, proxy pattern, package manager
• Contracts in scope: filenames and responsibilities
• Critical behaviors: deposits, liquidations, claims, rebase logic, governance
• Failure conditions: unauthorized access, rounding, reentrancy assumptions, stale data
• Desired artifacts: config, test plan, test file skeletons, mock strategy, fork scenario
• Constraints: keep tests deterministic, avoid external API reliance, target CI runtime under X minutes

这种格式能给 web3-testing guide 足够精确的上下文，让它生成团队可以快速接手改造的内容。

只在需要真实性时使用 fork 测试

这个 skill 会把 mainnet forking 作为差异化能力之一，但不是所有项目都需要它。适合用 fork 测试的情况包括：

• 行为依赖真实协议状态
• 和 DEX、借贷市场、价格源等集成确实重要
• 用 mock 会掩盖危险的边界情况

下面这些情况则应跳过或限制 fork 测试：

• CI 速度比真实性更重要
• 合约大部分是相对独立的业务逻辑
• 可复现性比生态模拟更重要

在采纳前先验证生成结果

在合并任何通过 web3-testing skill 产出的内容之前，至少检查这些点：

• revert reason 和访问控制假设是否正确？
• token decimals 和 rounding 假设是否符合实际？
• fork 的区块号是否和场景对应？
• gas 与 coverage 插件是否与你的技术栈兼容？
• 测试证明的是不变量，还是只覆盖了 happy path？

这个 skill 确实能节省时间，但协议级正确性仍然依赖你的审查。

web3-testing skill 常见问题

web3-testing 适合新手吗

适合，前提是你已经理解了 Solidity 的基础概念。它可以加速测试体系搭建，也能帮助你看到一套成熟测试栈应该长什么样。若是完全入门的新手，通常仍然需要额外补上 Solidity 语法、部署流程和框架基础。

web3-testing 只适用于 Hardhat 吗

不是。这个 skill 明确覆盖了 Hardhat 和 Foundry。不过它的适配效果在你明确告诉 agent 要优先哪个生态时会更好，而不是让它自己猜。

web3-testing 和普通 AI 提示有什么区别

普通提示经常只能返回比较表层的单元测试。web3-testing 更偏向完整的智能合约测试策略：基于 fork 的真实性、fuzzing、gas 检查、coverage，以及环境配置。也因此，它更适合真实协议验证，而不只是演示性质的测试。

web3-testing 能帮助测试 DeFi 协议吗

可以。这正是它比较契合的使用场景之一，尤其适合你需要基于真实状态做集成测试时。你需要提供协议依赖、预期不变量，以及你最关心的用户流程。

什么情况下不该用 web3-testing

以下情况不建议优先使用 web3-testing：

• 你只需要一个一次性的简单断言
• 你的项目不是以 Solidity 或 EVM 为核心
• 你想要的是一个已经打包好的框架，内含 helper 和 fixture
• 你没有足够的合约上下文，无法定义有意义的测试目标

web3-testing 自带可执行工具吗

基本没有。从仓库能看出来，这更像是文档优先的 skill，提供示例和方法，而不是打包好的脚本或可复用资产。更准确的定位是：指导和生成辅助，而不是可安装的测试框架。

如何改进 web3-testing skill 的使用效果

给 web3-testing 提供协议风险，而不只是文件名

想提高 web3-testing usage 效果，最快的方法就是直接写出你真正担心的失败模式：

• 账务漂移
• 价格操纵
• 权限绕过
• 升级初始化错误
• 极端输入下资不抵债

这样输出就会从泛泛的脚手架，转向真正以风险驱动的测试设计。

先要测试矩阵，再要代码

一个高杠杆的提问模式是：

1. “List test categories and invariants.”
2. “Now generate the highest-priority test skeletons.”
3. “Now fill in mocks and edge cases.”

这种方式能减少无效代码，也能更早暴露理解偏差。

提供真实的合约接口

如果你能贴出函数签名、事件、自定义错误以及存储约束，web3-testing skill 生成的测试会强很多。没有这些信息时，它就更可能虚构 setup 细节，或者依赖过于宽泛的假设。

把 happy path 和对抗性路径分开

可以要求这个 skill 按下面结构组织输出：

• happy-path functionality
• authorization checks
• boundary and rounding cases
• integration failures
• fork-specific scenarios
• fuzz or invariant candidates

这样不仅更方便评审，也更利于 CI 规划。

用精确状态假设改进 mainnet fork 提示

想让 fork 测试输出更可用，最好补充这些信息：

• network name
• RPC environment variable name
• target block number
• contracts to impersonate or interact with
• balances or approvals needed
• expected post-transaction state

没有这些前提，fork 建议通常只能停留在概念层面，后续还需要你手工清理很多细节。

需要重点留意的常见失败模式

web3-testing 产出最常见的问题有：

• 用不真实的 mock 替代了关键集成行为
• 测试看起来覆盖很广，却漏掉了真正有资金风险的路径
• 框架配置和你现有仓库相冲突
• 该用单元测试更快更清晰的地方，却用了 fork 测试
• 过度强调 setup，却没有把不变量定义清楚

评审生成内容时，重点看风险覆盖，而不只是语法是否正确。

第一稿不完整时，迭代比重来更有效

如果第一轮结果已经接近目标，只是还不完整，可以直接给出修正反馈，例如：

• “Add revert-path tests for every admin function.”
• “Convert these integration cases into Foundry fuzz tests.”
• “Replace mocks with a fork-based scenario for the oracle dependency.”
• “Prioritize accounting invariants over boilerplate deployment tests.”

通常这会比直接丢弃第一版、从头重写 prompt 更有效。

用仓库级上下文提升 web3-testing 的实用性

当你明确说明下面这些信息时，这个 skill 会明显更有用：

• 当前仓库布局
• 现有的 fixtures 或 helper libraries
• CI 时间限制
• 是否已经在用 forge-std、hardhat-toolbox 或自定义部署脚本
• 测试与 fixture 的命名约定

这样 agent 才能按你的仓库现实情况调整输出，而不是生成一套孤立示例。

高质量的 web3-testing 输出应该长什么样

好的 web3-testing 输出，通常应该给到你：

• 一份与协议风险直接对应的清晰测试计划
• 与你技术栈匹配的框架级配置
• 能映射到真实函数和不变量的测试骨架
• 只在真正有价值的地方使用 fork 与 fuzz 测试
• 清楚的下一步，让生成代码能继续演化成可维护的测试体系

如果输出既没有提升判断质量，也没有节省实现时间，那与其继续要求“更全面”，不如先把输入收紧、补全。