AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

property-based-testing

Writes, reviews, and debugs property-based tests — Hypothesis, fast-check, proptest, jqwik, rapid, and Echidna or Medusa for Solidity invariants. Use whenever tests should cover a whole input domain instead of a hand-picked list of examples: encode/decode and serialize/deserialize pairs, parsers, canonicalizers and normalizers, validators, numeric and Decimal types, comparators and sort order, data structures, and smart-contract state invariants. Also use when adding cases to an existing @given, fast-check, or proptest suite, when judging whether existing property tests assert anything real, and when a generator has shrunk a counterexample and you need to tell a wrong property from a genuine bug. Not for coverage-guided binary fuzzing (libFuzzer, AFL), mutation-testing campaigns, static analysis, benchmarking, or end-to-end UI tests.

Original source
trailofbits
License
CC-BY-SA-4.0
Pinned revision
2be6433b39e009cd2b6fd3be1895f6b1faa5af9a

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read trailofbits--property-based-testing at revision 2be6433b39e009cd2b6fd3be1895f6b1faa5af9a, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 7

references/libraries.md

PBT Libraries by Language

Match the project's existing choice. Introducing a second PBT library into a codebase that already has one is not worth the property you wanted to write.

| Language | Default | Also in use | |---|---|---| | Python | Hypothesis | — | | TypeScript / JavaScript | fast-check | — | | Rust | proptest | quickcheck (simpler API, per-type shrinking) | | Go | rapid | gopter (ScalaCheck-style, more explicit) | | Java | jqwik | — | | Scala | ScalaCheck | — | | C# | FsCheck | — | | Elixir | StreamData | — | | Haskell | QuickCheck | Hedgehog (integrated shrinking, no type classes) | | Clojure | test.check | — | | Ruby | PropCheck | — | | Kotlin | Kotest | — | | C++ | RapidCheck | — | | Swift | SwiftCheck | unmaintained — check before recommending |

Detect what a repo already uses before proposing anything:

rg "from hypothesis import|fast-check|use proptest|pgregory.net/rapid|net.jqwik|echidna_|invariant_"

Smart contracts (EVM / Solidity)

This is where PBT earns the most, because contract state is adversarial and the input domain is every possible call sequence. Trail of Bits maintains both tools:

  • Echidna — property fuzzer, mature, the default choice.
  • Medusa — parallel execution, coverage-guided; faster on large contract suites.

Two testing modes, and picking the wrong one is the usual mistake:

Property mode — a function returning bool that must never become false.

// Echidna calls this after every transaction sequence.
function echidna_total_matches_sum() public view returns (bool) {
    return token.totalSupply() == trackedSum;
}

Assertion mode — an assert inside a function the fuzzer is allowed to call directly, for properties about a specific operation rather than global state.

function testDepositIncreasesBalance(uint256 amount) public {
    uint256 before = vault.balanceOf(address(this));
    vault.deposit(amount);
    assert(vault.balanceOf(address(this)) >= before);
}

Contract invariants worth asserting

Solvency (sum(balances) <= totalAssets), supply conservation, access control (a non-owner call sequence never reaches an owner-only state change), monotonic counters, and round-trip on share/asset conversion (convertToShares then convertToAssets never returns more than you put in).

Tautologies specific to Solidity

Type bounds are not properties. uint256 x >= 0 is always true, and so is address(this).balance >= 0 — the compiler guarantees it. Likewise a property that only reads state the fuzzer cannot reach is vacuous: if no call sequence can enter the branch, the invariant is never exercised. Check Echidna's coverage output rather than assuming.

echidna_ functions must be view/pure and take no arguments — a property that mutates state silently changes what it is testing.

Tutorials: secure-contracts.com.