Skip to content
A tool that generates and runs test cases for Open API / Swagger based apps
Python Other
  1. Python 99.9%
  2. Other 0.1%
Branch: master
Clone or download
Latest commit b4c6659 Feb 22, 2020
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows chore(ci): Run scheduled hypothesis tests with custom profile Feb 17, 2020
adr Refactor Sep 16, 2019
docs Release 0.24.4 Feb 22, 2020
img Fix link to CONTRIBUTING.rst Nov 6, 2019
src/schemathesis fix: Resolving references when schema is loaded from a file on Windows Feb 22, 2020
test chore: Fix pytest warning on not registered marks Feb 22, 2020
.adr-dir Add ADR Aug 21, 2019
.coveragerc Add `` and `Case.as_requests_kwargs` convenience methods. Oct 14, 2019
.dockerignore chore(docker): Remove the poetry environment from the docker image Jan 15, 2020
.gitignore .gitignore: Add .envrc Oct 4, 2019
.pre-commit-config.yaml chore: Add more checks to pre-commit Jan 8, 2020
.pydocstyle chore: Add more checks to pre-commit Jan 8, 2020
.pylintrc Initial commit Aug 19, 2019
.relint.yml chore: Add more checks to pre-commit Jan 8, 2020
.yamllint chore: Add more checks to pre-commit Jan 8, 2020 Create Sep 13, 2019
CONTRIBUTING.rst Create CONTRIBUTING.rst Sep 19, 2019
Dockerfile fix: Dockerfile entrypoint was not working as per docs Jan 15, 2020
LICENSE Create LICENSE Sep 13, 2019
README.rst docs: Add Read the Docs badge to the README file Feb 6, 2020
mypy.ini chore: Use built-in `importlib.metadata` on Python 3.8 Jan 27, 2020
poetry.lock chore: Use built-in `importlib.metadata` on Python 3.8 Jan 27, 2020
pyproject.toml Release 0.24.4 Feb 22, 2020 feat: WSGI applications support Dec 12, 2019
tox.ini chore: Pin hypothesis-jsonschema for versioned hypothesis tests Jan 27, 2020



Build status for master branch Version Python versions Documentation Status License

Schemathesis is a tool for testing your web applications built with Open API / Swagger specifications.

It reads the application schema and generates test cases which will ensure that your application is compliant with its schema.

The application under test could be written in any language, the only thing you need is a valid API schema in a supported format.

Supported specification versions:

  • Swagger 2.0
  • Open API 3.0.x

More API specifications will be added in the future.

Built with:

Inspired by wonderful swagger-conformance project.

If you are looking for more information, then there is an article about Schemathesis:


To install Schemathesis via pip run the following command:

pip install schemathesis



There are two basic ways to use Schemathesis:

CLI is pretty simple to use and requires no coding, in-code approach gives more flexibility.

Command Line Interface

The schemathesis command can be used to perform Schemathesis test cases:

schemathesis run

If your application requires authorization then you can use --auth option for Basic Auth and --header to specify custom headers to be sent with each request.

To filter your tests by endpoint name, HTTP method or Open API tags you could use -E, -M, -T options respectively.

CLI supports passing options to hypothesis.settings. All of them are prefixed with --hypothesis-:

schemathesis run --hypothesis-max-examples=1000

To speed up the testing process Schemathesis provides -w/--workers option for concurrent test execution:

schemathesis run -w 8

In the example above all tests will be distributed among 8 worker threads.

If you'd like to test your web app (Flask or AioHTTP for example) then there is --app option for you:

schemathesis run --app=importable.path:app /swagger.json

You need to specify an importable path to the module where your app instance resides and a variable name after : that points to your app. Note, app factories are not supported. The schema location could be:

  • A full URL;
  • An existing filesystem path;
  • In-app endpoint with schema.

This method is significantly faster for WSGI apps, since it doesn't involve network.

For the full list of options, run:

schemathesis --help
# Or
schemathesis run --help


Schemathesis CLI also available as a docker image

docker run kiwicom/schemathesis:stable run

To run it against localhost server add --network=host parameter:

docker run --network="host" kiwicom/schemathesis:stable run

Pre-run CLI hook

Sometimes you need to execute custom code before the CLI run, for example setup an environment, register custom string format strategies or modify Schemathesis behavior in runtime you can use --pre-run hook:

schemathesis --pre-run run

NOTE. This option should be passed before the run part.

The passed value will be processed as an importable Python path, where you can execute your code. An example -

Registering custom checks for CLI

To add a new check for the Schemathesis CLI there is a special function

import schemathesis

def new_check(response, case):
    # some awesome assertions!

The registered check should accept a response with requests.Response / schemathesis.utils.WSGIResponse type and case with schemathesis.models.Case type.

