Self-Hosted Property-Based Testing: Hypothesis vs Fast-Check vs Proptest Guide 2026

Property-based testing is a testing methodology where instead of writing individual test cases with specific inputs and expected outputs, you define properties — invariants that should hold true for all valid inputs — and let a testing framework automatically generate thousands of random inputs to verify them. This approach finds edge cases that traditional example-based testing routinely misses.

Unlike example-based tests where you manually write assert add(2, 3) == 5, property-based testing asks: “Is add(a, b) == add(b, a) true for all integers a and b?” The framework then generates hundreds of random pairs to find counterexamples.

What Is Property-Based Testing?

Traditional example-based testing checks specific scenarios you anticipate. Property-based testing, pioneered by the QuickCheck library for Haskell in 1999, takes a fundamentally different approach:

1. Define properties — logical invariants that must always hold
2. Generate random inputs — the framework creates thousands of test cases automatically
3. Shrink failures — when a test fails, the framework finds the minimal input that triggers the bug
4. Reproduce deterministically — use a seed to re-run the exact same failing case

This methodology is particularly valuable for testing business logic, parsers, serializers, mathematical functions, and data transformations — areas where edge cases abound and manual test case enumeration is impractical.

Hypothesis (Python)

Hypothesis is the leading property-based testing framework for Python with 8,600+ GitHub stars. It integrates seamlessly with pytest and supports complex data generation strategies.

Key Features:

• Deep pytest integration with @given decorator
• Rich strategy system for generating complex data (nested dicts, recursive structures, Pandas DataFrames)
• Built-in database for persisting examples between test runs
• Stateful testing for verifying sequences of operations
• Django and Pandas integration

Installation:

1
2
3

pip install hypothesis
pip install hypothesis[django]  # for Django support
pip install hypothesis[pandas]  # for Pandas DataFrames

Docker Compose Setup for CI:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

version: "3.8"
services:
  test-runner:
    image: python:3.12-slim
    working_dir: /app
    volumes:
      - .:/app
      - hypothesis-db:/app/.hypothesis
    environment:
      - HYPOTHESIS_PROFILE=ci
    command: >
      bash -c "pip install -r requirements.txt &&
               pytest --hypothesis-profile ci --hypothesis-seed=42 tests/"
    networks:
      - test-network

volumes:
  hypothesis-db:

networks:
  test-network:
    driver: bridge

Example Test:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

from hypothesis import given, settings
from hypothesis import strategies as st

@given(st.integers(), st.integers())
@settings(max_examples=1000)
def test_addition_commutative(a, b):
    assert a + b == b + a

@given(st.text())
def test_reverse_twice_is_identity(text):
    assert text[::-1][::-1] == text

Fast-Check (JavaScript/TypeScript)

Fast-Check is the most popular property-based testing library for the JavaScript ecosystem, available for Node.js and browser environments with 14,000+ GitHub stars.

Key Features:

• Full TypeScript support with rich type inference
• Works with Jest, Vitest, Mocha, and Jasmine
• Arbitrary composition for complex data structures
• Async property support for testing promises
• Model-based testing for stateful systems

Installation:

1
2
3
4
5

npm install fast-check --save-dev
# or
yarn add -D fast-check
# or
pnpm add -D fast-check

Docker Compose Setup:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

version: "3.8"
services:
  test-runner:
    image: node:22-slim
    working_dir: /app
    volumes:
      - .:/app
      - node_modules:/app/node_modules
    environment:
      - NODE_ENV=test
      - FC_SEED=42
    command: >
      bash -c "npm ci &&
               npx jest --testTimeout=30000 --testMatch='**/*.fastcheck.test.ts'"
    networks:
      - test-network

volumes:
  node_modules:

networks:
  test-network:
    driver: bridge

Example Test:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import fc from 'fast-check';

describe('Array properties', () => {
  it('reversing twice returns the original array', () => {
    fc.assert(
      fc.property(fc.array(fc.integer()), (arr) => {
        const reversed = [...arr].reverse().reverse();
        expect(reversed).toEqual(arr);
      })
    );
  });

  it('sorting produces ordered array', () => {
    fc.assert(
      fc.property(fc.array(fc.integer()), (arr) => {
        const sorted = [...arr].sort((a, b) => a - b);
        for (let i = 1; i < sorted.length; i++) {
          expect(sorted[i]).toBeGreaterThanOrEqual(sorted[i - 1]);
        }
      })
    );
  });
});

Proptest (Rust)

Proptest brings property-based testing to Rust with 5,500+ GitHub stars. It is inspired by QuickCheck but offers a more powerful strategy system.

Key Features:

• Native Rust integration with procedural macros
• Fork and timeout support for testing unsafe code
• Rich strategy combinators for complex data generation
• Test state machines with the state machine module
• Compatible with cargo test workflow

