Testing

You can test a FastAPI application without starting a server. This chapter covers testing endpoints with TestClient and pytest, swapping databases and settings for test versions with dependency overrides, async tests, and measuring coverage.

Setup

TestClient is built on HTTPX. If you installed fastapi[standard], HTTPX is already there, so you only need pytest:

pip install pytest

Put tests in files named tests/test_*.py and start test function names with test_. Running pytest from the project root discovers and runs them. To make the app package importable, either add an empty __init__.py to tests or set pythonpath = ["."] in the pytest section of pyproject.toml.

A first test with TestClient

Hand your app to TestClient and you can send requests and inspect responses much as you would with requests. Test functions are plain def.

# tests/test_main.py
from fastapi.testclient import TestClient

from app.main import app

client = TestClient(app)


def test_read_root():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello, world!"}


def test_read_item_validation_error():
    response = client.get("/items/not-a-number")
    assert response.status_code == 422


def test_create_item():
    response = client.post("/items", json={"name": "Pen", "price": 1.5})
    assert response.status_code == 201
    assert response.json()["name"] == "Pen"

Pass headers with headers={"X-Token": "..."} and query parameters with params={"q": "pen"}. Tests asserting that bad input returns 422 are worth having too: they catch accidental changes to your API contract early.

Overriding dependencies

To replace a real database or external service with a test implementation, map the original dependency to a substitute in app.dependency_overrides. This example swaps the session dependency for an in-memory SQLite database:

# tests/test_heroes.py
import pytest
from fastapi.testclient import TestClient
from sqlmodel import Session, SQLModel, create_engine
from sqlmodel.pool import StaticPool

from app.db import get_session
from app.main import app


@pytest.fixture(name="session")
def session_fixture():
    engine = create_engine(
        "sqlite://",
        connect_args={"check_same_thread": False},
        poolclass=StaticPool,
    )
    SQLModel.metadata.create_all(engine)
    with Session(engine) as session:
        yield session


@pytest.fixture(name="client")
def client_fixture(session: Session):
    app.dependency_overrides[get_session] = lambda: session
    client = TestClient(app)
    yield client
    app.dependency_overrides.clear()


def test_create_hero(client: TestClient):
    response = client.post(
        "/heroes", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
    )
    data = response.json()
    assert response.status_code == 200
    assert data["name"] == "Deadpond"
    assert "secret_name" not in data