Schemathesis — Property-Based API Testing and Fuzzing

Introduction

Schemathesis is an open-source API testing tool that uses property-based testing and fuzzing techniques to automatically find bugs in HTTP APIs. It reads your OpenAPI or GraphQL schema, generates thousands of valid and edge-case requests, and reports crashes, 500 errors, and specification violations without writing a single test case.

What Schemathesis Does

• Generates test cases automatically from OpenAPI 2.0/3.0/3.1 and GraphQL schemas
• Finds server crashes, 500 errors, and unhandled exceptions through fuzzing
• Detects response validation failures where the API violates its own schema
• Applies property-based testing with Hypothesis for thorough input coverage
• Provides minimal reproducible examples for each discovered failure

Architecture Overview

Schemathesis parses API schemas to build a model of all endpoints, their parameters, and expected responses. The Hypothesis engine then generates randomized but schema-valid inputs, exploring edge cases like boundary values, empty strings, special characters, and deeply nested objects. Each response is validated against the schema. Failures are automatically minimized to the simplest reproducible case.

Self-Hosting & Configuration

• Install via pip and point at your API's schema URL or file
• Configure authentication via CLI flags or environment variables
• Set custom headers, base URLs, and request timeouts
• Use as a pytest plugin for integration into existing test suites
• Run in CI with st run and fail the build on any findings

Key Features

• Zero test code required — generates all tests from the API schema
• Built on Hypothesis for exhaustive property-based input generation
• Automatic failure minimization produces the simplest reproducing case
• Stateful testing mode discovers multi-step workflow bugs
• CLI and Python API for flexible integration

Comparison with Similar Tools

• Dredd — validates API against docs but uses example-based, not generative testing
• Postman/Newman — requires manually written test cases
• REST Assured — Java library requiring explicit test code for each endpoint
• Hurl — HTTP request runner, not a generative tester
• Burp Suite — commercial security scanner, different focus and cost

FAQ

Q: Do I need to write any tests? A: No. Schemathesis generates all test cases from your OpenAPI or GraphQL schema automatically.

Q: What kinds of bugs does Schemathesis find? A: Server crashes (500 errors), unhandled exceptions, response schema violations, authentication bypasses, and input validation gaps.

Q: Can I use Schemathesis with a schema file instead of a live server? A: You still need a running server to send requests to. The schema can be loaded from a file, but tests execute against a live endpoint.

Q: Does Schemathesis support GraphQL? A: Yes. It can generate and test GraphQL queries and mutations from your GraphQL schema.

Sources

• https://github.com/schemathesis/schemathesis
• https://schemathesis.io