Hypothesis Cheat Sheet

1Install & @given6.x

pip install hypothesis★
Add hypothesis[numpy,pandas] for array/DataFrame strategies.
from hypothesis import given, strategies as st★
The two imports you always need: the @given decorator and the strategies module (st).
@given(st.lists(st.integers())) def test_sort_idempotent(xs): assert sorted(sorted(xs)) == sorted(xs)★
Each @given arg maps to a test parameter. Hypothesis runs the body against ~100 generated xs by default.
pytest test_x.py # just a normal pytest run
No special runner — @given tests are collected & run by pytest/unittest. Failures print the minimal counterexample.

2Thinking in propertieswhat to assert

# round-trip: decode(encode(x)) == x★
The most productive pattern — serialize/parse, compress/decompress, to/from JSON.
# invariant: len(dedupe(xs)) <= len(xs); result is sorted★
Properties that must always hold regardless of input (bounds, ordering, type).
# oracle: my_fast_fn(x) == reference_slow_fn(x)★
Compare against a known-correct (if slow) implementation — great for optimizations.
# metamorphic: f(x)+f(y) == f(x+y) (relationships between outputs)
When you can't compute the exact answer, assert relationships that must hold.

3Built-in strategiesst.*

st.integers(min_value=0, max_value=100) · st.floats(allow_nan=False)★
Numbers with bounds/constraints. allow_nan/allow_infinity matter — NaN breaks most equality assertions.
st.text() · st.characters() · st.binary() · st.booleans() · st.none()★
Text is Unicode-heavy by default (emoji, control chars) — that's the point; it finds encoding bugs.
st.lists(st.integers(), min_size=1, max_size=10, unique=True)★
Collections: lists, sets, dictionaries(keys, values), tuples(a, b), fixed_dictionaries({...}).
st.sampled_from(["a","b"]) · st.from_regex(r"\d{3}-\d{4}") · st.datetimes()★
Pick from a set, match a regex, or generate dates/times/UUIDs/IPs. st.from_type(int) infers from a type hint.

4Composing strategiesbuild complex data

st.integers().map(lambda x: x * 2) # transform outputs★
.map transforms generated values; .filter(pred) keeps only some (use sparingly — see gotchas).
st.one_of(st.integers(), st.none()) # or: st.integers() | st.none()★
Union of strategies — "an int or None". The | operator is shorthand.
st.builds(User, name=st.text(), age=st.integers(0, 120))★
Construct objects by drawing constructor args — the clean way to generate your domain classes.
@st.composite def pairs(draw): x = draw(st.integers()); return (x, x+1)★
For custom generation logic: draw() pulls from other strategies. .flatmap for strategies that depend on earlier draws.

7Stateful testingsequences of actions

from hypothesis.stateful import RuleBasedStateMachine, rule, invariant★
Test stateful systems (a data structure, an API) by generating random sequences of operations, not just single inputs.
class QueueTest(RuleBasedStateMachine): @rule(x=st.integers()) def push(self, x): self.q.append(x)★
@rule methods are the operations Hypothesis chains together in random orders.
@invariant() def not_negative(self): assert len(self.q) >= 0★
@invariant checks a condition after every step. Expose the machine with TestQueue = QueueTest.TestCase.

8NumPy / pandas extrasarray data

from hypothesis.extra.numpy import arrays arrays(dtype="float64", shape=(3, 3))★
Generate NumPy arrays of a dtype/shape — property-test numeric code. array_shapes(), floating_dtypes() too.
from hypothesis.extra.pandas import data_frames, column
Generate DataFrames/Series with typed columns for data-pipeline tests.
st.data() # draw interactively inside the test body
data.draw(strategy) for cases where the next value depends on earlier logic in the test.

!Common gotchasread before shipping

don't over-filter
Heavy .filter()/assume() that rejects most inputs is slow and can raise "unsatisfied" — generate the right shape directly (map/composite) instead.
deadline on slow tests
Hypothesis flags a test that suddenly runs slow as flaky. For genuinely slow code set deadline=None.
no @given with function-scoped fixtures
A pytest fixture runs once per test, but @given runs the body many times — don't rely on per-example fixture setup; build state inside the test.
floats include NaN/inf
st.floats() generates NaN & infinities by default — they break ==. Constrain with allow_nan=False, allow_infinity=False.
failures are saved & replayed
Hypothesis caches counterexamples in .hypothesis/ — a fixed bug re-tests the exact input. Commit or clear this DB deliberately.

Hypothesis cheat sheet