- Home
- Property-Based Testing Tools
- Hypothesis
Hypothesis
What it is
Hypothesis is a free property-based testing library for Python. You describe behaviors your code should satisfy, and it generates inputs—including edge cases—to check those properties. Its strategies let you define and combine the kinds of data tests should use. When it detects a failure, Hypothesis reports an example and tries to simplify it; failing examples are saved in a local database so they can be replayed in later test runs. Tests run as regular Python functions inside pytest, unittest, nose, or another framework that can run a Python function. Hypothesis is not itself a test runner. Rule-based state machines can generate operation sequences for checking stateful systems and objects. By default, it generates 100 random inputs per test, a count that can be changed with max_examples. The project says it works on Linux, macOS, Windows, and Emscripten, and supports CPython and PyPy 3.10 and later. The project supports only the most recent Hypothesis version; undocumented behavior may change in patch releases.
For and against
For
- Generates inputs, including edge cases.
- Simplifies failing examples.
- Stores failures for replay in later runs.
- Supports stateful testing with rule-based state machines.
- Works with pytest and unittest.
Against
- It is not a test runner.
- Supports only the most recent Hypothesis version.
- Undocumented behavior may change in patch releases.
The verdict
Hypothesis adds generated-input testing to a Python test suite and helps retain and reduce failures for follow-up. Users need a separate test framework to run their tests.
Who it suits
Hypothesis suits Python developers who want tests to explore generated inputs and edge cases rather than relying only on examples they choose themselves. It fits teams already using a framework that runs Python functions.
On the record
- Community help
- Users can ask questions using the python-hypothesis Stack Overflow tag or join the mailing list for help and discussion.hypothesis.readthedocs.io · read 29 Sep 2026
- Compatibility limit
- The project supports only the most recent Hypothesis version; documented APIs are not expected to break except between major version bumps, while undocumented behavior may break in patch releases.hypothesis.readthedocs.io · read 29 Sep 2026
- Data generation
- Its strategies let users describe and compose the kinds of data their tests should generate.hypothesis.works · read 28 Sep 2026
- Default run count
- By default, Hypothesis generates 100 random inputs per test, and this count can be controlled with the max_examples setting.hypothesis.readthedocs.io · read 29 Sep 2026
- Development model
- The maintainers say new features must be sponsored or implemented by someone else, and the project has no long-term release plan.hypothesis.readthedocs.io · read 29 Sep 2026
- Edge cases
- Hypothesis randomly chooses inputs, including edge cases the user may not have considered.hypothesis.works · read 29 Sep 2026
- Integrations
- First-party extras include integrations for specific packages, and the documentation gives Django as an example installable extra.hypothesis.readthedocs.io · read 29 Sep 2026
- Intended users
- Hypothesis is for people writing software tests who want to describe acceptable behavior and have the computer explore inputs.hypothesis.works · read 28 Sep 2026
- Operating systems
- The project says it is known to work and regularly tested on macOS, Windows, Linux, and Emscripten.hypothesis.readthedocs.io · read 29 Sep 2026
- Python support
- Hypothesis is supported and tested on CPython and PyPy 3.10 and later.hypothesis.readthedocs.io · read 29 Sep 2026
- Release availability
- The project describes publishing new packages to PyPI after changes are merged, usually within half an hour.hypothesis.works · read 28 Sep 2026
- Repeatable failures
- Hypothesis saves failing examples in a local test database so it can replay them when tests run again.hypothesis.works · read 28 Sep 2026
- Simplifies failures
- When Hypothesis finds a bug, it reports the simplest possible failing example.hypothesis.works · read 29 Sep 2026
- Stateful testing
- Rule-based state machines let Hypothesis generate sequences of operations to test stateful systems and objects.hypothesis.works · read 28 Sep 2026
- Test framework support
- Hypothesis works with pytest, unittest, nose, or another framework that can run a Python function.hypothesis.works · read 28 Sep 2026
- Test runner limitation
- Hypothesis is not itself a test runner; it works inside a user's normal testing framework.hypothesis.works · read 28 Sep 2026
- Test runners
- Hypothesis tests can run as regular Python functions and work with pytest or unittest.hypothesis.readthedocs.io · read 29 Sep 2026
- Thread safety
- As of version 6.136.9, Hypothesis supports running the same test simultaneously from multiple threads.hypothesis.works · read 28 Sep 2026
