Property-based testing

Test the rules across more inputs.

A few hand-picked examples can leave important combinations unexplored. Property-based testing checks an approved rule across generated inputs. Cue April gives your team concrete counterexamples for the cases that break the rule, with the recorded information needed to investigate them.

What is property-based testing?

Property-based testing checks that a rule holds across many generated inputs. You state the property, such as “a round trip preserves the value”, and a tool such as fast-check generates cases and reports a counterexample when the rule breaks.

Start with a rule you can explain.

Our fictional rule says delivery costs 500p below £50 and is free from £50. Work in integer pence to keep this example about the boundary rather than floating-point rounding. The deliberately buggy implementation uses >, so exactly £50 is charged. The requirement was specified separately from this implementation.

src/delivery-buggy.mjs: deliberately incorrect boundary
// Deliberately seeded boundary defect: exactly £50 incorrectly costs 500p.
export function deliveryPence(basketPence) {
  return basketPence > 5000 ? 0 : 500;
}

Generate baskets that should always get free delivery.

This genuine fast-check property generates basket values from 5000p to 10000p. Every value in that range should return zero delivery charge. The run requests 1,000 generated cases and fixes the seed so another reader can repeat it. The script imports the buggy implementation with --buggy and the corrected implementation otherwise.

property.mjs: the complete runnable property
import fc from 'fast-check';
const buggy = process.argv.includes('--buggy');
const { deliveryPence } = await import(buggy ? './src/delivery-buggy.mjs' : './src/delivery.mjs');

// The requirement is independent of the implementation: every basket from
// 5000p to 10000p must get free delivery. This is generated sampling, not an
// exhaustive search of every integer in that range.
const property = fc.property(
  fc.integer({ min: 5000, max: 10000 }),
  basketPence => deliveryPence(basketPence) === 0,
);
const result = fc.check(property, {
  numRuns: 1000,
  seed: 20261015,
  ...(process.env.REPLAY_PATH ? { path: process.env.REPLAY_PATH } : {}),
});
const summary = {
  fixture: buggy ? 'buggy' : 'fixed',
  failed: result.failed,
  seed: result.seed,
  path: result.counterexamplePath,
  counterexample: result.counterexample,
  numRuns: result.numRuns,
  numShrinks: result.numShrinks,
};
console.log(JSON.stringify(summary, null, 2));
if (result.failed) process.exitCode = 1;
Run from the downloaded example folder with Node 24
npm ci --ignore-scripts
npm run test:property:bug

The buggy command intentionally exits with status 1. The archive also contains a verification harness that expects this failure and checks the recorded counterexample.

Inspect the counterexample and replay it.

The local run found a failing basket of 5000p on its 27th generated case. Its replay seed is 20261015 and path is 26. No shrinking was needed for this run. Keep the package lockfile, generator and property unchanged when replaying: a seed alone is not a promise of identical results after tool or test changes. fast-check documents seed and path replay.

Observed local result, summarised from the recorded JSON
Buggy implementation:
failed: true
seed: 20261015
path: "26"
counterexample: [5000]
numRuns: 27
numShrinks: 0

Corrected implementation:
failed: false
numRuns: 1000
Replay the same failing case
REPLAY_PATH=26 npm run test:property:bug

Fix the boundary and keep a regression case.

Change > to >=. Running the same property against the corrected function passed all 1,000 requested cases locally. Also keep a direct assertion for 5000p so the known requirement remains obvious to a reviewer. A passing sampled run describes this property and domain; it does not establish correctness for invalid inputs or the rest of an invoice application.

src/delivery.mjs: the corrected function
// Fictional requirement: delivery costs 500p below £50 and is free from £50.
// The example accepts a non-negative integer basket value in pence.
export function deliveryPence(basketPence) {
  return basketPence >= 5000 ? 0 : 500;
}
Run the corrected property and boundary tests
npm run test:property
npm test

Distinguish generated sampling from an exhaustive finite check.

The homepage invoice sample enumerates all 10,001 integer basket amounts from 0p through 10000p in your browser. This fast-check example instead generates samples from 5000p through 10000p and supports seed/path replay. The two exercises have different scopes and results. The separate actual product-engine run also shows a 100-case random shipping check missing the exact boundary. Input domain, seed and run count affect what is exercised, so retain an explicit regression for a known boundary. None of these local runs qualifies a hosted evaluation.

  • An explicit example records an important known case, such as exactly 5000p.
  • A property checks a stated rule across generated inputs.
  • An exhaustive finite loop checks every input in its declared bounded set.

Bring a bounded business rule to your evaluation.

Start with a rule such as tenant isolation, a round trip or a pricing threshold. Agree the expected result, input domain and permitted effects before running it against your code. Cue April can coordinate supported property checks with API testing and mutation testing. Repository tooling, qualified runners and approved scope determine what runs. Compare platform setup and managed testing.

Primary documentation

Framework behaviour and configuration are documented by their maintainers.

Questions about this testing method

01

Will the agent invent my business rules?

Expected behaviour comes from approved requirements and definitions. Missing or ambiguous expectations require review before they can become authoritative test assertions.

02

Does property testing replace example tests?

The methods answer complementary questions. The owned sample shows a shipping property passing while a tenant isolation fault is present, which is why the tested rule and other methods remain important.

03

How is property-based testing different from fuzz testing?

Both generate many inputs. Fuzz testing usually looks for crashes or security faults caused by unexpected input. Property-based testing checks that a stated rule holds, so every generated case has an expected outcome to compare against.

04

How do you write a property-based test?

State a rule that must always hold, choose generators for its inputs and let the tool check the rule across many generated cases. When a case breaks the rule, the tool reports the counterexample so your team can reproduce it.

Your next release starts here

Keep building.
Put testing to work.

Give Cue April your next testing challenge. Let your AI quality lead coordinate the checks, so your team can focus on what comes next.

Create account

Create your account, connect a repository and review your proposed setup before approving a run.