CLI Forge

Foundry Testing & Script Skill

Rules and patterns for Foundry tests. Find examples in the actual codebase.

Bundled References

Test Types

1. Integration Tests (Concrete)

Naming Convention

Rules

1. Stack modifiers to document BTT path (modifiers are often empty - just document the path)
2. Expect events BEFORE action - vm.expectEmit() then call function
3. Assert state AFTER action - Check state changes after function executes
4. Use revert helpers for common patterns (expectRevert_DelegateCall, expectRevert_Null)
5. Named parameters in assertions - assertEq(actual, expected, "description")

Mock Rules

1. Place all mocks in tests/mocks/
2. One mock per scenario (not one mega-mock)
3. Naming: *Good, *Reverting, *InvalidSelector, *Reentrant

2. Fuzz Tests

Naming Convention

testFuzz_{FunctionName}_{Scenario}

Rules

1. Bound before assume - _bound() is more efficient than vm.assume()
2. Bound in dependency order - Independent params first, then dependent
3. Never hardcode params with validation constraints
4. Document fuzzed scenarios in NatSpec

Bounding Pattern

// 1. Bound independent params first
cliffDuration = boundUint40(cliffDuration, 0, MAX - 1);

// 2. Bound dependent params based on constraints
totalDuration = boundUint40(totalDuration, cliffDuration + 1, MAX);

3. Fork Tests

Rules

1. Create fork with vm.createSelectFork("ethereum")
2. Use deal() to give tokens to test users
3. Use assumeNoBlacklisted() for USDC/USDT
4. Use forceApprove() for non-standard tokens (USDT)

Token Quirks

4. Invariant Tests

Architecture

tests/invariant/
├── handlers/     # State manipulation (call functions with bounded params)
├── stores/       # State tracking (record totals, IDs)
└── Invariant.t.sol

Rules

1. Target handlers only - targetContract(address(handler))
2. Exclude protocol contracts - excludeSender(address(vault))
3. Use stores to track totals for invariant assertions
4. Early return in handlers if preconditions not met

5. Solidity Scripts

Rules

1. Inherit from BaseScript with broadcast modifier
2. Use env vars: ETH_FROM, MNEMONIC
3. Simulation first, then broadcast

Commands

# Simulation
forge script scripts/Deploy.s.sol --sig "run(...)" ARGS --rpc-url $RPC

# Broadcast
forge script scripts/Deploy.s.sol --sig "run(...)" ARGS --rpc-url $RPC --broadcast --verify

Running Tests

# By type
forge test --match-path "tests/integration/concrete/**"
forge test --match-path "tests/fork/**"
forge test --match-contract Invariant_Test

# Specific test
forge test --match-test test_WhenCallerRecipient -vvvv

# Fuzz with more runs
forge test --match-test testFuzz_ --fuzz-runs 1000

# Coverage
forge coverage --report lcov

Debugging

Verbosity Levels

Console Logging

import { console2 } from "forge-std/console2.sol";

console2.log("value:", someValue);
console2.log("address:", someAddress);
console2.logBytes32(someBytes32);

Debugging Commands

# Trace specific failing test
forge test --match-test test_MyTest -vvvv

# Gas report for a test
forge test --match-test test_MyTest --gas-report

# Debug in interactive debugger
forge debug --debug tests/MyTest.t.sol --sig "test_MyTest()"

# Inspect storage layout
forge inspect MyContract storage-layout

Debugging Tips

1. Label addresses - vm.label(addr, "Recipient") for readable traces
2. Check state with logs - Add console2.log before reverts
3. Isolate failures - Run single test with --match-test
4. Compare gas - Use --gas-report to spot unexpected costs
5. Snapshot comparisons - Use vm.snapshot() / vm.revertTo() to isolate state changes

Best Practices Summary

1. Use constants from Defaults/Constants - never hardcode
2. Specialized mocks - one per scenario, all in tests/mocks/
3. Modifiers in Modifiers.sol - centralize BTT path modifiers
4. Label addresses with vm.label() for traces
5. Events before actions - vm.expectEmit() then call
6. Bound before assume - more efficient

External References

• Foundry Book

Example Invocations

Test this skill with these prompts:

1. Integration test: "Write a concrete test for withdraw that expects Errors.Flow_Overdraw when amount exceeds balance"
2. Fuzz test: "Create a fuzz test for deposit that bounds amount between 1 and type(uint128).max"
3. Fork test: "Write a fork test for USDC deposits on mainnet with blacklist handling"
4. Invariant test: "Create an invariant handler for the deposit and withdraw functions"
5. Deploy script: "Write a deployment script for SablierFlow with verification"