Web3 Testing (Foundry primary, Hardhat 3 supported)

Routing-first skill. The body is intentionally thin; depth lives in reference/. Open only the files you actually need.

Token economy rules for the agent

Read these before doing anything else. They cut answer cost without losing quality.

1. Do not paste the user's contract back at them. Reference function names and line ranges; write only the test harness or the diff.
2. Read at most 2 reference files per turn. Use the routing table to pick.
3. Never reproduce forge-std internals. Reference them by name (Test, StdInvariant, StdCheats) and assume the user has forge-std installed.
4. Default to Foundry in examples. Only show Hardhat when the user says Hardhat or already has a Hardhat project.
5. Prefer tables over prose for cheatcode catalogs, option matrices, or revert-parsing rules.
6. Verify version-specific APIs via Context7 for Foundry, Hardhat, OpenZeppelin, Slither, Echidna, Halmos, and ethers/viem. Foundry and Hardhat both moved fast through 2024-2026; treat any pre-2026 snippet in your training as suspect -- especially testFail*, ethers v5, Goerli, and Hardhat 2 ESM assumptions.

Routing table

Golden rules (non-negotiable)

These prevent the failures that actually matter in production.

1. Test against custom errors, not strings. vm.expectRevert(MyErr.selector) and revertedWithCustomError for Hardhat. revertedWith("...") is brittle and breaks under Solidity optimizer changes.
2. Never use Foundry's testFail* prefix. It masks unrelated reverts. Always use vm.expectRevert with an explicit reason or selector.
3. Pin the fork block. Unpinned forks are the #1 source of "passes locally, fails in CI" flakiness.
4. Fuzz everything that takes user input. Every public function with numeric, address, or byte inputs gets at least one fuzz test with bound(...) to constrain to the domain.
5. Invariants for protocols, not unit tests. Any system with accumulating state (lending, vaults, AMMs, staking, governance) needs a StdInvariant-based harness with handlers. Pure unit tests cannot find state-space bugs.
6. Run forge snapshot in CI and fail on regressions. Silent gas bloat is a deployment-blocking problem you can only catch mechanically.
7. Pair tests with at least one static analyzer (Slither or Aderyn). Tests find behavioral bugs; static analysis finds class-of-bug issues (reentrancy, tx.origin, unchecked-low-level-call) in patterns tests cannot exhaustively cover.
8. Test access control exhaustively. Every onlyRole/onlyOwner path needs a negative test proving unauthorized callers revert.
9. Never vm.skip() or disable a test without a tracked issue. Skipped tests are permanent dead code.
10. Coverage is a floor, not a ceiling. Aim for >90% line AND branch, but stop measuring coverage once a suite has solid invariants and fuzz tests -- they find bugs coverage metrics never will.

Default stack (one choice, one escape hatch)

If the user explicitly chose another stack, do not argue; help them with what they have.

Decision matrix: what kind of test does this bug need?

When NOT to apply this skill

• Writing the contracts themselves or architecting new protocols -> use ultimate-web3.
• Solidity patterns, secure fixes, and audit preparation -> use solidity-security.
• A codebase audit, pen test, or findings report -> use security-audit.
• dApp frontend testing (component, E2E) -> that is frontend testing, not contract testing.

Companion skills

• solidity-security -- vulnerability patterns and secure coding
• ultimate-web3 -- protocol architecture
• security-audit -- coverage-led codebase audit and findings report
• web3-frontend -- dApp frontend patterns (wagmi, viem, Next.js)
• gh -- CI authoring, GitHub Actions hygiene