web3-testing

web3-testing スキルの概要

web3-testing ができること

web3-testing スキルは、Hardhat と Foundry を使ったスマートコントラクトのテストワークフロー設計と雛形作成を、エージェントに支援させるためのスキルです。単に「Solidity のテストを書いて」で済ませたくないチーム向けで、ユニットテスト、統合テスト、mainnet fork、fuzzing、gas チェック、verification 周りのセットアップまで、実務で必要になりやすい範囲を視野に入れています。

web3-testing を使うべき人

この web3-testing スキルが特に合うのは、次のような人です。

• テストスイートをこれから整備する、または刷新したい Solidity 開発者
• Web3 領域に入っていく QA・テスト自動化エンジニア
• fork ベースで現実に近い検証が必要な DeFi チーム
• 監査担当やプロトコルエンジニアで、構造化されたテスト観点を素早く出したい人

一方で、単純なユニットテストを 1 本だけ書きたい場合や、スタックが Hardhat / Foundry ではない場合は、web3-testing の恩恵は小さめです。

実際のジョブ・トゥ・ビー・ダン

多くのユーザーが欲しいのは理論ではありません。「コントラクトとリスク領域はある」状態から、「信頼できる、実行可能なテスト計画とスターターテストがある」状態に進むことです。web3-testing の価値は、会話を具体的なテスト設計へ引き寄せてくれる点にあります。特に、通常のプロンプトでは抜けやすい forked state、fuzzing、gas レポート、複数レイヤーのテスト戦略まで踏み込めるのが強みです。

web3-testing の差別化ポイント

一般的なコーディングプロンプトと比べると、web3-testing は次の点でより強いガイドになります。

• Hardhat と Foundry のどちらで進めるべきかの判断
• 現実的なネットワーク設定・環境設定の組み立て
• スマートコントラクトで起きやすいエッジケースの洗い出し
• fork したチェーン状態に対するプロトコル挙動の検証
• coverage や gas reporting といった品質シグナルの追加

インストール前に知っておきたいこと

このリポジトリの中身は、広いツールキットというより、主に 1 つの SKILL.md プレイブックです。つまり導入は簡単ですが、得られるのは自動化された仕組みではなく、ガイダンスと例です。すぐ使えるヘルパー群込みの規定フレームワークを期待するなら、これは drop-in のパッケージというより、考え方の整理と足場づくりを助けるスキルだと捉えるのが適切です。

web3-testing スキルの使い方

web3-testing のインストール情報

親リポジトリからこのスキルをインストールします。

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

リポジトリ上のパスは plugins/blockchain-web3/skills/web3-testing なので、インストールされるのは独立した npm テストライブラリではなく、用途を絞ったスキル文書です。

最初に読むべきファイル

まず確認するのは次です。

• SKILL.md

ここが実質的な一次情報です。スキルディレクトリ内に意味のある補助フォルダはないため、別の場所に隠れたヘルパーがある前提では見ないほうがよいです。

web3-testing に渡すべき入力

web3-testing スキルは、次の情報があると最も力を発揮します。

• コントラクトの目的
• 主要な関数とアクセス制御
• invariant や安全性プロパティ
• 希望するツールチェーン: Hardhat、Foundry、または両方
• oracle、pool、token、proxy contract などの外部依存
• 必要なテスト種別が unit test、integration test、fork test、fuzzing、gas check のどれか

弱い入力例: 「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 プロンプトは、通常 4 つの要素で構成されます。

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.”

これは単に「comprehensive tests が欲しい」と頼むよりはるかに有効です。あなたのケースで “comprehensive” が何を意味するのかを、エージェントに具体的に伝えられるからです。

Hardhat と Foundry は意図して選ぶ

元の素材は両フレームワークを扱っているため、プロンプトではどちらを主軸にするかを明示すべきです。

次のような場合は Hardhat を使うのが向いています。

• JavaScript または TypeScript のテストフローにしたい
• plugin を多用するワークフローにしたい
• Node 環境で馴染みのある coverage や gas reporter を使いたい
• より広いアプリケーションツール群と統合しやすくしたい

次のような場合は Foundry が向いています。

• Solidity ネイティブな高速テストを回したい
• fuzzing や invariant ベースのワークフローを重視したい
• スマートコントラクト中心の短い開発ループを回したい

