web3-testing

Overview of web3-testing skill

What web3-testing does

The web3-testing skill helps an agent design and scaffold smart contract test workflows using Hardhat and Foundry. It is aimed at teams that need more than a generic “write some Solidity tests” prompt: unit tests, integration coverage, mainnet forking, fuzzing, gas checks, and verification-related setup all appear in scope.

Who should use web3-testing

This web3-testing skill is best for:

• Solidity developers starting or upgrading a test suite
• QA and test automation engineers moving into Web3
• DeFi teams that need realistic fork-based validation
• auditors or protocol engineers who want structured test ideas fast

It is less useful if you only need a single trivial unit test or if your stack does not use Hardhat or Foundry.

Real job-to-be-done

Most users are not looking for theory. They want to get from “I have contracts and risk areas” to “I have a credible, runnable testing plan and starter tests.” The value of web3-testing is that it pushes the conversation toward concrete test setup and advanced patterns that ordinary prompts often miss, especially forked state, fuzzing, gas reporting, and multi-layer test strategy.

What differentiates this skill

Compared with a generic coding prompt, web3-testing gives stronger guidance for:

• choosing between Hardhat and Foundry workflows
• setting up realistic network and environment configuration
• covering edge cases common in smart contracts
• testing protocol behavior against forked chain state
• adding quality signals such as coverage and gas reporting

What to know before installing

The repository signal is narrow but practical: the skill is primarily a single SKILL.md playbook rather than a larger toolkit with scripts or references. That means adoption is easy, but you should expect guidance and examples, not automation. If you want a prescriptive testing framework with ready-made helpers, this is more of a thinking-and-scaffolding aid than a drop-in package.

How to Use web3-testing skill

Install context for web3-testing

Install the skill from the parent repository:

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

Because the repo path is plugins/blockchain-web3/skills/web3-testing, you are installing a focused skill document, not a standalone npm test library.

Read this file first

Start with:

• SKILL.md

That is the real source of truth here. There are no meaningful support folders in the skill directory, so users should not expect hidden helpers elsewhere.

What input the skill needs from you

The web3-testing skill works best when you provide:

• the contract purpose
• key functions and access controls
• invariants or safety properties
• the toolchain you prefer: Hardhat, Foundry, or both
• external dependencies such as oracles, pools, tokens, or proxy contracts
• whether you need unit tests, integration tests, fork tests, fuzzing, or gas checks

Weak input: “Write tests for my contract.”

Strong input: “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.”

Turn a rough goal into a usable prompt

A good web3-testing usage prompt usually has four parts:

1. stack
2. contract surface
3. risk areas
4. desired output format

Example:

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

That is much better than asking for “comprehensive tests,” because it tells the agent what “comprehensive” means in your case.

Choose Hardhat vs Foundry deliberately

The source material covers both frameworks, so your prompt should state which one to optimize for.

Use Hardhat when you want:

• JavaScript or TypeScript test flows
• plugin-heavy workflows
• coverage and gas reporter setup in a familiar Node environment
• easier integration with broader app tooling

Use Foundry when you want:

• faster Solidity-native tests
• fuzzing and invariant-style workflows
• a tighter smart-contract-focused developer loop

If your team runs both, say so explicitly and ask the skill to split responsibilities instead of blending them loosely.

Best workflow for web3-testing for Test Automation

For web3-testing for Test Automation, the strongest workflow is:

1. ask for a test matrix first
2. review missing failure cases
3. ask for setup/config files
4. generate starter tests
5. refine with real contract code and ABI details
6. add fork and fuzz layers last

This sequence prevents the common failure mode where the agent generates runnable-looking tests that do not actually reflect your protocol risks.

What the skill can produce well

In practice, web3-testing is most useful for generating:

• initial hardhat.config.js testing setup
• test category breakdowns
• starter unit tests for standard behaviors
• fork-test ideas for DeFi integrations
• fuzzing targets and edge-case inventories
• gas reporting and coverage suggestions

It is strongest when used as a structured testing guide plus code scaffold generator.

What usually blocks good results

The biggest blockers are not installation issues. They are missing protocol context:

• no contract code or function list
• no statement of critical invariants
• no explanation of external integrations
• asking for “full coverage” without priorities
• mixing framework assumptions in one vague request

If you omit these, the output often becomes generic ERC20-style testing advice rather than protocol-specific test automation.

