schemathesis: Open Source API Development & Testing

What is schemathesis?

What it is

Schemathesis is a Python API testing tool that generates test inputs from OpenAPI and GraphQL schemas. It adapts to server responses, chains operations into realistic workflows, and checks whether the API behaves as documented. The project lives in the Python developer tools ecosystem and connects with pytest, unittest, and property-based testing workflows.

It solves the problem of API bugs that manual testing misses. It targets 500 errors on edge case inputs, schema violations where responses differ from documented data, validation bypasses where invalid data is accepted, integration failures when responses do not match client expectations, and stateful bugs where operations work individually but fail in realistic workflows.

Key capabilities

Schemathesis generates inputs from OpenAPI and GraphQL schemas and adapts to server responses during a run.
It performs stateful testing by inferring operation links from the schema and chaining calls such as create user, get user, and delete user.
It supports authentication through static headers, Basic credentials, per-security-scheme credentials, and custom refresh logic.
It allows custom checks so teams can assert business rules alongside built-in validation checks.
It supports fuzz dictionaries that mix real IDs, wordlists, or LLM-generated payloads into generated data.
It provides rate limiting and can use auto mode to follow Retry-After responses on HTTP 429.
It produces reports in JUnit, VCR, HAR, NDJSON, JSON, and Allure formats, shows keyword-level schema coverage, replays past failures, and supports baselines that fail CI only on new ones.

Who uses it and how

Teams at Spotify, WordPress, JetBrains, Red Hat, and dozens of other companies use the tool.
Red Hat describes using it for examining applications at functional and integration testing levels.
Users run it from the command line against a demo API or their own API schema URL.
Users integrate it into CI/CD with the GitHub action schemathesis/action@v3 and a schema URL.
Users write Python tests by loading a schema, parametrizing operations, and creating state machine test classes for pytest or unittest.

Getting started

Install with uv pip install schemathesis, then run schemathesis run followed by an OpenAPI URL. The project also runs with uvx schemathesis run, supports headers, generation limits, and rate limiting in schemathesis.toml, and provides a GitHub action for CI.

When to use it — and when not to

Use Schemathesis when an API exposes a usable OpenAPI or GraphQL schema and the team wants automated schema-driven, adaptive, and stateful testing. Avoid it when the API has no usable OpenAPI or GraphQL schema, because input generation is schema-driven. Upgrading from older versions requires checking the migration guide for key changes.

project readme (upstream, from github) — read inline

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.

Schemathesis automatically finding a server error
Finding bugs that manual testing missed

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 auto to follow Retry-After on 429.
📊 Reports — 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 pip 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, Red Hat, and dozens of other companies.

"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

🔬 Live Benchmarks showing continuous testing results from real-world APIs:

Code & API schema coverage achieved
Issues found with detailed categorization
Performance across different fuzzing strategies

Documentation

📚 Documentation with guides, examples, and API reference.

Get Help

💬 Discord community
🐛 GitHub issues

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.

Frequently asked questions

Is schemathesis free to use?

schemathesis is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does schemathesis do?

Catch API bugs before your users do

What is schemathesis written in?

schemathesis is primarily written in Python. Its source is publicly available at https://github.com/schemathesis/schemathesis, and it has 3,608 GitHub stars.