Installation:

Add to your Cargo.toml:

1
2

[dev-dependencies]
proptest = "1.4"

Docker Compose Setup:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

version: "3.8"
services:
  test-runner:
    image: rust:1.78-slim
    working_dir: /app
    volumes:
      - .:/app
      - cargo-registry:/usr/local/cargo/registry
      - cargo-git:/usr/local/cargo/git
      - target-cache:/app/target
    environment:
      - PROPTEST_CASES=1000
      - RUST_BACKTRACE=1
    command: >
      bash -c "cargo test --lib -- --test-threads=1 prop_"
    networks:
      - test-network

volumes:
  cargo-registry:
  cargo-git:
  target-cache:

networks:
  test-network:
    driver: bridge

Example Test:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

use proptest::prelude::*;

proptest! {
    #[test]
    fn reverse_twice_is_identity(s in ".*") {
        let reversed: String = s.chars().rev().collect();
        let double_reversed: String = reversed.chars().rev().collect();
        prop_assert_eq!(s, double_reversed);
    }

    #[test]
    fn addition_commutative(a in any::<i32>(), b in any::<i32>()) {
        // Avoid overflow
        if let Some(sum1) = a.checked_add(b) {
            if let Some(sum2) = b.checked_add(a) {
                prop_assert_eq!(sum1, sum2);
            }
        }
    }
}

Comparison Table

Integration with CI/CD Pipelines

Property-based testing fits naturally into CI/CD pipelines. Configure your test runner to use a fixed seed in CI for reproducibility while allowing random seeds locally:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# GitHub Actions example
name: Test
on: [push, pull_request]
jobs:
  property-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python: ["3.11", "3.12"]
    steps:
      - uses: actions/checkout@v4
      - name: Run property-based tests
        run: |
          pip install hypothesis pytest
          pytest --hypothesis-profile ci --hypothesis-seed=${{ github.sha }}

Why Property-Based Testing Matters

Traditional example-based testing is limited by the scenarios you think to write. Property-based testing removes that constraint by exploring the input space systematically. The key benefits:

• Finds edge cases you would never think to write manually — null bytes, empty strings, boundary values, Unicode edge cases
• Documents invariants — properties serve as executable specifications of expected behavior
• Reduces test maintenance — one property replaces dozens of individual test cases
• Improves code quality — thinking in properties forces you to understand your code’s invariants
• Shrinking — when a test fails, you get the simplest possible reproducer, not a random large input

For mutation testing, property-based tests provide stronger guarantees because they verify invariants rather than specific outputs, making them harder for mutants to survive. See our mutation testing guide for complementary approaches.

If you are already using load testing to validate system behavior under stress (k6 vs Locust vs Gatling), combining property-based testing with load testing gives you both correctness and performance guarantees. For chaos testing, property-based approaches can verify that your system maintains invariants even when components fail (Toxiproxy vs Pumba).

FAQ

What is the difference between example-based and property-based testing?

Example-based testing verifies specific input/output pairs you manually write (e.g., assert add(2, 3) == 5). Property-based testing verifies logical invariants across all valid inputs — the framework generates random inputs and checks that your property holds. Example-based testing checks “this specific case works”; property-based testing checks “the rule is always true.”

When should I use property-based testing?

Property-based testing excels when testing: parsers and serializers, mathematical or financial calculations, data transformations and pipelines, business logic with clear invariants, API request/response validation, and sorting or search algorithms. It is less useful for UI testing, integration tests with external services, or tests where the expected output depends on non-deterministic state.

How many test examples should I generate?

A good starting point is 100 examples for local development and 1,000+ for CI. Hypothesis defaults to 100, Fast-Check to 100, and Proptest to 100. Increase the count for critical code paths or when you discover new edge cases. The diminishing returns typically appear around 1,000-10,000 examples.

What is shrinking and why does it matter?

When a property-based test fails, shrinking is the process of finding the minimal input that still triggers the failure. Instead of reporting “failed with input: [92837, -48291, 0, 77]”, the framework might shrink it to “failed with input: [0, 0]”. This makes debugging dramatically easier because you immediately see the core issue.

Can I use property-based testing with existing unit tests?

Yes. Property-based testing is complementary to, not a replacement for, example-based testing. Keep your critical regression tests as examples (they document known bugs and their fixes). Add property-based tests for invariants and edge case coverage. Both approaches together provide stronger test coverage than either alone.

Does property-based testing replace code coverage tools?

No. Property-based testing and code coverage serve different purposes. Coverage tools tell you which lines of code your tests execute. Property-based testing tells you whether your code’s logical invariants hold across many inputs. Use both: property tests for correctness guarantees, coverage analysis for identifying untested code paths.