After registration, your checks will be available in Schemathesis CLI and you can use them via -c command line option.

schemathesis --pre-run module.with.checks run -c new_check


To examine your application with Schemathesis you need to:

  • Setup & run your application, so it is accessible via the network;
  • Write a couple of tests in Python;
  • Run the tests via pytest.

Suppose you have your application running on and its schema is available at

A basic test, that will verify that any data, that fit into the schema will not cause any internal server error could look like this:

import requests
import schemathesis

schema = schemathesis.from_uri("")

def test_no_server_errors(case):
    # `requests` will make an appropriate call under the hood
    response =  # use `call_wsgi` if you used `schemathesis.from_wsgi`
    # You could use built-in checks
    # Or assert the response manually
    assert response.status_code < 500

It consists of four main parts:

  1. Schema preparation; schemathesis package provides multiple ways to initialize the schema - from_path, from_dict, from_uri, from_file and from_wsgi.
  2. Test parametrization; @schema.parametrize() generates separate tests for all endpoint/method combination available in the schema.
  3. A network call to the running application; does it.
  4. Verifying a property you'd like to test; In the example, we verify that any app response will not indicate a server-side error (HTTP codes 5xx).

NOTE. Look for from_wsgi usage below

Run the tests:


Other properties that could be tested:

  • Any call will be processed in <50 ms - you can verify the app performance;
  • Any unauthorized access will end with 401 HTTP response code;

Each test function should have the case fixture, that represents a single test case.

Important Case attributes:

  • method - HTTP method
  • formatted_path - full endpoint path
  • headers - HTTP headers
  • query - query parameters
  • body - request body

You can use them manually in network calls or can convert to a dictionary acceptable by requests.request:

import requests

schema = schemathesis.from_uri("")

def test_no_server_errors(case):
    kwargs = case.as_requests_kwargs()
    response = requests.request(**kwargs)

For each test, Schemathesis will generate a bunch of random inputs acceptable by the schema. This data could be used to verify that your application works in the way as described in the schema or that schema describes expected behavior.

By default, there will be 100 test cases per endpoint/method combination. To limit the number of examples you could use hypothesis.settings decorator on your test functions:

from hypothesis import settings

def test_something(client, case):

To narrow down the scope of the schemathesis tests it is possible to filter by method or endpoint:

@schema.parametrize(method="GET", endpoint="/pet")
def test_no_server_errors(case):

