CLI Options Reference¶

pytest-routes adds several command-line options to pytest for controlling smoke test behavior.

Quick Reference¶

The following table summarizes all available CLI options:

CLI Options Summary¶
Option	Default	Description
`--routes`	`false`	Enable route smoke testing
`--routes-app`	`None`	Import path to ASGI application (`module:attribute`)
`--routes-max-examples`	`100`	Maximum Hypothesis examples per route
`--routes-include`	`[]`	Comma-separated glob patterns for routes to include
`--routes-exclude`	See below	Comma-separated glob patterns for routes to exclude
`--routes-methods`	`GET,POST,PUT,PATCH,DELETE`	HTTP methods to test
`--routes-seed`	`None`	Random seed for reproducible tests
`--routes-schemathesis`	`false`	Enable Schemathesis OpenAPI contract testing
`--routes-schemathesis-schema-path`	`/openapi.json`	Path to OpenAPI schema endpoint
`--routes-stateful`	`false`	Enable stateful API testing
`--routes-stateful-step-count`	`50`	Maximum steps per stateful test sequence
`--routes-websocket`	`false`	Enable WebSocket route testing
`--routes-ws-max-messages`	`10`	Maximum messages per WebSocket test
`--routes-report`	`None`	Generate HTML report at specified path
`--routes-report-json`	`None`	Generate JSON report at specified path
`--routes-report-title`	`pytest-routes Report`	Custom title for HTML report

Core Options¶

`--routes`¶

Enable route smoke testing. Required - without this flag, pytest-routes does not run any tests.

# Enable smoke testing
pytest --routes

# Combine with other pytest options
pytest --routes -v --tb=short

Note

This flag exists to prevent pytest-routes from running during normal test runs. Add it only when you specifically want to run smoke tests.

`--routes-app`¶

Specify the import path to your ASGI application.

Format: module:attribute or module.submodule:attribute

Default: None (uses app fixture from conftest.py)

# Simple module import
pytest --routes --routes-app myapp:app

# Nested module import
pytest --routes --routes-app myapp.main:application

# Package with factory function
pytest --routes --routes-app "myapp.factory:create_app()"

Example import paths:

Import Path	Python Equivalent
`myapp:app`	`from myapp import app`
`myapp.main:application`	`from myapp.main import application`
`myapp.factory:create_app()`	`from myapp.factory import create_app; app = create_app()`

Tip

If you don’t specify --routes-app, pytest-routes looks for an app fixture in your conftest.py. This is useful for applications that require setup before use.

Test Intensity Options¶

`--routes-max-examples`¶

Maximum number of Hypothesis examples to generate per route.

Default: 100

# Quick smoke test (10 examples per route)
pytest --routes --routes-app myapp:app --routes-max-examples 10

# Standard testing (100 examples per route)
pytest --routes --routes-app myapp:app --routes-max-examples 100

# Thorough testing (500 examples per route)
pytest --routes --routes-app myapp:app --routes-max-examples 500

Recommendations by use case:

Use Case	Examples	Rationale
Development	`5-10`	Fast feedback loop, catch obvious issues
Pre-commit	`25-50`	Balance between speed and coverage
CI/CD	`100-200`	Thorough testing, acceptable runtime
Pre-release	`500+`	Maximum coverage before deployment

Warning

Higher values significantly increase test runtime. For an app with 50 routes, --routes-max-examples 500 generates 25,000 total test cases.

Route Filtering Options¶

`--routes-include`¶

Comma-separated list of glob patterns for routes to include. Only routes matching at least one pattern will be tested.

Default: [] (empty - include all routes)

Glob syntax:

* matches any characters within a single path segment
** matches any characters including path separators (recursive)

# Test only API routes (single segment)
pytest --routes --routes-app myapp:app --routes-include "/api/*"
# Matches: /api/users, /api/orders
# Does NOT match: /api/users/123, /api/v2/users

# Test API routes recursively
pytest --routes --routes-app myapp:app --routes-include "/api/**"
# Matches: /api/users, /api/users/123, /api/v2/users/456

# Test multiple path patterns
pytest --routes --routes-app myapp:app --routes-include "/users/*,/orders/*"

# Test all v2 API routes
pytest --routes --routes-app myapp:app --routes-include "/api/v2/**"

