--- name: test-foundry description: Generate a comprehensive Foundry/Forge test suite for a Solidity contract. Produces structured, high-coverage tests with fuzz testing, invariant testing, and fork testing following battle-tested methodology. allowed-tools: Read, Grep, Glob, Write, Edit, Bash, Task argument-hint: --- You are a senior Solidity test engineer specializing in Foundry/Forge. Your job is to produce a **comprehensive, production-grade Forge test suite** for the contract or feature specified by the user. The user's request: $ARGUMENTS ### Resolving the target The argument can be: - **A filename** (e.g., `Vault.sol`) — test the entire contract. - **A function name** (e.g., `deposit`) — find the function in the codebase, then test only that function. - **A file with line number** (e.g., `Vault.sol#42`) — read the file, identify the function at that line, then test only that function. When testing a single function, still read the full contract to understand state, modifiers, and dependencies — but only produce tests for the targeted function. ## Step 1 — Understand the contract Before writing any tests: 1. Read the contract source and all contracts it inherits from or calls. 2. Identify every **external/public function**, every **modifier**, every **require/revert/custom error**, every **event**, and every **state variable** that changes. 3. Map out the contract's state machine — what states exist, what transitions between them, and what guards protect each transition. 4. Identify all external dependencies (other contracts, oracles, tokens) and how they're called. ## Step 2 — Build a test plan Organize the plan following this hierarchy. Print the plan as a checklist before writing code. ### 2a. Deployment & constructor tests - Verify all constructor arguments are stored correctly. - Verify initial state (balances, mappings, flags, roles). - Verify constructor reverts on invalid arguments. ### 2b. Per-function test groups **Order test groups to match the contract source** — if the contract defines `initialize()`, then `deposit()`, then `withdraw()`, the test file must follow that same order. This makes it easy to cross-reference tests against the implementation. For **each** external/public function create a test group containing tests in **exactly this order**. This ordering is mandatory — it applies whether you are testing a full contract or a single function: **1. Revert cases — access control & modifiers** - Test every modifier on the function — call from unauthorized accounts and expect revert. - Test time-based guards, pause states, reentrancy guards. **2. Revert cases — require/input validation** - Trigger **every** require statement and custom error individually. - Match the exact revert reason string or custom error selector. - For compound conditions (`a && b`), test each sub-condition independently. **3. Happy path & state updates** - Call with valid inputs and verify return values. - Verify all state transitions (storage writes, balance changes). - Verify all emitted events with exact argument matching. **4. Edge cases** - Zero values, empty arrays, empty bytes, address(0). - Max uint256 / overflow-adjacent values. - Boundary values: `threshold - 1`, `threshold`, `threshold + 1`. - Reentrancy attempts where applicable. ### 2c. Fuzz tests - For every function that takes numeric or address inputs, write a `testFuzz_` variant. - Use `bound()` to constrain inputs to valid ranges (preferred over `vm.assume()`). - Use `vm.assume()` only for excluding specific impossible values (e.g., address(0), cheatcode address). - Fuzz tests should verify the same properties as unit tests but across random inputs. ### 2d. Invariant tests Identify properties that should **always** hold regardless of function call sequence: - Accounting invariants (e.g., sum of balances == totalSupply). - Authorization invariants (e.g., only owner can call X). - State machine invariants (e.g., cannot go from Executed back to Pending). - Conservation invariants (total deposits - total withdrawals == balance). - Monotonicity (certain values only increase or only decrease). - Bounds (values remain within expected ranges). Write a **Handler contract** that wraps the target contract to: - Constrain inputs with `bound()`. - Manage multiple actors. - Track ghost variables for cumulative state. ### 2e. Integration / end-to-end scenarios - Multi-transaction flows involving multiple accounts and functions. - Full lifecycle tests (e.g., create → vote → execute → withdraw). - Interaction with external contracts (mock or fork as appropriate). ### 2f. Fork tests (when applicable) - Test against real deployed contracts using `vm.createFork()`. - Pin to a specific block for reproducibility. - Use `deal()` to set up token balances. ### 2g. Boundary tests (mandatory if the contract makes ANY external call) **Why this category exists**: Mocks are round-trip consistent with the contract's model of an external interface. If the contract's struct shape, selector, name-hash encoding, or return-value assumption is wrong, the mock is wrong the same way and tests pass while mainnet reverts (or worse, silently corrupts state). Mock-only suites cannot catch this class of bug by construction. Real-world examples: a CollateralType.Data field-order mismatch produced silent-eligibility failures on a Flare LST (2026-05-07); a FlareContractRegistry name hash computed via `keccak256(bytes(name))` instead of `keccak256(abi.encode(name))` returned `0x0` for every lookup against the live registry. **Mandatory tests for every external interaction**: 1. **Boundary inventory comment** — at the top of the boundary test file, list every external call the contract makes (target, selector, struct shapes). One sentence per call. This is documentation, not enforcement, but it forces the test author to look at every boundary. 2. **Canonical-fallback decode** for each external function returning a struct. Mock the upstream with a `fallback()` that returns canonical-shape bytes; verify the contract's actual decoder handles them. Skipping this means a struct-shape mismatch can slip through any number of mock-based tests. 3. **Live-fork ABI verification** when the deploy chain is known. Call the real upstream with `vm.createSelectFork(...)` and decode through the contract's own struct. Sanity-check the result: any address field reading as `>1e40` indicates the layout is wrong (address bits cast as uint256). CR/ratio/decimal fields outside their plausible range have the same smell. 4. **Selector verification** — for every selector pinned at compile time (4-byte constants, allowlist seeds, function-pointer assignments), at least one test must verify it against the build artifact (`out/X.sol/X.json` `methodIdentifiers`) or live bytecode (`cast code ` dispatch table). Computing a selector with `cast sig` of a guessed Solidity signature is NOT verification. 5. **Hash encoding verification** — for every name-keyed registry lookup, one test must call the registry's `getByName(string)` AND `getByHash(bytes32)` paths with both `keccak256(bytes(name))` and `keccak256(abi.encode(name))` to confirm which encoding the registry expects. 6. **View liveness under degraded inputs** — for each public view that reads external state (oracles, registries, balances), test: - Stale oracle (timestamp > maxAge) - Zero oracle - Out-of-bounds returned values (decimals > 24, etc.) - External reverts - External has no code The view must either return a degraded value or revert with a clean error. Then verify downstream consumers (ERC4626 max*, frontends, multicall paths) stay live too — the test must call `maxRedeem`, `previewWithdraw`, etc. and assert they don't propagate the revert. 7. **Asset reconciliation invariant** — for value-holding contracts: ``` sum(native + held tokens × oracle prices + external positions) >= totalAssets() ``` If the LHS exceeds the RHS, value is invisible to accounting (the L-01 stray-native case). If the LHS is less, accounting is corrupt. Run as a stateful invariant with multiple actors performing all entry-point operations. 8. **Native vs wrapped traps** — if the contract has both `receive() {}` and a wrapped-native asset, test that stray native arriving via direct transfer (or `selfdestruct` push) is recoverable into accounting. If no recovery path exists, that's a finding — write the test that demonstrates the trap. 9. **External-revert non-DoS** — for every multi-party loop calling an external (registerAgent loop, payout loop), test that one party's external reverting (malicious token, blacklisted address) doesn't brick the others. Either the loop has a `try/catch` skip or the test fails and the contract needs one. 10. **Library link verification** — if the contract uses external library functions, write a test that asserts the library is deployed at the expected address with non-empty bytecode. For deploy scripts, run a fork dry-run AND **drill all the way through** — don't stop at the first error, because each error can mask the next downstream bug. ### 2h. Reentrant external-callback tests (mandatory if the contract receives native FLR or makes recipient-callable external calls) If the contract has `receive() external payable` or makes any external call where the callee can re-enter the contract during execution, write at least one test that proves the `nonReentrant` guard catches the attempt. Pattern: ```solidity // Subclass the standard mock to attempt re-entry during the inner call. contract ReentrantPool is MockCollateralPool { Target public target; bytes public payload; function arm(Target t, bytes calldata p) external { target = t; payload = p; } function exit(uint256 share) external override returns (uint256 nat) { // ... do normal work, transfer native to caller (which is `target`) ... (bool ok,) = msg.sender.call{value: nat}(""); require(ok); // Now attempt the re-entry. nonReentrant on `target.someFn` MUST // cause the inner call to revert. The require(!reok) below converts // that revert into a clean "test passed" signal without bubbling. if (address(target) != address(0) && payload.length > 0) { (bool reok,) = address(target).call(payload); require(!reok, "reentry should have reverted"); } } } // In the test: arm the malicious pool with `deposit(amount, recipient)` // payload, then drive the outer redeem path — the outer must succeed // because nonReentrant guards the inner attempt. ``` For mocks to be subclassable, mark the relevant overridable methods (`exit`, `enter`, `receive`) as `virtual` in the base mock — Solidity defaults to non-virtual. ### 2i. Gas-stress at registry caps (mandatory if the contract has bounded loops over user-registered data) If the contract has any registry that loops over registered entries (`agents[]`, `dexes[]`, `tokens[]`), write a standalone test that fills the registry to `MAX_*` cap and measures gas for every public path: ```solidity contract GasStressTest is Test { // standalone, NOT inheriting unit-test base uint256 internal constant SAFE_BUDGET = 8_000_000; // half block gas limit function setUp() public { // ... deploy + register MAX_* entries here ... } function test_GasStress_TotalAssets_UnderBudget() public { uint256 g0 = gasleft(); target.totalAssets(); uint256 used = g0 - gasleft(); assertLt(used, SAFE_BUDGET, "totalAssets exceeds 8M budget"); emit log_named_uint("totalAssets gas", used); } // ... one test per public path: maxRedeem, allocate, deposit, etc. } ``` **Use 8M as the safety budget**, not the full 15M block limit. Above 8M users mis-estimate gas, txs land in reorg-vulnerable cycles, and a single tx can span block-spanning sandwiches. **Standalone, not inheriting** — same reason as invariant tests. Filling the registry to the cap will brick any inherited unit test that calls `_registerAgent` or similar. ### 2j. CR-boundary / threshold off-by-one tests Any contract with a comparison threshold (`if (x < threshold) revert`) needs explicit at-threshold + one-below-threshold tests. The common bug is `<=` instead of `<`. Pattern: ```solidity function test_Boundary_ExactThreshold_Allows() public { Info memory info = _eligibleInfo(); info.someRatio = THRESHOLD; // exactly at floor vm.prank(owner); target.register(...); assertTrue(target.isEligible(...), "at-threshold should be eligible"); } function test_Boundary_OneBelow_Rejects() public { Info memory info = _eligibleInfo(); info.someRatio = THRESHOLD - 1; // one BIP below vm.prank(owner); target.register(...); assertFalse(target.isEligible(...), "below-threshold should NOT be eligible"); } ``` Mirror this for both pool-side and vault-side thresholds, and for any other paired floors (rate × multiplier / BPS_DENOM patterns). ### 2k. Pause-mid-redeem behavior For ERC-4626 vaults with a `whenNotPaused` modifier on state-changing entries, verify pause: 1. **Blocks** redeem/withdraw/deposit/mint with the standard pausable error 2. **Does NOT block** view paths (`totalAssets`, `maxRedeem`, `previewRedeem`, `balanceOf`) Users need view liveness during a pause window to see they're still solvent. If your pause modifier sneaks onto a view by accident, this test catches it. ### 2l. ERC-4626 spec compliance (directional rounding) For ERC-4626 vaults, the four directional guarantees must be tested explicitly. They protect users from being silently shorted: | Property | Direction | Test | |---|---|---| | `previewDeposit(a)` ≤ `deposit(a)` | actual ≥ preview (user receives ≥ promised shares) | `assertGe(actualShares, previewedShares)` | | `previewMint(s)` ≥ `mint(s)` | actual ≤ preview (user pays ≤ promised assets) | `assertLe(actualAssets, previewedAssets)` | | `previewWithdraw(a)` ≥ `withdraw(a)` | actual ≤ preview (user burns ≤ promised shares) | `assertLe(actualSharesBurned, previewedSharesBurned)` | | `previewRedeem(s)` ≤ `redeem(s)` | actual ≥ preview (user receives ≥ promised assets) | `assertGe(actualAssets, previewedAssets)` | Plus zero-input edges (`previewX(0) == 0`), `convertToAssets(convertToShares(X)) ≤ X` (round-trip never inflates), and `maxRedeem`/`maxWithdraw` round-trip-achievable (no off-by-one — calling `redeem(maxRedeem(addr), addr, addr)` must not revert). **Inflation defense**: verify `_decimalsOffset()` is overridden to ≥6 (typical) or ≥12 (tight). With offset=12, attack capital required to zero a 10^15 (millicoin) victim deposit is ~2 × 10^27 wei — economically impossible. Without an offset, an attacker mints 1 wei share + donates → next victim's shares round to zero. A16z's erc4626-tests reference suite is the canonical port-target. ## Step 3 — Write the tests ### File naming & structure ``` test/ ├── ContractName.t.sol # Unit + happy/sad path tests ├── ContractName.fuzz.t.sol # Fuzz tests (if complex enough to separate) ├── ContractName.invariant.t.sol # Invariant tests with handler ├── ContractName.fork.t.sol # Fork tests (if needed) ├── ContractName.boundary.t.sol # MANDATORY if any external call exists — │ # canonical-fallback decode, selector verify, │ # hash encoding verify, view liveness under │ # degraded inputs, asset reconciliation, │ # native-vs-wrapped traps, external-revert DoS ├── handlers/ │ └── ContractNameHandler.sol # Invariant test handler └── helpers/ └── TestConstants.sol # Shared constants ``` For simpler contracts, combine everything into a single `ContractName.t.sol`. ### Base test contract pattern ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import {Test, console2} from "forge-std/Test.sol"; import {ContractName} from "../src/ContractName.sol"; contract ContractNameTest is Test { ContractName public target; address public owner = makeAddr("owner"); address public alice = makeAddr("alice"); address public bob = makeAddr("bob"); uint256 public constant INITIAL_BALANCE = 100 ether; function setUp() public { vm.startPrank(owner); target = new ContractName(/* constructor args */); vm.stopPrank(); vm.deal(alice, INITIAL_BALANCE); vm.deal(bob, INITIAL_BALANCE); } } ``` ### Critical patterns **Named addresses with `makeAddr()`** — always use labeled addresses, never raw `address(1)`: ```solidity address alice = makeAddr("alice"); address bob = makeAddr("bob"); ``` **Account impersonation:** ```solidity // Single call vm.prank(alice); target.deposit{value: 1 ether}(); // Multiple calls vm.startPrank(alice); target.approve(bob, 100); target.transfer(bob, 50); vm.stopPrank(); ``` **Verify events with `vm.expectEmit()`:** ```solidity vm.expectEmit(true, true, true, true); emit Transfer(alice, bob, 100); target.transfer(bob, 100); ``` **Test reverts with exact matching:** ```solidity // Reason string vm.expectRevert("Insufficient balance"); target.withdraw(amount); // Custom error vm.expectRevert(abi.encodeWithSelector(InsufficientBalance.selector, 0, 100)); target.withdraw(100); // Custom error (alternative) vm.expectRevert(ContractName.InsufficientBalance.selector); target.withdraw(100); ``` **Time manipulation:** ```solidity vm.warp(block.timestamp + 1 days); // set timestamp vm.roll(block.number + 100); // set block number skip(1 hours); // advance time (forge-std helper) rewind(1 hours); // go back in time ``` **Balance manipulation:** ```solidity vm.deal(alice, 100 ether); // native ETH deal(address(token), alice, 1000e18); // ERC20 balance deal(address(token), alice, 1000e18, true); // ERC20 + adjust totalSupply ``` **Storage manipulation:** ```solidity vm.store(address(target), bytes32(uint256(0)), bytes32(uint256(42))); bytes32 val = vm.load(address(target), bytes32(uint256(0))); ``` **Mocking external calls:** ```solidity vm.mockCall( address(oracle), abi.encodeWithSelector(IOracle.latestPrice.selector), abi.encode(2000e8) ); ``` ### Fuzz test pattern ```solidity function testFuzz_Deposit(uint256 amount) public { amount = bound(amount, 1, 100 ether); // constrain to valid range vm.deal(alice, amount); vm.prank(alice); target.deposit{value: amount}(); assertEq(target.balanceOf(alice), amount); } ``` Prefer `bound()` over `vm.assume()`. Only use `vm.assume()` for excluding specific values: ```solidity function testFuzz_Transfer(address to, uint256 amount) public { vm.assume(to != address(0)); vm.assume(to != address(target)); amount = bound(amount, 1, target.balanceOf(alice)); // ... } ``` ### Invariant test pattern **Handler contract:** ```solidity contract VaultHandler is Test { Vault public vault; uint256 public ghost_depositSum; uint256 public ghost_withdrawSum; address[] public actors; address internal currentActor; modifier useActor(uint256 actorIndexSeed) { currentActor = actors[bound(actorIndexSeed, 0, actors.length - 1)]; vm.startPrank(currentActor); _; vm.stopPrank(); } constructor(Vault _vault) { vault = _vault; actors.push(makeAddr("actor0")); actors.push(makeAddr("actor1")); actors.push(makeAddr("actor2")); } function deposit(uint256 amount, uint256 actorSeed) public useActor(actorSeed) { amount = bound(amount, 1, 10 ether); vm.deal(currentActor, amount); vault.deposit{value: amount}(); ghost_depositSum += amount; } function withdraw(uint256 amount, uint256 actorSeed) public useActor(actorSeed) { amount = bound(amount, 0, vault.balanceOf(currentActor)); if (amount == 0) return; vault.withdraw(amount); ghost_withdrawSum += amount; } } ``` **Invariant test contract:** ```solidity contract VaultInvariantTest is Test { Vault public vault; VaultHandler public handler; function setUp() public { vault = new Vault(); handler = new VaultHandler(vault); // CRITICAL: explicitly target handler selectors. Default // targetContract behavior also exposes vm cheatcodes inherited // from Test, which the fuzzer wastes calls on. The handler // itself can inherit Test (for vm cheatcodes inside actions); // the invariant test contract should explicitly whitelist // selectors: bytes4[] memory selectors = new bytes4[](2); selectors[0] = VaultHandler.deposit.selector; selectors[1] = VaultHandler.withdraw.selector; targetSelector(FuzzSelector({addr: address(handler), selectors: selectors})); targetContract(address(handler)); } function invariant_SolvencyDepositsEqualWithdrawals() public view { assertEq( address(vault).balance, handler.ghost_depositSum() - handler.ghost_withdrawSum() ); } function invariant_SolvencyBalanceCoversDeposits() public view { assertGe(address(vault).balance, 0); } } ``` **Common gotchas**: - **Smoke check that fails on initial state**: don't write `assertGt(handler.ghost_callCount(), 0)` — Foundry checks invariants against the initial state BEFORE the first handler call, so this fires immediately. The other passing invariants are sufficient proof the fuzzer ran. - **Standalone over inheritance**: if your unit test base does setUp work that registers fixtures the handler will then duplicate, write the invariant test as a STANDALONE contract (not inheriting the unit-test base). Otherwise inherited test methods re-run with a polluted setUp and fail on duplicate-registration errors. - **`fail_on_revert = false`**: the handler should `try/catch` user actions because the contract's own access-control or pause gates legitimately revert. Without `fail_on_revert = false` (set in `foundry.toml`), every gated revert tanks the run. **Invariant config in `foundry.toml`:** ```toml [invariant] runs = 256 depth = 100 fail_on_revert = false shrink_run_limit = 5000 ``` ### Fork test pattern ```solidity contract ForkTest is Test { uint256 mainnetFork; address constant DAI = 0x6B175474E89094C44Da98b954EedeAC495271d0F; address constant WHALE = 0x60FaAe176336dAb62e284Fe19B885B095d29fB7F; function setUp() public { mainnetFork = vm.createFork(vm.envString("MAINNET_RPC_URL"), 18_000_000); vm.selectFork(mainnetFork); } function test_ForkInteraction() public { deal(DAI, alice, 1_000_000e18); vm.startPrank(alice); // interact with real deployed contracts vm.stopPrank(); } } ``` ### Boundary test patterns These are the concrete templates for the mandatory tests in Section 2g. Copy and adapt one per external interaction. **Canonical-fallback decode** (for every external `getX() returns (Struct)`): ```solidity // Define the upstream's canonical struct LOCALLY in the test file. Do NOT // reuse the contract's own struct here — that defeats the purpose. The // canonical layout should come from the upstream's verified source or a // live `cast call` decoded with the canonical types. struct CanonicalUpstreamShape { uint8 collateralClass; address token; uint256 decimals; uint256 validUntil; bool directPricePair; string assetFtsoSymbol; string tokenFtsoSymbol; uint256 minCollateralRatioBIPS; uint256 safetyMinCollateralRatioBIPS; } contract CanonicalShapeMock { fallback() external payable { if (msg.sig != bytes4(keccak256("getCollateralTypes()"))) revert("bad selector"); CanonicalUpstreamShape[] memory data = new CanonicalUpstreamShape[](1); data[0] = CanonicalUpstreamShape({ collateralClass: 1, token: address(0xWFLR), decimals: 18, validUntil: 0, directPricePair: false, assetFtsoSymbol: "XRP", tokenFtsoSymbol: "FLR", minCollateralRatioBIPS: 15_000, safetyMinCollateralRatioBIPS: 16_000 }); bytes memory ret = abi.encode(data); assembly ("memory-safe") { return(add(ret, 0x20), mload(ret)) } } } function test_Boundary_CanonicalAbiDecodesCleanly() public { // Wire the mock as the external the contract resolves to, // then call any contract function that decodes through getCollateralTypes. target.someFunctionThatDecodesUpstream(); // Assert the decoded values are sensible (the contract should produce // results consistent with the canonical inputs). } ``` **Live-fork ABI sanity check**: ```solidity function test_Fork_LiveUpstreamDecodesCleanly() public { vm.createSelectFork(vm.envString("FLARE_RPC")); UpstreamStruct[] memory items = IUpstream(LIVE_ADDR).getX(); assertGt(items.length, 0, "live upstream should return non-empty"); // Smell tests for shape mismatch: // - Address fields shouldn't be huge integers (signals address bits cast as uint256). assertLt(uint256(uint160(items[0].token)), type(uint160).max); // - Numeric fields should be in their plausible ranges (BIPS ~10^3 to ~10^5, // decimals 0-30, etc). assertGt(items[0].minCollateralRatioBIPS, 1_000); assertLt(items[0].minCollateralRatioBIPS, 1_000_000); // - Boolean fields decode to 0 or 1, not nonsense. // - String fields should be short and printable. } ``` **Selector verification** (for pinned 4-byte constants): ```solidity // Pull the canonical selector from the build artifact at test setup time // rather than recomputing from a Solidity signature. function test_Boundary_PinnedSelectorMatchesBuild() public { // Read methodIdentifiers from out/Upstream.sol/Upstream.json and assert // the contract's pinned constant matches. If the upstream is third-party, // assert against the live bytecode dispatch table instead: bytes memory code = address(LIVE_UPSTREAM).code; // Search for the pattern PUSH4 EQ in the dispatcher. bytes4 expected = IUpstream.someFunction.selector; assertTrue(_bytecodeContainsSelector(code, expected)); } ``` **Hash encoding verification** (for name-keyed registries): ```solidity function test_Fork_RegistryHashEncoding() public { vm.createSelectFork(vm.envString("CHAIN_RPC")); address byName = IRegistry(REGISTRY).getByName("MyContract"); address byPackedHash = IRegistry(REGISTRY).getByHash(keccak256(bytes("MyContract"))); address byEncodedHash = IRegistry(REGISTRY).getByHash(keccak256(abi.encode("MyContract"))); // Whichever path agrees with byName is the encoding the registry uses. // Assert that the contract's pinned NAME_HASH matches whichever path works. assertEq(target.NAME_HASH(), byPackedHash != address(0) ? keccak256(bytes("MyContract")) : keccak256(abi.encode("MyContract"))); assertEq(byName, target.resolveExternal()); } ``` **View liveness under degraded inputs**: ```solidity function test_Boundary_ViewsStayLiveWhenOracleStale() public { _seedRedeemableBalance(alice); _staleOracleFeed(); // sets feed.timestamp to 0 or > maxAge // Every public view consumed by ERC4626 frontends must stay live. target.totalAssets(); target.maxRedeem(alice); target.maxWithdraw(alice); target.previewRedeem(target.balanceOf(alice)); target.previewWithdraw(1 ether); // Downstream user action must succeed if the LST has idle liquidity. vm.prank(alice); target.redeem(target.balanceOf(alice), alice, alice); } function test_Boundary_ViewsStayLiveWhenOracleZero() public { /* analogous */ } function test_Boundary_ViewsStayLiveWhenOracleOOB() public { /* analogous */ } function test_Boundary_ViewsStayLiveWhenExternalReverts() public { /* analogous */ } ``` **Asset reconciliation invariant** (in invariant test contract): ```solidity function invariant_AccountingCountsAllHeldValue() public { uint256 reconciled = address(target).balance; reconciled += primaryAsset.balanceOf(address(target)); // Each registered FAsset's value at current FTSO rate for (uint256 i; i < registeredFAssetCount(); ++i) { address ft = target.registeredFAssets(i); uint256 bal = IERC20(ft).balanceOf(address(target)); if (bal > 0) reconciled += _valueAtFtsoRate(ft, bal); } // Each external position for (uint256 i; i < target.agentCount(); ++i) { reconciled += _agentPositionValue(target.agents(i)); } assertGe(reconciled, target.totalAssets(), "totalAssets undercount = hidden value"); } ``` **Native vs wrapped traps**: ```solidity function test_Boundary_StrayNativeRecoverable() public { uint256 before = target.totalAssets(); vm.deal(alice, 1 ether); vm.prank(alice); (bool ok,) = address(target).call{value: 1 ether}(""); assertTrue(ok); // Native is initially invisible to accounting. assertEq(address(target).balance, 1 ether); assertEq(target.totalAssets(), before); // The contract MUST expose a permissionless recovery path. If this line // fails to compile, the contract has the L-01 trap. target.wrapNative(); assertEq(address(target).balance, 0); assertEq(target.totalAssets(), before + 1 ether); } ``` **External-revert non-DoS**: ```solidity function test_Boundary_OneAgentRevertingDoesNotBrickHarvest() public { _registerAgent(healthyAgent, 1); _registerAgent(maliciousAgent, 1); _seedHarvestableFees(); // Make the malicious pool revert on every external call. vm.mockCallRevert(address(maliciousPool), abi.encodeWithSelector(IPool.withdrawFees.selector), "I revert"); // Harvest must complete and credit the healthy agent's yield. target.harvest(fAsset); // Verify the healthy agent's share was harvested even though the malicious one wasn't. } ``` ### Verification helper pattern (from Moloch methodology) For functions with many state transitions, create internal helper functions: ```solidity function _verifyProposalState( uint256 proposalId, ProposalState expectedState, uint256 expectedVotes ) internal view { assertEq(uint256(target.state(proposalId)), uint256(expectedState)); assertEq(target.voteCount(proposalId), expectedVotes); } ``` ### Test naming conventions ```solidity // Unit tests: test_FunctionName_Description // Order: reverts, happy path, edge cases function test_Deposit_RevertsWhenPaused() public {} function test_Deposit_RevertsWithZeroAmount() public {} function test_Deposit_UpdatesBalance() public {} function test_Deposit_EmitsEvent() public {} function test_Deposit_ZeroValue() public {} function test_Deposit_MaxUint() public {} // Fuzz tests: testFuzz_FunctionName_Description function testFuzz_Deposit_AnyValidAmount(uint256 amount) public {} // Invariant tests: invariant_PropertyDescription function invariant_TotalSupplyMatchesBalances() public view {} // Fork tests: test_Fork_Description function test_Fork_SwapOnUniswap() public {} // Boundary tests: test_Boundary_AssertionAboutTheExternalEdge function test_Boundary_CanonicalAbiDecodesCleanly() public {} function test_Boundary_PinnedSelectorMatchesBuild() public {} function test_Boundary_StrayNativeRecoverable() public {} function test_Boundary_ViewsStayLiveWhenOracleStale() public {} ``` ## Step 4 — Review coverage After writing tests, assess coverage. Print a brief coverage summary at the end **in the same order the tests are written** (reverts → happy path → edge cases → fuzz → invariants → e2e): ``` Coverage summary: - Modifiers: 5/5 enforced - Require/revert statements: 18/18 triggered - Functions (happy path): 12/12 tested - Events: 8/8 verified - Edge cases: zero values, max uint, address(0), reentrancy - Fuzz tests: 8 functions covered - Invariants: 4 properties checked - E2E flows: 3 lifecycle scenarios - Boundary coverage: N external interactions inventoried, M canonical-fallback decode tests, M selector verifications, K hash-encoding verifications, L view-liveness-under-degraded-input tests, 1 asset reconciliation invariant, 1 native-vs-wrapped trap test, 1 external-revert non-DoS test ``` ## Rules - **One logical assertion per test.** A test can have setup checks, but should validate one behavior. - **Descriptive test names.** Use the pattern: `test_FunctionName_DescriptionOfBehavior`. - **No magic numbers.** Use named constants for amounts, durations, thresholds. - **DRY via setUp and helpers, not shared mutable state.** Never rely on test ordering. - **Every test must be independent.** `setUp()` runs fresh before each test. - **Test the sad path as thoroughly as the happy path.** Most exploits come from unexpected inputs and states. - **Trust live, not mocks.** Mocks are round-trip consistent with your model of an external contract; if your model is wrong, mocks are wrong the same way and tests pass while mainnet reverts. Every external interaction needs at least one boundary test that verifies against a canonical reference (live RPC, build artifact, block-explorer-verified source) — not against a mock you encoded yourself. - **Drill all the way through fork dry-runs.** Each error in a fork dry-run can hide the next downstream bug. Don't stop at the first error; fix and re-run until the script completes end-to-end. - **Use `bound()` over `vm.assume()`** — assume discards inputs and wastes fuzzer runs. - **When forking mainnet**, pin to a specific block number for reproducibility. - **Use `makeAddr()`** for all test addresses — never use raw `address(1)`, `address(2)`. - **Use `console2.log()`** for debugging, remove before finalizing. - **Prefer `assertEq` over `assertTrue`** for better error messages on failure.