Defines input range
DevOps & Tooling / Knowledge library
Hypothesis
generated examples shrinking and invariant checks
Why learn Hypothesis?
Useful for finding edge cases beyond hand-written examples. The properties and input strategies must describe meaningful valid behavior.
Where it came from
Hypothesis tests Python programs using generated examples derived from strategies. It searches for counterexamples and simplifies failures to aid diagnosis.
Build your understanding
Work through these exercises in order. Try the task before opening a reference.
- State an invariant for a pure function.
- Generate inputs using a suitable strategy.
- Observe a reduced counterexample for a broken implementation.
- Add a regression example for a known bug.
- Avoid excessive filtering by constructing valid inputs directly.
Documentation and sources
- Official project documentation (hypothesis.readthedocs.io)
Catalog research notes
- Research snapshot: September 9, 2026. This entry summarizes the linked primary documentation; it does not assert a latest release version.
Connect the ideas
Built on
Explore next
Real World Example
Automated Currency Exchange Rate Validation
A global fintech firm managing multi-currency ledger reconciliations.
The business problem
Manual unit tests fail to capture extreme volatility or edge-case rounding errors in currency conversion logic, leading to intermittent ledger imbalances that are difficult to reproduce.
How this topic solves it
Utilizing Hypothesis to perform property-based testing, we define invariants—such as the requirement that a conversion followed by its inverse must return the original amount within a tiny epsilon—and allow the library to generate thousands of randomized exchange rate inputs to identify the specific values that trigger rounding failures.
- Define a strategy to generate valid currency pairs and floating-point exchange rates.
- Implement a test function that asserts the invariant property of reversible conversion.
- Use the @given decorator to inject randomized inputs into the test logic.
- Allow Hypothesis to shrink failing inputs to the smallest possible counter-example.
- Integrate the discovered edge cases into the permanent regression test suite.
This flow illustrates how Hypothesis transforms random inputs into verified system invariants.
Generates random data
Validates business logic
Reduces failure case
Final edge case
- Strategy → provides constraints → Hypothesis Engine
- Hypothesis Engine → executes test → Test Invariant
- Test Invariant → triggers on failure → Shrinker
- Shrinker → outputs minimal input → Report
Implementation example
This code maps to the scenario by using the @given decorator to feed random exchange rates into a test that asserts the mathematical invariant of reversible conversion.
from hypothesis import given, strategies as st
@given(st.floats(min_value=0.01, max_value=1000.0))
def test_conversion_invariant(rate):
# Verify that conversion is reversible within precision
original = 100.0
converted = original * rate
assert abs(original - (converted / rate)) < 1e-9Expected business outcome
The system achieves higher reliability by automatically uncovering obscure floating-point precision errors that human testers would likely overlook during standard development cycles.
Limitations and checks
The primary limitation is test execution time; as the complexity of the input strategy increases, the number of generated examples can grow significantly, requiring developers to monitor health checks to ensure tests remain performant.