hypothesis

hypothesis Best Practices

Hypothesis is a powerful property-based testing library. These guidelines ensure your Hypothesis tests are effective, maintainable, and integrate seamlessly into modern Python development workflows.

1. Code Organization and Structure

Always integrate Hypothesis with pytest. Keep test files in a dedicated tests/ directory, mirroring your src/ structure. Adhere to PEP 8, use clear docstrings, and apply type hints.

❌ BAD: Generic test function names, no st alias, mixed with application code.

# my_app/utils.py
from hypothesis import given, strategies
def add(a, b): return a + b

@given(strategies.integers(), strategies.integers())
def test_add(a, b):
    assert add(a, b) == a + b

✅ GOOD: Dedicated test files, st alias, clear naming, pytest integration.

# src/my_app/utils.py
def add(a: int, b: int) -> int:
    """Adds two numbers."""
    return a + b

# tests/test_utils.py
from hypothesis import given, strategies as st
import pytest
from src.my_app.utils import add

@given(st.integers(), st.integers())
def test_add_is_commutative(a: int, b: int) -> None:
    """Verify addition is commutative."""
    assert add(a, b) == add(b, a)

@given(st.integers())
def test_add_identity_element(a: int) -> None:
    """Verify zero is the identity element for addition."""
    assert add(a, 0) == a

2. Strategy Selection and Constraints

Always use the most specific and constrained strategies possible. This improves performance and focuses generated examples on relevant edge cases. Use st.composite for dependent generation.

❌ BAD: Overly broad strategies or excessive filtering with assume() for basic constraints.

@given(st.integers(), st.integers())
def test_division(numerator, denominator):
    assume(denominator != 0) # Discards many examples
    assume(numerator % denominator == 0) # Discards even more
    assert numerator / denominator == numerator // denominator

✅ GOOD: Constrain strategies directly. Use st.composite for dependent values.

from hypothesis import given, strategies as st, assume
from hypothesis.extra.math import non_zero_floats
from typing import Tuple

@given(st.integers(), st.integers(min_value=1, max_value=100))
def test_division_positive_divisor(numerator: int, divisor: int) -> None:
    """Test integer division with a positive divisor."""
    assert (numerator // divisor) * divisor + (numerator % divisor) == numerator

@st.composite
def non_zero_pairs(draw) -> Tuple[int, int]:
    """Generates a pair of integers where the second is non-zero."""
    numerator = draw(st.integers())
    denominator = draw(st.integers().filter(lambda d: d != 0))
    return numerator, denominator

@given(non_zero_pairs())
def test_division_any_non_zero(pair: Tuple[int, int]) -> None:
    """Test division property with any non-zero denominator."""
    numerator, denominator = pair
    # Property: (q * d) + r = n, where 0 <= abs(r) < abs(d)
    quotient = numerator // denominator
    remainder = numerator % denominator
    assert (quotient * denominator) + remainder == numerator
    assert abs(remainder) < abs(denominator)