Testing a FastAPI app

The framework is unusually testable, and the reason is dependency injection: every external thing a handler touches arrives through Depends, so every external thing has a seam. Most of the work is deciding what to replace.

TestClient is synchronous, and that is fine

from fastapi.testclient import TestClient

client = TestClient(app)

def test_creates_order():
    r = client.post("/orders", json={"sku": "ABC", "qty": 2})
    assert r.status_code == 201
    assert r.json()["sku"] == "ABC"

TestClient wraps httpx and runs the ASGI app in a worker thread, so your tests stay plain synchronous pytest even though the handlers are async. It runs lifespan when used as a context manager, which is the detail people trip on:

# lifespan runs: pools built, then closed
with TestClient(app) as client:
    ...

Without the with, lifespan never fires and anything set up there — app.state.http, a connection pool — is missing. The symptom is an AttributeError on app.state that looks nothing like the cause.

When you need a real async client

TestClient is enough until the test itself must be async — an async fixture, a concurrency assertion, or exercising an async context manager:

from httpx import AsyncClient, ASGITransport

@pytest.fixture
async def client():
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as c:
        yield c

async def test_concurrent(client):
    rs = await asyncio.gather(*(client.get("/slow") for _ in range(10)))
    assert all(r.status_code == 200 for r in rs)

ASGITransport calls the app in-process — no socket, no port, no server. That is what makes it fast enough to run per test.

dependency_overrides is the seam

app.dependency_overrides[get_session] = lambda: test_session
app.dependency_overrides[current_user] = lambda: User(id=1, role="admin")
app.dependency_overrides[billing] = lambda: FakeBilling()

The whole real request path still runs — routing, validation, middleware, serialisation, the response model — and only the leaves are swapped. That is the difference between this and calling the handler function directly, which tests none of it.

Two rules. Override by the function object, not by name — the key is identity, so importing the same symbol matters. And clear between tests, or one test’s fake leaks into the next:

@pytest.fixture(autouse=True)
def _reset_overrides():
    yield
    app.dependency_overrides.clear()

The database: real, in a transaction

Mocking the session tests your mock. Run a real database and roll back:

@pytest.fixture(scope="session")
async def engine():
    async with PostgresContainer("postgres:18") as pg:
        e = create_async_engine(pg.get_connection_url())
        async with e.begin() as c:
            await c.run_sync(Base.metadata.create_all)
        yield e

@pytest.fixture
async def test_session(engine):
    async with engine.connect() as conn:
        tx = await conn.begin()
        async with AsyncSession(bind=conn) as s:
            yield s
        # isolation, without re-creating anything
        await tx.rollback()

Session-scoped container for the cost, function-scoped transaction for the isolation. Same shape as Fixtures, parametrize and scope, and the reason a suite is fast or a suite is twenty minutes.

Gotcha: the override must yield that session. If get_session opens its own from the engine, the handler writes in a different transaction from the one your test rolls back, and rows leak between tests while every assertion still passes.

What to assert

• Status and shape, not internals. assert r.status_code == 201 and the parsed body — see the behaviour-versus-implementation argument in Test Strategy and the Test Pyramid.
• The failures. 422 on bad input, 404 on missing, 409 on conflict. The happy path rarely regresses.
• Authorisation, per role. A parametrised test over roles catches the endpoint someone forgot to guard.
• The contract. A response containing a field your response_model does not declare is a leak; the model prevents it, and a test proves the model is applied.

Outbound HTTP is mocked at the transport with respx, never by patching your own client class — Mocking external APIs.

Related

• Dependencies and injection — why the seam exists
• Deployment — what runs in production
• Fixtures, parametrize and scope — fixtures and scope
• Testing Patterns — the database half