Public API reference

Checks

schemathesis.check(check: CheckFunction) → CheckFunction

Register a new check for schemathesis CLI.

Parameters:: check – A function to validate API responses.

@schemathesis.check
def new_check(ctx, response, case):
    # some awesome assertions!
    ...

Data Generation

class schemathesis.GenerationConfig(allow_x00: bool = True, graphql_allow_null: bool = True, codec: str | None = 'utf-8', with_security_parameters: bool = True, headers: ~schemathesis.generation.HeaderConfig = <factory>)[source]: Holds various configuration options relevant for data generation.

Fixups

Available fixups:

fast_api
utf8_bom

schemathesis.fixups.install(fixups: Iterable[str] | None = None) → None[source]

Install fixups.

Without the first argument installs all available fixups.

Parameters:: fixups – Names of fixups to install.

schemathesis.fixups.uninstall(fixups: Iterable[str] | None = None) → None[source]

Uninstall fixups.

Without the first argument uninstalls all available fixups.

Parameters:: fixups – Names of fixups to uninstall.

Authentication

Support for custom API authentication mechanisms.

schemathesis.auth(provider_class: type[AuthProvider] | None = None, *, refresh_interval: int | None = 300, cache_by_key: CacheKeyFunction | None = None) → FilterableRegisterAuth | FilterableApplyAuth: Store and manage API authentication.

class schemathesis.auths.AuthProvider(*args, **kwargs)[source]

Get authentication data for an API and set it on the generated test cases.

get(case: Case, context: AuthContext) → Auth | None[source]

Get the authentication data.

Parameters:

case (Case) – Generated test case.
context (AuthContext) – Holds state relevant for the authentication process.

Returns:

Any authentication data you find useful for your use case. For example, it could be an access token.

set(case: Case, data: Auth, context: AuthContext) → None[source]

Set authentication data on a generated test case.

Parameters:

data (Optional[Auth]) – Authentication data you got from the get method.
case (Case) – Generated test case.
context (AuthContext) – Holds state relevant for the authentication process.

class schemathesis.auths.AuthContext(operation: APIOperation, app: Any | None)[source]

Holds state relevant for the authentication process.

Variables:

operation (APIOperation) – API operation that is currently being processed.
app – Optional Python application if the WSGI / ASGI integration is used.

Hooks

class schemathesis.hooks.HookContext(operation: APIOperation | None = None)[source]

A context that is passed to some hook functions.

Variables:: operation (Optional[APIOperation]) – API operation that is currently being processed. Might be absent in some cases.

These functions affect Schemathesis behavior globally:

schemathesis.hook(hook: str | Callable) → Callable

schemathesis.hooks.unregister(hook: Callable) → None

Unregister a specific hook.

Parameters:: hook – A hook function to unregister.

schemathesis.hooks.unregister_all() → None

Remove all registered hooks.

Useful in tests.

class schemathesis.schemas.BaseSchema

All functions above can be accessed via schema.hooks.<function-name> on a schema instance. Such calls will affect only tests generated from the schema instance. Additionally you can use the following:

schema.hooks.apply()

Register hook to run only on one test function.

Parameters:

hook – A hook function.
name (Optional[str]) – A hook name.

def before_generate_query(context, strategy):
    ...


@schema.hooks.apply(before_generate_query)
@schema.parametrize()
def test_api(case):
    ...

Serializers

class schemathesis.serializers.SerializerContext(case: Case)[source]

The context for serialization process.

Variables:: case (Case) – Generated example that is being processed.

schemathesis.serializer(media_type: str, *, aliases: Collection[str] = ()) → Callable[[type[schemathesis.serializers.Serializer]], type[schemathesis.serializers.Serializer]]

Register a serializer for the given media type.

Schemathesis uses requests for regular network calls and werkzeug for WSGI applications. Your serializer should have two methods, as_requests and as_werkzeug, providing keyword arguments that Schemathesis will pass to requests.request and werkzeug.Client.open respectively.

