solidity-testing · diff
v1.0.0 to git:20260209.f77aa76
47 added, 31 removed. Audit A to A.
---
name: solidity-testing
- description: Solidity Testing Standards - Test organization, coverage requirements, testing tools for Foundry
- author: 0xlayerghost
- version: 1.0.0
- triggers:
- - "write test"
- - "test"
- - "forge test"
- - "coverage"
- - "fuzz"
- globs:
- - "test/**/*.sol"
- - "test/**/*.t.sol"
+ description: Enforce Solidity testing standards with Foundry. Use when writing tests, reviewing test coverage, or running test suites — covers test file structure, naming conventions, coverage requirements, fuzz testing, and Foundry cheatcodes.
---
# 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.
- ## Organization Principles
+ ## Test Organization
- - **Single Responsibility**: One test contract per module, file naming `<ContractName>.t.sol`
- - **Composable**: Tests run independently, support `--match-test` filtering
- - **Naming Convention**: Test functions named `test_<feature>_<scenario>`, e.g. `test_transfer_revertsWhenInsufficientBalance`
+ - **One test contract per source contract**: `MyToken.sol` → `MyToken.t.sol`
+ - **File location**: All tests in `test/` directory
+ - **Naming**: `test_<feature>_<scenario>` for passing tests, `testFail_<feature>_<scenario>` for expected reverts
+ - Example: `test_transfer_revertsWhenInsufficientBalance`
+ - Example: `test_stake_updatesBalanceCorrectly`
+ - **Independence**: Each test must run in isolation — use `setUp()` for shared state, no cross-test dependencies
+ - **Filtering**: Support `--match-test` and `--match-contract` for targeted runs
## Coverage Requirements
- Every core function must cover the following scenarios:
+ Every core function must have tests covering:
- - **Happy Path**: Standard input, expected output
- - **Permission Checks**: Unauthorized calls should revert
- - **Boundary Conditions**: Zero values, max values, overflow boundaries
- - **Failure Scenarios**: All require/revert conditions
- - **State Changes**: Verify storage variables, balances, and events are correctly updated
+ | Scenario | What to verify |
+ |----------|---------------|
+ | Happy path | Standard input → expected output, correct state changes |
+ | Permission checks | Unauthorized caller → `vm.expectRevert` with correct error |
+ | Boundary conditions | Zero values, max values (`type(uint256).max`), off-by-one |
+ | Failure scenarios | Every `require` / `revert` / custom error path |
+ | State changes | Storage updates, balance changes, event emissions (`vm.expectEmit`) |
+ | Edge cases | Empty arrays, duplicate calls, self-transfers |
- ## Testing Tools
+ ## Foundry Cheatcodes Quick Reference
- - Use Foundry cheatcodes: `vm.prank`, `vm.warp`, `vm.expectRevert`, `vm.expectEmit`, etc.
- - Use Fuzz testing for critical math and fund flows: `function testFuzz_xxx(uint256 amount) public`
- - Run coverage checks regularly: `forge coverage`
- - Run gas reports regularly: `forge test --gas-report`
+ | Cheatcode | Usage |
+ |-----------|-------|
+ | `vm.prank(addr)` | Next call from `addr` |
+ | `vm.startPrank(addr)` | All calls from `addr` until `vm.stopPrank()` |
+ | `vm.warp(timestamp)` | Set `block.timestamp` |
+ | `vm.roll(blockNum)` | Set `block.number` |
+ | `vm.deal(addr, amount)` | Set ETH balance |
+ | `vm.expectRevert(error)` | Next call must revert with specific error |
+ | `vm.expectEmit(true,true,false,true)` | Verify event emission (topic checks) |
+ | `vm.record()` / `vm.accesses()` | Track storage reads/writes |
+ | `makeAddr("name")` | Create labeled address for readable traces |
+ ## Fuzz Testing Rules
+
+ - All math-heavy and fund-flow functions must have fuzz tests
+ - Pattern: `function testFuzz_<name>(uint256 amount) public`
+ - Use `vm.assume()` to constrain inputs: `vm.assume(amount > 0 && amount < MAX_SUPPLY);`
+ - Default runs: 256 — increase to 10,000+ for critical functions: `forge test --fuzz-runs 10000`
+
## Common Commands
```bash
# Run all tests
forge test
- # Run specific test
+ # Run specific test function
forge test --match-test test_transfer
- # Run specific contract tests
+ # Run specific test contract
forge test --match-contract MyTokenTest
- # Verbose output (with trace)
+ # Verbose output with full trace
forge test -vvvv
# Gas report
forge test --gas-report
- # Coverage
+ # Fuzz with more runs
+ forge test --fuzz-runs 10000
+
+ # Test coverage
forge coverage
+
+ # Coverage with report
+ forge coverage --report lcov
```