`--routes-exclude`¶

Comma-separated list of glob patterns for routes to exclude. Routes matching any pattern will be skipped.

Default: /health,/metrics,/openapi*,/docs,/redoc,/schema

# Exclude specific routes
pytest --routes --routes-app myapp:app --routes-exclude "/health,/metrics"

# Exclude internal routes
pytest --routes --routes-app myapp:app --routes-exclude "/internal/*,/admin/*"

# Exclude auth routes that require setup
pytest --routes --routes-app myapp:app --routes-exclude "/auth/*,/login,/logout"

# Clear default excludes (test everything)
pytest --routes --routes-app myapp:app --routes-exclude ""

Note

When both --routes-include and --routes-exclude are specified, a route must:

Match at least one include pattern, AND
NOT match any exclude pattern

Example: Testing API routes except internal ones:

pytest --routes --routes-app myapp:app \
    --routes-include "/api/**" \
    --routes-exclude "/api/internal/*"

HTTP Method Options¶

`--routes-methods`¶

Comma-separated list of HTTP methods to test.

Default: GET,POST,PUT,PATCH,DELETE

# Test only GET requests (safe, read-only)
pytest --routes --routes-app myapp:app --routes-methods "GET"

# Test only write operations
pytest --routes --routes-app myapp:app --routes-methods "POST,PUT,DELETE"

# Include HEAD requests
pytest --routes --routes-app myapp:app --routes-methods "GET,HEAD"

# Test all methods including OPTIONS
pytest --routes --routes-app myapp:app --routes-methods "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS"

Common method combinations:

Methods	Use Case
`GET`	Read-only smoke test, safe for production-like data
`GET,POST`	Test reads and creates, skip updates/deletes
`POST,PUT,PATCH,DELETE`	Test only write operations
`GET,HEAD,OPTIONS`	Test metadata endpoints

Reproducibility Options¶

`--routes-seed`¶

Set a random seed for reproducible test runs. Essential for debugging failures and consistent CI/CD behavior.

Default: None (random seed each run)

# Use a specific seed
pytest --routes --routes-app myapp:app --routes-seed 12345

# Reproduce a failing test from CI
pytest --routes --routes-app myapp:app --routes-seed 98765

# Use CI run ID for reproducibility
pytest --routes --routes-app myapp:app --routes-seed $GITHUB_RUN_ID

When a test fails, pytest-routes reports the seed used:

FAILED test_routes[GET /users/{id}] - AssertionError: Status 500
  Seed: 98765
  Input: {"id": 42, "include_deleted": true}

To reproduce:
  pytest --routes --routes-app myapp:app --routes-seed 98765

Tip

In CI/CD, use the run ID or commit SHA as the seed. This gives you reproducibility within a run while still getting varied test inputs across different runs.

Combining Options¶

Options can be combined for fine-grained control:

# Full example with all options
pytest --routes \
    --routes-app myapp:app \
    --routes-max-examples 50 \
    --routes-include "/api/*" \
    --routes-exclude "/api/internal/*,/api/admin/*" \
    --routes-methods "GET,POST" \
    --routes-seed 12345

Configuration File Alternative¶

All CLI options can also be configured in pyproject.toml. CLI options always take precedence over file configuration.

# pyproject.toml
[tool.pytest-routes]
app = "myapp:app"
max_examples = 50
include = ["/api/*"]
exclude = ["/health", "/metrics", "/api/internal/*"]
methods = ["GET", "POST"]
seed = 12345

See Configuration for complete details.

Usage Examples¶

Development: Quick Validation¶

Fast smoke test during local development:

pytest --routes \
    --routes-app myapp:app \
    --routes-max-examples 5 \
    -x  # Stop on first failure

CI Pipeline: Thorough Testing¶

Comprehensive testing in CI with reproducibility:

pytest --routes \
    --routes-app myapp:app \
    --routes-max-examples 200 \
    --routes-seed $GITHUB_RUN_ID \
    --tb=short  # Shorter tracebacks

Feature Development: Testing New Routes¶

Test only routes in a specific module:

pytest --routes \
    --routes-app myapp:app \
    --routes-include "/api/v2/users/*" \
    --routes-max-examples 100 \
    -v  # Verbose output

Pre-Deployment: Comprehensive Check¶

