Peyton Green

Posted on May 5

Testing FastAPI Endpoints Without Spinning Up a Server

#fastapi #python #testing #webdev

The most common FastAPI testing setup I see in the wild: the test suite starts the full server with uvicorn, runs requests against localhost:8000, and tears down at the end.

It works. It's also unnecessary. FastAPI ships with a TestClient that runs your app in-process — no server, no ports, no network. Once you understand how it works, you write faster tests and catch a class of dependency-injection bugs that the full-server approach misses.

TestClient: what it actually does

TestClient wraps httpx.Client around your FastAPI app. When you call client.get("/endpoint"), it routes the request through FastAPI's routing machinery without any network I/O. The request goes in as an ASGI request dict; the response comes back as an httpx.Response.

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

client = TestClient(app)

def test_health():
    response = client.get("/health")
    assert response.status_code == 200
    assert response.json() == {"status": "ok"}

No uvicorn. No localhost. No port binding. The test runs entirely in-process.

What this means for test speed: A full server startup adds 200-500ms per test file (or more with slow dependencies). In-process routing adds ~0ms. On a test suite with 50 test files, this is the difference between a 25-second run and a 5-second run.

Dependency overrides: the pattern that changes everything

FastAPI's dependency injection system is the reason TestClient is genuinely useful rather than just fast.

Every endpoint can declare dependencies — database connections, auth tokens, service clients. In production, FastAPI resolves them from the real providers. In tests, you can swap them out per-test with app.dependency_overrides:

from fastapi import Depends, FastAPI
from fastapi.testclient import TestClient

app = FastAPI()

# Production dependency
def get_db():
    db = create_db_connection()
    try:
        yield db
    finally:
        db.close()

@app.get("/users/{user_id}")
def get_user(user_id: int, db=Depends(get_db)):
    user = db.query(User).get(user_id)
    if not user:
        return {"error": "not found"}, 404
    return user.to_dict()

# Test override
def get_test_db():
    db = create_in_memory_db()
    db.add(User(id=1, name="Alice"))
    yield db

def test_get_user():
    app.dependency_overrides[get_db] = get_test_db
    client = TestClient(app)

    response = client.get("/users/1")
    assert response.status_code == 200
    assert response.json()["name"] == "Alice"

    app.dependency_overrides.clear()

The key behavior: dependency_overrides is a dict on the app object. You set it before the test, the test runs with the override, you clear it after. FastAPI resolves get_db → looks it up in dependency_overrides → finds get_test_db → uses that instead.

The bug it catches: If your real get_db wraps a production database and your test override wraps an in-memory database with different schema or constraints, the tests will pass and the prod code will fail. The right pattern is an override that uses the same ORM models and schema as production — just a different database URL (SQLite in-memory is fine for most tests).

Fixture pattern: TestClient with scoped overrides

The cleanest way to handle this in a real test suite is to push the override into a pytest fixture:

import pytest
from fastapi.testclient import TestClient
from app.main import app
from app.dependencies import get_db
from tests.fixtures import get_test_db

@pytest.fixture
def client():
    app.dependency_overrides[get_db] = get_test_db
    with TestClient(app) as c:
        yield c
    app.dependency_overrides.clear()

Using TestClient as a context manager (the with block) is important for async endpoints — it ensures the lifespan context runs correctly. For sync-only apps it's optional, but it's a good habit.

Now every test that takes client as a fixture gets the overridden dependencies automatically:

def test_get_user_not_found(client):
    response = client.get("/users/999")
    assert response.status_code == 404

def test_create_user(client):
    response = client.post("/users", json={"name": "Bob"})
    assert response.status_code == 201
    assert response.json()["name"] == "Bob"

No setup or teardown in the test functions. The fixture owns the lifecycle.

Auth: overriding security dependencies

Auth is where dependency overrides pay off most clearly. Most FastAPI apps use Depends for auth:

from fastapi import Depends, HTTPException, Security
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials

security = HTTPBearer()

def get_current_user(credentials: HTTPAuthorizationCredentials = Security(security)):
    token = credentials.credentials
    user = verify_token(token)  # hits an external auth service
    if not user:
        raise HTTPException(status_code=401)
    return user

@app.get("/me")
def get_me(current_user=Depends(get_current_user)):
    return current_user.to_dict()

In tests, you don't want to hit the external auth service. Override it:

@pytest.fixture
def authenticated_client():
    fake_user = User(id=42, name="TestUser", role="admin")

    def override_auth():
        return fake_user

    app.dependency_overrides[get_current_user] = override_auth
    with TestClient(app) as c:
        yield c
    app.dependency_overrides.clear()

def test_get_me(authenticated_client):
    response = authenticated_client.get("/me")
    assert response.status_code == 200
    assert response.json()["name"] == "TestUser"

You can create multiple fixtures for different auth states — admin_client, readonly_client, unauthenticated_client — each with a different user in the override. The endpoint code doesn't change.

Async endpoints: the one gotcha

If your endpoints are async def, TestClient handles them correctly when used as a context manager. If you need to test async behavior more directly (async fixtures, async teardown), use httpx.AsyncClient with ASGITransport instead:

import pytest
import httpx
from app.main import app

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

@pytest.mark.anyio
async def test_async_endpoint(async_client):
    response = await async_client.get("/async-endpoint")
    assert response.status_code == 200

This requires anyio (for pytest.mark.anyio) or pytest-asyncio. For most test suites, synchronous TestClient is sufficient — it handles async endpoints correctly in a sync context.

What to test vs what to skip

TestClient tests are fast and isolated. That means you can afford to test more coverage per request. What to focus on:

Status codes: every non-200 path (404, 422 validation errors, 401/403 auth failures)
Response shape: the JSON structure your callers depend on
Validation: FastAPI auto-validates request bodies via Pydantic — confirm it rejects bad input with 422
Dependency injection edge cases: what happens when your DB dependency returns None?

What to leave for integration tests (or skip entirely):

The exact SQL queries your ORM generates
Database migration behavior
Third-party API behavior (mock that at the HTTP level)

The boundary: TestClient tests should test your code (routing, business logic, response serialization). They should not test FastAPI itself or your ORM.

Putting it together: a minimal test setup

# tests/conftest.py
import pytest
from fastapi.testclient import TestClient
from app.main import app
from app.db import get_db
from tests.db import get_test_db

@pytest.fixture(scope="module")
def client():
    """TestClient with test database override. Module-scoped for speed."""
    app.dependency_overrides[get_db] = get_test_db
    with TestClient(app) as c:
        yield c
    app.dependency_overrides.clear()

# tests/test_users.py
def test_list_users_empty(client):
    response = client.get("/users")
    assert response.status_code == 200
    assert response.json() == []

def test_create_user(client):
    response = client.post("/users", json={"name": "Alice", "email": "alice@example.com"})
    assert response.status_code == 201
    data = response.json()
    assert data["name"] == "Alice"
    assert "id" in data

def test_get_user_not_found(client):
    response = client.get("/users/999")
    assert response.status_code == 404

def test_create_user_invalid_email(client):
    response = client.post("/users", json={"name": "Bob", "email": "not-an-email"})
    assert response.status_code == 422  # Pydantic validation failure

No server. No ports. Runs in under a second.

DEV Community