Hypothesis

Visit Website

Introduction

Hypothesis is the property-based testing library for Python. Instead of writing individual examples, you write tests that should pass for all inputs in a range you describe, and Hypothesis chooses which inputs to try, including edge cases you might not have thought about.

Its README shows the core idea with a sorting example: a test asserts that sorted(ls) == my_sort(ls) for any list of integers. When my_sort is implemented as sorted(set(ls)), Hypothesis does not just report a random failing list; it shrinks the input and reports the simplest failing case, ls=[0, 0]. That shrinking is what makes property-based tests useful for debugging as well as testing.

Hypothesis integrates with pytest and unittest, stores failing examples in a local database so they are replayed on the next run, and provides strategies for built-in types, dates, text, data frames (via extras) and your own classes. It also supports stateful testing, where Hypothesis generates sequences of operations against a model of your system.

The library is licensed under the Mozilla Public License 2.0 and released very frequently; version 6.170.15 was published on 6 November 2026. In the quality loop, it strengthens unit tests for parsers, serialisers, algorithms and business rules.

The source code is at HypothesisWorks/hypothesis on GitHub under the MPL-2.0 licence, with about 9,200 stars; the most recent commit was on 8 November 2026.

How it compares: property-based testing started with QuickCheck for Haskell, and most languages now have a port. Hypothesis is notable for its shrinking approach, which works on the underlying choice sequence rather than requiring a hand-written shrinker per type, so custom strategies shrink well automatically. That design has influenced libraries in other ecosystems. Compared with example-based pytest tests, Hypothesis tests are fewer but broader; many teams keep both, using examples to document expected behaviour and properties to search for the unexpected. Hypothesis also offers a ghostwriter command that drafts property tests for existing functions, which is a useful starting point when adopting it on an older codebase.

Health checks are another practical detail: Hypothesis warns when a strategy filters out too many examples or when data generation is unusually slow, which helps you write efficient strategies instead of silently testing very little.

Features

1. Strategies: hypothesis.strategies generates integers, floats, text, lists, dictionaries, dates, UUIDs and more, and composes them with builds, composite, map and filter.
2. Shrinking: Failing inputs are reduced to a minimal example that is easy to understand and reproduce.
3. Example database: Failing examples are saved locally and replayed first on later runs, so a found bug is not lost.
4. pytest integration: @given works with pytest fixtures, parametrisation and plugins.
5. Settings and profiles: Control the number of examples, deadlines and health checks, with separate profiles for local and CI runs.
6. Stateful testing: Rule-based state machines generate sequences of actions to test APIs and data structures with internal state.
7. Explicit examples: @example(...) pins important cases so they always run alongside generated ones.
8. Extras: Optional strategies for libraries such as NumPy, pandas and Django, listed in the docs.

Pros

1. Finds real edge cases: Empty lists, duplicates, Unicode, NaN and boundary values come up naturally.
2. Free to use: Open source under the MPL-2.0 licence, so the core tool costs nothing to use.
3. Actively maintained: The repository had commits as recent as 8 November 2026.
4. Community: About 9,200 GitHub stars.

Cons

1. Thinking in properties: Writing good properties (round trips, invariants, model comparisons) takes practice.
2. Slower than example tests: Each test runs many examples; deadlines and example counts need tuning for big suites.
3. Flaky external dependencies: Tests that hit networks or clocks interact poorly with repeated generation.
4. Python only: Other languages need their own libraries, such as fast-check, jqwik or proptest.

Usage and Links (Example)

Install and write a property test with pytest:

pip install hypothesis

from hypothesis import given, strategies as st
import json

@given(st.dictionaries(st.text(), st.integers()))
def test_json_round_trip(d):
    assert json.loads(json.dumps(d)) == d

Pin a known edge case and tune settings:

from hypothesis import example, settings

@settings(max_examples=500)
@given(st.text())
@example("")
def test_slugify_is_idempotent(s):
    assert slugify(slugify(s)) == slugify(s)

Register a faster profile for pull requests and a deeper one for nightly runs:

from hypothesis import settings
settings.register_profile("ci", max_examples=200)
settings.register_profile("nightly", max_examples=5000)

Practical tips:

1. Start with round-trip properties (encode/decode, serialise/parse); they are easy and catch many bugs.
2. Compare against a simple reference implementation when optimising code.
3. Commit the shrunk failing case as an @example once fixed, so it stays covered.

Resources:

• Hypothesis website
• GitHub repository
• Documentation

Pricing

Hypothesis is free and open source under the MPL-2.0 licence.

Recommended for?

1. Python developers testing parsers, serialisers, algorithms and validation logic.
2. Library maintainers who want broader input coverage than hand-picked examples.
3. Teams with tricky state, using stateful testing to explore sequences of operations.
4. Not a fit for tests dominated by slow external systems.

Conclusion

Hypothesis brings mature property-based testing to Python, with excellent shrinking, a replay database and tight pytest integration.

A handful of well-chosen properties often finds bugs that hundreds of example tests miss, which makes it one of the highest-value additions to a Python test suite.