Skip to content

Latest commit

 

History

History
247 lines (190 loc) · 11.7 KB

testing.md

File metadata and controls

247 lines (190 loc) · 11.7 KB

Check the API and access rejection

Русский

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

Navigation

Dependencies by task

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'

Setup

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 httpx2

Use 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.

Synchronous TestClient

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.

Dependency override

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.

Async client

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.

Files and middleware

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.

Database sessions and lifespan

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.

Authentication

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.

Sources