Property-Based Testing: Testing Rules, Not Examples
Property-based tests assert invariants that hold for all inputs, and the framework generates the cases. Learn how it finds bugs example tests miss.
By Velloreth
The idea
An example-based test asserts a specific outcome for a specific input.
test('reverses a string', () => {
expect(reverse('hello')).toBe('olleh');
});
A property-based test asserts a rule that should hold for all valid inputs, and the framework generates the inputs.
test('reversing twice returns the original', () => {
fc.assert(
fc.property(fc.string(), (s) => {
expect(reverse(reverse(s))).toBe(s);
}),
);
});
The framework generates hundreds of strings — empty, single characters, unicode, emoji, very long — and checks the property for each. If any fails, it reports the input.
The shift is from “does it work for this input?” to “does it work for every input?”.
Why it finds bugs
The value is in the inputs you would not think to write.
A developer writing example tests for reverse would test 'hello', maybe '', maybe 'a'. They would probably not test:
- A string with a combining character, like
'é'ase+ combining accent. - A string with an emoji that is a surrogate pair.
- A string with a right-to-left mark.
- A very long string.
The framework generates all of these. And reverse implemented with split('').reverse().join('') breaks on surrogate pairs, because splitting by code unit separates the halves of an emoji.
reverse('👋'); // broken: the surrogate pair is split
That is a real bug, found by a generated input, that an example test would almost certainly miss.
Shrinking
When a property fails, the framework does not just report the random input. It shrinks it to the smallest input that still fails.
Falsifying example: reverse(reverse(s)) !== s
with s = "a👋b"
shrunk to s = "👋"
The shrunk input is minimal and readable. Without shrinking, you would get a 200-character random string and have to work out which part matters.
Shrinking is what makes property-based testing practical. It turns a random failure into a specific, minimal counterexample.
Good properties
Round-trip
Encode then decode returns the original.
test('JSON round-trip preserves the value', () => {
fc.assert(
fc.property(fc.jsonValue(), (value) => {
expect(JSON.parse(JSON.stringify(value))).toEqual(value);
}),
);
});
This is one of the most valuable properties. It applies to serialisation, compression, encryption, and any encode/decode pair.
Invariant
Something that must always be true of the output.
test('sorting preserves length', () => {
fc.assert(
fc.property(fc.array(fc.integer()), (arr) => {
expect(sort(arr).length).toBe(arr.length);
}),
);
});
test('sorting produces an ordered array', () => {
fc.assert(
fc.property(fc.array(fc.integer()), (arr) => {
const sorted = sort(arr);
for (let i = 1; i < sorted.length; i++) {
expect(sorted[i]).toBeGreaterThanOrEqual(sorted[i - 1]);
}
}),
);
});
Two properties together — same length, and ordered — pin down sorting without asserting a specific output.
Idempotence
Applying the operation twice equals applying it once.
test('normalising is idempotent', () => {
fc.assert(
fc.property(fc.string(), (s) => {
expect(normalize(normalize(s))).toBe(normalize(s));
}),
);
});
This catches a large class of bugs in normalisation, formatting, and cleanup functions.
Equivalence with a reference
Compare against a simple, obviously correct implementation.
test('fast sort matches the reference sort', () => {
fc.assert(
fc.property(fc.array(fc.integer()), (arr) => {
expect(fastSort(arr)).toEqual([...arr].sort((a, b) => a - b));
}),
);
});
The reference is slow but simple. If the fast version disagrees, one of them is wrong.
Commutativity and associativity
test('addition is commutative', () => {
fc.assert(
fc.property(fc.integer(), fc.integer(), (a, b) => {
expect(add(a, b)).toBe(add(b, a));
}),
);
});
Useful for mathematical operations and for verifying that an optimisation preserves semantics.
Libraries
| Language | Library |
|---|---|
| Haskell | QuickCheck |
| Python | Hypothesis |
| JavaScript / TypeScript | fast-check |
| Java | jqwik |
| Rust | proptest |
| Go | gopter |
| Scala | ScalaCheck |
The concept originated with QuickCheck in Haskell and has been ported widely. The API differs, but the model is the same: define generators, assert properties, shrink failures.
Custom generators
For domain types, you write generators.
const userArbitrary = fc.record({
id: fc.uuid(),
email: fc.emailAddress(),
age: fc.integer({ min: 0, max: 120 }),
isActive: fc.boolean(),
});
test('serialising a user round-trips', () => {
fc.assert(
fc.property(userArbitrary, (user) => {
expect(deserialiseUser(serialiseUser(user))).toEqual(user);
}),
);
});
The generator encodes the valid input space. Constraints like min: 0, max: 120 for age keep the generated data realistic.
When it is most valuable
Parsers and serialisers. Round-trip properties catch a huge class of bugs.
Data transformations. Invariants and equivalence with a reference.
Algorithms. Sorting, searching, and graph operations have clear properties.
Financial calculations. Invariants like “the sum of parts equals the whole”.
State machines. Model-based testing generates sequences of operations and checks invariants after each.
Anything with a spec. If you can state a rule, you can test it as a property.
When it is less useful
UI layout. There is no meaningful property to assert about visual arrangement.
One-off scripts. The setup cost exceeds the benefit.
Code with no clear invariants. If you cannot state a rule, you cannot write a property.
Slow operations. Hundreds of iterations of a slow function is impractical.
Combining with example tests
Property-based tests do not replace example tests. They serve different purposes.
Example tests document specific expected behaviour. They are readable, they serve as documentation, and they pin down exact outputs.
Property tests explore the input space. They find edge cases and verify general rules.
The practical approach: write example tests for the documented behaviour and the known edge cases, and add property tests for the general rules. When a property test finds a bug, add an example test for the specific case so the regression is documented.
Practical guidance
- Start with round-trip properties — they are the easiest and most valuable.
- Add invariants for the output of each function.
- Use a reference implementation when one exists.
- Write custom generators for domain types.
- Keep the iteration count reasonable — 100 is usually enough.
- Add an example test for each bug a property test finds.
- Do not replace example tests — use both.
- Check the shrunk input when a property fails; it usually points straight at the bug.
For the related practices, see unit testing basics and test-driven development guide. For the broader context, code coverage myths and fixing flaky tests.
Quotable summary
A property-based test asserts a rule that should hold for all valid inputs, and the framework generates hundreds of cases to try to falsify it. It finds edge cases you would not think to write, including empty inputs, extreme values, and unusual unicode, and when a case fails the framework shrinks it to the smallest input that still fails, which makes debugging practical. Good properties include round-trips, invariants, idempotence, and equivalence with a simple reference implementation. Property-based testing complements example-based tests rather than replacing them: examples document specific behaviour and are easy to read, while properties explore the input space. It is most valuable for parsers, serialisers, data transformations, and algorithms.