Skip to content
Velloreth
Programming 6 min read

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

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 'é' as e + 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

LanguageLibrary
HaskellQuickCheck
PythonHypothesis
JavaScript / TypeScriptfast-check
Javajqwik
Rustproptest
Gogopter
ScalaScalaCheck

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.

Frequently asked questions

What is property-based testing?
It is a testing approach where you assert a property that should hold for all valid inputs, and the framework generates many random inputs to try to falsify it. When one fails, it shrinks the input to a minimal counterexample.
What is shrinking?
Shrinking is the process of reducing a failing input to the smallest version that still fails. If a test fails on a 500-element array, the framework tries smaller arrays and simpler values until it finds the minimal case, which makes the bug much easier to diagnose.
What are good properties to test?
Round-trips (encode then decode returns the original), invariants (the output length is always the input length), idempotence (applying twice equals applying once), and equivalence with a simple reference implementation.
Which languages have property-based testing libraries?
QuickCheck for Haskell, Hypothesis for Python, fast-check for JavaScript and TypeScript, jqwik for Java, proptest for Rust, and gopter for Go.
Does property-based testing replace example-based tests?
No. Example-based tests document specific expected behaviour and are easy to read. Property-based tests explore the input space. Use both: examples for clarity and documentation, properties for coverage.
How many iterations should a property test run?
The default is usually 100. Increasing it explores more of the input space and finds rarer bugs, at the cost of runtime. For critical code, a few hundred to a few thousand iterations is reasonable.