チームで両方使っているなら、その旨を明記し、曖昧に混ぜるのではなく役割分担して出力するよう依頼してください。

Test Automation 向け web3-testing のベストな進め方

web3-testing for Test Automation では、次の流れが最も安定します。

1. まずテストマトリクスを出させる
2. 抜けている failure case をレビューする
3. セットアップ / 設定ファイルを出させる
4. スターターテストを生成する
5. 実際のコントラクトコードと ABI 詳細で詰める
6. 最後に fork と fuzz のレイヤーを足す

この順序にすると、「見た目は実行できそうだが、実際にはプロトコルのリスクを反映していないテスト」が先に量産される、よくある失敗を防ぎやすくなります。

web3-testing が得意な出力

実務上、web3-testing が特に役立つのは次の生成です。

• 初期の hardhat.config.js テスト設定
• テストカテゴリの分解
• 標準的な振る舞いに対するスターターユニットテスト
• DeFi 統合向けの fork test アイデア
• fuzzing ターゲットとエッジケース一覧
• gas reporting と coverage の提案

位置づけとしては、構造化されたテストガイド兼コード雛形ジェネレーターとして使うのが最も強いです。

良い結果を阻む要因

大きな障害はインストールではなく、プロトコル文脈の不足です。

• コントラクトコードや関数一覧がない
• 重要な invariant の明示がない
• 外部統合の説明がない
• 優先順位なしに「full coverage」を要求する
• 1 つの曖昧な依頼に複数フレームワーク前提を混ぜる

これらが欠けると、出力はプロトコル固有のテスト自動化ではなく、汎用的な ERC20 風テスト助言に寄りがちです。

出力品質を上げる実践的なプロンプト構成

可能なら、常に次の形を使ってください。

• Repository context: framework、Solidity version、proxy pattern、package manager
• Contracts in scope: ファイル名と役割
• 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: テストは deterministic に保つ、外部 API 依存を避ける、CI 実行時間を X 分以内に抑える

この形式なら、web3-testing guide にチームがすぐ流用できるレベルの精度を与えられます。

fork test は現実性が必要な場面だけで使う

このスキルは mainnet fork を差別化要素として前面に出していますが、すべてのプロジェクトで必要なわけではありません。fork test を使うべきなのは、次のような場合です。

• 挙動が実際のプロトコル状態に依存する
• DEX、レンディング市場、price feed との統合が重要
• mock では危険なエッジケースを隠してしまう

逆に、次のような場合は fork test を省く、または絞るほうがよいです。

• 現実性より CI 速度を優先したい
• コントラクトがほぼ独立した業務ロジックで成り立つ
• エコシステム再現より再現性の高さが重要

生成結果は採用前に必ず検証する

web3-testing skill を使って生成した内容をマージする前に、少なくとも次を確認してください。

• revert reason やアクセス制御前提は正しいか
• token の decimals や rounding 前提は実態と一致しているか
• fork の block number はシナリオに合っているか
• gas / coverage plugin は現在のスタックと互換性があるか
• テストは invariant を証明しているか、それとも happy path だけか

このスキルは時間短縮にはなりますが、プロトコル固有の正しさは最終的にレビューに依存します。

web3-testing スキル FAQ

web3-testing は初心者にも向いているか

はい。ただし、基本的な Solidity の概念をすでに理解していることが前提です。web3-testing はセットアップを加速し、成熟したテストスタックの形を見せるのに役立ちます。完全な初学者であれば、Solidity の構文、デプロイの流れ、各フレームワークの基礎については別途サポートが必要です。

web3-testing は Hardhat 専用か

いいえ。web3-testing は Hardhat と Foundry の両方を明示的にカバーしています。曖昧に任せるより、どちらのエコシステムを優先するかをエージェントに伝えたときに最もフィットします。

web3-testing は普通の AI プロンプトと何が違うか

通常のプロンプトは、表面的なユニットテストを返して終わりになりがちです。web3-testing は、スマートコントラクト全体のテスト戦略により向いています。fork ベースの現実性、fuzzing、gas check、coverage、環境設定まで含めて扱えるため、デモ用テストではなく、実際のプロトコル検証で使いやすいのが違いです。

