Hypothesis

Overview

Hypothesis is for Python developers who want tests to explore inputs beyond a hand-picked set of examples. Its generated cases, failure simplification and replay make property-based testing practical within a familiar test framework.

It is a focused testing library, not a complete testing environment: you still need a runner and must describe the behavior your code should satisfy.

Key features

Strategies and generated cases

Strategies define and compose the data a test can receive, letting you check a stated property against varied inputs, including edge cases. Hypothesis generates 100 random inputs per test by default; the max_examples setting lets you control that count. This gives a test broader reach than a fixed example set, though the cases depend on the properties and data you choose to describe.

Failures you can investigate and replay

When a generated input exposes a bug, Hypothesis reports it and tries to simplify the failing example. That can make an unexpected failure easier to diagnose than a complex input you assembled by hand. It also saves failing examples in a local test database and replays them on later runs, helping prevent a discovered problem from disappearing into a one-off run.

Framework and stateful testing

Hypothesis tests are ordinary Python functions, so they can run under pytest, unittest, nose or another framework that runs Python functions. First-party extras integrate with particular packages; Django is one example. For systems whose behavior depends on operation order, rule-based state machines generate sequences of operations against stateful objects. Hypothesis itself is not a runner, so it fits teams that already have a Python test setup rather than those seeking an all-in-one testing tool.

As of version 6.136.9, the same test can run simultaneously from multiple threads. The project says it regularly tests compatibility with CPython and PyPy 3.10 and later. It supports macOS, Windows, Linux and Emscripten, although the listed platforms for this entry are Linux, macOS and Windows.

Pricing

Hypothesis is free, with a free plan and no paid tier described. That makes it straightforward to adopt for individual developers or teams, but the project’s development model is not a promise of a long-term release schedule: maintainers say new features need sponsorship or implementation by someone else, and there is no long-term release plan.

New packages are published to PyPI after changes are merged, usually within half an hour. The project supports the most recent Hypothesis version; documented APIs are not expected to break except between major version bumps, while undocumented behavior can change in patch releases. Teams relying on undocumented behavior should account for that compatibility boundary.

Platforms

Hypothesis is a Python library for Linux, macOS and Windows. The project also reports regular testing on Emscripten. It is not a cross-language choice: Python is its supported language.

Who it's for

Choose Hypothesis if you write Python tests and want to express acceptable behavior once, then have generated inputs probe it for edge cases. It is especially useful when a system has stateful behavior that can be exercised through sequences of operations, or when preserving and simplifying failures would help your debugging process.

Look elsewhere if you need a test runner rather than a library, or if your codebase uses a language other than Python. Its help channels include the python-hypothesis tag on Stack Overflow and a mailing list.

Pros and cons

• Broader input exploration: Composable strategies and generated cases can expose edge cases absent from manually chosen examples.
• Actionable failures: Shrinking and local replay make generated bugs easier to inspect and keep in the test cycle.
• Fits existing Python tests: Support for common runners means adoption does not require replacing the test framework.
• Requires a runner and property descriptions: Hypothesis does not execute tests on its own, and generated coverage depends on the behavior and input strategies you define.
• Python-only, current-version support: Other languages need another tool, and users are expected to use the latest Hypothesis release.

Alternatives

For other language ecosystems, these free property-testing tools may fit better:

• Gopter is a free, MIT-licensed Go property-testing library for Linux and self-hosted use; choose it for Go rather than Python.
• RapidCheck is a free alternative for Linux, self-hosted and Windows platforms.
• fast-check is a free, MIT-licensed JavaScript/TypeScript project for API, Linux and web platforms; choose it for those languages instead of Python.
• Proptest is a free alternative listed for web use.
• QuickCheck is a free Haskell library for random testing of program properties on Linux; it is the language-specific choice for Haskell.
• Rapid is a free, open-source Go library with no dependencies outside Go’s standard library, for self-hosted use.
• SwiftCheck is a free option for macOS and iOS.
• CsCheck is another free alternative.

Browse the Property-Based Testing Tools list for more options.

Verdict

Hypothesis is a strong fit for Python developers who want tests to discover, simplify and preserve surprising inputs without changing their runner. Its biggest advantage is that complete cycle from generated case to replayable failure; its main limitation is the same focus that makes it effective: it is a Python testing library, not a runner or a cross-language solution.