Testing FastAPI Apps: TestClient, AsyncClient, dependency_overrides
#FastAPI's dependency injection system makes it one of the most testable web frameworks in Python. Instead of patching functions at the call site with `unittest.mock`, you replace entire dependency chains at the app level before a test runs — cleanly and without touching any production code.
## Two testing clients
**`TestClient`** (synchronous, from `fastapi.testclient`):
```python
from fastapi.testclient import TestClient
from myapp.main import app
client = TestClient(app)
def test_get_items():
response = client.get('/items/')
assert response.status_code == 200
```
`TestClient` is built on httpx. It runs your ASGI app synchronously inside the test process — no real server is started. It's the right choice for most tests: simple, fast, and works without `pytest-asyncio`. Tests are plain `def` functions.
**`httpx.AsyncClient`** (asynchronous):
```python
# pytest.ini: asyncio_mode = auto
import httpx
import pytest
from myapp.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
async def test_get_items(async_client):
response = await async_client.get('/items/')
assert response.status_code == 200
```
Use `AsyncClient` when the code under test is inherently async and you need to verify async behaviour — testing concurrent requests, async generators, or streaming responses. Requires `pytest-asyncio` with `asyncio_mode = auto` in `pytest.ini`.
## `app.dependency_overrides` — the core testing pattern
In FastAPI, routes declare their dependencies as function parameters:
```python
from fastapi import Depends
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()
@app.get('/items/')
def list_items(db: Session = Depends(get_db)):
return db.query(Item).all()
```
In tests, replace `get_db` with a fake function returning an in-memory store — without touching any production code:
```python
def fake_get_db():
yield {'items': []}
app.dependency_overrides[get_db] = fake_get_db
```
The override applies to every request made through the app while it is set. Always clean up when done — otherwise the override persists across test functions and pollutes subsequent tests:
```python
app.dependency_overrides.clear()
```
The standard pattern wraps setup and cleanup in a pytest fixture with `yield`:
```python
@pytest.fixture
def client_with_fake_db():
store = []
def override():
yield store
app.dependency_overrides[get_db] = override
yield TestClient(app), store
app.dependency_overrides.clear() # always runs, even on test failure
```
## When to use which client
| Scenario | Client |
|---|---|
| Testing request/response (status, JSON body) | `TestClient` |
| Testing async behaviour or concurrent requests | `AsyncClient` |
| Streaming responses, WebSockets | `AsyncClient` |
| Simplicity and speed | `TestClient` |
## Lifespan events in tests
FastAPI apps often have startup/shutdown events (initialising a connection pool, loading ML models). `TestClient` triggers these when used as a context manager:
```python
with TestClient(app) as client:
# startup has run
response = client.get('/items/')
# shutdown has run
```
For tests that verify startup-dependent state, always use the context manager form.
## `yield` vs `return` in dependency overrides
When the original dependency uses `yield` (common for resources that need teardown — database sessions, open files, network connections), your override replacement must **also use `yield`**. A plain `return` in the replacement silently skips teardown:
```python
# Original — yield dependency with teardown
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close() # ← this teardown runs after the request
# WRONG — override uses return; db.cleanup() will never run
def fake_db_wrong():
return FakeSession() # FastAPI gets the value; no teardown phase
# CORRECT — override uses yield; teardown runs after the route handler returns
def fake_db_correct():
db = FakeSession()
try:
yield db
finally:
db.cleanup() # ← guaranteed teardown
```
FastAPI resolves the override as a generator if it contains `yield`. If it's a plain function (no `yield`), FastAPI calls it, takes the return value, and skips any teardown logic. This is not an error — FastAPI does not warn you — so the bug is silent.
A `lambda` override only works for dependencies that have no teardown:
```python
# OK — get_store just returns a list, no teardown needed
app.dependency_overrides[get_store] = lambda: []
# WRONG — get_db has teardown; lambda silently skips it
app.dependency_overrides[get_db] = lambda: FakeSession() # db.close() never runs
```
## Overriding a SQLAlchemy database session
> **SQLAlchemy version note:** The pattern below uses `bind=` on `sessionmaker` and `Session` — these keyword arguments were deprecated in SQLAlchemy 1.4 and **removed in SQLAlchemy 2.0**. On SQLAlchemy 2.x, replace `sessionmaker(bind=engine)` with `sessionmaker(engine)` and `TestingSession(bind=connection)` with the `join_transaction_mode` pattern (see SQLAlchemy 2.x testing docs). The dependency-override approach and test isolation concept are identical across versions.
Overriding the database session dependency is the most common `dependency_overrides` pattern in real FastAPI projects. The canonical test setup creates an in-memory SQLite database for the test session, wraps each test in a rolled-back transaction, and injects the same session into both the test and the app:
```python
# 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.database import get_db, Base
engine = create_engine('sqlite://', connect_args={'check_same_thread': False})
TestingSession = sessionmaker(bind=engine)
@pytest.fixture(scope='session', autouse=True)
def create_tables():
Base.metadata.create_all(engine)
yield
Base.metadata.drop_all(engine)
@pytest.fixture
def db_session():
connection = engine.connect()
transaction = connection.begin()
session = TestingSession(bind=connection)
yield session
session.close()
transaction.rollback() # ← every INSERT/UPDATE/DELETE from the test is undone
connection.close()
@pytest.fixture
def client(db_session):
def override_get_db():
yield db_session
app.dependency_overrides[get_db] = override_get_db
yield TestClient(app)
app.dependency_overrides.clear()
```
Key decisions in this pattern:
- `scope='session'` for `create_tables` — run schema creation once for the whole test run, not per-test.
- Per-test `db_session` wraps each test in a transaction and rolls it back on teardown. Every test starts with a clean schema without dropping and re-creating tables.
- The `client` fixture injects the same session the test holds, so you can read the app's writes directly from `db_session` without a second query through a separate connection.
## BackgroundTasks: `TestClient` vs `AsyncClient` behaviour
FastAPI's `BackgroundTasks` runs functions after the response is returned to the client. The behaviour in tests differs between the two clients:
```python
from fastapi import BackgroundTasks
results = []
def record(value: str):
results.append(value)
@app.post('/jobs/')
def create_job(bt: BackgroundTasks):
bt.add_task(record, 'done')
return {'status': 'queued'}
```
**With `TestClient`**, background tasks run **synchronously before** `TestClient` returns the response. By the time your assertion runs, the task is already complete:
```python
def test_job_with_test_client():
results.clear()
response = client.post('/jobs/')
assert response.status_code == 200
assert 'done' in results # task ran synchronously before TestClient returned
```
**With `AsyncClient` and `ASGITransport`**, background tasks also complete **before** `await async_client.post(...)` returns. Starlette invokes background tasks as part of the ASGI response lifecycle, and `ASGITransport` drives that lifecycle synchronously within the test coroutine — no separate asyncio task is scheduled that you could yield to:
```python
async def test_job_with_async_client(async_client):
results.clear()
response = await async_client.post('/jobs/')
assert response.status_code == 200
assert 'done' in results # task already ran before the response was returned
```
Both testing clients behave identically: background tasks complete before the response object is returned. This differs from production — a real server sends the HTTP response first and then runs tasks, so the client receives the response before the tasks finish. In tests with either client you can assert on task results immediately after the request.
## Testing custom exception handlers
By default, `TestClient` re-raises any server-side exception in the test process. If a route raises `ValueError`, the test sees a `ValueError`, not a 500 response — you cannot assert on the HTTP status.
When you have a custom exception handler and want to verify it returns the correct status and body, disable re-raising with `raise_server_exceptions=False`:
```python
from fastapi import Request
from fastapi.responses import JSONResponse
class AppError(Exception):
def __init__(self, code: int, message: str):
self.code = code
self.message = message
@app.exception_handler(AppError)
async def app_error_handler(request: Request, exc: AppError):
return JSONResponse(status_code=exc.code, content={'error': exc.message})
@app.get('/boom')
def boom():
raise AppError(409, 'conflict')
```
```python
def test_custom_error_handler():
error_client = TestClient(app, raise_server_exceptions=False)
response = error_client.get('/boom')
assert response.status_code == 409
assert response.json() == {'error': 'conflict'}
```
Without `raise_server_exceptions=False`, `TestClient` would propagate `AppError` into the test and the assertion lines would never execute. Keep this flag scoped to tests that specifically test error handling — for all other tests you want exceptions to propagate so that unexpected server errors cause immediate test failures.
## File uploads
Use the `files` parameter to send multipart file uploads through `TestClient`. The value is a dict mapping the form field name to a tuple `(filename, file-like-object, content-type)`:
```python
from fastapi import UploadFile, File
@app.post('/upload/')
async def upload_file(file: UploadFile = File(...)):
content = await file.read()
return {'filename': file.filename, 'size': len(content)}
```
```python
import io
def test_file_upload():
data = b'hello world'
response = client.post(
'/upload/',
files={'file': ('hello.txt', io.BytesIO(data), 'text/plain')},
)
assert response.status_code == 200
assert response.json() == {'filename': 'hello.txt', 'size': 11}
```
The tuple format is `(filename, file-like-object, content-type)`. The `content-type` part is optional — if omitted, httpx infers it from the filename extension. For binary or unknown files use `'application/octet-stream'`.
For multipart forms that mix regular fields with files, combine `data` and `files`:
```python
response = client.post(
'/upload/',
data={'description': 'profile picture'},
files={'avatar': ('avatar.png', io.BytesIO(png_bytes), 'image/png')},
)
```