Docs / Getting started

Quick start

From nothing to a shrunk counterexample in five steps.

1. Install fe and Node

You need fe 26.6 and Node 22.18 or newer:

bash
curl -fsSL https://raw.githubusercontent.com/argotorg/fe/master/feup/feup.sh | bash -s -- --version v26.6.0
node --version

diff and --backend native also need fe's native backend, which runs on Linux and macOS. On Windows, install fe inside WSL as well; Fuzzloom then runs native tests there by itself.

2. Check your setup

Run this from inside any Fe ingot (a directory with fe.toml and src/):

bash
npx fuzzloom doctor
text
ok    Node              v22.18.0
ok    fe                fe 26.6.0 (5b3f96a) at /home/you/.fe/bin/fe
ok    Fe library        .../node_modules/fuzzloom/ingot
ok    Library compiles  fe check passed
ok    Native backend    fe 26.6.0 (5b3f96a) in this machine
warn  Project           ingot my_ingot: 0 prop_* and 0 diff_* functions, 0 skipped
                        write `pub fn prop_<name>(args) -> bool` (or diff_<name>) in the ingot's src/

The project warning goes away once you write your first property.

3. Write a property

Add a public function whose name starts with prop_ and which returns bool, anywhere under src/:

fe
pub fn fee(_ amount: u64) -> u64 {
    amount.wrapping_mul(30) / 10000
}

/// The fee matches exact arithmetic for every amount.
pub fn prop_fee_matches_exact_math(_ amount: u64) -> bool {
    let exact: u128 = (amount as u128) * 30 / 10000
    (fee(amount) as u128) == exact
}

4. Fuzz it

bash
npx fuzzloom fuzz --seed 7
text
FAIL  prop_fee_matches_exact_math(u64)  counterexample at input 2
      amount = 614891469123651721
      shrunk from 4762291152399575021 in 1414 evaluations
      reproduce: fuzzloom reproduce prop_fee_matches_exact_math-0e05b819

614891469123651721 is u64::MAX / 30 + 1, the smallest amount for which amount * 30 wraps. The shrinker found the exact threshold. The seed makes the run repeatable; leave it out and Fuzzloom picks one at random and prints it.

5. Fix it and replay

Widen before multiplying, then check the saved failure again:

fe
pub fn fee(_ amount: u64) -> u64 {
    ((amount as u128) * 30 / 10000).downcast_truncate()
}
bash
npx fuzzloom replay
text
FIXED  prop_fee_matches_exact_math-0e05b819  now passes

Commit .fuzzloom/failures/: it is your regression suite. Every later fuzz also mutates those saved inputs, to catch a fix that only handles the one input that was saved.

Next