Hooks Reference

Schema-Level Hooks

Hooks that execute during schema loading and operation initialization.

Data Generation Hooks

Control how test data is generated for each request component.

Where {component} is one of: path_parameters, headers, cookies, query, body, case

Request-Lifecycle Hooks

Hooks that execute during test case execution.

Success flow: before_call -> HTTP Request -> after_call -> Checks -> filter_failure -> after_validate

Return False from filter_failure to drop a failure. A dropped failure does not fail the run, does not spend the --max-failures budget, does not reach deduplication, and writes no crash file; the run reports how many were dropped:

@schemathesis.hook
def filter_failure(ctx, failure, case, response):
    # A flaky upstream is not this API's bug
    return response.status_code != 503

Filtered: 3 (dropped by `filter_failure`)

Use it for failures that depend on the response rather than on which operation was hit. For a fixed set of failures you have accepted and want reviewed, use a baseline instead. Network errors and failures raised from a check's after_run never reach this hook - they have no response to judge.

Network error flow: before_call -> HTTP Request -> after_network_error -> (re-raises)

CheckResult fields: name (check name), status (Status.SUCCESS or Status.FAILURE), failure (Failure instance or None).

Hook Registration

Hook Name Detection: If not specified, uses function name (must match hook name exactly).

Conditional Application

Apply hooks selectively using filters.

Filter Methods

Available Filters

Phase Compatibility

Not all hooks apply in every phase.

Examples phase runs test cases built from examples embedded in the schema. * Component-level hooks apply only to the parts Schemathesis generates to complete an example, such as a required parameter without an example, so map_headers can still add a header the example lacks. Values taken from schema examples are never changed by hooks. Case-level hooks (before_generate_case, filter_case, map_case, flatmap_case) have no effect on example cases. With fill-missing enabled, the case generated for an operation without examples gets all data generation hooks.

Coverage phase generates test cases from the schema based on coverage goals (boundary values, required/optional combinations, etc.). Cases bypass the strategy pipeline, so component-level hooks (filter_query, map_headers, etc.) have no effect.

Fuzzing phase uses Hypothesis data generation and respects all data generation hooks.

Stateful phase drives multi-step API workflows using a Hypothesis state machine. Each transition generates a new test case via the same strategy as the fuzzing phase, so all data generation hooks apply.

Schema-level hooks (before_load_schema, after_load_schema, before_process_path, before_init_operation) run during schema loading, before any test phase begins.

Execution Order

When multiple hooks of the same type are registered, they execute in registration order. For filter_* hooks, the value is discarded as soon as any hook returns False - subsequent hooks for that event are not called. For map_* hooks, each hook receives the output of the previous. For flatmap_* hooks, each hook receives the output of the previous, as with map_* hooks. Schema-level hooks run before test-level hooks of the same type.