schemathesis/schemathesis

Catch API bugs before your users do

Summary

Schemathesis is a Python tool that tests OpenAPI and GraphQL APIs by generating inputs from a schema, adapting to server responses, and chaining operations into realistic workflows. It runs as a CLI, integrates with pytest, and is built on top of the Hypothesis property-based testing library.

What it is useful for

The tool targets API bugs that manual testing tends to miss: 500 errors on edge case inputs, schema violations where responses differ from the documentation, validation bypasses where invalid data is accepted, and stateful bugs where operations work individually but fail when chained. It is most useful when a team already has an OpenAPI or GraphQL schema and wants broader test coverage without hand-writing every case. The README notes use at Spotify (Backstage), WordPress (Openverse), JetBrains, and Red Hat, and lists supported problem categories such as integration failures and authentication edge cases. It supports static headers, Basic auth, per-security-scheme credentials, and custom auth refresh logic, plus a rate-limit option that can follow Retry-After on 429 responses.

How engineers can use it

The README documents three entry points.

Quick run from the command line:

uvx schemathesis run https://example.schemathesis.io/openapi.json

Local install: uv tool install schemathesis, then schemathesis run https://your-api.com/openapi.json.

Inside a Python test suite, the documented pattern loads a schema and parameterizes a test:

import schemathesis

schema = schemathesis.openapi.from_url("https://your-api.com/openapi.json")

@schema.parametrize()
def test_api(case):
    case.call_and_validate()

APIWorkflow = schema.as_state_machine()
TestAPI = APIWorkflow.TestCase

The state-machine form chains operations like create user → get user → delete user.

For non-Python setups, the README documents a schemathesis.toml file for auth, generation limits, and rate limiting, plus a GitHub Action (schemathesis/action@v3) for CI/CD. Reports are available in JUnit, VCR, HAR, NDJSON, JSON, and Allure, and there is a baseline mode for failing CI only on new regressions. The README flags a Migration Guide for users coming from older versions, which is worth reviewing before upgrading. Detailed configuration and extension options live in the linked documentation.