web3-testing は DeFi プロトコルにも有効か

はい。むしろ適合度の高いユースケースの 1 つです。特に、現実に近い状態で統合テストをしたい場合に向いています。プロトコル依存関係、期待する invariant、重視するユーザーフローを具体的に渡してください。

web3-testing を使わないほうがいいのはいつか

次のような場合は web3-testing を無理に使う必要はありません。

• 単発の assertion を 1 つ書きたいだけ
• プロジェクトが Solidity / EVM 中心ではない
• helper や fixture を含むパッケージ済みフレームワークが欲しい
• 意味のあるテスト目標を指定できるだけのコントラクト文脈がない

web3-testing に実行可能なツール群は含まれるか

基本的には含まれません。リポジトリから確認できるのは、バンドル済みの script や再利用アセットではなく、サンプル付きのドキュメント中心スキルです。インストール可能なテストフレームワークではなく、ガイダンスと生成支援として扱ってください。

web3-testing スキルを改善する方法

ファイル名だけでなく、プロトコルのリスクを渡す

web3-testing usage を最も手早く改善する方法は、実際に恐れている failure mode を明示することです。

• accounting drift
• price manipulation
• permission bypass
• bad upgrade initialization
• insolvency after extreme inputs

これだけで、出力は汎用的な雛形から、リスク駆動のテスト設計へ大きく変わります。

いきなりコードではなく、先にテストマトリクスを依頼する

レバレッジの高い進め方は次のとおりです。

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

この流れにすると、無駄なコード生成を減らし、認識違いを早い段階で表に出せます。

実際のコントラクトインターフェースを渡す

関数シグネチャ、events、custom errors、storage 上の制約を貼り付ければ、web3-testing skill はかなり精度の高いテストを生成できます。これらがないと、セットアップ詳細を勝手に補ったり、大づかみな前提に頼ったりしやすくなります。

happy path と adversarial path を分ける

出力を次の区分で整理するよう依頼してください。

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

この形にするとレビューしやすくなり、CI 設計も立てやすくなります。

mainnet fork のプロンプトは状態前提まで具体化する

より良い fork test 出力のために、次の情報を入れてください。

• network name
• RPC environment variable name
• target block number
• impersonate または interaction 対象の contracts
• 必要な balances や approvals
• 取引後に期待する state

これがないと、fork の提案は概念的なままになり、手作業での後処理が増えます。

よくある失敗パターンに注意する

web3-testing の出力が崩れやすい主なパターンは次のとおりです。

• 重要な統合挙動が、非現実的な mock に置き換わっている
• 一見広そうな test coverage でも、value-at-risk の経路を外している
• framework config が既存リポジトリと衝突する
• unit test のほうが速く明確なのに fork test を使っている
• セットアップ説明に比重が寄りすぎて invariant 指定が薄い

生成物は、構文が通るかどうかだけでなく、リスクをどこまでカバーしているかで評価してください。

最初のドラフトを捨てず、修正指示で育てる

初回の結果が近いが不十分な場合は、最初からやり直すより、次のような修正指示を返すほうがうまくいきます。

• “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.”

このやり方のほうが、最初の出力を捨ててゼロから再プロンプトするより、精度が上がりやすいです。

リポジトリ固有の前提を伝えて web3-testing を改善する

次の情報を添えると、このスキルは一段と実用的になります。

• 現在のリポジトリ構成
• 既存の fixture や helper library
• CI の時間制限
• forge-std、hardhat-toolbox、カスタム deployment script をすでに使っているか
• test や fixture の命名規則

これにより、エージェントは孤立したサンプルではなく、あなたのリポジトリに合わせた出力を返しやすくなります。

web3-testing の高品質な出力とは何か

良い web3-testing の出力には、次の要素が揃っているはずです。

• プロトコルリスクに結びついた明確なテスト計画
• 現在のスタックに合った framework 固有のセットアップ
• 実際の関数や invariant に対応したテスト skeleton
• 価値がある場面に絞った fork / fuzz testing の活用
• 生成コードを保守しやすいテストスイートへ育てる次の一手

もし出力が意思決定の質を上げず、実装時間の短縮にもつながらないなら、「more comprehensive」と曖昧に追加要求するのではなく、まず入力条件を締め直すべきです。