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>)[source]
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)[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
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 [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.openapi.from_dict(schema: dict[str, Any]) BaseOpenAPISchema [source]
Base loader that others build upon.
- schemathesis.openapi.from_file(file: IO[str] | str) BaseOpenAPISchema [source]
Load from file-like object or string.
- schemathesis.openapi.from_path(path: PathLike | str, *, encoding: str = 'utf-8') BaseOpenAPISchema [source]
Load from a filesystem path.
- schemathesis.openapi.from_url(url: str, *, wait_for_schema: float | None = None, **kwargs: Any) BaseOpenAPISchema [source]
Load from URL.
- schemathesis.graphql.from_path(path: PathLike | str, *, encoding: str = 'utf-8') GraphQLSchema [source]
Load from a filesystem path.
- schemathesis.graphql.from_dict(schema: dict[str, Any]) GraphQLSchema [source]
Base loader that others build upon.
- schemathesis.graphql.from_file(file: IO[str] | str) GraphQLSchema [source]
Load from file-like object or string.
Sanitizing Output
Schema
- class schemathesis.schemas.BaseSchema[source]
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)
Open API-specific API
- class schemathesis.specs.openapi.schemas.BaseOpenAPISchema[source]
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 [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.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"}, )