9.1k stars · MPL-2.0 · v6.170.2 (2026-10-19) · Track this in Scout
A Python library that generates test inputs and reduces any failure to the smallest example that still fails.
▶Repo detailsthe review · specs · pros & cons · install
What it does
You add one decorator to an existing test function and say what kind of data it takes. Hypothesis then builds examples from that description — integers, text, lists, dates, dictionaries, or combinations you define yourself. It runs your test once per example, by default around a hundred times per test. When a test fails, it starts shrinking: it removes list items, lowers numbers and shortens strings until any further simplification makes the test pass again. It also remembers failures between runs in a local database file, so a case that broke yesterday is tried first today. It plugs into pytest and unittest rather than replacing them, and it can also check that a sequence of method calls on an object never reaches a bad state. It does not test a running website or an API over the network, it does not measure how fast your code is, and it is Python only.
Why it matters
Who it suits. Anyone who writes code that parses, converts or validates data and has no colleague to review it. Encoders, date handling, money arithmetic, anything with string input, anything where the awkward case is the one you did not think of. It fits well where a bug is cheap to find and expensive to ship. Skip it if your code mostly calls other services, because the interesting failures there are in the network and not in the inputs.
Verdict. Worth half an hour, and it is the rare testing tool that pays back on the first afternoon. The thing that makes it worth the time is not the random inputs, it is the shrinking: a failure arrives as a two-character string rather than a six-kilobyte blob, so you can read it. The real cost is thinking clearly about what your function actually accepts, which is work, and it is also most of the benefit. Two meters to set honestly: it will slow your test suite down, because a hundred runs take longer than one. Keep it on the tests where inputs vary and leave your plain examples alone. Version 6.170.1 landed on 16 October 2026 and code was pushed on 31 August 2026. For other languages, dubzzz/fast-check does the same job in JavaScript and proptest-rs/proptest in Rust.
- The shrinking is the feature, and almost nothing else does it as well.
- Works inside pytest and unittest, so nothing has to be rewritten.
- Remembers past failures locally and retries them first.
- Test suites get slower. A hundred examples per test is a hundred runs.
- A test can fail for a reason that is technically correct but of no interest, and tuning that out takes some reading.
- Python only. Other languages need the alternatives named above.
- dubzzz/fast-check
The same generate-and-shrink idea for JavaScript and TypeScript; smaller library, same approach, MIT licence.
Track this in Scout - proptest-rs/proptest
The Rust version, directly inspired by this project; its own README says it now sees mainly passive maintenance.
Track this in Scout 
schemathesis/schemathesisBuilt on Hypothesis, but aimed at web APIs: it reads an OpenAPI description and generates requests rather than function arguments.
Track this in Scout
python3 -m venv venv source venv/bin/activate pip install hypothesis pytest