pytest-routes

Property-based smoke testing for ASGI application routes.

Overview

pytest-routes automatically discovers routes from your ASGI application and performs randomized smoke testing using Hypothesis. It works with any ASGI framework, with first-class support for Litestar.

Key Features

Automatic Route Discovery - Extracts routes directly from your ASGI app
Property-Based Testing - Uses Hypothesis to generate diverse test inputs
Framework Agnostic - Works with Litestar, FastAPI, Starlette, and any ASGI app
Configurable - Filter routes, set examples per route, customize validation
Zero Config - Works out of the box with sensible defaults

Installation

# With pip
pip install pytest-routes

# With uv
uv add pytest-routes

# With framework extras
uv add "pytest-routes[litestar]"
uv add "pytest-routes[fastapi]"

Quick Start

# Run smoke tests on your ASGI app
pytest --routes --routes-app myapp:app

# With options
pytest --routes --routes-app myapp:app --routes-max-examples 50

Or define your app as a fixture:

# conftest.py
import pytest
from myapp import create_app

@pytest.fixture(scope="session")
def app():
    return create_app()

pytest --routes

Configuration

CLI Options

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

pyproject.toml

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

Supported Frameworks

Framework	Status	Notes
Litestar	First-class	Full type extraction
FastAPI	Supported	Via Starlette
Starlette	Supported	Base ASGI support

How It Works

Discovery - Extracts routes from your ASGI app using framework-specific extractors
Generation - Creates Hypothesis strategies based on route parameter types
Execution - Runs property-based tests against each route
Validation - Checks responses meet smoke test criteria (no 5xx, etc.)

Documentation

Full documentation available at jacobcoffee.github.io/pytest-routes

License

MIT License - see LICENSE

Metadata

Release files for pytest-routes 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pytest-routes 0.4.0
File	Size	Uploaded
pytest_routes-0.4.0.tar.gz	83.5 kB	Dec 1, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for pytest-routes 0.4.0
File	Interpreter	ABI	Platform	Reset
pytest_routes-0.4.0-py3-none-any.whl 102.1 kB Dec 1, 2025	Python 3	none	any	Details

Total release size: 185.6 kB

Release files / pytest_routes-0.4.0.tar.gz

Download URL	pytest_routes-0.4.0.tar.gz
Size	83.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`976638d2e89f886993d613c2c34aede773e9ce90eda96792e629dd64c3b76587`
BLAKE2b-256 checksum How to use checksums	`7c1a58a88b1ac290ec5715f19ce2a17078e78744c00b9f24182c84a3b9560dd0`
Upload date	Dec 1, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/JacobCoffee/pytest-routes
Publishing commit: github.com/JacobCoffee/pytest-routes/tree/ba9c7043650f3bc00aaa618ca6728aa0e8ec10f8

Workflow

Publishing configuration: github.com/JacobCoffee/pytest-routes/blob/ba9c7043650f3bc00aaa618ca6728aa0e8ec10f8/.github/workflows/publish.yml
Publishing logs: github.com/JacobCoffee/pytest-routes/actions/runs/19807865097/attempts/1

Artifact

Subject: pytest_routes-0.4.0.tar.gz
SHA-256 checksum: 976638d2e89f886993d613c2c34aede773e9ce90eda96792e629dd64c3b76587 Verifying attestations

Release files / pytest_routes-0.4.0-py3-none-any.whl

Download URL	pytest_routes-0.4.0-py3-none-any.whl
Size	102.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`bb4deb5890e4ee2bc4890b38d94b9a0a0a217554914424427e3bb3dba8f22014`
BLAKE2b-256 checksum How to use checksums	`c082221e8f1e8f7546725afb83d2a0b9c2ecf2eb6bf9cefd5b53ac38d1ee06ed`
Upload date	Dec 1, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/JacobCoffee/pytest-routes
Publishing commit: github.com/JacobCoffee/pytest-routes/tree/ba9c7043650f3bc00aaa618ca6728aa0e8ec10f8

Workflow

Publishing configuration: github.com/JacobCoffee/pytest-routes/blob/ba9c7043650f3bc00aaa618ca6728aa0e8ec10f8/.github/workflows/publish.yml
Publishing logs: github.com/JacobCoffee/pytest-routes/actions/runs/19807865097/attempts/1

Artifact

Subject: pytest_routes-0.4.0-py3-none-any.whl
SHA-256 checksum: bb4deb5890e4ee2bc4890b38d94b9a0a0a217554914424427e3bb3dba8f22014 Verifying attestations