Metadata-Version: 2.3
Name: pytest-routes
Version: 0.3.0
Summary: Property-based smoke testing for ASGI application routes
Keywords: pytest,pytest-plugin,testing,asgi,litestar,fastapi,starlette,hypothesis,property-based-testing,smoke-testing
Author: Jacob Coffee
Author-email: Jacob Coffee <jacob@z7x.org>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Plugins
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Dist: pytest>=7.0
Requires-Dist: hypothesis>=6.0
Requires-Dist: httpx>=0.24
Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
Requires-Dist: pytest-routes[litestar,fastapi,starlette,schemathesis] ; extra == 'all'
Requires-Dist: fastapi>=0.100.0 ; extra == 'fastapi'
Requires-Dist: litestar>=2.0.0 ; extra == 'litestar'
Requires-Dist: schemathesis>=3.0 ; extra == 'schemathesis'
Requires-Dist: starlette>=0.27.0 ; extra == 'starlette'
Requires-Python: >=3.10, <3.14
Project-URL: Changelog, https://github.com/JacobCoffee/pytest-routes/releases/
Project-URL: Discord, https://discord.gg/litestar-919193495116337154
Project-URL: Documentation, https://jacobcoffee.github.io/pytest-routes
Project-URL: Homepage, https://github.com/JacobCoffee/pytest-routes
Project-URL: Issue Tracker, https://github.com/JacobCoffee/pytest-routes/issues
Project-URL: Repository, https://github.com/JacobCoffee/pytest-routes
Provides-Extra: all
Provides-Extra: fastapi
Provides-Extra: litestar
Provides-Extra: schemathesis
Provides-Extra: starlette
Description-Content-Type: text/markdown

# pytest-routes

[![PyPI](https://img.shields.io/pypi/v/pytest-routes)](https://pypi.org/project/pytest-routes/)
[![Python Version](https://img.shields.io/pypi/pyversions/pytest-routes)](https://pypi.org/project/pytest-routes/)
[![License](https://img.shields.io/github/license/JacobCoffee/pytest-routes)](https://github.com/JacobCoffee/pytest-routes/blob/main/LICENSE)

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](https://hypothesis.works/). It works with any ASGI framework, with first-class support for [Litestar](https://litestar.dev/).

### 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

```bash
# 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

```bash
# 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:

```python
# conftest.py
import pytest
from myapp import create_app

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

```bash
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

```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

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

## Documentation

Full documentation available at [jacobcoffee.github.io/pytest-routes](https://jacobcoffee.github.io/pytest-routes)

## License

MIT License - see [LICENSE](LICENSE)
