Hypothesis

6.151.10 verified Tue May 12 auth: no python install: verified

Hypothesis is the property-based testing library for Python. With Hypothesis, you write tests which should pass for all inputs in whatever range you describe, and let Hypothesis randomly choose which of those inputs to check - including edge cases you might not have thought about. This randomized testing can catch bugs and edge cases that you didn't think of and wouldn't have found. When Hypothesis finds a bug, it reports the simplest possible example. It is currently at version 6.151.10 and receives regular updates.

pip install hypothesis

Common errors

error hypothesis.errors.InvalidArgument: Expected SearchStrategy but got function ↓

cause This error occurs when a strategy function (e.g., `st.integers`) is passed to `@given` or another strategy combinator without being called, meaning the function itself is passed instead of the strategy it returns.

fix

Ensure that all strategy functions are called with parentheses, even if they take no arguments (e.g., use st.integers() instead of st.integers).

error hypothesis.errors.UnsatisfiableExample ↓

cause Hypothesis raises this error when it cannot find enough examples that satisfy the constraints imposed by `assume()` calls, `.filter()` methods, or an overly restrictive strategy definition, indicating that the conditions might be too hard or impossible to meet.

fix

Review your assume() and .filter() conditions to ensure they do not eliminate too many valid examples. Consider if your strategy definition allows for a sufficient range of inputs to satisfy your test's assumptions.

error hypothesis.errors.ResolutionFailed: Could not resolve ... to a strategy ↓

cause This error occurs when Hypothesis attempts to automatically infer a strategy for a type, often in `builds()`, but fails to find a suitable mapping, particularly with custom types or when type annotations are missing or unresolvable.

fix

Explicitly provide a strategy for the type in question using st.builds() or ensure that the type hints are correct and Hypothesis has a registered strategy for that type.

Warnings

breaking Documented APIs only guarantee backward compatibility across major version bumps. Undocumented attributes, modules, and behavior may include breaking changes in patch or minor releases. Always check the changelog for significant updates. ↓

fix Refer to the official documentation and changelog before upgrading major versions or relying on undocumented features. Pin minor versions for stability in production.

deprecated Deprecated features will emit a `HypothesisDeprecationWarning` for at least six months before being removed in a subsequent major release. ↓

fix Pay attention to `HypothesisDeprecationWarning` messages and update your code to use the recommended alternatives to avoid breakage in future major releases.

gotcha Tests must have deterministic outcomes and data generation. If tests involve threads or other non-deterministic elements and data generation depends on timing, Hypothesis may report flaky failures. ↓

fix Refactor data generation to be independent of test timings or other non-deterministic factors. Ensure that a given input always produces the same outcome during the test execution.

gotcha Using overly broad strategies (e.g., `st.text()` without length limits) can lead to extremely slow test runs, high memory consumption, or tests that struggle to find simple counterexamples due to the vast search space. ↓

fix Constrain strategies as much as possible to the domain relevant to your code. For instance, use `st.text(min_size=1, max_size=255, alphabet=string.ascii_letters)` instead of a generic `st.text()`.

gotcha The `.example()` method on strategies is intended for interactive use (e.g., in a REPL) and should not be used within test functions or production code. ↓

fix Always use the `@given` decorator for defining property-based tests. `.example()` is for exploring what a strategy generates, not for testing assertions.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.55s 21.9M

3.10 alpine (musl) - - 0.61s 21.8M

3.10 slim (glibc) wheel 2.3s 0.42s 22M

3.10 slim (glibc) - - 0.39s 22M

3.11 alpine (musl) wheel - 0.77s 24.1M

3.11 alpine (musl) - - 0.82s 24.0M

3.11 slim (glibc) wheel 2.2s 0.68s 25M

3.11 slim (glibc) - - 0.66s 25M

3.12 alpine (musl) wheel - 0.97s 15.8M

3.12 alpine (musl) - - 0.99s 15.7M

3.12 slim (glibc) wheel 1.9s 0.90s 16M

3.12 slim (glibc) - - 0.92s 16M

3.13 alpine (musl) wheel - 0.94s 15.5M

3.13 alpine (musl) - - 1.00s 15.4M

3.13 slim (glibc) wheel 1.9s 0.88s 16M

3.13 slim (glibc) - - 0.99s 16M

3.9 alpine (musl) wheel - 0.61s 21.9M

3.9 alpine (musl) - - 0.60s 21.9M

3.9 slim (glibc) wheel 2.8s 0.53s 22M

3.9 slim (glibc) - - 0.50s 22M

Imports

given
```
from hypothesis import given
```
The primary decorator for property-based tests.
strategies
```
from hypothesis import strategies as st
```
Commonly imported as 'st' for convenience to access built-in strategies.

Quickstart last tested: 2026-04-24

This quickstart demonstrates a basic property-based test using Hypothesis. The `@given` decorator takes a strategy (here, `st.integers()`) and repeatedly calls the decorated test function with generated inputs, looking for counterexamples.

from hypothesis import given, strategies as st

def my_function(x):
    return x + 1

@given(st.integers())
def test_my_function_increments(n):
    assert my_function(n) == n + 1

# To run this, save as a Python file (e.g., example.py) and run with pytest
# For manual execution, uncomment and call the function:
# test_my_function_increments()