Configuration¶

The configuration module provides the RouteTestConfig dataclass and related utilities for controlling pytest-routes behavior.

Overview¶

Configuration in pytest-routes follows a layered approach:

Built-in defaults - Sensible defaults for common use cases
pyproject.toml - Project-level configuration in [tool.pytest-routes]
CLI options - Command-line overrides for specific test runs

The merge_configs() function handles combining these layers with appropriate precedence.

Quick Start¶

Basic configuration for most projects:

from pytest_routes import RouteTestConfig

# Use defaults for most options
config = RouteTestConfig(
    max_examples=50,           # Fewer examples for faster tests
    exclude_patterns=[         # Skip health and docs endpoints
        "/health",
        "/metrics",
        "/docs",
    ],
)

Loading from pyproject.toml:

from pytest_routes import load_config_from_pyproject
from pathlib import Path

# Load from default location (./pyproject.toml)
config = load_config_from_pyproject()

# Or from a specific path
config = load_config_from_pyproject(Path("/path/to/pyproject.toml"))

Configuration Options¶

The following table summarizes all available configuration options:

Option	Default	Description
`max_examples`	100	Maximum Hypothesis examples per route
`timeout_per_route`	30.0	Timeout in seconds for each route test
`include_patterns`	[]	Route patterns to include (empty = all)
`exclude_patterns`	[“/health”, …]	Route patterns to exclude
`methods`	[“GET”, “POST”, …]	HTTP methods to test
`strategy`	“hybrid”	Data generation strategy
`seed`	None	Random seed for reproducibility
`allowed_status_codes`	[200-499]	Status codes that pass tests
`fail_on_5xx`	True	Fail tests on server errors
`validate_responses`	False	Enable response validation
`framework`	“auto”	Framework hint for route extraction

pyproject.toml Example¶

Configure pytest-routes in your project’s pyproject.toml:

[tool.pytest-routes]
max_examples = 50
timeout = 30.0
include = ["/api/*"]
exclude = ["/health", "/metrics", "/docs", "/openapi*"]
methods = ["GET", "POST", "PUT", "DELETE"]
strategy = "hybrid"
fail_on_5xx = true
allowed_status_codes = [200, 201, 204, 400, 401, 403, 404, 422]
framework = "litestar"
verbose = false

API Reference¶

RouteTestConfig¶

class pytest_routes.config.RouteTestConfig[source]¶

Bases: object

Configuration for route smoke testing.

Parameters:

max_examples (int)
timeout_per_route (float)
include_patterns (list[str])
exclude_patterns (list[str])
methods (list[str])
strategy (Literal['random', 'openapi', 'hybrid'])
seed (int | None)
allowed_status_codes (list[int])
fail_on_5xx (bool)
fail_on_validation_error (bool)
validate_responses (bool)
response_validators (list[str])
framework (Optional[Literal['auto', 'litestar', 'fastapi', 'starlette']])
verbose (bool)
auth (AuthProvider | None)
route_overrides (list[RouteOverride])
schemathesis (SchemathesisConfig)
report (ReportConfig)
stateful (StatefulTestConfig | None)
websocket (WebSocketTestConfig | None)

Example

from pytest_routes import RouteTestConfig

config = RouteTestConfig(
    max_examples=100,
    timeout_per_route=30.0,
    exclude_patterns=["/health", "/metrics"],
    fail_on_5xx=True,
    allowed_status_codes=list(range(200, 500)),
)

max_examples: int = 100¶

timeout_per_route: float = 30.0¶

include_patterns: list[str]¶

exclude_patterns: list[str]¶

methods: list[str]¶

strategy: Literal['random', 'openapi', 'hybrid'] = 'hybrid'¶

seed: int | None = None¶

allowed_status_codes: list[int]¶

fail_on_5xx: bool = True¶

fail_on_validation_error: bool = True¶

validate_responses: bool = False¶

response_validators: list[str]¶

framework: Optional[Literal['auto', 'litestar', 'fastapi', 'starlette']] = 'auto'¶

verbose: bool = False¶

auth: AuthProvider | None = None¶

route_overrides: list[RouteOverride]¶

schemathesis: SchemathesisConfig¶

report: ReportConfig¶

stateful: StatefulTestConfig | None = None¶

websocket: WebSocketTestConfig | None = None¶

