Schemathesis

Warnings

• breaking The `schema.validate_response()` method for running tests was removed in Schemathesis v4. It has been replaced by `schema.test()`.
  Fix: Migrate your test calls from `schema.validate_response(...)` to `result = schema.test(...)`. The `test()` method returns a `TestResult` object which provides success status and detailed reports.
• breaking The signatures for `schemathesis.from_asgi()` and `schemathesis.from_wsgi()` changed significantly in v4. The `app` parameter for the ASGI/WSGI application was renamed to `app_or_path` and its behavior was refined.
  Fix: Review the v4 migration guide for `from_asgi`/`from_wsgi` to update function calls. Ensure you're passing the application instance or the correct import path string as `app_or_path`.
• gotcha Authentication for your API under test is often overlooked. Schemathesis by default sends requests without authentication, leading to 401/403 errors and incomplete test coverage.
  Fix: Provide authentication credentials via the `headers`, `auth`, `app_url`, or `base_url` parameters when calling `schema.test()` or `schemathesis.from_uri()`. For complex scenarios, use Schemathesis hooks to inject authentication dynamically for each request.
• gotcha The `base_url` parameter for `schema.test()` is critical. If not specified correctly, tests might be sent to the wrong endpoint, or if your schema lacks a `servers` field, requests might fail entirely.
  Fix: Always explicitly provide the `base_url` argument to `schema.test()` to ensure tests target the correct API environment. For `schemathesis.from_uri()`, the `base_url` can also override or provide the API base URL if the schema doesn't define it or if it points to an incorrect environment.

Install

• pip install schemathesis Install core library
• pip install schemathesis[fastapi] Install with FastAPI support
• pip install schemathesis[flask] Install with Flask support

Imports

• from_uri

  import schemathesis; schema = schemathesis.from_uri(...)

  Used to load an API schema from a URL or file path.
• from_dict

  import schemathesis; schema = schemathesis.from_dict(...)

  Used to load an API schema from a Python dictionary.
• test

  result = schema.test(base_url='...')

  The main programmatic method to run tests against a live API.
• register_check

  import schemathesis; @schemathesis.register_check('my_check') def my_check_function(...): ...

  Decorator to register custom checks for generated test cases.

Quickstart

This quickstart demonstrates how to load an OpenAPI schema from a URI and then execute property-based tests against a live API endpoint using `schemathesis.test()`. It includes notes on specifying the API base URL and handling authentication.

import schemathesis
import os

# For this example, we use a public OpenAPI spec and a public API endpoint.
# In a real scenario, SCHEMA_URL would be your API's spec and API_BASE_URL
# would be the target environment (e.g., 'http://localhost:8000').
SCHEMA_URL = "https://petstore.swagger.io/v2/swagger.json"
API_BASE_URL = "https://petstore.swagger.io/v2"

# Optional: Configure authentication if your API requires it.
# For example, with an API key in a header:
# AUTH_HEADER_KEY = os.environ.get('MY_API_KEY_HEADER', '')
# AUTH_HEADER_VALUE = os.environ.get('MY_API_KEY_VALUE', '')
# custom_headers = {AUTH_HEADER_KEY: AUTH_HEADER_VALUE} if AUTH_HEADER_KEY else {}

try:
    # Load the API schema from a URI
    schema = schemathesis.from_uri(SCHEMA_URL)

    # Run the tests against the live API.
    # The `base_url` parameter is crucial to specify the actual API endpoint
    # where requests will be sent. Add `headers=custom_headers` for auth.
    result = schema.test(base_url=API_BASE_URL)

    if result.is_success:
        print("\nAll Schemathesis tests passed successfully!")
    else:
        print("\nSchemathesis tests failed. See report for details.")
        # Uncomment the line below for a detailed failure report
        # print(result.to_json())
        exit(1) # Indicate failure in a script context

except Exception as e:
    print(f"\nAn error occurred during testing: {e}")
    exit(1)