API Reference¶

This section provides complete API documentation for pytest-routes, organized by functional area. All public APIs are fully documented with type hints, examples, and cross-references to related functionality.

Quick Reference¶

The most commonly used classes and functions, organized by task:

Task	API
Configure testing	`RouteTestConfig`
Extract routes	`RouteInfo`, `get_extractor()`
Generate test data	`strategy_for_type()`, `register_strategy()`
Execute tests	`RouteTestRunner`, `RouteTestClient`
Validate responses	`StatusCodeValidator`, `CompositeValidator`
Generate reports	`HTMLReportGenerator`, `RunMetrics`
Schemathesis integration	`SchemathesisAdapter`, `SchemathesisValidator`

Usage Examples¶

Importing the Public API¶

All public APIs are exported from the top-level pytest_routes package:

from pytest_routes import (
    # Configuration
    RouteTestConfig,
    load_config_from_pyproject,
    merge_configs,

    # Discovery
    RouteInfo,
    RouteExtractor,
    get_extractor,

    # Execution
    RouteTestClient,
    RouteTestRunner,
    RouteTestFailure,

    # Strategy generation
    strategy_for_type,
    register_strategy,
    unregister_strategy,
    register_strategies,
    get_registered_types,
    strategy_provider,
    temporary_strategy,

    # Header generation
    generate_headers,
    generate_optional_headers,
    register_header_strategy,

    # Validation
    ResponseValidator,
    ValidationResult,
    StatusCodeValidator,
    ContentTypeValidator,
    JsonSchemaValidator,
    OpenAPIResponseValidator,
    CompositeValidator,
)

Basic Usage Pattern¶

Here is a typical workflow for using the pytest-routes API programmatically:

from pytest_routes import (
    RouteTestConfig,
    get_extractor,
    RouteTestRunner,
)

# 1. Configure testing parameters
config = RouteTestConfig(
    max_examples=50,
    fail_on_5xx=True,
    exclude_patterns=["/health", "/metrics"],
)

# 2. Get the appropriate extractor for your app
extractor = get_extractor(app)

# 3. Extract routes from your application
routes = extractor.extract_routes(app)

# 4. Create a test runner
runner = RouteTestRunner(app, config)

# 5. Generate and execute tests
for route in routes:
    test_func = runner.create_test(route)
    test_func()  # Run the Hypothesis-powered test

Registering Custom Strategies¶

When your API uses custom types, register Hypothesis strategies for them:

from hypothesis import strategies as st
from pytest_routes import register_strategy, temporary_strategy

# Register a permanent strategy
register_strategy(
    MyCustomType,
    st.builds(MyCustomType, name=st.text(min_size=1, max_size=50))
)

# Or use a temporary strategy for a specific test
with temporary_strategy(MyCustomType, st.just(MyCustomType("test"))):
    # Strategy only active within this block
    result = strategy_for_type(MyCustomType).example()

Custom Response Validation¶

Combine multiple validators for comprehensive response checking:

from pytest_routes import (
    CompositeValidator,
    StatusCodeValidator,
    ContentTypeValidator,
    JsonSchemaValidator,
)

# Build a composite validator
validator = CompositeValidator([
    StatusCodeValidator(allowed_codes=[200, 201, 204]),
    ContentTypeValidator(expected_types=["application/json"]),
    JsonSchemaValidator(schema={
        "type": "object",
        "required": ["id", "name"],
    }),
])

# Use in your tests
result = validator.validate(response, route)
if not result.valid:
    print(f"Validation failed: {result.errors}")

API Modules¶

The API is organized into the following modules:

API Documentation

Module Overview¶

Configuration (pytest_routes.config): Controls test execution parameters including the number of examples, timeout settings, route filtering patterns, and validation options. See Configuration.
Discovery (pytest_routes.discovery): Extracts route information from ASGI applications. Includes framework-specific extractors for Litestar, Starlette, FastAPI, and OpenAPI schemas. See Route Discovery.
Generation (pytest_routes.generation): Creates Hypothesis strategies for generating test data including path parameters, query parameters, request bodies, and headers. See Strategy Generation.
Execution (pytest_routes.execution): Runs property-based tests against routes using the generated data and validates responses according to configuration. See Test Execution.
Validation (pytest_routes.validation): Validates HTTP responses against expected schemas, status codes, and content types. Supports OpenAPI schema validation. See Response Validation.
Reporting (pytest_routes.reporting): Generates HTML and JSON reports with test metrics, coverage statistics, and performance timing data. See Reporting.
Integrations (pytest_routes.integrations): Provides adapters for external testing tools like Schemathesis for OpenAPI contract testing. See Integrations.

Plugin Integration¶

The pytest plugin module provides integration with pytest’s collection and execution hooks. This module is typically not used directly but is loaded automatically when pytest-routes is installed.