get_override_for_route(path)[source]¶

Get the matching override for a route path.

Finds the first RouteOverride whose pattern matches the given path. Uses glob-style pattern matching.

Parameters:: path (str) – The route path to match.
Return type:: RouteOverride | None
Returns:: The first matching RouteOverride, or None if no match.

get_effective_config_for_route(path)[source]¶

Get effective configuration for a specific route.

Merges the base config with any matching route override.

Parameters:: path (str) – The route path to get config for.
Return type:: dict[str, Any]
Returns:: Dictionary with effective configuration values.

classmethod from_dict(data)[source]¶

Create config from dictionary (e.g., from pyproject.toml).

Parameters:: data (dict[str, Any]) – Dictionary containing configuration values.
Return type:: RouteTestConfig
Returns:: RouteTestConfig instance with values from dictionary.

Examples

>>> config_data = {
...     "max_examples": 50,
...     "timeout": 30.0,
...     "include": ["/api/*"],
...     "exclude": ["/health", "/metrics"],
...     "methods": ["GET", "POST"],
...     "fail_on_5xx": True,
...     "allowed_status_codes": [200, 201, 400, 404],
...     "seed": 12345,
...     "framework": "litestar",
... }
>>> config = RouteTestConfig.from_dict(config_data)
>>> config.max_examples
50

__init__(max_examples=100, timeout_per_route=30.0, include_patterns=<factory>, exclude_patterns=<factory>, methods=<factory>, strategy='hybrid', seed=None, allowed_status_codes=<factory>, fail_on_5xx=True, fail_on_validation_error=True, validate_responses=False, response_validators=<factory>, framework='auto', verbose=False, auth=None, route_overrides=<factory>, schemathesis=<factory>, report=<factory>, stateful=None, websocket=None)¶

Parameters:

max_examples (int)
timeout_per_route (float)
include_patterns (list[str])
exclude_patterns (list[str])
methods (list[str])
strategy (Literal['random', 'openapi', 'hybrid'])
seed (int | None)
allowed_status_codes (list[int])
fail_on_5xx (bool)
fail_on_validation_error (bool)
validate_responses (bool)
response_validators (list[str])
framework (Optional[Literal['auto', 'litestar', 'fastapi', 'starlette']])
verbose (bool)
auth (AuthProvider | None)
route_overrides (list[RouteOverride])
schemathesis (SchemathesisConfig)
report (ReportConfig)
stateful (StatefulTestConfig | None)
websocket (WebSocketTestConfig | None)

Configuration Functions¶

pytest_routes.config.load_config_from_pyproject(path=None)[source]¶

Load configuration from pyproject.toml [tool.pytest-routes] section.

Parameters:

path (Path | None) – Path to pyproject.toml file. If None, looks in current working directory.

Return type:

RouteTestConfig

Returns:

RouteTestConfig instance loaded from file, or defaults if file not found.

Raises:

ImportError – If tomllib/tomli is not available (Python < 3.11 and tomli not installed).
ValueError – If pyproject.toml contains invalid configuration.

Examples

>>> # Load from default location (./pyproject.toml)
>>> config = load_config_from_pyproject()
>>> # Load from specific path
>>> config = load_config_from_pyproject(Path("/path/to/pyproject.toml"))

pytest_routes.config.merge_configs(cli_config=None, file_config=None)[source]¶

Merge CLI and file configs, with CLI taking precedence.

Priority order (highest to lowest): 1. CLI options (if provided and not default) 2. pyproject.toml values 3. Built-in defaults

Parameters:

cli_config (RouteTestConfig | None) – Configuration from CLI options.
file_config (RouteTestConfig | None) – Configuration from pyproject.toml.

Return type:

RouteTestConfig

Returns:

Merged configuration with CLI options taking precedence.

Examples

>>> file_cfg = RouteTestConfig(max_examples=50, seed=123)
>>> cli_cfg = RouteTestConfig(max_examples=100)  # Override max_examples
>>> merged = merge_configs(cli_cfg, file_cfg)
>>> merged.max_examples  # From CLI
100
>>> merged.seed  # From file
123

Configuration¶

Overview¶

Quick Start¶

Configuration Options¶

pyproject.toml Example¶

API Reference¶

RouteTestConfig¶

Configuration Functions¶

See Also¶