@register("text/csv")
class CSVSerializer:
    def as_requests(self, context, value):
        return {"data": to_csv(value)}

    def as_werkzeug(self, context, value):
        return {"data": to_csv(value)}

The primary purpose of serializers is to transform data from its Python representation to the format suitable for making an API call. The generated data structure depends on your schema, but its type matches Python equivalents to the JSON Schema types.

schemathesis.serializers.unregister(media_type: str) → None[source]: Remove registered serializer for the given media type.

Targeted testing

class schemathesis.targets.TargetContext(case: Case, response: GenericResponse, response_time: float)[source]

Context for targeted testing.

Variables:

case (Case) – Generated example that is being processed.
response (GenericResponse) – API response.
response_time (float) – API response time.

schemathesis.target(target: Callable[[TargetContext], float]) → Callable[[TargetContext], float]

Register a new testing target for schemathesis CLI.

Parameters:: target – A function that will be called to calculate a metric passed to hypothesis.target.

Custom strategies for Open API “format” keyword

schemathesis.openapi.format(name: str, strategy: st.SearchStrategy) → None

Register a new strategy for generating data for specific string “format”.

Parameters:

name (str) – Format name. It should correspond the one used in the API schema as the “format” keyword value.
strategy – Hypothesis strategy you’d like to use to generate values for this format.

Custom strategies for Open API media types

schemathesis.openapi.media_type(name: str, strategy: st.SearchStrategy[bytes], *, aliases: Collection[str] = ()) → None: Register a strategy for the given media type.

Custom scalars for GraphQL

schemathesis.graphql.scalar(name: str, strategy: st.SearchStrategy[graphql.ValueNode]) → None[source]

Register a new strategy for generating custom scalars.

Parameters:

name (str) – Scalar name. It should correspond the one used in the schema.
strategy – Hypothesis strategy you’d like to use to generate values for this scalar.

Loaders

schemathesis.from_aiohttp(schema_path: str, app: Any, *, base_url: str | None = None, method: Filter | None = None, endpoint: Filter | None = None, tag: Filter | None = None, operation_id: Filter | None = None, skip_deprecated_operations: bool | None = None, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | None = None, output_config: OutputConfig | None = None, code_sample_style: str = 'curl', rate_limit: str | None = None, sanitize_output: bool = True, **kwargs: Any) → BaseOpenAPISchema[source]

Load Open API schema from an AioHTTP app.

Parameters:

schema_path (str) – An in-app relative URL to the schema.
app – An AioHTTP app instance.

schemathesis.from_asgi(schema_path: str, app: Any, *, base_url: str | None = None, method: Filter | None = None, endpoint: Filter | None = None, tag: Filter | None = None, operation_id: Filter | None = None, skip_deprecated_operations: bool | None = None, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | None = None, output_config: OutputConfig | None = None, code_sample_style: str = 'curl', rate_limit: str | None = None, sanitize_output: bool = True, **kwargs: Any) → BaseOpenAPISchema[source]

Load Open API schema from an ASGI app.

Parameters:

schema_path (str) – An in-app relative URL to the schema.
app – An ASGI app instance.

schemathesis.from_dict(raw_schema: dict[str, Any], *, app: Any = None, base_url: str | None = None, method: Filter | None = None, endpoint: Filter | None = None, tag: Filter | None = None, operation_id: Filter | None = None, skip_deprecated_operations: bool | None = None, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>,), generation_config: GenerationConfig | None = None, output_config: OutputConfig | None = None, code_sample_style: str = 'curl', location: str | None = None, rate_limit: str | None = None, sanitize_output: bool = True) → BaseOpenAPISchema[source]

Load Open API schema from a Python dictionary.

Parameters:: raw_schema (dict) – A schema to load.

schemathesis.from_file(file: IO[str] | str, *, app: Any = None, base_url: str | None = None, method: Filter | None = None, endpoint: Filter | None = None, tag: Filter | None = None, operation_id: Filter | None = None, skip_deprecated_operations: bool | None = None, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | None = None, output_config: OutputConfig | None = None, code_sample_style: str = 'curl', location: str | None = None, rate_limit: str | None = None, sanitize_output: bool = True, __expects_json: bool = False, __expects_yaml: bool = False, **kwargs: Any) → BaseOpenAPISchema[source]