The acceptable values are regexps or list of regexps (matched with

WSGI applications support

Schemathesis supports making calls to WSGI-compliant applications instead of real network calls, in this case the test execution will go much faster.

app = Flask("test_app")

def schema():
    return {...}

@app.route("/v1/users", methods=["GET"])
def users():
    return jsonify([{"name": "Robin"}])

schema = schemathesis.from_wsgi("/schema.json", app)

def test_no_server_errors(case):
    response = case.call_wsgi()
    assert response.status_code < 500

Explicit examples

If the schema contains parameters examples, then they will be additionally included in the generated cases.

    - in: body
      name: body
      required: true
      schema: '#/definitions/Pet'

    additionalProperties: false
      name: Doggo
        type: string
    - name
    type: object

With this Swagger schema example, there will be a case with body {"name": "Doggo"}. Examples handled with example decorator from Hypothesis, more info about its behavior is here.

NOTE. Schemathesis supports only examples in parameters at the moment, examples of individual properties are not supported.

Direct strategies access

For convenience you can explore the schemas and strategies manually:

>>> import schemathesis
>>> schema = schemathesis.from_uri("")
>>> endpoint = schema["/v2/pet"]["POST"]
>>> strategy = endpoint.as_strategy()
>>> strategy.example()
        'name': '\x15.\x13\U0008f42a',
        'photoUrls': ['\x08\U0009f29a', '\U000abfd6\U000427c4', '']

Schema instances implement Mapping protocol.

If you want to customize how data is generated, then you can use hooks of two types:

  • Global, which are applied to all schemas;
  • Schema-local, which are applied only for specific schema instance;

Each hook accepts a Hypothesis strategy and should return a Hypothesis strategy:

import schemathesis

def global_hook(strategy):
    return strategy.filter(lambda x: x["id"].isdigit())

schemathesis.hooks.register("query", hook)

schema = schemathesis.from_uri("")

def schema_hook(strategy):
    return strategy.filter(lambda x: int(x["id"]) % 2 == 0)

schema.register_hook("query", schema_hook)

There are 6 places, where hooks can be applied and you need to pass it as the first argument to schemathesis.hooks.register or schema.register_hook:

  • path_parameters
  • headers
  • cookies
  • query
  • body
  • form_data

It might be useful if you want to exclude certain cases that you don't want to test, or modify the generated data, so it will be more meaningful for the application - add existing IDs from the database, custom auth header, etc.

NOTE. Global hooks are applied first.

Lazy loading

If you have a schema that is not available when the tests are collected, for example it is build with tools like apispec and requires an application instance available, then you can parametrize the tests from a pytest fixture.

import schemathesis

schema = schemathesis.from_pytest_fixture("fixture_name")

def test_api(case):

In this case the test body will be used as a sub-test via pytest-subtests library.

NOTE: the used fixture should return a valid schema that could be created via schemathesis.from_dict or other schemathesis.from_ variations.

Extending schemathesis

If you're looking for a way to extend schemathesis or reuse it in your own application, then runner module might be helpful for you. It can run tests against the given schema URI and will do some simple checks for you.

from schemathesis import runner


The built-in checks list includes the following:

  • Not a server error. Asserts that response's status code is less than 500;
  • Status code conformance. Asserts that response's status code is listed in the schema;
  • Content type conformance. Asserts that response's content type is listed in the schema;
  • Response schema conformance. Asserts that response's content conforms to the declared schema;

You can provide your custom checks to the execute function, the check is a callable that accepts one argument of requests.Response type.

from datetime import timedelta
from schemathesis import runner, models

def not_too_long(response, case: models.Case):
    assert response.elapsed < timedelta(milliseconds=300)

runner.execute("", checks=[not_too_long])

Custom string strategies

Some string fields could use custom format and validators, e.g. card_number and Luhn algorithm validator.

For such cases it is possible to register custom strategies:

  1. Create hypothesis.strategies.SearchStrategy object
  2. Optionally provide predicate function to filter values
  3. Register it via schemathesis.register_string_format
strategy = strategies.from_regex(r"\A4[0-9]{15}\Z").filter(luhn_validator)
schemathesis.register_string_format("visa_cards", strategy)

Unittest support

Schemathesis supports Python's built-in unittest framework out of the box, you only need to specify strategies for hypothesis.given:

from unittest import TestCase
from hypothesis import given
import schemathesis

schema = schemathesis.from_uri("")
new_pet_strategy = schema["/v2/pet"]["POST"].as_strategy()

class TestSchema(TestCase):

    def test_pets(self, case):
        response =
        assert response.status_code < 500

Schema validation

To avoid obscure and hard to debug errors during test runs Schemathesis validates input schemas for conformance with the relevant spec. If you'd like to disable this behavior use --validate-schema=false in CLI and validate_schema=False argument in loaders.


For the full documentation, please see (WIP)

Or you can look at the docs/ directory in the repository.

Local development

First, you need to prepare a virtual environment with poetry. Install poetry (check out the installation guide) and run this command inside the project root:

poetry install

For simpler local development Schemathesis includes a aiohttp-based server with the following endpoints in Swagger 2.0 schema:

  • /api/success - always returns {"success": true}
  • /api/failure - always returns 500
  • /api/slow - always returns {"slow": true} after 250 ms delay
  • /api/unsatisfiable - parameters for this endpoint are impossible to generate
  • /api/invalid - invalid parameter definition. Uses int instead of integer
  • /api/flaky - returns 1/1 ratio of 200/500 responses
  • /api/multipart - accepts multipart data
  • /api/teapot - returns 418 status code, that is not listed in the schema
  • /api/text - returns plain/text responses, which are not declared in the schema
  • /api/malformed_json - returns malformed JSON with application/json content type header

To start the server:

./ 8081

It is possible to configure available endpoints via --endpoints option. The value is expected to be a comma separated string with endpoint names (success, failure, slow, etc):

./ 8081 --endpoints=success,slow

Then you could use CLI against this server:

schemathesis run
================================== Schemathesis test session starts =================================
platform Linux -- Python 3.7.4, schemathesis-0.12.2, hypothesis-4.39.0, hypothesis_jsonschema-0.9.8
rootdir: /
hypothesis profile 'default' -> database=DirectoryBasedExampleDatabase('/.hypothesis/examples')
Schema location:
Base URL:
Specification version: Swagger 2.0
collected endpoints: 2

GET /api/slow .                                                                               [ 50%]
GET /api/success .                                                                            [100%]

============================================== SUMMARY ==============================================

not_a_server_error            2 / 2 passed          PASSED

========================================= 2 passed in 0.29s =========================================

Running tests

You could run tests via tox:

tox -p all -o

or pytest in your current environment:

pytest test/ -n auto


Any contribution in development, testing or any other area is highly appreciated and useful to the project.

Please, see the CONTRIBUTING.rst file for more details.

Python support

Schemathesis supports Python 3.6, 3.7 and 3.8.


The code in this project is licensed under MIT license. By contributing to schemathesis, you agree that your contributions will be licensed under its MIT license.

You can’t perform that action at this time.