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(response, case):
    # some awesome assertions!
    ...

Data Generation

class schemathesis.GenerationConfig(allow_x00: bool = True, codec: str | None = 'utf-8')[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) 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

Register a new hook.

Parameters:

hook – Either a hook function or a string.

Can be used as a decorator in two forms. Without arguments for registering hooks and autodetecting their names:

@schemathesis.hook
def before_generate_query(context, strategy):
    ...

With a hook name as the first argument:

@schemathesis.hook("before_generate_query")
def hook(context, strategy):
    ...
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 = False, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | 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 = False, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | 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 = False, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>,), generation_config: GenerationConfig | 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 = False, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | 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 = False, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | 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 = False, validate_schema: bool = False, data_generation_methods: DataGenerationMethodInput | NotSet = <schemathesis.types.NotSet object>, generation_config: GenerationConfig | 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 = False, validate_schema: bool = False, force_schema_version: str | 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) 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 = False, validate_schema: bool = False, force_schema_version: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | 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_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, 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_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_wsgi(schema_path: str, app: Any, *, base_url: str | None = None, data_generation_methods: DataGenerationMethodInput = (<DataGenerationMethod.positive: 'positive'>, ), generation_config: GenerationConfig | 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]’, location: ‘str | None’ = None, base_url: ‘str | None’ = None, method: ‘Filter | None’ = None, endpoint: ‘Filter | None’ = None, tag: ‘Filter | None’ = None, operation_id: ‘Filter | None’ = None, app: ‘Any’ = None, hooks: ‘HookDispatcher’ = <factory>, auth: ‘AuthStorage’ = <factory>, test_function: ‘GenericTest | None’ = None, validate_schema: ‘bool’ = True, skip_deprecated_operations: ‘bool’ = False, data_generation_methods: ‘list[DataGenerationMethod]’ = <factory>, generation_config: ‘GenerationConfig’ = <factory>, code_sample_style: ‘CodeSampleStyle’ = <CodeSampleStyle.curl: ‘curl’>, rate_limiter: ‘Limiter | None’ = None, sanitize_output: ‘bool’ = True)

parametrize(method: str | ~typing.List[str] | ~typing.Tuple[str] | ~typing.Set[str] | ~schemathesis.types.NotSet | None = <schemathesis.types.NotSet object>, endpoint: str | ~typing.List[str] | ~typing.Tuple[str] | ~typing.Set[str] | ~schemathesis.types.NotSet | None = <schemathesis.types.NotSet object>, tag: str | ~typing.List[str] | ~typing.Tuple[str] | ~typing.Set[str] | ~schemathesis.types.NotSet | None = <schemathesis.types.NotSet object>, operation_id: str | ~typing.List[str] | ~typing.Tuple[str] | ~typing.Set[str] | ~schemathesis.types.NotSet | None = <schemathesis.types.NotSet object>, validate_schema: bool | ~schemathesis.types.NotSet = <schemathesis.types.NotSet object>, skip_deprecated_operations: bool | ~schemathesis.types.NotSet = <schemathesis.types.NotSet object>, data_generation_methods: ~typing.Iterable[~schemathesis.generation.DataGenerationMethod] | ~schemathesis.types.NotSet = <schemathesis.types.NotSet object>, code_sample_style: str | ~schemathesis.types.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[schemathesis.stateful.state_machine.APIStateMachine][source]

Create a state machine class.

Use it for stateful testing.

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.

make_case(*, path_parameters: ~typing.Dict[str, ~typing.Any] | None = None, headers: ~typing.Dict[str, ~typing.Any] | None = None, cookies: ~typing.Dict[str, ~typing.Any] | None = None, query: ~typing.Dict[str, ~typing.Any] | None = None, body: ~typing.List | ~typing.Dict[str, ~typing.Any] | str | int | float | bool | bytes | ~schemathesis.types.NotSet = <schemathesis.types.NotSet object>, media_type: str | None = None) C[source]

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]’, location: ‘str | None’ = None, base_url: ‘str | None’ = None, method: ‘Filter | None’ = None, endpoint: ‘Filter | None’ = None, tag: ‘Filter | None’ = None, operation_id: ‘Filter | None’ = None, app: ‘Any’ = None, hooks: ‘HookDispatcher’ = <factory>, auth: ‘AuthStorage’ = <factory>, test_function: ‘GenericTest | None’ = None, validate_schema: ‘bool’ = True, skip_deprecated_operations: ‘bool’ = False, data_generation_methods: ‘list[DataGenerationMethod]’ = <factory>, generation_config: ‘GenerationConfig’ = <factory>, code_sample_style: ‘CodeSampleStyle’ = <CodeSampleStyle.curl: ‘curl’>, rate_limiter: ‘Limiter | None’ = None, sanitize_output: ‘bool’ = True, _inline_reference_cache: ‘dict[str, Any]’ = <factory>, _inline_reference_cache_lock: ‘RLock’ = <factory>, _override: ‘CaseOverride | None’ = None)

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"},
)