Load Open API schema from a file descriptor, string or bytes.

Parameters:: file – Could be a file descriptor, string or bytes.

schemathesis.from_path(path: PathLike, *, app: Any = None, base_url: str | None = None, method: Filter | None = None, endpoint: Filter | None = None, tag: Filter | None = None, operation_id: Filter | None = None, skip_deprecated_operations: bool | None = None, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | None = None, output_config: OutputConfig | None = None, code_sample_style: str = 'curl', rate_limit: str | None = None, encoding: str = 'utf8', sanitize_output: bool = True) → BaseOpenAPISchema[source]

Load Open API schema via a file from an OS path.

Parameters:

path – A path to the schema file.
encoding – The name of the encoding used to decode the file.

schemathesis.from_pytest_fixture(fixture_name: str, *, app: Any = <schemathesis.types.NotSet object>, base_url: str | None | NotSet = <schemathesis.types.NotSet object>, method: Filter | None = <schemathesis.types.NotSet object>, endpoint: Filter | None = <schemathesis.types.NotSet object>, tag: Filter | None = <schemathesis.types.NotSet object>, operation_id: Filter | None = <schemathesis.types.NotSet object>, skip_deprecated_operations: bool | None = None, validate_schema: bool = False, data_generation_methods: DataGenerationMethodInput | NotSet = <schemathesis.types.NotSet object>, generation_config: GenerationConfig | NotSet = <schemathesis.types.NotSet object>, output_config: OutputConfig | NotSet = <schemathesis.types.NotSet object>, code_sample_style: str = 'curl', rate_limit: str | None = None, sanitize_output: bool = True) → LazySchema[source]

Load schema from a pytest fixture.

It is useful if you don’t want to make network requests during module loading. With this loader you can defer it to a fixture.

Note, the fixture should return a BaseSchema instance loaded with another loader.

Parameters:: fixture_name (str) – The name of a fixture to load.

schemathesis.from_uri(uri: str, *, app: Any = None, base_url: str | None = None, port: int | None = None, method: Filter | None = None, endpoint: Filter | None = None, tag: Filter | None = None, operation_id: Filter | None = None, skip_deprecated_operations: bool | None = None, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | None = None, output_config: OutputConfig | None = None, code_sample_style: str = 'curl', wait_for_schema: float | None = None, rate_limit: str | None = None, sanitize_output: bool = True, **kwargs: Any) → BaseOpenAPISchema[source]

Load Open API schema from the network.

Parameters:: uri (str) – Schema URL.

schemathesis.from_wsgi(schema_path: str, app: Any, *, base_url: str | None = None, method: Filter | None = None, endpoint: Filter | None = None, tag: Filter | None = None, operation_id: Filter | None = None, skip_deprecated_operations: bool | None = None, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | None = None, output_config: OutputConfig | None = None, code_sample_style: str = 'curl', rate_limit: str | None = None, sanitize_output: bool = True, **kwargs: Any) → BaseOpenAPISchema[source]

Load Open API schema from a WSGI app.

Parameters:

schema_path (str) – An in-app relative URL to the schema.
app – A WSGI app instance.

schemathesis.graphql.from_path(path: PathLike, *, app: Any = None, base_url: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | None = None, output_config: OutputConfig | None = None, code_sample_style: str = 'curl', rate_limit: str | None = None, encoding: str = 'utf8', sanitize_output: bool = True) → GraphQLSchema[source]

Load GraphQL schema via a file from an OS path.

Parameters:

path – A path to the schema file.
encoding – The name of the encoding used to decode the file.

schemathesis.graphql.from_dict(raw_schema: dict[str, Any], *, app: Any = None, base_url: str | None = None, location: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>,), generation_config: GenerationConfig | None = None, output_config: OutputConfig | None = None, code_sample_style: str = 'curl', rate_limit: str | None = None, sanitize_output: bool = True) → GraphQLSchema[source]

