Hypothesis generates test cases automatically to find edge cases in Python code. pip install hypothesis. from hypothesis import given, settings, assume, example. from hypothesis import strategies as st. Basic: @given(st.integers()) def test_abs(n): assert abs(n) >= 0. Text: @given(st.text()) def test_round_trip(s):. Lists: @given(st.lists(st.integers(), min_size=1)). Floats: @given(st.floats(allow_nan=False, allow_infinity=False)). Dicts: @given(st.dictionaries(st.text(), st.integers())). Assume: assume(n != 0) — skip invalid inputs. Example: @example(0) @example(-1) @given(st.integers()) — always test specifics. Settings: @settings(max_examples=1000, deadline=None). Profile: settings.register_profile("ci", max_examples=1000). Composite: @st.composite def user(draw): name = draw(st.text(min_size=1)). One of: st.one_of(st.none(), st.integers()). Builds: st.builds(User, name=st.text(), age=st.integers(0,120)). From type: st.from_type(MyClass). Sampled: st.sampled_from(["a","b","c"]). Fixed dicts: st.fixed_dictionaries({"key": st.integers()}). Recursive: st.recursive(st.integers(), lambda c: st.lists(c)). st.from_regex(r"\d{4}-\d{2}-\d{2}"). Numpy: from hypothesis.extra.numpy import arrays, arrays(dtype=np.float64, shape=(5,5)). Pandas: from hypothesis.extra.pandas import data_frames, column. Find: hypothesis.find(st.integers(), lambda x: x > 100). Shrink: Hypothesis automatically shrinks failing examples to minimal case. DB: failures saved to .hypothesis/ directory for re-run. Claude Code generates Hypothesis property tests for data structures, serialization round-trips, and API invariants.
CLAUDE.md for Hypothesis
## Hypothesis Stack
- Version: hypothesis >= 6.100
- Decorator: @given(st.type()) | @settings(max_examples=N, deadline=None)
- Filter: assume(condition) — skip inputs that violate preconditions
- Edge cases: @example(value) — always test specific inputs
- Compose: @st.composite def strategy(draw): ... — build complex inputs
- Numpy: hypothesis.extra.numpy.arrays(dtype, shape)
- Pandas: hypothesis.extra.pandas.data_frames([column(...)])
- Shrink: failing cases auto-minimize to smallest reproducerHypothesis Property-Based Testing Pipeline
# tests/hypothesis_pipeline.py — property-based testing with Hypothesis
from __future__ import annotations
import json
import math
import re
from collections import Counter
from typing import Any
import pytest
from hypothesis import assume, example, given, settings, HealthCheck
from hypothesis import strategies as st
from hypothesis.stateful import Bundle, RuleBasedStateMachine, initialize, rule
# ── 0. Simple property tests ─────────────────────────────────────────────────
class TestArithmetic:
"""Basic numeric invariants."""
@given(st.integers())
def test_abs_non_negative(self, n: int):
assert abs(n) >= 0
@given(st.integers(), st.integers())
def test_addition_commutative(self, a: int, b: int):
assert a + b == b + a
@given(st.integers(), st.integers(), st.integers())
def test_addition_associative(self, a: int, b: int, c: int):
assert (a + b) + c == a + (b + c)
@given(st.floats(allow_nan=False, allow_infinity=False))
def test_abs_idempotent(self, x: float):
assert abs(abs(x)) == abs(x)
@given(st.integers(), st.integers(min_value=1))
def test_divmod_invariant(self, n: int, d: int):
q, r = divmod(n, d)
assert q * d + r == n
assert 0 <= r < d
class TestStrings:
"""String operation invariants."""
@given(st.text())
def test_len_non_negative(self, s: str):
assert len(s) >= 0
@given(st.text())
def test_upper_lower_round_trip(self, s: str):
# lower(upper(lower(s))) == lower(s) — not always true for upper/lower
# but this holds: len doesn't change
assert len(s.upper()) == len(s)
assert len(s.lower()) == len(s)
@given(st.text(), st.text())
def test_concatenation_length(self, a: str, b: str):
assert len(a + b) == len(a) + len(b)
@given(st.text(min_size=1))
def test_split_join_round_trip(self, s: str):
# Splitting on a char not in s and joining gives back the original
delimiter = chr(0) # null byte — rarely in test strings
assume(delimiter not in s)
parts = s.split(delimiter)
assert delimiter.join(parts) == s
# ── 1. Serialization round-trips ──────────────────────────────────────────────
class TestJSONRoundTrip:
"""JSON serialization is an identity function on JSON-compatible types."""
@given(
st.recursive(
st.one_of(
st.none(), st.booleans(),
st.integers(-2**53, 2**53), # JSON int range
st.floats(allow_nan=False, allow_infinity=False, min_value=-1e15, max_value=1e15),
st.text(),
),
lambda children: st.one_of(
st.lists(children, max_size=5),
st.dictionaries(st.text(min_size=1, max_size=20), children, max_size=5),
),
max_leaves=10,
)
)
@settings(max_examples=500, suppress_health_check=[HealthCheck.too_slow])
def test_json_round_trip(self, obj: Any):
"""json.loads(json.dumps(obj)) is identity for JSON-compatible values."""
serialized = json.dumps(obj)
deserialized = json.loads(serialized)
assert deserialized == obj
# ── 2. Custom strategies ──────────────────────────────────────────────────────
@st.composite
def email_strategy(draw) -> str:
"""Generate plausible email address strings."""
local = draw(st.text(alphabet=st.characters(whitelist_categories=("Ll",)), min_size=1, max_size=20))
domain = draw(st.text(alphabet=st.characters(whitelist_categories=("Ll",)), min_size=2, max_size=15))
tld = draw(st.sampled_from(["com", "org", "net", "io", "dev"]))
return f"{local}@{domain}.{tld}"
@st.composite
def bounded_list_strategy(draw, element_strategy=None, min_sum=0, max_sum=1000):
"""Generate a list whose sum lies within [min_sum, max_sum]."""
n = draw(st.integers(min_value=1, max_value=20))
elems = draw(st.lists(
element_strategy or st.integers(0, max_sum),
min_size=n, max_size=n,
))
assume(min_sum <= sum(elems) <= max_sum)
return elems
@st.composite
def sorted_list_strategy(draw):
"""Generate a non-empty sorted list of integers."""
lst = draw(st.lists(st.integers(min_value=-1000, max_value=1000), min_size=1))
return sorted(lst)
@st.composite
def user_dict_strategy(draw) -> dict:
"""Generate a user dict with realistic fields."""
return {
"id": draw(st.integers(min_value=1, max_value=10**9)),
"name": draw(st.text(min_size=1, max_size=100)),
"email": draw(email_strategy()),
"age": draw(st.integers(min_value=0, max_value=150)),
"active": draw(st.booleans()),
"score": draw(st.floats(min_value=0.0, max_value=1.0, allow_nan=False)),
}
# ── 3. Algorithm invariants ───────────────────────────────────────────────────
class TestSortingInvariants:
"""Properties every sorting algorithm must satisfy."""
@given(st.lists(st.integers()))
def test_sort_is_permutation(self, lst: list):
"""Sorted list is a permutation of the original."""
assert Counter(sorted(lst)) == Counter(lst)
@given(st.lists(st.integers()))
def test_sort_is_ordered(self, lst: list):
"""Sorted list is non-decreasing."""
s = sorted(lst)
assert all(s[i] <= s[i+1] for i in range(len(s) - 1))
@given(st.lists(st.integers()))
def test_sort_idempotent(self, lst: list):
"""Sorting a sorted list gives the same result."""
once = sorted(lst)
twice = sorted(once)
assert once == twice
@given(st.lists(st.integers(), min_size=1))
def test_min_max(self, lst: list):
"""min and max are elements of the list."""
assert min(lst) in lst
assert max(lst) in lst
class TestBinarySearch:
"""Verify a binary search implementation."""
@staticmethod
def binary_search(arr: list[int], target: int) -> int:
lo, hi = 0, len(arr) - 1
while lo <= hi:
mid = (lo + hi) // 2
if arr[mid] == target:
return mid
elif arr[mid] < target:
lo = mid + 1
else:
hi = mid - 1
return -1
@given(sorted_list_strategy(), st.integers(-1000, 1000))
def test_found_is_correct(self, arr: list, target: int):
"""If binary_search returns i ≥ 0, arr[i] == target."""
idx = self.binary_search(arr, target)
if idx >= 0:
assert arr[idx] == target
@given(sorted_list_strategy(), st.integers(-1000, 1000))
def test_not_found_means_absent(self, arr: list, target: int):
"""If binary_search returns -1, target is not in arr."""
idx = self.binary_search(arr, target)
if idx == -1:
assert target not in arr
# ── 4. Stateful testing ───────────────────────────────────────────────────────
class BoundedStackMachine(RuleBasedStateMachine):
"""
Stateful test for a bounded stack.
Hypothesis generates sequences of operations and checks invariants after each.
"""
def __init__(self):
super().__init__()
self.stack = []
self.max_size = 5
@initialize(value=st.integers())
def init_with(self, value: int):
"""Start from a non-empty state."""
self.stack = [value]
@rule(value=st.integers())
def push(self, value: int):
if len(self.stack) < self.max_size:
self.stack.append(value)
@rule()
def pop(self):
if self.stack:
self.stack.pop()
def invariant(self):
assert 0 <= len(self.stack) <= self.max_size
BoundedStackTest = BoundedStackMachine.TestCase
# ── 5. API contract tests ─────────────────────────────────────────────────────
def normalize_user(user: dict) -> dict:
"""Example function under test: normalize a user dict."""
return {
"id": int(user["id"]),
"name": str(user["name"]).strip().title(),
"email": str(user["email"]).lower(),
"active": bool(user.get("active", True)),
"score": max(0.0, min(1.0, float(user.get("score", 0.0)))),
}
class TestNormalizeUser:
@given(user_dict_strategy())
def test_output_schema(self, user: dict):
"""normalize_user always returns a dict with the expected keys and types."""
result = normalize_user(user)
assert isinstance(result["id"], int)
assert isinstance(result["name"], str)
assert isinstance(result["email"], str)
assert isinstance(result["active"], bool)
assert isinstance(result["score"], float)
@given(user_dict_strategy())
def test_score_clamped(self, user: dict):
"""score is always in [0, 1] after normalization."""
result = normalize_user(user)
assert 0.0 <= result["score"] <= 1.0
@given(user_dict_strategy())
def test_idempotent(self, user: dict):
"""Normalizing twice gives the same result as once."""
once = normalize_user(user)
twice = normalize_user(once)
assert once == twice
@given(user_dict_strategy())
def test_email_lowercase(self, user: dict):
"""Normalized email is always lowercase."""
result = normalize_user(user)
assert result["email"] == result["email"].lower()
@example({"id": 0, "name": " alice ", "email": "[email protected]",
"active": True, "score": 1.5})
@given(user_dict_strategy())
def test_name_stripped(self, user: dict):
"""Normalized name has no leading/trailing whitespace."""
result = normalize_user(user)
assert result["name"] == result["name"].strip()
# ── Demo ──────────────────────────────────────────────────────────────────────
if __name__ == "__main__":
print("Hypothesis Property-Based Testing Demo")
print("=" * 50)
print("\nRun with pytest to execute all property tests:")
print(" pytest tests/hypothesis_pipeline.py -v")
print("\nKey patterns demonstrated:")
print(" @given(st.integers()) — numeric invariants")
print(" @given(st.recursive(...)) — JSON round-trip with nested types")
print(" @st.composite — custom email/user strategies")
print(" @given(sorted_list_strategy()) — algorithm invariants (binary search)")
print(" RuleBasedStateMachine — stateful bounded stack")
print(" user_dict_strategy() — API contract testing")
print("\nHypothesis saves failing examples to .hypothesis/ for re-run.")For the unittest / pytest with hand-crafted test cases alternative — writing parametrize cases by hand tests the examples the developer thought of while Hypothesis generates thousands of cases including boundary conditions, empty strings, max integers, NaN, and surrogate Unicode characters that humans miss, then automatically shrinks a failing 100-element list to the minimal 2-element counterexample, giving a concrete regression test that is then saved in .hypothesis/ for future runs. For the faker library alternative — Faker generates realistic-looking test data for UI screenshots and smoke tests but makes no guarantees about invariants while Hypothesis systematically searches the input space for inputs that violate a property, and @st.composite builds domain-specific strategies (sorted lists, valid users, bounded graphs) that can be reused across any test that needs the same type, so a user_dict_strategy used in 20 tests will surface a common edge case once and fix it everywhere. The Claude Skills 360 bundle includes Hypothesis skill sets covering @given with all primitive strategies, @settings max_examples and deadline, assume for precondition filtering, @example for explicit edge cases, @st.composite strategy builders, st.recursive for nested data, JSON round-trip tests, sorting algorithm invariants, binary search proofs, RuleBasedStateMachine stateful testing, and API contract properties. Start with the free tier to try property-based testing code generation.