FastAPI Testing¶

Best practices for testing FastAPI applications with pytest.

Agent Quick Path¶

Use this sequence before reading the full reference:

1. If test is pure route behavior, use TestClient and plain def tests.
2. If test must await other async work, use AsyncClient + @pytest.mark.anyio.
3. Prefer app.dependency_overrides over mock.patch.
4. Reset overrides after each test/fixture teardown.
5. For startup/shutdown logic, use TestClient as context manager or LifespanManager with async client.

Decision rules: - Need DB contract verification: choose integration tests and override get_db/get_session. - Need pure business logic checks: keep tests HTTP-free (unit). - Need one critical path sanity check: one endpoint per smoke test.

Tools¶

Install deps: httpx, anyio (or pytest-anyio).

Synchronous Tests (Preferred Default)¶

Use TestClient for route tests that don't need to await anything else. Test functions are plain def — no async def, no await.

from fastapi.testclient import TestClient
from myapp.main import app

client = TestClient(app)

def test_read_item_returns_200():
    response = client.get("/items/foo", headers={"X-Token": "secret"})
    assert response.status_code == 200
    assert response.json()["id"] == "foo"

def test_read_item_bad_token_returns_400():
    response = client.get("/items/foo", headers={"X-Token": "wrong"})
    assert response.status_code == 400

Rules: - One TestClient per test module is fine (stateless between calls). - Pass headers, query params, JSON body, or form data the same way as HTTPX/requests. - Do not pass Pydantic models directly; use .model_dump() or jsonable_encoder.

Async Tests¶

Use AsyncClient only when the test itself needs to await other coroutines (e.g. querying a real async DB after an API call to verify side effects).

import pytest
from httpx import ASGITransport, AsyncClient
from myapp.main import app

@pytest.mark.anyio
async def test_root_async():
    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
        response = await ac.get("/")
    assert response.status_code == 200

Rules: - Mark with @pytest.mark.anyio; register the anyio marker in pyproject.toml. - AsyncClient does not trigger lifespan events by default; use asgi-lifespan's LifespanManager when startup/shutdown matters. - Instantiate objects that require an event loop (e.g. async DB clients) inside async functions, not at module level.

Dependency Overrides (Preferred Over Mocking)¶

app.dependency_overrides is the idiomatic FastAPI seam — use it instead of patching internals with unittest.mock.

from fastapi.testclient import TestClient
from myapp.main import app
from myapp.deps import get_current_user

client = TestClient(app)

def fake_user():
    return {"id": 1, "name": "Test User"}

def test_protected_route_with_fake_user():
    app.dependency_overrides[get_current_user] = fake_user
    response = client.get("/me")
    app.dependency_overrides = {}          # always reset after the test
    assert response.status_code == 200
    assert response.json()["name"] == "Test User"

Or reset cleanly with autouse=False fixture teardown:

import pytest
from myapp.main import app

@pytest.fixture()
def override_user():
    app.dependency_overrides[get_current_user] = lambda: {"id": 1, "name": "Test User"}
    yield
    app.dependency_overrides = {}

Rules: - Override at the lowest-level dependency that owns the external boundary (e.g. get_db, get_current_user, get_settings). - Always reset app.dependency_overrides after each test or fixture teardown. - Prefer a real in-process fake (e.g. in-memory SQLite session) over a mock object.

Database Testing¶

The preferred pattern is a real SQLite (or test Postgres) session injected via dependency override, not a mock.

# tests/conftest.py
import pytest
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from fastapi.testclient import TestClient
from myapp.main import app
from myapp.db.session import get_db
from myapp.db.models import Base

TEST_DB_URL = "sqlite:///./test.db"

@pytest.fixture(scope="session")
def engine():
    e = create_engine(TEST_DB_URL, connect_args={"check_same_thread": False})
    Base.metadata.create_all(bind=e)
    yield e
    Base.metadata.drop_all(bind=e)

@pytest.fixture()
def db_session(engine):
    Session = sessionmaker(bind=engine)
    session = Session()
    yield session
    session.rollback()
    session.close()

@pytest.fixture()
def client(db_session):
    app.dependency_overrides[get_db] = lambda: db_session
    yield TestClient(app)
    app.dependency_overrides = {}

Rules: - Prefer session-scoped engine creation; function-scoped session with rollback per test. - Keep unit tests DB-free; use this pattern only in integration-marked tests. - For async SQLAlchemy, mirror the same pattern using AsyncEngine / AsyncSession.

Lifespan and Startup Events¶

TestClient triggers lifespan events (startup/shutdown) when used as a context manager:

def test_with_lifespan():
    with TestClient(app) as client:
        response = client.get("/health")
        assert response.status_code == 200

For AsyncClient, use asgi-lifespan:

from asgi_lifespan import LifespanManager

@pytest.mark.anyio
async def test_with_async_lifespan():
    async with LifespanManager(app):
        async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
            response = await ac.get("/health")
    assert response.status_code == 200

Marker Strategy for FastAPI Tests¶

Quick Reference: Sending Data¶

Official Docs¶

• Testing tutorial
• Async tests
• Testing dependencies with overrides
• Testing a database (SQLModel)
• Testing lifespan events
• Testing WebSockets
• HTTPX docs