Hypothesis

6.151.10 · active · verified Sun Mar 29

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.

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

pip install hypothesis Install stable version

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

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()

view raw JSON →