Schemathesis

Visit Website

Introduction

Schemathesis tests OpenAPI, GraphQL and gRPC APIs by generating inputs from your schema, adapting to server responses and chaining operations into realistic workflows. Its tagline is “Catch API bugs before your users do”. The project is MIT-licensed with about 3,800 GitHub stars and active development.

It is property-based testing for APIs: instead of hand-writing example requests, you let Schemathesis explore the input space that your schema allows, plus edge cases, and check that responses stay valid.

The README lists the problems it targets: 500 errors on edge-case inputs, schema violations where the API returns different data than documented, validation gaps, and stateful bugs where operations work individually but fail in realistic workflows. Stateful testing infers operation links from your schema.

The README warns that Schemathesis sends real requests that create, change and delete data, so it should run against dev or staging, never production. In the quality loop it sits between API contract testing and security testing.

Features

1. Schema-driven generation: Inputs generated from OpenAPI, GraphQL and gRPC definitions.
2. Stateful testing: Chains operations such as create, get and delete based on inferred links.
3. Response validation: Checks status codes, headers and bodies against the schema.
4. Python integration: Use with pytest and unittest.
5. CLI: Run without writing code, for example with uvx.
6. HTML report: --report html gives a verdict, timeline and failures in one offline page.
7. gRPC with reflection: Test gRPC services using server reflection.
8. Reproducible failures: Minimal failing examples to reproduce bugs.

Pros

1. Finds real bugs fast: The README claims real bugs on a demo API in 30 seconds.
2. Low effort: Uses the schema you already have.
3. Free: MIT.
4. Fits CI: CLI and pytest options.
5. Active: Commits on the day of review.

Cons

1. Needs a good schema: Weak schemas limit results.
2. Mutates data: Must target non-production environments.
3. Noise from loose specs: Failures may reveal spec issues rather than code bugs.
4. Auth setup: Authenticated APIs need configuration.
5. Not a load tool: It finds correctness bugs, not throughput limits.

Usage and Links (Example)

Try it against the demo API or your own:

uvx schemathesis run https://example.schemathesis.io/openapi.json
uvx schemathesis run https://your-api.com/openapi.json

From pytest:

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

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

Tips: run it in CI against a disposable staging environment, fix schema mismatches as well as crashes, and keep the HTML report as a build artefact.

Resources:

• Documentation
• GitHub repository

Pricing

Schemathesis is free and open source under MIT.

Recommended for?

1. API teams with OpenAPI or GraphQL schemas wanting automated edge-case coverage.
2. QA engineers adding property-based API tests to CI.
3. Security-minded teams looking for crashes and validation gaps.
4. Not a fit for production monitoring or load testing.

Conclusion

Schemathesis turns an API schema into a powerful bug-finding test suite, including stateful workflows.

Run it against staging, keep schemas accurate, and pair it with contract tests and security scanners.