Pytest plugin for route smoke testing.

pytest_routes.plugin.route_config(request)[source]¶

Build configuration from CLI options and pyproject.toml.

Configuration priority (highest to lowest): 1. CLI options 2. pyproject.toml [tool.pytest-routes] 3. Built-in defaults

Parameters:: request (FixtureRequest)
Return type:: RouteTestConfig

pytest_routes.plugin.asgi_app(request)[source]¶

Load the ASGI application.

Parameters:: request (FixtureRequest)
Return type:: Any

pytest_routes.plugin.discovered_routes(asgi_app, route_config)[source]¶

Discover routes from the ASGI application.

Parameters:

asgi_app (Any)
route_config (RouteTestConfig)

Return type:

list[RouteInfo]

pytest_routes.plugin.route_runner(asgi_app, route_config)[source]¶

Provide configured test runner.

Parameters:

asgi_app (Any)
route_config (RouteTestConfig)

Return type:

RouteTestRunner

class pytest_routes.plugin.RouteTestItem[source]¶

Bases: Item

Custom pytest Item for individual route smoke tests.

This class represents a single test case for a discovered route. Each RouteTestItem executes property-based tests against one route using Hypothesis to generate test data. The item is created during pytest’s collection phase and executed during the test phase.

Variables:

route – The RouteInfo object containing route metadata (path, methods, parameters).
runner – The RouteTestRunner instance used to execute the route test.

Parameters:

name (str)
parent (Collector)
route (RouteInfo)
runner (RouteTestRunner)

__init__(name, parent, route, runner)[source]¶

Initialize a RouteTestItem.

Parameters:

name (str) – The test item name (e.g., “test_GET_users_id”).
parent (Collector) – The parent pytest Collector that owns this item.
route (RouteInfo) – The RouteInfo object describing the route to test.
runner (RouteTestRunner) – The RouteTestRunner instance for executing route tests.

runtest()[source]¶

Execute the route smoke test.

This pytest hook runs the actual test logic for this item. It executes the async route test using the RouteTestRunner, handling the async/sync boundary with asyncio. The test uses Hypothesis to generate multiple examples of valid requests and validates the route’s responses.

Raises:: RouteTestError – If the route test fails (e.g., unexpected status code, validation error, or exception during test execution).
Return type:: None

repr_failure(excinfo, style=None)[source]¶

Represent a test failure for reporting.

This pytest hook formats the failure output shown to users when a test fails. For RouteTestError exceptions, it provides a custom formatted message with route details and error information. For other exceptions, it delegates to the default pytest failure representation.

Parameters:

excinfo (ExceptionInfo[BaseException]) – Exception information captured by pytest.
style (str | None) – Optional formatting style for the failure representation.

Return type:

str

Returns:

A formatted string representation of the test failure.

reportinfo()[source]¶

Report test information for pytest’s output.

This pytest hook provides metadata about the test for reporting purposes, including the file path, line number (if applicable), and a human-readable description of what’s being tested.

Returns:

file_path: Path to the test file (str)
line_number: Line number in the file (None for synthetic tests)
description: Human-readable test description (e.g., “GET, POST /users/{id}”)

Return type:

A tuple of (file_path, line_number, description) where

config: Config¶: The pytest config object.

name: str¶: A unique name within the scope of the parent node.

parent¶: The parent collector node.

path: pathlib.Path¶: Filesystem path where this node was collected from (can be None).

session: Session¶: The pytest session this node is part of.

exception pytest_routes.plugin.RouteTestError[source]¶

Bases: Exception

Exception raised when a route smoke test fails.

This exception is raised by RouteTestItem.runtest() when a route test does not pass. It contains the route information and error details for reporting.

Variables:

route – The RouteInfo object for the route that failed testing.
error – A string describing what went wrong during the test.

Parameters:

route (RouteInfo)
error (str)

__init__(route, error)[source]¶

Initialize a RouteTestError.

Parameters:

route (RouteInfo) – The RouteInfo object for the route that failed.
error (str) – Description of the test failure (e.g., “Expected 200, got 500”).

class pytest_routes.plugin.StatefulTestItem[source]¶

Bases: Item

Custom pytest Item for stateful API testing.

This item represents a stateful test execution using Hypothesis state machines to test API workflows and sequences.

Variables:

runner – The StatefulTestRunner instance for executing stateful tests.
stateful_config – The StatefulTestConfig with test parameters.

Parameters:

name (str)
parent (Collector)
runner (Any)

__init__(name, parent, runner)[source]¶

Initialize a StatefulTestItem.

Parameters:

name (str) – The test item name.
parent (Collector) – The parent pytest Collector.
runner (Any) – The StatefulTestRunner instance.

runtest()[source]¶

Execute the stateful test.

Runs the state machine and collects results. Raises an exception if any test sequences fail.

