Property-Based Testing

What it is

A property-based test does not check one hard-coded example. You state a property — an invariant that must hold for all valid inputs — and the framework generates hundreds of random inputs, hunting for a counterexample.

When it finds one, it shrinks it to the smallest failing input, so you get [] or 0 instead of a 200-character string.

1
  property + generator
2
          │
3
          ▼
4
   ┌─────────────┐   pass   ┌──────────┐
5
   │ generate N  │─────────►│  done    │
6
   │  inputs     │          └──────────┘
7
   └──────┬──────┘
8
          │ fail
9
          ▼
10
   ┌─────────────┐
11
   │  shrink to  │  → minimal counterexample
12
   │  smallest   │
13
   └─────────────┘

Example properties: reverse(reverse(xs)) == xs, sorting is idempotent, a round-trip encode/decode returns the original, length(concat(a, b)) == length(a) + length(b).

When to use it / when to avoid it

Use it for

Pure functions with a checkable invariant (parsers, codecs, sorters, math)
Round-trip properties: encode/decode, serialize/deserialize, parse/print
Finding edge cases you would never write by hand (NaN, empty, unicode, overflow)
Complementing example-based tests, not replacing them

Avoid it when

The expected output is just as complex as the input (no oracle to compare against)
The system is stateful, slow or non-deterministic (prefer model-based or a real harness)
You cannot describe a generator for valid inputs — garbage in, garbage out
A handful of examples already covers the risk

Frameworks & tools

Tool	Ecosystem	Notes
fast-check	JS/TS	Rich arbitraries, integrated with Vitest/Jest
Hypothesis	Python	Best-in-class shrinking; `@given`, strategies
jqwik	Java/JVM	JUnit 5 platform engine; `@Property`, `@ForAll`
proptest	Rust	Generator + shrinker, `proptest!` macro
gopter	Go	Property testing on top of `testing`
QuickCheck	Haskell	The original that inspired them all
FsCheck / CsCheck	.NET	Idiomatic properties for C# and F#
QuickTheories	Java	Lightweight alternative to jqwik

Quick setup

1
npm install -D fast-check vitest

1
pip install hypothesis pytest

1
go get github.com/leanovate/gopter

1
<!-- Maven: jqwik (JUnit 5 platform) -->
2
<dependency>
3
  <groupId>net.jqwik</groupId>
4
  <artifactId>jqwik</artifactId>
5
  <version>1.9.1</version>
6
  <scope>test</scope>
7
</dependency>

1
dotnet add package FsCheck.Xunit

Example

1
import { describe, it, expect } from 'vitest';
2
import fc from 'fast-check';
3
import { encode, decode } from './codec';
4

5
describe('codec', () => {
6
  it('round-trips any string', () => {
7
    fc.assert(
8
      fc.property(fc.string(), (s) => {
9
        expect(decode(encode(s))).toBe(s);
10
      }),
11
    );
12
  });
13
});

1
from hypothesis import given, strategies as st
2
from codec import encode, decode
3

4
@given(st.text())
5
def test_round_trip(s):
6
    assert decode(encode(s)) == s

1
import (
2
  "testing"
3

4
  "github.com/leanovate/gopter"
5
  "github.com/leanovate/gopter/gen"
6
  "github.com/leanovate/gopter/prop"
7
)
8

9
func TestRoundTrip(t *testing.T) {
10
  params := gopter.DefaultTestParameters()
11
  properties := gopter.NewProperties(params)
12
  properties.Property("decode(encode(s)) == s", prop.ForAll(
13
    func(s string) bool { return Decode(Encode(s)) == s },
14
    gen.AnyString(),
15
  ))
16
  properties.TestingRun(t)
17
}

1
import net.jqwik.api.ForAll;
2
import net.jqwik.api.Property;
3
import static org.assertj.core.api.Assertions.assertThat;
4

5
class CodecProperties {
6
  @Property
7
  void roundTripsAnyString(@ForAll String s) {
8
    assertThat(Codec.decode(Codec.encode(s))).isEqualTo(s);
9
  }
10
}

1
using FsCheck;
2
using FsCheck.Xunit;
3

4
public class CodecProperties
5
{
6
    [Property]
7
    public Property RoundTripsAnyString(NonNull<string> input)
8
    {
9
        var s = input.Get;
10
        return (Codec.Decode(Codec.Encode(s)) == s).ToProperty();
11
    }
12
}

Anti-patterns & best practices

Start from a real example. Write the example-based test first, then generalise it into a property: it is the “most valuable first test”.
Keep generators small but honest. A generator that only produces valid input is fine; one that produces nothing useful tests nothing.
Do not assert the exact same logic you are testing. A tautological property (f(x) == f(x)) always passes and proves nothing.
Seed and reproduce. Log the generated seed so a rare failure can be replayed deterministically in CI.
Watch runtime. Randomised tests are slower than examples — bound the number of runs and keep the property pure.
Treat every counterexample as a gift. Add it as an explicit regression example once fixed.