Practical prompt pattern that improves output quality

Use this structure whenever possible:

• 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

This format gives the web3-testing guide enough precision to produce something your team can adapt quickly.

Use fork tests only where realism matters

The skill surfaces mainnet forking as a differentiator, but not every project needs it. Use fork tests when:

• behavior depends on real protocol state
• integrations with DEXes, lending markets, or price feeds matter
• mocks would hide dangerous edge cases

Skip or limit fork tests when:

• CI speed is more important than realism
• your contract is mostly isolated business logic
• reproducibility matters more than ecosystem simulation

Validate generated output before adopting it

Before merging anything produced with the web3-testing skill, check:

• are revert reasons and access-control assumptions correct?
• do token decimals and rounding assumptions match reality?
• do fork block numbers align with the scenario?
• are gas and coverage plugins compatible with your stack?
• do tests prove invariants, or only happy paths?

This skill can save time, but protocol-specific correctness still depends on your review.

web3-testing skill FAQ

Is web3-testing good for beginners

Yes, if you already understand basic Solidity concepts. The skill can accelerate setup and show what a mature testing stack looks like. Absolute beginners may still need separate help on Solidity syntax, deployment flow, and framework basics.

Is web3-testing only for Hardhat

No. The skill explicitly covers both Hardhat and Foundry. Its fit is strongest when you tell the agent which ecosystem to prioritize rather than leaving it ambiguous.

How is web3-testing different from a normal AI prompt

A normal prompt often returns surface-level unit tests. web3-testing is better oriented toward full smart contract test strategy: fork-based realism, fuzzing, gas checks, coverage, and environment setup. That makes it more useful for real protocol validation, not just demo tests.

Can web3-testing help with DeFi protocols

Yes. This is one of the better-fit use cases, especially if you need integration tests against realistic state. Provide protocol dependencies, expected invariants, and the exact user flows you care about.

When should I not use web3-testing

Do not reach for web3-testing if:

• you only need a one-off assertion
• your project is not Solidity or EVM-focused
• you want a packaged framework with helpers and fixtures included
• you lack enough contract context to specify meaningful test goals

Does web3-testing include executable tooling

Not really. The repository evidence shows a document-first skill with examples, not bundled scripts or reusable assets. Treat it as guidance and generation support, not an installable testing framework.

How to Improve web3-testing skill

Give the skill protocol risks, not just filenames

The fastest way to improve web3-testing usage is to state the failure modes you actually fear:

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

That changes the output from generic scaffolding to risk-driven test design.

Ask for a test matrix before code

A high-leverage pattern is:

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

This reduces wasted code and surfaces misunderstandings early.

Provide real contract interfaces

If you paste function signatures, events, custom errors, and storage constraints, the web3-testing skill can generate much stronger tests. Without these, it may invent setup details or rely on broad assumptions.

Separate happy paths from adversarial paths

Ask the skill to organize output into:

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

This structure makes review easier and improves CI planning.

Improve mainnet fork prompts with exact state assumptions

For better fork test output, include:

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

Without these, fork suggestions stay conceptual and require more manual cleanup.

Common failure modes to watch for

The main ways web3-testing output can go wrong:

• unrealistic mocks replacing critical integration behavior
• test coverage that looks broad but misses value-at-risk paths
• framework config that conflicts with your existing repo
• using fork tests where unit tests would be faster and clearer
• overemphasis on setup while under-specifying invariants

Review generated work for risk coverage, not just syntactic correctness.

Iterate on the first draft instead of starting over

When the initial result is close but incomplete, give corrective feedback like:

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

This usually yields better results than discarding the first output and prompting from scratch.

Improve web3-testing with repository-specific context

The skill becomes much more useful when you mention:

• current repo layout
• existing fixtures or helper libraries
• CI time limits
• whether you already use forge-std, hardhat-toolbox, or custom deployment scripts
• naming conventions for tests and fixtures

That lets the agent adapt output to your repository instead of generating isolated examples.

What high-quality output from web3-testing looks like

Good output from web3-testing should give you:

• a clear test plan tied to protocol risk
• framework-specific setup that matches your stack
• test skeletons that map to real functions and invariants
• selective use of fork and fuzz testing where they add value
• obvious next steps for turning generated code into a maintainable suite

If the output does not improve decision quality or save implementation time, tighten the input rather than asking for “more comprehensive” results.