Raises:

StatefulTestError – If any stateful test sequences fail.
pytest.skip.Exception – If the app doesn’t have OpenAPI schema.

Return type:

None

repr_failure(excinfo, style=None)[source]¶

Represent a test failure for reporting.

Parameters:

excinfo (ExceptionInfo[BaseException]) – Exception information captured by pytest.
style (str | None) – Optional formatting style for the failure representation.

Return type:

str

Returns:

A formatted string representation of the test failure.

reportinfo()[source]¶

Report test information for pytest’s output.

Return type:: tuple[str, int | None, str]
Returns:: A tuple of (file_path, line_number, description).

config: Config¶: The pytest config object.

name: str¶: A unique name within the scope of the parent node.

parent¶: The parent collector node.

path: pathlib.Path¶: Filesystem path where this node was collected from (can be None).

session: Session¶: The pytest session this node is part of.

exception pytest_routes.plugin.StatefulTestError[source]¶

Bases: Exception

Exception raised when stateful tests fail.

class pytest_routes.plugin.WebSocketTestItem[source]¶

Bases: Item

Custom pytest Item for WebSocket route testing.

This item represents a WebSocket test execution for a single route.

Variables:

route – The RouteInfo for the WebSocket route.
runner – The WebSocketTestRunner instance.

Parameters:

name (str)
parent (Collector)
route (RouteInfo)
runner (Any)

__init__(name, parent, route, runner)[source]¶

Initialize a WebSocketTestItem.

Parameters:

name (str) – The test item name.
parent (Collector) – The parent pytest Collector.
route (RouteInfo) – The RouteInfo for the WebSocket route.
runner (Any) – The WebSocketTestRunner instance.

runtest()[source]¶

Execute the WebSocket test.

Runs property-based tests against the WebSocket route.

Raises:: WebSocketTestError – If the WebSocket test fails.
Return type:: None

repr_failure(excinfo, style=None)[source]¶

Represent a test failure for reporting.

Parameters:

excinfo (ExceptionInfo[BaseException]) – Exception information captured by pytest.
style (str | None) – Optional formatting style for the failure representation.

Return type:

str

Returns:

A formatted string representation of the test failure.

reportinfo()[source]¶

Report test information for pytest’s output.

Return type:: tuple[str, int | None, str]
Returns:: A tuple of (file_path, line_number, description).

config: Config¶: The pytest config object.

name: str¶: A unique name within the scope of the parent node.

parent¶: The parent collector node.

path: pathlib.Path¶: Filesystem path where this node was collected from (can be None).

session: Session¶: The pytest session this node is part of.

exception pytest_routes.plugin.WebSocketTestError[source]¶

Bases: Exception

Exception raised when a WebSocket test fails.

Variables:

route – The RouteInfo for the route that failed.
error – Description of the test failure.

Parameters:

route (RouteInfo)
error (str)

__init__(route, error)[source]¶

Initialize a WebSocketTestError.

Parameters:

route (RouteInfo) – The RouteInfo for the route that failed.
error (str) – Description of the test failure.

class pytest_routes.plugin.RouteTestCollector[source]¶

Bases: Collector

Pytest Collector for route smoke tests.

This collector is responsible for discovering and creating RouteTestItem instances from the globally discovered routes. It’s part of pytest’s collection phase and generates test items based on the routes found during plugin configuration.

Note

This collector is currently not actively used in favor of the pytest_collection_modifyitems hook, but is kept for potential future use or alternative collection strategies.

Parameters:

name (str)
parent (Collector)

__init__(name, parent)[source]¶

Parameters:

name (str)
parent (Collector)

collect()[source]¶

Collect route tests from discovered routes.

This pytest hook creates RouteTestItem instances for each discovered route. It’s called during pytest’s collection phase to gather all tests to be run.

Return type:: list[RouteTestItem]
Returns:: A list of RouteTestItem instances, one for each discovered route. Returns an empty list if route testing is disabled or no routes were discovered.

config: Config¶: The pytest config object.

name: str¶: A unique name within the scope of the parent node.

parent¶: The parent collector node.

path: pathlib.Path¶: Filesystem path where this node was collected from (can be None).

session: Session¶: The pytest session this node is part of.

pytest_routes.plugin.pytest_unconfigure(config)[source]¶

Clean up plugin state after test run.

This pytest hook resets the global state used by the plugin, ensuring that subsequent test runs start with a clean slate. It’s called when pytest is shutting down or when a test session completes.

Parameters:: config (Config) – The pytest Config object.
Return type:: None

API Reference¶

Quick Reference¶

Usage Examples¶

Importing the Public API¶

Basic Usage Pattern¶

Registering Custom Strategies¶

Custom Response Validation¶

API Modules¶

Module Overview¶

Plugin Integration¶

Indices and Tables¶