By WebNest Studio Engineering Team
Python Tutorial
Testing FastAPI Applications
Automated tests let you change an API with confidence. FastAPI apps are easy to test: TestClient (built on HTTPX) sends requests straight to the app without starting a server, pytest runs the tests, and app.dependency_overrides swaps real dependencies — the database, the current user, external services — for test versions.
This lesson shows a typical project test suite with fixtures, a separate test database, authentication overrides and parametrised tests.
Why it matters
An API is a contract, and tests are how you make sure a change has not broken it. FastAPI's TestClient calls the application in memory, with no server and no network, so a full test suite runs in seconds. Dependency overrides let tests replace the database or the logged-in user, which makes even protected endpoints easy to test.
The Basics
Install pytest (HTTPX is already included in fastapi[standard]). Put tests in files named test_*.py with functions named test_*, create client = TestClient(app), send requests with client.get/post/patch/delete, and assert on response.status_code and response.json(). Run pytest -q. Test the unhappy paths too: 404s, 401s, 409s and validation errors are part of your API contract.
Fixtures and Dependency Overrides
pytest fixtures prepare what tests need and clean up afterwards; a fixture with yield works like a FastAPI yield dependency. app.dependency_overrides[get_session] = get_test_session makes every endpoint use a fresh in-memory test database, and app.dependency_overrides[get_current_user] = lambda: fake_user skips real authentication. Clear the overrides after each test so tests stay independent. For async code, httpx.AsyncClient with ASGITransport and pytest-anyio or pytest-asyncio let tests themselves be async.
Examples
test_api.py — fixtures, overrides and parametrised tests
# test_api.py run with: pytest -q
from typing import Annotated
import pytest
from fastapi import Depends, FastAPI, HTTPException
from fastapi.testclient import TestClient
# ---- the application under test (normally imported from app.main) ----
app = FastAPI()
def get_store(): # the "database" dependency
raise RuntimeError("real database not available in tests")
def get_current_user(): # the auth dependency
raise HTTPException(401, "Not authenticated")
Store = Annotated[dict, Depends(get_store)]
User = Annotated[str, Depends(get_current_user)]
@app.post("/notes", status_code=201)
def create_note(text: str, store: Store, user: User):
note_id = len(store) + 1
store[note_id] = {"text": text, "owner": user}
return {"id": note_id, **store[note_id]}
@app.get("/notes/{note_id}")
def read_note(note_id: int, store: Store, user: User):
if note_id not in store:
raise HTTPException(404, "Note not found")
return store[note_id]
# ---- tests ----
@pytest.fixture
def store():
return {}
@pytest.fixture
def client(store):
app.dependency_overrides[get_store] = lambda: store
app.dependency_overrides[get_current_user] = lambda: "asha"
yield TestClient(app)
app.dependency_overrides.clear() # keep tests independent
def test_create_and_read_note(client):
created = client.post("/notes?text=Buy milk")
assert created.status_code == 201
assert created.json() == {"id": 1, "text": "Buy milk", "owner": "asha"}
assert client.get("/notes/1").json()["text"] == "Buy milk"
def test_missing_note_returns_404(client):
response = client.get("/notes/99")
assert response.status_code == 404
assert response.json() == {"detail": "Note not found"}
def test_requires_authentication(store):
app.dependency_overrides[get_store] = lambda: store # no user override this time
response = TestClient(app).post("/notes?text=x")
app.dependency_overrides.clear()
assert response.status_code == 401
@pytest.mark.parametrize("url, expected", [
("/notes/abc", 422), # invalid path parameter
("/notes", 405), # GET not allowed on the collection
])
def test_bad_requests(client, url, expected):
assert client.get(url).status_code == expected
..... [100%]
5 passed in 0.21s
Testing asynchronously with httpx.AsyncClient
# pip install pytest anyio
import pytest
from fastapi import FastAPI
from httpx import ASGITransport, AsyncClient
app = FastAPI()
@app.get("/ping")
async def ping():
return {"pong": True}
@pytest.mark.anyio
async def test_ping():
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
response = await ac.get("/ping")
assert response.json() == {"pong": True}
. [100%]
1 passed in 0.05s
Common Mistakes
- Testing against the real production or development database.
- Forgetting to clear dependency_overrides, so one test changes the behaviour of the next.
- Only testing the happy path and never checking 401, 404, 409 and 422 responses.
- Sharing state between tests through module-level variables instead of fixtures.
- Starting a real server with uvicorn for tests when TestClient can call the app directly.
Exercise
The endpoint returns the settings supplied by the get_settings dependency. Write one test that checks the normal response, and a second that overrides the dependency to return {"env": "test"}, checks the response, and removes the override afterwards.
Expected output: 2 passed
from fastapi import Depends, FastAPI
from fastapi.testclient import TestClient
app = FastAPI()
def get_settings():
return {"env": "prod"}
@app.get("/env")
def read_env(settings: dict = Depends(get_settings)):
return settings
client = TestClient(app)
def test_default_env():
# TODO: assert that GET /env returns {"env": "prod"}
pass
def test_overridden_env():
# TODO: override get_settings, assert the response, then clear the override
pass
test_default_env()
test_overridden_env()
print("2 passed")
Show hints
- Overrides are set in a dictionary:
app.dependency_overrides[get_settings] = lambda: {"env": "test"}. - Clear the override in a
finallyblock, so that it is removed even if the assertion fails.
Show solution
from fastapi import Depends, FastAPI
from fastapi.testclient import TestClient
app = FastAPI()
def get_settings():
return {"env": "prod"}
@app.get("/env")
def read_env(settings: dict = Depends(get_settings)):
return settings
client = TestClient(app)
def test_default_env():
assert client.get("/env").json() == {"env": "prod"}
def test_overridden_env():
app.dependency_overrides[get_settings] = lambda: {"env": "test"}
try:
assert client.get("/env").json() == {"env": "test"}
finally:
app.dependency_overrides.clear()
test_default_env()
test_overridden_env()
print("2 passed")
Quick quiz
1. Does TestClient need a running server?
- A. Yes, on port 8000
- B. Only for POST requests
- C. No; it calls the application directly in the same process
- D. Only on Linux
Show answer
C. This makes the tests fast and independent of the network.
2. What is app.dependency_overrides for?
- A. Changing routes
- B. Caching dependencies
- C. Overriding status codes
- D. Replacing a dependency with another function during tests
Show answer
D. It maps the original dependency function to its replacement.
3. What should an API test check besides the response body?
- A. Nothing else
- B. The status code
- C. The server uptime
- D. The Python version
Show answer
B. A wrong status code with a correct-looking body is still a bug.
Interview questions
How do you test a FastAPI endpoint that needs a database?
Show answer
Override the dependency that provides the database session with one that uses a separate test database, such as an in-memory SQLite database or a temporary PostgreSQL schema, created in a pytest fixture and discarded afterwards. The endpoints then run unchanged against data the test controls, and the real database is never touched.
How do you test endpoints that require authentication?
Show answer
Either override the dependency that returns the current user so that it returns a fixed test user, which avoids tokens entirely, or log in through the real login endpoint in a fixture and send the token in the Authorization header. The first is simpler for most tests; the second is used to test the authentication flow itself. Tests should also check that a request without credentials is rejected with 401.
Key Points to Remember
- TestClient sends requests to the app in-process; pytest runs and reports the tests.
- Fixtures prepare clients, databases and data, and clean up with yield.
- app.dependency_overrides swaps databases, users and external services in tests.
- Parametrised tests cover many inputs and error cases compactly.
- httpx.AsyncClient with ASGITransport tests async code from async tests.
Practice in the playground
Write and run your own code for this topic, or start from the exercise or an example. Runs Python in your browser. Your code for each topic is kept in this browser.
Run the examples
Change an input, predict the result, then compare it with the output. Explain why the result changes.
These examples need a project environment on your computer, so they can be copied but not run here. Codelab runs Python, FastAPI backends with SQLite, plain Java 17 and HTML/CSS/JavaScript.
Written by
WebNest Studio Engineering Team
Practical lessons from developers working with Java, Python, React, databases and production systems.
Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering