python-test-pyramid

Test pyramid for FastAPI + SQLAlchemy

The testing strategy for an opinionated FastAPI + SQLAlchemy service. The core trade-off: real Postgres, protocol-level doubles for external systems. The DB is the part most likely to surprise you in production (constraints, transactions, types); external systems are where you want speed and determinism.

This skill encodes the canonical conftest, fixture organization, and test layout.

When to use this skill

• Setting up tests/conftest.py and fixtures for a new service
• Adding a new test for a service, repo, route, or client
• Restructuring an existing test suite into unit / integration
• Diagnosing flaky tests, missing fixture wiring, or session lifetime issues

The layout

tests/
  conftest.py           # session-scoped: settings, db setup, app, db_pool. function-scoped: session, client.
  fixtures/             # split fixture modules (pytest_plugins)
    models.py
    services.py
    clients.py
    repos.py
  doubles/              # httpx.MockTransport handlers (one class per external client)
    openai.py
    stripe.py
  unit/                 # no DB, no HTTP — fast
    schemas/            # cohesion methods (from_X, to_X)
    common/             # exceptions, utilities, value objects
  integration/          # real DB and/or external doubles
    repos/              # exercises real DB
    services/           # real DB + fake clients
  api/                  # full app via httpx ASGITransport

The rules

1. conftest.py at tests/ root, fixtures split by topic via pytest_plugins

# tests/conftest.py — shape; full version in examples/conftest.py
pytest_plugins = [
    "tests.fixtures.models",
    "tests.fixtures.services",
    "tests.fixtures.clients",
    "tests.fixtures.repos",
]

@pytest.fixture(scope="session")
def config() -> AppConfig:
    return AppConfig()

Splitting fixtures into tests/fixtures/*.py keeps conftest.py short and lets you find a fixture by topic.

2. Real Postgres, set up once per test session