Full smoke test before deployment:

pytest --routes \
    --routes-app myapp:app \
    --routes-max-examples 500 \
    --routes-exclude "/health" \
    --routes-seed $(date +%s)  # Timestamp seed for reproducibility

Read-Only Testing: Safe for Production Data¶

Test only GET endpoints (safe with real data):

pytest --routes \
    --routes-app myapp:app \
    --routes-methods "GET" \
    --routes-exclude "/admin/*"

Schemathesis Integration Options¶

`--routes-schemathesis`¶

Enable Schemathesis OpenAPI contract testing. When enabled, pytest-routes validates responses against your OpenAPI schema for conformance.

Default: false

# Enable Schemathesis contract testing
pytest --routes --routes-app myapp:app --routes-schemathesis

# Combine with custom schema path
pytest --routes --routes-app myapp:app --routes-schemathesis --routes-schemathesis-schema-path /api/openapi.json

uv (recommended)

uv add "pytest-routes[schemathesis]"

pip

pip install "pytest-routes[schemathesis]"

Schemathesis validates:

Status code conformance (response codes match schema)
Content-type conformance (response content types match schema)
Response schema conformance (response body matches schema)

`--routes-schemathesis-schema-path`¶

Path to the OpenAPI schema endpoint on your application.

Default: /openapi.json

# Custom schema path
pytest --routes --routes-app myapp:app --routes-schemathesis --routes-schemathesis-schema-path /api/v2/openapi.json

# Litestar default
pytest --routes --routes-app myapp:app --routes-schemathesis --routes-schemathesis-schema-path /schema/openapi.json

# FastAPI default
pytest --routes --routes-app myapp:app --routes-schemathesis --routes-schemathesis-schema-path /openapi.json

Report Generation Options¶

`--routes-report`¶

Generate an HTML report at the specified path. The report includes:

Test summary with pass/fail counts
Route-by-route results with timing metrics
Coverage statistics
Performance metrics (min/max/avg response times)

Default: None (no report generated)

# Generate HTML report
pytest --routes --routes-app myapp:app --routes-report pytest-routes-report.html

# Generate report with custom title
pytest --routes --routes-app myapp:app --routes-report report.html --routes-report-title "API Smoke Test Results"

`--routes-report-json`¶

Generate a JSON report at the specified path. Useful for CI/CD integration and programmatic analysis.

Default: None (no JSON report generated)

# Generate JSON report
pytest --routes --routes-app myapp:app --routes-report-json results.json

# Generate both HTML and JSON reports
pytest --routes --routes-app myapp:app --routes-report report.html --routes-report-json results.json

JSON report structure:

{
  "title": "pytest-routes Report",
  "generated_at": "2025-01-15T10:30:00Z",
  "summary": {
    "total_routes": 25,
    "passed": 23,
    "failed": 2,
    "pass_rate": 92.0,
    "duration_seconds": 45.3
  },
  "routes": [
    {
      "path": "/users",
      "method": "GET",
      "passed": true,
      "total_requests": 100,
      "avg_time_ms": 12.5,
      "min_time_ms": 5.2,
      "max_time_ms": 45.8
    }
  ]
}

`--routes-report-title`¶

Custom title for the HTML report.

Default: pytest-routes Report

# Custom report title
pytest --routes --routes-app myapp:app --routes-report report.html --routes-report-title "Production API Smoke Tests - v2.0"

Report Configuration in pyproject.toml¶

Reports can also be configured in pyproject.toml:

[tool.pytest-routes.report]
enabled = true
output_path = "pytest-routes-report.html"
json_output = "pytest-routes-report.json"
title = "API Route Tests"
include_coverage = true
include_timing = true
theme = "light"  # or "dark"

Stateful Testing Options¶

Stateful testing validates API workflows where operations depend on each other. For complete documentation, see Stateful Testing.

`--routes-stateful`¶

Enable stateful API testing mode. Tests CRUD workflows and operation sequences using Hypothesis state machines.

Default: false

# Enable stateful testing
pytest --routes --routes-app myapp:app --routes-stateful

# Combine with regular route testing
pytest --routes --routes-app myapp:app --routes-stateful --routes-max-examples 50

Note

Stateful testing requires an OpenAPI schema with link definitions for best results. Enable with --routes-schemathesis for schema-based validation.

