Getting Started¶

Get up and running with pytest-routes in a few minutes.

This guide walks you through installing pytest-routes and running your first smoke test.

Requirements¶

Requirement	Version
Python	3.10 or higher
pytest	7.0 or higher
ASGI Application	Litestar, FastAPI, or Starlette

Installation¶

Base Package¶

uv (recommended)

uv is the recommended package manager for Python projects:

uv add pytest-routes

pip

pip install pytest-routes

With Framework Extras¶

Install with your framework of choice for optimal type extraction:

Litestar

# uv (recommended)
uv add "pytest-routes[litestar]"

# pip
pip install "pytest-routes[litestar]"

FastAPI

# uv (recommended)
uv add "pytest-routes[fastapi]"

# pip
pip install "pytest-routes[fastapi]"

Starlette

# uv (recommended)
uv add "pytest-routes[starlette]"

# pip
pip install "pytest-routes[starlette]"

All Extras

# uv (recommended)
uv add "pytest-routes[all]"

# pip
pip install "pytest-routes[all]"

Verify Installation¶

After installation, verify that pytest-routes is installed correctly:

pytest --help | grep routes

You should see the pytest-routes CLI options listed:

--routes              Enable route smoke testing
--routes-app          Import path to ASGI app (e.g., myapp:app)
--routes-max-examples Maximum Hypothesis examples per route
...

Your First Smoke Test¶

Option 1: CLI App Path¶

The simplest way to run smoke tests is to specify your app directly:

pytest --routes --routes-app myapp:app

Where myapp:app is the import path to your ASGI application:

myapp is the module name
app is the application variable name

Example:

# myapp.py
from litestar import Litestar, get

@get("/")
async def hello() -> dict[str, str]:
    return {"message": "Hello, World!"}

@get("/users/{user_id:int}")
async def get_user(user_id: int) -> dict[str, int]:
    return {"user_id": user_id}

app = Litestar([hello, get_user])

pytest --routes --routes-app myapp:app

Option 2: Pytest Fixture¶

For more complex applications that require setup (database connections, configuration, etc.), define your app as a pytest fixture:

# conftest.py
import pytest
from myapp import create_app

@pytest.fixture(scope="session")
def app():
    """Create and configure the application for testing."""
    return create_app(testing=True)

pytest --routes

This approach is useful when your app needs:

Database setup and teardown
Environment-specific configuration
Dependency injection setup
Custom middleware for testing

Understanding the Output¶

When you run pytest-routes, each discovered route becomes a separate test item:

$ pytest --routes --routes-app myapp:app -v

collecting ... collected 6 items

test_route[GET /] PASSED
test_route[GET /users] PASSED
test_route[POST /users] PASSED
test_route[GET /users/{user_id}] PASSED
test_route[PUT /users/{user_id}] PASSED
test_route[DELETE /users/{user_id}] PASSED

========================= 6 passed in 2.34s =========================

Each test runs multiple iterations with randomized inputs generated by Hypothesis.

When Tests Fail¶

If a route returns a 5xx error, pytest-routes reports the failure with a minimal reproducing example:

FAILED test_route[POST /users]

RouteTestFailure: Route POST /users failed with status 500

Request:
  Method: POST
  Path: /users
  Body: {"name": "", "email": "invalid"}

Response:
  Status: 500 Internal Server Error
  Body: {"detail": "Internal server error"}

Shrunk example (minimal failing case):
  body={"name": "", "email": "x"}

Hypothesis automatically shrinks the failing input to the smallest example that still causes the failure, making debugging much easier.

Configuration¶

Command Line Options¶

Option	Description	Default
`--routes`	Enable route smoke testing	`False`
`--routes-app`	Import path to ASGI app (e.g., `myapp:app`)	-
`--routes-max-examples`	Maximum Hypothesis examples per route	`100`
`--routes-exclude`	Comma-separated patterns to exclude	`/health,/metrics,...`
`--routes-include`	Comma-separated patterns to include (only test these)	-
`--routes-methods`	HTTP methods to test	`GET,POST,PUT,PATCH,DELETE`
`--routes-seed`	Random seed for reproducibility	-

pyproject.toml¶

You can also configure pytest-routes in your pyproject.toml:

[tool.pytest-routes]
app = "myapp:app"
max_examples = 100
exclude = ["/health", "/metrics", "/docs"]
methods = ["GET", "POST"]

See the Configuration Guide for all options.

Next Steps¶

Now that you have pytest-routes installed and running, explore these resources to get the most out of it:

Usage Guide

Learn about filtering routes, custom strategies, response validation, and CI/CD integration.

Usage Guide

CLI Reference

Complete documentation for all command-line options and their usage.

CLI Options Reference

Framework Support

Framework-specific features, tips, and best practices for Litestar, FastAPI, and Starlette.

Framework Support

API Reference

Full API documentation for extending pytest-routes with custom strategies and validators.

API Reference