Quick reference · Applications under test · Database · JWT
Use this page to check an HTTP response or temporarily replace a dependency in a test.
TestClient sends requests to the application in process, without a network server.
Here, a dependency is a function that FastAPI calls through Depends before the handler.
| Situation | Technique | Example |
|---|---|---|
| Check object creation and invalid input | Requests through TestClient |
CRUD and validation |
| Check the header-validation rule itself | Keep the original dependency and send different headers | Original function · Complete test |
| Check the handler without header validation | Set app.dependency_overrides |
Override card |
Check the API from async def |
Use ASGITransport |
Async client |
| Parameter | Value |
|---|---|
| Level | Intermediate. Async clients and database isolation are advanced |
| Prerequisites | pytest, HTTP, and context managers. Async requires async/await |
- Synchronous TestClient
- Dependency override
- Async client
- Files and middleware
- Database sessions and lifespan
- Authentication
For overrides, use the standalone example with separate installation.
For the other tests, create a practice environment on Python 3.14.
Install the common packages with python -m pip install 'fastapi==0.162.0' 'starlette==1.10.0' 'pytest==9.2.0' 'httpx2==2.16.0'.
Then add only the dependencies of the selected application.
| Application under test | Additional installation |
|---|---|
| main.py with CRUD and validation | python -m pip install 'pydantic[email]==2.14.3' 'email-validator==2.3.0' |
| uploads.py with multipart | python -m pip install 'python-multipart==0.0.33' |
| middleware_app.py with CORS | No additional packages required |
| db_app.py with a sync database | python -m pip install 'sqlalchemy==2.1.8' 'pydantic[email]==2.14.3' 'email-validator==2.3.0' |
| async_db_app.py with an async database | python -m pip install 'sqlalchemy[asyncio]==2.1.8' 'aiosqlite==0.22.1' |
| auth_app.py with passwords and JWT | python -m pip install 'python-multipart==0.0.33' 'PyJWT==2.15.1' 'pwdlib[argon2]==0.3.1' |
Save the selected application and corresponding complete test module together in the practice directory.
test_integrations.py needs both uploads.py and middleware_app.py.
test_database.py needs both database variants and their dependencies.
For the async test, add pytest-asyncio==1.4.1.post1.
Install the async test tools with this separate command.
python -m pip install pytest pytest-asyncio httpx2Use httpx2 with Starlette 1.10.0.
The earlier httpx package is still supported, but its use in TestClient is deprecated.
In older environments, adapt the async-client example by importing from httpx while retaining ASGITransport.
Avoid the direct AsyncClient(app=app) form.
HTTPX removed this argument in 0.28.0.
From the practice directory, run python -m pytest -q TEST_FILE_NAME.py.
For async tests, add -o asyncio_default_fixture_loop_scope=function to set the event-loop scope explicitly.
Tests execute requests in process.
They need neither a Uvicorn server nor external network access.
Situation — POST /items must create Book with price 25, while a negative price must be rejected.
Change — check the status code and content using the actual handler.
This test snippet targets the complete main.py.
from fastapi.testclient import TestClient
from main import app, items
items.clear()
try:
with TestClient(app) as client:
created = client.post("/items", json={"name": "Book", "price": 25})
assert created.status_code == 201
assert created.json()["name"] == "Book"
assert client.post("/items", json={"name": "Book", "price": -1}).status_code == 422
finally:
items.clear()Result — a valid item is created, and invalid input is rejected.
The TestClient context runs lifespan. The dictionary is cleared even when an assertion fails.
The snippet assumes a separate test process without concurrent changes to the shared dictionary.
Complete CRUD, PATCH, error, and output-model module.
Situation — check a handler's response without calling the real dependency.
In the practice example, /checked returns JSON, and verify_client checks the X-Client header.
To check the header itself, keep the original dependency.
For a first run, use one file with the application, installation, and two tests.
Change — add an original-function → replacement mapping to app.dependency_overrides.
Depends(verify_client) associates the route with the original function.
The dictionary key is that function object. The value is the replacement function, supplied without calling it.
Example test fragment for the complete header_dependency.py
from fastapi.testclient import TestClient
from header_dependency import app, verify_client
def skip_client_check():
return None
def test_override():
previous = app.dependency_overrides.copy()
try:
app.dependency_overrides[verify_client] = skip_client_check
with TestClient(app) as client:
response = client.get("/checked")
assert response.status_code == 200
assert response.json() == {"checked": True}
finally:
app.dependency_overrides.clear()
app.dependency_overrides.update(previous)Result — a request without the header receives 200 and {"checked": true}. The original dependency would return 422.
finally also runs on an exception. Here, it restores the entire previous override dictionary.
Limitations — an override belongs to the application. Its scope extends beyond a client or one request.
Exiting TestClient does not clear the dictionary.
Avoid concurrent override changes on a shared app within one process.
None suits a decorator-level check. A dependency supplying handler data requires an appropriate value.
To choose a function, read the dictionary-key, return-value, and sub-dependency explanations. To check cleanup, run the restoration tests after test and dependency errors. See FastAPI dependency overrides.
Situation — the test already runs in async def and needs a request without a separate server.
Change — use ASGITransport, which replaces the removed AsyncClient(app=...) argument.
This async-test snippet targets the complete main.py.
import pytest
from httpx2 import ASGITransport, AsyncClient
from main import app
@pytest.mark.asyncio
async def test_root():
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
response = await client.get("/")
assert response.json() == {"message": "Каталог работает"}Result — the request executes in the test process.
ASGITransport does not start lifespan itself. Startup resources require a separate LifespanManager.
Complete async test and cleanup boundaries.
Situation — /upload must measure a synthetic file without reading user files from disk.
Change — pass the name, bytes, and media type through files.
This test snippet targets the complete uploads.py.
from fastapi.testclient import TestClient
from uploads import app
with TestClient(app) as client:
response = client.post("/upload", files={"file": ("demo.txt", b"abc", "text/plain")})
assert response.status_code == 200
assert response.json() == {"filename": "demo.txt", "size": 3}Result — the handler returns size 3.
This request does not check the proxy's total HTTP-body limit.
Complete multiple-file, 413, CORS, and preflight checks.
Situation — a duplicate email must return 409, and the test must avoid changing the application's practice database.
Change — before TestClient, replace the engine and factory with SQLite under tmp_path.
This test snippet uses tmp_path and monkeypatch fixtures for the complete db_app.py.
import db_app
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
engine = create_engine(f"sqlite:///{tmp_path / 'users.db'}", connect_args={"check_same_thread": False})
monkeypatch.setattr(db_app, "engine", engine)
monkeypatch.setattr(db_app, "SessionLocal", sessionmaker(engine))Result — lifespan creates the schema in a separate file. The dependency obtains sessions from the test factory. Keep the replacement until the client context exits so lifespan closes the test engine. The snippet prepares the resource. The complete sync/async module checks the HTTP rejection itself.
Situation — /users/me must reject a request without a bearer token.
Change — keep the real authentication dependency and check the HTTP contract.
This snippet targets the complete auth_app.py after practice-key setup.
from fastapi.testclient import TestClient
from auth_app import app
with TestClient(app) as client:
response = client.get("/users/me")
assert response.status_code == 401
assert response.headers["WWW-Authenticate"] == "Bearer"Result — the client receives 401 and a bearer-authentication challenge.
Overriding current_user would bypass this check.
Complete module covering passwords, signatures, expiration, and a disabled user.