Load GraphQL schema from a Python dictionary.

Parameters:

raw_schema (dict) – A schema to load.
location (Optional[str]) – Optional schema location. Either a full URL or a filesystem path.
base_url (Optional[str]) – Base URL to send requests to.
app – A WSGI app instance.

Returns:

GraphQLSchema

schemathesis.graphql.from_file(file: IO[str] | str, *, app: Any = None, base_url: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | None = None, output_config: OutputConfig | None = None, code_sample_style: str = 'curl', location: str | None = None, rate_limit: str | None = None, sanitize_output: bool = True) → GraphQLSchema[source]

Load GraphQL schema from a file descriptor or a string.

Parameters:: file – Could be a file descriptor, string or bytes.

schemathesis.graphql.from_url(url: str, *, app: Any = None, base_url: str | None = None, port: int | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | None = None, code_sample_style: str = 'curl', wait_for_schema: float | None = None, rate_limit: str | None = None, sanitize_output: bool = True, **kwargs: Any) → GraphQLSchema[source]

Load GraphQL schema from the network.

Parameters:

url – Schema URL.
base_url (Optional[str]) – Base URL to send requests to.
port (Optional[int]) – An optional port if you don’t want to pass the base_url parameter, but only to change port in url.
app – A WSGI app instance.

Returns:

GraphQLSchema

schemathesis.graphql.from_asgi(schema_path: str, app: Any, *, base_url: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | None = None, output_config: OutputConfig | None = None, code_sample_style: str = 'curl', rate_limit: str | None = None, sanitize_output: bool = True, **kwargs: Any) → GraphQLSchema[source]

Load GraphQL schema from an ASGI app.

Parameters:

schema_path (str) – An in-app relative URL to the schema.
app – An ASGI app instance.
base_url (Optional[str]) – Base URL to send requests to.

schemathesis.graphql.from_wsgi(schema_path: str, app: Any, *, base_url: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | None = None, output_config: OutputConfig | None = None, code_sample_style: str = 'curl', rate_limit: str | None = None, sanitize_output: bool = True, **kwargs: Any) → GraphQLSchema[source]

Load GraphQL schema from a WSGI app.

Parameters:

schema_path (str) – An in-app relative URL to the schema.
app – A WSGI app instance.
base_url (Optional[str]) – Base URL to send requests to.

Returns:

GraphQLSchema

Sanitizing Output

class schemathesis.sanitization.Config[source]

Configuration class for sanitizing sensitive data.

Parameters:

keys_to_sanitize (FrozenSet[str]) – The exact keys to sanitize (case-insensitive).
sensitive_markers (FrozenSet[str]) – Markers indicating potentially sensitive keys (case-insensitive).
replacement (str) – The replacement string for sanitized values.

with_keys_to_sanitize(*keys: str) → Config[source]: Create a new configuration with additional keys to sanitize.

without_keys_to_sanitize(*keys: str) → Config[source]: Create a new configuration without certain keys to sanitize.

with_sensitive_markers(*markers: str) → Config[source]: Create a new configuration with additional sensitive markers.

without_sensitive_markers(*markers: str) → Config[source]: Create a new configuration without certain sensitive markers.

Schema

class schemathesis.schemas.BaseSchema[source]

BaseSchema(raw_schema: ‘dict[str, Any]’, transport: ‘Transport’, specification: ‘Specification’, location: ‘str | None’ = None, base_url: ‘str | None’ = None, filter_set: ‘FilterSet’ = <factory>, app: ‘Any’ = None, hooks: ‘HookDispatcher’ = <factory>, auth: ‘AuthStorage’ = <factory>, test_function: ‘GenericTest | None’ = None, validate_schema: ‘bool’ = True, data_generation_methods: ‘list[DataGenerationMethod]’ = <factory>, generation_config: ‘GenerationConfig’ = <factory>, output_config: ‘OutputConfig’ = <factory>, code_sample_style: ‘CodeSampleStyle’ = <CodeSampleStyle.curl: ‘curl’>, rate_limiter: ‘Limiter | None’ = None, sanitize_output: ‘bool’ = True)

parametrize(method: Filter | None = <schemathesis.types.NotSet object>, endpoint: Filter | None = <schemathesis.types.NotSet object>, tag: Filter | None = <schemathesis.types.NotSet object>, operation_id: Filter | None = <schemathesis.types.NotSet object>, validate_schema: bool | NotSet = <schemathesis.types.NotSet object>, skip_deprecated_operations: bool | NotSet = <schemathesis.types.NotSet object>, data_generation_methods: Iterable[DataGenerationMethod] | NotSet = <schemathesis.types.NotSet object>, code_sample_style: str | NotSet = <schemathesis.types.NotSet object>) → Callable[source]: Mark a test function as a parametrized one.

given(*args: SearchStrategy | ellipsis, **kwargs: SearchStrategy | ellipsis) → Callable[source]: Proxy Hypothesis strategies to hypothesis.given.

as_state_machine() → type[APIStateMachine][source]: Create a state machine class.

class schemathesis.models.APIOperation[source]

A single operation defined in an API.

You can get one via a schema instance.

# Get the POST /items operation
operation = schema["/items"]["POST"]

Members:

validate_response(response: GenericResponse) → bool | None[source]

Validate API response for conformance.

Raises:: CheckFailed – If the response does not conform to the API schema.

is_response_valid(response: GenericResponse) → bool[source]: Validate API response for conformance.

Create a new example for this API operation.

The main use case is constructing Case instances completely manually, without data generation.

as_strategy(hooks: HookDispatcher | None = None, auth_storage: AuthStorage | None = None, data_generation_method: DataGenerationMethod = DataGenerationMethod.positive, generation_config: GenerationConfig | None = None, **kwargs: Any) → st.SearchStrategy[source]: Turn this API operation into a Hypothesis strategy.

Open API-specific API

class schemathesis.specs.openapi.schemas.BaseOpenAPISchema[source]

BaseOpenAPISchema(raw_schema: ‘dict[str, Any]’, transport: ‘Transport’, specification: ‘Specification’, location: ‘str | None’ = None, base_url: ‘str | None’ = None, filter_set: ‘FilterSet’ = <factory>, app: ‘Any’ = None, hooks: ‘HookDispatcher’ = <factory>, auth: ‘AuthStorage’ = <factory>, test_function: ‘GenericTest | None’ = None, validate_schema: ‘bool’ = True, data_generation_methods: ‘list[DataGenerationMethod]’ = <factory>, generation_config: ‘GenerationConfig’ = <factory>, output_config: ‘OutputConfig’ = <factory>, code_sample_style: ‘CodeSampleStyle’ = <CodeSampleStyle.curl: ‘curl’>, rate_limiter: ‘Limiter | None’ = None, sanitize_output: ‘bool’ = True, _operation_cache: ‘OperationCache’ = <factory>, _inline_reference_cache: ‘dict[str, Any]’ = <factory>, _inline_reference_cache_lock: ‘RLock’ = <factory>)

add_link(source: APIOperation, target: str | APIOperation, status_code: str | int, parameters: dict[str, str] | None = None, request_body: Any = None, name: str | None = None) → None[source]

Add a new Open API link to the schema definition.

Parameters:

source (APIOperation) – This operation is the source of data
target – This operation will receive the data from this link. Can be an APIOperation instance or a reference like this - #/paths/~1users~1{userId}/get
status_code (str) – The link is triggered when the source API operation responds with this status code.
parameters – A dictionary that describes how parameters should be extracted from the matched response. The key represents the parameter name in the target API operation, and the value is a runtime expression string.
request_body – A literal value or runtime expression to use as a request body when calling the target operation.
name (str) – Explicit link name.

schema = schemathesis.from_uri("http://0.0.0.0/schema.yaml")

schema.add_link(
    source=schema["/users/"]["POST"],
    target=schema["/users/{userId}"]["GET"],
    status_code="201",
    parameters={"userId": "$response.body#/id"},
)