Solidity Testing Standards

Language Rule

• Always respond in the same language the user is using. If the user asks in Chinese, respond in Chinese. If in English, respond in English.

Toolchain Baseline

• Use solc 0.8.24, OpenZeppelin Contracts 5.0.2, and the Foundry version installed by the repository.
• Read foundry.toml before changing test configuration. Preserve existing profiles and raise fuzz or invariant intensity according to risk instead of overwriting project settings.
• Use OpenZeppelin 5.x APIs and import paths in test fixtures and mocks.

Test Organization

• Organize tests by behavior and boundary: unit, integration, fuzz, invariant, fork, and regression tests may use separate contracts or directories.
• Name ordinary tests test_<behavior>_<scenario> and fuzz tests testFuzz_<behavior>.
• Do not use testFail_*. Assert the intended failure with vm.expectRevert, preferably matching a custom-error selector or fully encoded error.
• Each test must run independently. Use setUp() for fixtures and never depend on execution order.
• Keep helpers and mocks minimal. A reference model must be independent from the production implementation it checks.

Behavioral Coverage

Every core function must have tests covering:

Select additional tests from the contract's behavior:

Foundry Cheatcodes Quick Reference

Fuzz Testing Rules

• Fuzz math-heavy, accounting, authorization, and fund-flow boundaries.
• Map scalar inputs into the valid domain with bound() when possible. Use vm.assume() only for relational or structurally invalid inputs that cannot be mapped cheaply.
• Assert properties, balance deltas, and postconditions rather than duplicating the implementation line by line.
• Increase runs for high-value or complex paths based on execution cost and risk; do not prescribe one universal run count.
• Preserve any minimized failure as a deterministic regression test and record the seed needed to reproduce unresolved failures.

Stateful Invariant Testing

• Use StdInvariant with a handler for multi-step protocols and state machines.
• Restrict the action space with targetContract and targetSelector; do not let irrelevant reverts dominate exploration.
• Track ghost variables when expected totals cannot be derived directly from contract state.
• Check system properties such as conservation, solvency, monotonic counters, authorization isolation, and legal state transitions.
• Unexpected reverts are findings. Do not hide them by weakening the invariant or adding broad assumptions.

Read references/advanced-testing.md when implementing invariant handlers, deterministic fork tests, adversarial mocks, differential tests, mutation testing, or gas-regression gates.

Fork Testing

• Pin the chain and block number. Do not base reproducible tests on the latest block.
• Assert block.chainid, dependency bytecode, and critical interface bindings before exercising protocol behavior.
• A missing RPC or archive capability must produce an explicit skip or failure; it must not silently pass the test.
• Keep local unit tests for business logic. Fork tests validate integration assumptions, not every code path.

Verification Rules

• Verify state and balance changes in addition to events and return values.
• Every fixed vulnerability or production incident requires a regression test that fails before the fix.
• Coverage percentage is diagnostic only. It does not replace branch, adversarial, invariant, or mutation testing.
• Use gas snapshots for regression detection, not brittle exact-gas assertions inside ordinary tests.
• Never broadcast transactions or load production signing keys from tests.

Common Commands

# Run all tests
forge test

# Run specific test function
forge test --match-test test_transfer

# Run specific test contract
forge test --match-contract MyTokenTest

# Verbose output with full trace
forge test -vvvv

# Gas report
forge test --gas-report

# Fuzz with a risk-appropriate run count
forge test --fuzz-runs <RUNS>

# Run invariant tests
forge test --match-test invariant_ -vvvv

# Check gas snapshots when the repository tracks them
forge snapshot --check

# Test coverage
forge coverage

# Coverage with report
forge coverage --report lcov