FastAPI Testing Strategy — Unit, Integration and API Testing

Introduction

Tests are how a FastAPI codebase stays shippable past month 6. This tutorial lays out a layered strategy — fast unit tests for logic, integration tests with a real Postgres, and API tests through FastAPI's async TestClient.

For the Java view, see Spring Boot Testing Strategy.

Key takeaways

• Pyramid, not ice-cream cone: many unit tests, fewer integration, fewest end-to-end.
• Use httpx.AsyncClient with ASGITransport — true async testing, no event-loop tricks.
• Override dependencies, don't monkey-patch — that's why Depends() exists.
• Use testcontainers for real Postgres in integration tests. SQLite-as-Postgres lies.
• Mark slow tests and run them in their own CI job.

Project layout

tests/
  unit/            # pure logic, no I/O
  integration/     # touches DB / Redis
  api/             # end-to-end through TestClient
  conftest.py

Async TestClient

```python
# tests/conftest.py
import pytest, pytest_asyncio
from httpx import AsyncClient, ASGITransport
from app.main import app
from app.db.session import get_session

@pytest_asyncio.fixture async def client(db_session): app.dependency_overrides[get_session] = lambda: db_session async with AsyncClient(transport=ASGITransport(app=app), base_url="http://t") as c: yield c app.dependency_overrides.clear() ```

Real Postgres with testcontainers

```python
# tests/conftest.py
from testcontainers.postgres import PostgresContainer
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker

@pytest.fixture(scope="session") def pg(): with PostgresContainer("postgres:16-alpine") as c: yield c.get_connection_url().replace("psycopg2", "asyncpg")

@pytest_asyncio.fixture async def db_session(pg): engine = create_async_engine(pg) async with engine.begin() as conn: await conn.run_sync(Base.metadata.create_all) Session = async_sessionmaker(engine, expire_on_commit=False) async with Session() as s: yield s await engine.dispose() ```

Unit test (pure logic)

def test_password_policy_rejects_short():
    with pytest.raises(ValueError):
        UserCreate(email="a@b.co", full_name="A", password="short")

API test

@pytest.mark.asyncio
async def test_create_user(client):
    r = await client.post("/api/v1/users", json={
        "email": "a@b.co", "full_name": "Alice", "password": "x" * 12
    })
    assert r.status_code == 201
    assert r.json()["email"] == "a@b.co"

Coverage in CI

pytest -q --cov=app --cov-branch --cov-report=term-missing --cov-fail-under=80

Production best practices

• Test the error paths — 4xx and 5xx behavior matters more than the happy path.
• Each test should own its data. Don't share state across tests; flake hell follows.
• Run integration tests in parallel with pytest-xdist.
• Snapshot OpenAPI in CI to catch unintended API changes.

Common mistakes

• Mocking the database in API tests — you're testing the mock, not the code.
• Using requests instead of httpx — sync calls inside async code deadlock.
• Forgetting to reset dependency_overrides between tests.

Tools used in this tutorial

The setup below uses the following tools. Versions matter less than the role each one plays, so swap freely as long as you keep the responsibilities the same.

• Python 3.12+
• FastAPI
• Uvicorn / Gunicorn
• Pydantic v2
• SQLAlchemy 2.x
• Docker
• Kubernetes

Real-world production context

In production, a Python backend like this rarely runs as a single uvicorn process on a laptop. Teams build the app into a container image, push it to a registry, and run it behind a managed load balancer with autoscaling, health checks and centralized logging. Async FastAPI services typically use multiple Uvicorn workers managed by Gunicorn, a managed Postgres for state, Redis for cache and rate-limit counters, and an object store for uploads. The reason cloud hosting becomes a hard requirement is operational: zero-downtime rollouts, log aggregation, metrics, and TLS at the edge are not optional once real users depend on the API.

Recommended tools & deployment options

Once the tutorial works on your machine, the next question is *where do I run this for real?* These are the platforms most Python backend teams reach for:

• DigitalOcean — the simplest path from a working FastAPI container to a public URL. App Platform deploys directly from a Dockerfile, managed Postgres and Redis are one click away, and pricing is predictable. A common way to deploy the setup in this tutorial is using a cloud provider like DigitalOcean when you want to ship quickly without learning a full cloud SDK.
• AWS — the default for enterprise workloads. ECS Fargate or EKS run containers without you managing servers, RDS handles Postgres, and CloudWatch covers logs and metrics.
• Docker — the packaging format every modern deploy target understands. Build once, run the same image locally, in CI and in production.
• Kubernetes (managed: EKS, DOKS, GKE) — the right choice once you have more than a handful of services, need rolling updates, autoscaling and policy-driven networking.

A VPS or managed cloud service is required to run this architecture end-to-end — uvicorn --reload is for development, not for serving traffic.

FAQ

unittest or pytest? Pytest. Fixtures, parametrization and plugin ecosystem make it the obvious default.

Next steps & related tutorials

Keep the momentum going with the next tutorial in this learning path:

• Next: Building REST APIs with FastAPI
• Next: CI/CD Pipeline for FastAPI
• Next: JWT Authentication in FastAPI