Schemathesis
Catch API bugs before your users do.
Schemathesis tests OpenAPI and GraphQL APIs by generating inputs from your schema, adapting to server responses, and chaining operations into realistic workflows.
Finding bugs that manual testing missed
Verdict, timeline and every failure in one offline page: --report html
Try it now
# Test a demo API - finds real bugs in 30 seconds
uvx schemathesis run https://example.schemathesis.io/openapi.json
# Test your own API
uvx schemathesis run https://your-api.com/openapi.json
What problems does it solve?
- 💥 500 errors that crash your API on edge case inputs
- 📋 Schema violations where your API returns different data than documented
- 🚪 Validation bypasses where invalid data gets accepted
- 🔗 Integration failures when responses don't match client expectations
- 🔄 Stateful bugs where operations work individually but fail in realistic workflows
What can it do?
- ⚙️ Config file - auth, phases, and per-operation overrides in
schemathesis.toml. No Python. - 🔐 Authentication - static headers, Basic, per-security-scheme credentials, or custom refresh logic.
- 🔗 Stateful testing - operation links inferred from your schema, no manual wiring.
- 🧠 Adaptive testing - learns constraints, ids, and auth from responses, reusing them mid-run.
- ✅ Custom checks - assert your own business rules next to the built-in ones.
- 📖 Fuzz dictionaries - mix real ids, wordlists, or LLM-generated payloads into generated data.
- 🐌 Rate limiting - cap the request rate, or use
autoto followRetry-Afteron 429. - 📊 Reports - an offline HTML page with every failure and its
curlcommand, plus JUnit, VCR, HAR, NDJSON, JSON, and Allure. - 🎯 Schema coverage - keyword-level coverage report showing which constraints your tests exercised.
- 🔁 Replay & baseline - re-run past failures and fail CI only on new ones.
⚠️ Upgrading from older versions? Check our Migration Guide for key changes.
Installation & Usage
Command Line:
uv tool install schemathesis
schemathesis run https://your-api.com/openapi.json
Config file (schemathesis.toml, no Python needed):
headers = { Authorization = "Bearer ${API_TOKEN}" }
generation.max-examples = 500
rate-limit = "auto"
Python Tests:
import schemathesis
schema = schemathesis.openapi.from_url("https://your-api.com/openapi.json")
@schema.parametrize()
def test_api(case):
# Tests with random data, edge cases, and invalid inputs
case.call_and_validate()
# Stateful testing: Tests workflows like: create user -> get user -> delete user
APIWorkflow = schema.as_state_machine()
# Creates a test class for pytest/unittest
TestAPI = APIWorkflow.TestCase
CI/CD:
- uses: schemathesis/action@v3
with:
schema: "https://your-api.com/openapi.json"
Who uses it
Used by teams at Spotify, WordPress, JetBrains, and Red Hat.
"Schemathesis is the best tool for fuzz testing of REST APIs on the market. We at Red Hat use it for examining our applications in functional and integration testing levels." - Dmitry Misharov, RedHat
See it in action
🏆 Trophy case: crashes and schema violations Schemathesis found in vLLM, Qdrant, OpenObserve, Ory Kratos and Formbricks, each with a link to the fix.
🔬 Live Benchmarks: Schemathesis runs for an hour against real-world APIs such as Apache Airflow, Open WebUI and Prefect. For each one:
- Code coverage and API schema coverage: operations, parameters, schema keywords (schema coverage measured with TraceCov)
- Issues found, by category
- How coverage grows over the run, phase by phase
Documentation
📚 Documentation with guides, examples, and API reference. Start here:
- Quick Start - 5 minutes
- CLI Tutorial - 20 minutes
- Pytest Tutorial - 15 minutes
Get Help
Contributing
We welcome contributions! See our contributing guidelines and join discussions in issues or Discord.
Acknowledgements
Schemathesis is built on top of Hypothesis, a powerful property-based testing library for Python.
License
This project is licensed under the terms of the MIT license.
1 maintainer
Metadata
1 maintainer
Release files for schemathesis 4.31.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| schemathesis-4.31.0.tar.gz | 3.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| schemathesis-4.31.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 4.5 MB
Release files / schemathesis-4.31.0.tar.gz
| Download URL | schemathesis-4.31.0.tar.gz |
|---|---|
| Size | 3.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2b9bb06ce2059a53bbaee0dd1cc60ec1c5bfd323f5c153dd82b23ce94d0be7f5
|
|
BLAKE2b-256 checksum How to use checksums |
b0a48431a1f5f841536bb74e5a3ac2240163f35107a06968232aa4219c15b5ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.
Transparency logRelease files / schemathesis-4.31.0-py3-none-any.whl
| Download URL | schemathesis-4.31.0-py3-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
12e4357ae07803e2620eff3a49ca6c7aa49bff95373b0002f12165afca523440
|
|
BLAKE2b-256 checksum How to use checksums |
61d8f78c387bf242cfdfdc8f7864ab0b89e181833c229c96a97c01b47b58892c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.
Transparency log
