pytest-hypothesis

10.0.3 · active · verified Fri Apr 10

pytest-hypothesis is a bridge for using the Hypothesis property-based testing library with the pytest test framework. It enables developers to write tests that automatically generate varied inputs, helping to discover edge cases and subtle bugs in their code. While the `pytest-hypothesis` PyPI package is a legacy wrapper, its core functionality for pytest integration is now built directly into the main Hypothesis library (version 6.0.0 and later). It is actively maintained as part of Hypothesis, with a continuous release cadence.

Warnings

deprecated The standalone `pytest-hypothesis` PyPI package is deprecated. Its functionality is now integrated directly into the core `Hypothesis` library (version 6.0.0 and newer). You no longer need to install `pytest-hypothesis` separately.
Fix: Remove `pytest-hypothesis` from your project's dependencies and ensure you have `hypothesis` installed. The integration works automatically.
gotcha `pytest` function-scoped fixtures (e.g., `@pytest.fixture(scope='function')`) will run only once for the entire Hypothesis test function, not once for each generated example. This can lead to unexpected state issues if your fixture is meant to reset state per example (e.g., database transactions).
Fix: Manually manage state resets within the test function (e.g., using context managers or explicit setup/teardown in the test body) or use broader fixture scopes (e.g., `module`, `session`) if appropriate, and ensure test examples are isolated.
gotcha Hypothesis tests can report 'Flaky: Inconsistent test results!' if the test's outcome depends on external state or non-deterministic factors that are not reset between examples. This often indicates a lack of proper test isolation.
Fix: Ensure your test environment and any stateful resources (e.g., databases, files) are properly cleaned up and reset before each Hypothesis example. Use fixtures with appropriate scope or explicit setup/teardown.
gotcha Hypothesis test functions decorated with `@given` should not return any value other than `None`. Returning a value will cause Hypothesis to error, and `pytest` itself will also raise a warning or error for non-None return values from test functions.
Fix: Ensure that `test_` functions using `@given` do not explicitly return any value.
gotcha When defining strategies, if certain generated inputs are invalid for your test's logic but are valid according to the strategy, use `hypothesis.assume()` to filter them out. Using `assert False` for filtering will be reported as a test failure, not a discarded example, and prevents Hypothesis from finding a valid failing example.
Fix: Replace `assert` statements used purely for input filtering with `from hypothesis import assume; assume(condition)`.

Install

pip install hypothesis pytest Install Hypothesis and pytest

Imports

given
```
from hypothesis import given
```
The primary decorator for defining property-based tests.
strategies
```
from hypothesis import strategies as st
```
Used to access built-in data generation strategies (e.g., st.integers(), st.text()).

Quickstart

This quickstart demonstrates how to use `hypothesis.given` decorator with `pytest`. Tests decorated with `@given` will be run multiple times by Hypothesis, with automatically generated inputs adhering to the specified strategies (e.g., `st.integers()`). Run these tests using the `pytest` command line tool.

from hypothesis import given, strategies as st
import pytest

def add(a, b):
    return a + b

@given(st.integers(), st.integers())
def test_add_integers(a, b):
    """Test that addition is commutative and associative for integers."""
    assert add(a, b) == a + b
    assert add(a, b) == add(b, a) # Commutativity
    # Run this file with `pytest -v your_test_file.py`

# Example of using assume() to filter inputs without failing the test
@given(st.integers(min_value=1), st.integers(min_value=1))
def test_division_produces_float_or_int(numerator, denominator):
    # Hypothesis generates pairs, but we might only care about certain conditions
    # For instance, if we only want to test non-zero results, we can use assume
    from hypothesis import assume
    assume(denominator != 0)
    result = numerator / denominator
    assert isinstance(result, (float, int))
    assert numerator == result * denominator

view raw JSON →