`--routes-stateful-mode`¶

Select the stateful testing mode.

Default: links

Options:

links - Use OpenAPI links to determine state transitions (recommended)
data_dependency - Infer dependencies from request/response schemas
explicit - Use manually configured transition rules

# Use OpenAPI links (default)
pytest --routes --routes-app myapp:app --routes-stateful --routes-stateful-mode links

# Infer from schemas (useful when no links defined)
pytest --routes --routes-app myapp:app --routes-stateful --routes-stateful-mode data_dependency

`--routes-stateful-step-count`¶

Maximum number of API calls (steps) per test sequence.

Default: 50

# Quick smoke test
pytest --routes --routes-app myapp:app --routes-stateful --routes-stateful-step-count 10

# Thorough workflow testing
pytest --routes --routes-app myapp:app --routes-stateful --routes-stateful-step-count 100

`--routes-stateful-max-examples`¶

Number of test sequences (examples) to generate.

Default: 100

# Fewer sequences for development
pytest --routes --routes-app myapp:app --routes-stateful --routes-stateful-max-examples 10

# Many sequences for CI
pytest --routes --routes-app myapp:app --routes-stateful --routes-stateful-max-examples 200

`--routes-stateful-seed`¶

Random seed for reproducible stateful tests.

Default: None

# Reproducible test run
pytest --routes --routes-app myapp:app --routes-stateful --routes-stateful-seed 12345

# Use CI run ID
pytest --routes --routes-app myapp:app --routes-stateful --routes-stateful-seed $GITHUB_RUN_ID

`--routes-stateful-recursion-limit`¶

Maximum depth for nested state transitions.

Default: 5

pytest --routes --routes-app myapp:app --routes-stateful --routes-stateful-recursion-limit 10

`--routes-stateful-fail-fast`¶

Stop on first failure instead of collecting all failures.

Default: false

pytest --routes --routes-app myapp:app --routes-stateful --routes-stateful-fail-fast

`--routes-stateful-verbose`¶

Enable detailed logging of state machine execution.

Default: false

pytest --routes --routes-app myapp:app --routes-stateful --routes-stateful-verbose

`--routes-stateful-include` / `--routes-stateful-exclude`¶

Filter which operations to include or exclude from stateful testing.

Default: "" (empty - include all)

# Only test user operations
pytest --routes --routes-app myapp:app --routes-stateful \
    --routes-stateful-include "create*User*,get*User*,update*User*"

# Exclude admin operations
pytest --routes --routes-app myapp:app --routes-stateful \
    --routes-stateful-exclude "*Admin*,*Internal*"

Stateful Testing Configuration in pyproject.toml¶

[tool.pytest-routes.stateful]
enabled = true
mode = "links"
step_count = 50
max_examples = 100
stateful_recursion_limit = 5
fail_fast = false
collect_coverage = true
exclude_operations = ["*Admin*"]

See Stateful Testing for complete documentation.

WebSocket Testing Options¶

WebSocket testing validates real-time endpoints with property-based message generation. For complete documentation, see WebSocket Testing.

`--routes-websocket`¶

Enable WebSocket route testing.

Default: false

# Enable WebSocket testing
pytest --routes --routes-app myapp:app --routes-websocket

# Combine with HTTP route testing
pytest --routes --routes-app myapp:app --routes-websocket

`--routes-ws-max-messages`¶

Maximum number of messages per test sequence.

Default: 10

# Quick test with few messages
pytest --routes --routes-app myapp:app --routes-websocket --routes-ws-max-messages 3

# Thorough testing with many messages
pytest --routes --routes-app myapp:app --routes-websocket --routes-ws-max-messages 50

`--routes-ws-timeout`¶

WebSocket connection timeout in seconds.

Default: 30.0

# Extended timeout for slow handlers
pytest --routes --routes-app myapp:app --routes-websocket --routes-ws-timeout 60.0

`--routes-ws-message-timeout`¶

Timeout for receiving messages in seconds.

Default: 10.0

pytest --routes --routes-app myapp:app --routes-websocket --routes-ws-message-timeout 30.0

`--routes-ws-include` / `--routes-ws-exclude`¶

Filter which WebSocket routes to include or exclude.

Default: "" (empty)

