sb-dev/openquant / .agents/skills/property-based-testing
property-based-testing
VerifiedWrites, 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.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 15.0 KB |
| SKILL.md | skill md | 4.2 KB |
| agents/openai.yaml | config | 254 B |
| assets/trail-of-bits-mark.svg | other | 3.0 KB |
| references/generating.md | markdown | 2.6 KB |
| references/interpreting-failures.md | markdown | 3.3 KB |
| references/libraries.md | markdown | 2.9 KB |
| references/refactoring.md | markdown | 4.7 KB |
| references/reviewing.md | markdown | 2.8 KB |
references/libraries.md
View on GitHub# 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:
```bash
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.
```solidity
// 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.
```solidity
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](https://secure-contracts.com).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |