Public API reference

Checks

schemathesis.check(item: T) → T

Data Generation

class schemathesis.GenerationConfig(modes: list[schemathesis.generation.modes.GenerationMode] = <factory>, allow_x00: bool = True, graphql_allow_null: bool = True, codec: str | None = 'utf-8', with_security_parameters: bool = True, headers: ~schemathesis.generation.HeaderConfig = <factory>)

Holds various configuration options relevant for data generation.

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)

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

get(case: Case, context: AuthContext) → Auth | None

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

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)

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)

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

Targeted testing

schemathesis.target(item: T) → T

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

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.openapi.from_asgi(path: str, app: Any, **kwargs: Any) → BaseOpenAPISchema

schemathesis.openapi.from_dict(schema: dict[str, Any]) → BaseOpenAPISchema

Base loader that others build upon.

schemathesis.openapi.from_file(file: IO[str] | str) → BaseOpenAPISchema

Load from file-like object or string.

schemathesis.openapi.from_path(path: PathLike | str, *, encoding: str = 'utf-8') → BaseOpenAPISchema

Load from a filesystem path.

schemathesis.openapi.from_url(url: str, *, wait_for_schema: float | None = None, **kwargs: Any) → BaseOpenAPISchema

Load from URL.

schemathesis.openapi.from_wsgi(path: str, app: Any, **kwargs: Any) → BaseOpenAPISchema

schemathesis.graphql.from_path(path: PathLike | str, *, encoding: str = 'utf-8') → GraphQLSchema

Load from a filesystem path.

schemathesis.graphql.from_dict(schema: dict[str, Any]) → GraphQLSchema

Base loader that others build upon.

schemathesis.graphql.from_file(file: IO[str] | str) → GraphQLSchema

Load from file-like object or string.

schemathesis.graphql.from_url(url: str, *, wait_for_schema: float | None = None, **kwargs: Any) → GraphQLSchema

Load from URL.

schemathesis.graphql.from_asgi(path: str, app: Any, **kwargs: Any) → GraphQLSchema

schemathesis.graphql.from_wsgi(path: str, app: Any, **kwargs: Any) → GraphQLSchema

schemathesis.pytest.from_fixture(name: str) → LazySchema

Sanitizing Output

Schema

class schemathesis.schemas.BaseSchema

BaseSchema(raw_schema: ‘dict[str, Any]’, location: ‘str | None’ = None, base_url: ‘str | None’ = None, filter_set: ‘FilterSet’ = <factory>, app: ‘Any’ = None, hooks: ‘HookDispatcher’ = <factory>, auth: ‘AuthStorage’ = <factory>, test_function: ‘Callable | None’ = None, generation_config: ‘GenerationConfig’ = <factory>, output_config: ‘OutputConfig’ = <factory>, rate_limiter: ‘Limiter | None’ = None)

parametrize() → Callable

Mark a test function as a parametrized one.

given(*args: GivenInput, **kwargs: GivenInput) → Callable

Proxy Hypothesis strategies to hypothesis.given.

as_state_machine() → type[APIStateMachine]

Create a state machine class.

Open API-specific API

class schemathesis.specs.openapi.schemas.BaseOpenAPISchema

BaseOpenAPISchema(raw_schema: ‘dict[str, Any]’, location: ‘str | None’ = None, base_url: ‘str | None’ = None, filter_set: ‘FilterSet’ = <factory>, app: ‘Any’ = None, hooks: ‘HookDispatcher’ = <factory>, auth: ‘AuthStorage’ = <factory>, test_function: ‘Callable | None’ = None, generation_config: ‘GenerationConfig’ = <factory>, output_config: ‘OutputConfig’ = <factory>, rate_limiter: ‘Limiter | None’ = None, _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

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.openapi.from_url("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"},
)