pytest-routes¶
Property-based smoke testing for ASGI application routes with first-class Litestar support.
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.
Get started with pytest-routes in minutes. Install with pip or uv and run your first smoke test.
Learn how to configure pytest-routes, filter routes, customize strategies, and integrate with CI/CD.
Complete API documentation for all public classes, functions, and configuration options.
Key Features¶
Extracts routes directly from your ASGI app - no OpenAPI schema required. Works with Litestar, FastAPI, Starlette, and any ASGI framework.
Uses Hypothesis to generate diverse, randomized test inputs that find edge cases you never thought to test.
Works out of the box with sensible defaults. Just add --routes to your
pytest command and start testing.
Deep integration with Litestar for full type extraction. Automatic support for FastAPI and Starlette route patterns.
Filter routes by pattern, customize HTTP methods, set examples per route, and configure validation rules.
Built-in validators for status codes, content types, and JSON schemas. Optional OpenAPI response validation.
New in v0.4.0¶
Test API workflows where operations depend on each other. Uses Hypothesis state machines to test CRUD sequences and complex interactions automatically.
pytest --routes --routes-app myapp:app --routes-stateful
Property-based testing for WebSocket endpoints. Generates randomized message sequences to validate your real-time API behavior.
pytest --routes --routes-app myapp:app --routes-websocket
Quick Start¶
Installation¶
# Using uv (recommended)
uv add pytest-routes
# Using pip
pip install pytest-routes
# With framework extras
uv add "pytest-routes[litestar]"
uv add "pytest-routes[fastapi]"
Basic Usage¶
Run smoke tests on your ASGI application:
# Specify app via CLI
pytest --routes --routes-app myapp:app
# With options
pytest --routes --routes-app myapp:app --routes-max-examples 50
Or define your app as a pytest fixture:
# conftest.py
import pytest
from myapp import create_app
@pytest.fixture(scope="session")
def app():
return create_app()
# App is discovered from fixture
pytest --routes
What It Does¶
Discovery - Extracts routes from your ASGI application
Generation - Creates Hypothesis strategies based on route parameter types
Execution - Runs property-based tests against each route
Validation - Checks that responses meet smoke test criteria (no 5xx errors)
Example Output¶
$ pytest --routes --routes-app examples.litestar_app:app -v
tests/test_routes.py::test_route[GET /] PASSED
tests/test_routes.py::test_route[GET /users] PASSED
tests/test_routes.py::test_route[POST /users] PASSED
tests/test_routes.py::test_route[GET /users/{user_id}] PASSED
tests/test_routes.py::test_route[PUT /users/{user_id}] PASSED
tests/test_routes.py::test_route[DELETE /users/{user_id}] PASSED
========================= 6 passed in 2.34s =========================
Each route is tested with multiple randomized inputs. If a route returns a 5xx error, the test fails with a minimal reproducing example.
Supported Frameworks¶
Framework |
Status |
Notes |
|---|---|---|
First-class |
Full type extraction from handlers |
|
Supported |
Via Starlette extractor |
|
Supported |
Base ASGI support |
License¶
pytest-routes is released under the MIT License.