FastAPI Pytest TDD Helper

High-performance TDD blueprint for FastAPI projects.

Core Principles

| Principle | Implementation | |-----------|----------------| | Speed | AsyncClient over TestClient (~20% faster) | | Isolation | Transaction rollback, not schema recreation | | TDD | Red-Green-Refactor cycle strictly | | Validation | Pydantic models, not just status codes |

Quick Start

1. Install Dependencies

pip install pytest pytest-asyncio httpx aiosqlite pytest-cov

2. Configure pytest (pyproject.toml)

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]
addopts = ["-v", "--tb=short", "-x"]

3. Create conftest.py

import pytest
from httpx import AsyncClient, ASGITransport
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
from sqlalchemy.pool import NullPool
from app.main import app
from app.database import Base, get_db

@pytest.fixture(scope="session")
async def async_engine():
    engine = create_async_engine("sqlite+aiosqlite:///./test.db", poolclass=NullPool)
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    yield engine
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.drop_all)

@pytest.fixture(scope="function")
async def db_session(async_engine):
    async_session = async_sessionmaker(async_engine, class_=AsyncSession)
    async with async_session() as session:
        async with session.begin():
            yield session
            await session.rollback()  # Fast isolation!

@pytest.fixture
async def client(db_session):
    app.dependency_overrides[get_db] = lambda: db_session
    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
        yield ac
    app.dependency_overrides.clear()

TDD Workflow: Red-Green-Refactor

Step 1: RED - Write Failing Test

from pydantic import BaseModel

class ItemResponse(BaseModel):
    id: int
    name: str
    price: float

async def test_create_item(client):
    response = await client.post("/items/", json={"name": "Widget", "price": 10.0})

    assert response.status_code == 201
    item = ItemResponse(**response.json())  # Validate shape!
    assert item.name == "Widget"

Run: pytest -x (fails - endpoint doesn't exist)

Step 2: GREEN - Minimal Implementation

@app.post("/items/", status_code=201, response_model=ItemResponse)
async def create_item(item: ItemCreate, db: Session = Depends(get_db)):
    db_item = Item(**item.model_dump())
    db.add(db_item)
    db.commit()
    return db_item

Run: pytest -x (passes)

Step 3: REFACTOR - Optimize

Improve code quality, run tests to verify nothing breaks.

Reference Documentation

| Task | Reference | |------|-----------| | conftest.py patterns, fixture scopes | references/conftest-patterns.md | | Red-Green-Refactor examples | references/tdd-workflow.md | | pyproject.toml, parallel execution | references/pytest-optimization.md | | Response validation with Pydantic | references/pydantic-validation.md | | CRUD tests, mocking, overrides | references/testing-patterns.md |

Assets

| Template | Description | |----------|-------------| | assets/conftest_template.py | Complete conftest.py ready to customize | | assets/pyproject_template.toml | Optimized pytest configuration |

Performance Decisions

Why AsyncClient Over TestClient

# AVOID: Sync-to-async bridge overhead
from fastapi.testclient import TestClient
client = TestClient(app)

# USE: Native async, ~20% faster
from httpx import AsyncClient, ASGITransport
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
    response = await client.get("/")

Why Transaction Rollback Over Schema Recreation

| Approach | 100 tests | 1000 tests | |----------|-----------|------------| | Schema recreation | ~60s | ~600s | | Transaction rollback | ~5s | ~50s |

# FAST: Rollback at end of each test
async with session.begin():
    yield session
    await session.rollback()

Fixture Scoping Strategy

| Scope | Use For | Example | |-------|---------|---------| | session | Expensive setup | DB engine, app instance | | function | Test isolation | DB session with rollback |

Common Commands

# Run all tests
pytest

# Run with coverage
pytest --cov=app --cov-report=term-missing

# Run specific test
pytest tests/test_items.py::test_create_item -v

# Run excluding slow tests
pytest -m "not slow"

# Parallel execution
pytest -n auto

# Stop on first failure (TDD mode)
pytest -x

# Run failed tests first
pytest --ff

Parametrize Pattern

@pytest.mark.parametrize("name,price,status", [
    ("Valid", 10.0, 201),
    ("", 10.0, 422),      # Empty name
    ("Item", -5.0, 422),  # Negative price
])
async def test_create_item_validation(client, name, price, status):
    response = await client.post("/items/", json={"name": name, "price": price})
    assert response.status_code == status

Factory Fixture Pattern

@pytest.fixture
def item_factory(db_session):
    async def _create(name="Item", price=10.0, **kwargs):
        item = Item(name=name, price=price, **kwargs)
        db_session.add(item)
        await db_session.flush()
        return item
    return _create

async def test_get_item(client, item_factory):
    item = await item_factory(name="Widget")
    response = await client.get(f"/items/{item.id}")
    assert response.json()["name"] == "Widget"