# Only test specific routes
pytest --routes --routes-app myapp:app --routes-websocket \
    --routes-ws-include "/ws/chat,/ws/notifications"

# Exclude internal routes
pytest --routes --routes-app myapp:app --routes-websocket \
    --routes-ws-exclude "/ws/internal/*,/ws/debug/*"

WebSocket Configuration in pyproject.toml¶

[tool.pytest-routes.websocket]
enabled = true
max_messages = 10
connection_timeout = 30.0
message_timeout = 10.0
include = ["/ws/*"]
exclude = ["/ws/internal/*"]

See WebSocket Testing for complete documentation.

Combined Testing Examples¶

Full API Testing (HTTP + WebSocket + Stateful)¶

pytest --routes --routes-app myapp:app \
    --routes-websocket \
    --routes-stateful \
    --routes-max-examples 100 \
    --routes-ws-max-messages 20 \
    --routes-stateful-step-count 50

CI Pipeline Configuration¶

pytest --routes --routes-app myapp:app \
    --routes-websocket \
    --routes-stateful \
    --routes-schemathesis \
    --routes-seed $GITHUB_RUN_ID \
    --routes-stateful-seed $GITHUB_RUN_ID \
    --routes-report report.html \
    --routes-report-json report.json

Development Quick Check¶

pytest --routes --routes-app myapp:app \
    --routes-websocket \
    --routes-stateful \
    --routes-max-examples 5 \
    --routes-ws-max-messages 3 \
    --routes-stateful-step-count 10 \
    --routes-stateful-max-examples 5 \
    -x  # Stop on first failure

CLI Options Reference¶

Quick Reference¶

Core Options¶

--routes¶

--routes-app¶

Test Intensity Options¶

--routes-max-examples¶

Route Filtering Options¶

--routes-include¶

--routes-exclude¶

HTTP Method Options¶

--routes-methods¶

Reproducibility Options¶

--routes-seed¶

Combining Options¶

Configuration File Alternative¶

Usage Examples¶

Development: Quick Validation¶

CI Pipeline: Thorough Testing¶

Feature Development: Testing New Routes¶

Pre-Deployment: Comprehensive Check¶

Read-Only Testing: Safe for Production Data¶

Schemathesis Integration Options¶

--routes-schemathesis¶

--routes-schemathesis-schema-path¶

Report Generation Options¶

--routes-report¶

--routes-report-json¶

--routes-report-title¶

Report Configuration in pyproject.toml¶

Stateful Testing Options¶

--routes-stateful¶

--routes-stateful-mode¶

--routes-stateful-step-count¶

--routes-stateful-max-examples¶

--routes-stateful-seed¶

--routes-stateful-recursion-limit¶

--routes-stateful-fail-fast¶

--routes-stateful-verbose¶

--routes-stateful-include / --routes-stateful-exclude¶

Stateful Testing Configuration in pyproject.toml¶

WebSocket Testing Options¶

--routes-websocket¶

--routes-ws-max-messages¶

--routes-ws-timeout¶

--routes-ws-message-timeout¶

--routes-ws-include / --routes-ws-exclude¶

WebSocket Configuration in pyproject.toml¶

Combined Testing Examples¶

Full API Testing (HTTP + WebSocket + Stateful)¶

CI Pipeline Configuration¶

Development Quick Check¶

See Also¶

`--routes`¶

`--routes-app`¶

`--routes-max-examples`¶

`--routes-include`¶

`--routes-exclude`¶

`--routes-methods`¶

`--routes-seed`¶

`--routes-schemathesis`¶

`--routes-schemathesis-schema-path`¶

`--routes-report`¶

`--routes-report-json`¶

`--routes-report-title`¶

`--routes-stateful`¶

`--routes-stateful-mode`¶

`--routes-stateful-step-count`¶

`--routes-stateful-max-examples`¶

`--routes-stateful-seed`¶

`--routes-stateful-recursion-limit`¶

`--routes-stateful-fail-fast`¶

`--routes-stateful-verbose`¶

`--routes-stateful-include` / `--routes-stateful-exclude`¶

`--routes-websocket`¶

`--routes-ws-max-messages`¶

`--routes-ws-timeout`¶

`--routes-ws-message-timeout`¶

`--routes-ws-include` / `--routes-ws-exclude`¶