fuzzing-patterns

# Fuzz Testing Patterns ## Stateless vs Stateful Fuzzing | Type | How It Works | Use Case | |------|-------------|----------| | **Stateless** | Random inputs per test, fresh state each run | Individual function properties | | **Stateful** | Random sequences of calls, accumulated state | System-level invariants | Stateless = `function testFuzz_*(uint256 x)` — Foundry randomizes `x` each run. Stateful = invariant tests with handlers (see `invariant-testing` skill). ## Basic Fuzz Test ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; import {Test} from "forge-std/Test.sol"; import {Vault} from "../src/Vault.sol"; contract VaultFuzzTest is Test { Vault vault; function setUp() public { vault = new Vault(address(token)); deal(address(token), address(this), type(uint128).max); token.approve(address(vault), type(uint256).max); } // Property: deposit then redeem never yields more than deposited function testFuzz_depositRedeemNoProfit(uint256 assets) public { assets = bound(assets, 1, type(uint128).max); uint256 shares = vault.deposit(assets, address(this)); uint256 received = vault.redeem(shares, address(this), address(this)); assertLe(received, assets, "profit from round-trip"); } // Property: transfer preserves total supply function testFuzz_transferPreservesSupply( address to, uint256 mintAmount, uint256 transferAmount ) public { vm.assume(to != address(0) && to != address(this)); mintAmount = bound(mintAmount, 1, type(uint128).max); transferAmount = bound(transferAmount, 0, mintAmount); vault.deposit(mintAmount, address(this)); uint256 supplyBefore = vault.totalSupply(); vault.transfer(to, transferAmount); uint256 supplyAfter = vault.totalSupply(); assertEq(supplyBefore, supplyAfter, "supply changed on transfer"); } } ``` ## Input Constraining ### `bound()` vs `vm.assume()` ```solidity // PREFER bound() — maps input to valid range without discarding runs function testFuzz_bounded(uint256 x) public { x = bound(x, 1e18, 1_000_000e18); // x is always in [1e18, 1_000_000e18] } // AVOID vm.assume() for wide ranges — discards too many inputs function testFuzz_assumed(uint256 x) public { vm.assume(x > 0 && x < 1000); // 99.99% of inputs discarded! // Only use for conditions that are hard to express with bound() } ``` ### When to Use `vm.assume()` ```solidity // Valid: exclude specific addresses function testFuzz_transfer(address to, uint256 amount) public { vm.assume(to != address(0)); vm.assume(to != address(vault)); vm.assume(to.code.length == 0); // no contracts amount = bound(amount, 1, balanceOf(address(this))); // ... } ``` ## Fuzz Configuration In `foundry.toml`: ```toml [fuzz] runs = 1000 # number of random inputs per test (default: 256) max_test_rejects = 65536 # max vm.assume rejections before fail seed = "0x1234" # fixed seed for reproducibility dictionary_weight = 40 # % of inputs from extracted constants [invariant] runs = 256 depth = 64 fail_on_revert = false ``` ## Property Categories ### Algebraic Properties ```solidity // Commutativity: f(a, b) == f(b, a) function testFuzz_addCommutative(uint256 a, uint256 b) public { assertEq(target.add(a, b), target.add(b, a)); } // Associativity: f(f(a, b), c) == f(a, f(b, c)) // Identity: f(a, 0) == a // Idempotency: f(f(a)) == f(a) ``` ### Roundtrip Properties ```solidity // encode then decode returns original function testFuzz_encodeDecodeRoundtrip(uint256 value) public { bytes memory encoded = target.encode(value); uint256 decoded = target.decode(encoded); assertEq(decoded, value); } // deposit then withdraw returns (approximately) original function testFuzz_depositWithdrawRoundtrip(uint256 amount) public { amount = bound(amount, 1e18, 1_000_000e18); uint256 shares = vault.deposit(amount, address(this)); uint256 returned = vault.redeem(shares, address(this), address(this)); assertApproxEqAbs(returned, amount, 1); // within 1 wei } ``` ### Monotonicity Properties ```solidity // More input -> more output (or equal) function testFuzz_depositMonotonic(uint256 a, uint256 b) public { a = bound(a, 1e18, 1_000_000e18); b = bound(b, a, 1_000_000e18); // b >= a uint256 sharesA = vault.previewDeposit(a); uint256 sharesB = vault.previewDeposit(b); assertGe(sharesB, sharesA, "more deposit should give more shares"); } ``` ### Boundary Properties ```solidity // No overflow at max values function testFuzz_noOverflow(uint256 a, uint256 b) public { a = bound(a, 0, type(uint128).max); b = bound(b, 0, type(uint128).max); // Should not revert with overflow target.safeMultiply(a, b); } ``` ## Interpreting Counterexamples When a fuzz test fails, Foundry shows the failing input: ``` [FAIL. Reason: profit from round-trip] Counterexample: calldata=0x..., args=[115792089237316195423570985008687907853269984665640564039457584007913129639935] ``` Steps: 1. Copy the failing args into a concrete test 2. Add `console2.log()` to trace execution 3. Check if it's a real bug or a test constraint issue 4. If real: fix the bug, keep the counterexample as a regression test 5. If false positive: tighten `bound()` constraints ```solidity // Regression test from fuzzer counterexample function test_regression_overflowOnMaxDeposit() public { uint256 amount = type(uint256).max; vm.expectRevert(); vault.deposit(amount, address(this)); } ``` ## Checklist - [ ] Use `bound()` over `vm.assume()` to minimize discarded runs - [ ] Properties categorized: algebraic, roundtrip, monotonicity, boundary - [ ] Fuzz runs set to 1000+ for CI, 256 for local development - [ ] Counterexamples from failures preserved as regression tests - [ ] Fixed seed used for reproducible CI results - [ ] Separate fuzz tests from unit tests (naming convention `testFuzz_`) - [ ] Edge values tested explicitly alongside fuzzing (0, 1, max) - [ ] Properties verified against known-correct reference implementation