litestar-testing
Use when working with test_*.py, conftest.py, litestar.testing, TestClient, AsyncTestClient, create_test_client, create_async_test_client, anyio, Guard mocks, or DI overrides. Not for generic pytest.
Install
npx skills add https://github.com/litestar-org/litestar-skills/tree/main/skills/litestar-testing
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install litestar-org-litestar-skills@llmmart
git clone https://github.com/litestar-org/litestar-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole litestar-org/litestar-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
litestar-testing
Litestar-specific testing patterns built on pytest + anyio. Covers:
TestClientvsAsyncTestClient— constructor options, lifespan, and when to use eachcreate_test_clientandcreate_async_test_client— inline app factories for isolated handler/controller tests@pytest.mark.anyiosetup andpytest-asynciocoexistence rules- App + lifespan fixtures (
on_startup/on_shutdown/lifespan) - Mocking Guards and overriding DI dependencies (native
Provideand DishkaProvider) - Session testing with
set_session_dataandget_session_data - WebSocket testing with
websocket_connectandWebSocketTestSession - Unit-testing Guards and dependencies with
RequestFactory - Live server subprocess testing with
subprocess_async_clientandsubprocess_sync_client - Integration with
pytest-databases(see../pytest-databases/SKILL.md) andpolyfactory(see../polyfactory/SKILL.md) - Autowire discovery and cache isolation (see
../litestar-autowire/references/testing.md)
For JS-side testing (Vitest, Testing Library, Playwright), use the upstream Vitest docs and Litestar's own JS examples. Out of scope here.
Code Style Rules
- PEP 604 unions:
T | None, neverOptional[T] - Test modules MAY use
from __future__ import annotations— they are pure consumer code. - Function-based tests (not class-based)
- One assertion concern per test
- Async Litestar tests use
@pytest.mark.anyioby default; do not mix AnyIO andpytest-asyncioauto modes. - Prefer
AsyncTestClientfor new code;TestClientonly for legacy / sync-only flows. - Always enter test clients as context managers (
async with AsyncTestClient(...)/with TestClient(...)) — implicit lifespan startup without a context manager emitsDeprecationWarningand is removed in Litestar 3.0.
Quick Reference
TestClient vs AsyncTestClient
| Client | Base Class | Context Manager | Session Helpers | WebSocket Connect |
|---|---|---|---|---|
AsyncTestClient |
httpx.AsyncClient, BaseTestClient |
async with AsyncTestClient(app=app) as client: |
await client.set_session_data(...) / await client.get_session_data() |
with await client.websocket_connect("/ws") as ws: |
TestClient |
httpx.Client, BaseTestClient |
with TestClient(app=app) as client: |
client.set_session_data(...) / client.get_session_data() |
with client.websocket_connect("/ws") as ws: |
Both clients accept the same constructor parameters:
from litestar.testing import AsyncTestClient, TestClient
AsyncTestClient(
app=app,
base_url="http://testserver.local", # Must contain a dot ('.') or UserWarning is emitted
raise_server_exceptions=True, # False wraps unhandled server exceptions as HTTP 500 responses
root_path="",
backend="asyncio", # "asyncio" | "trio"
backend_options=None,
session_config=None, # Required for get_session_data() / set_session_data()
timeout=None,
cookies=None,
)
Both set follow_redirects=True and headers={"user-agent": "testclient"} by default. When testing template responses, TestClientTransport populates response.template and response.context on the returned httpx.Response.
from litestar.testing import AsyncTestClient
async def test_index(async_client: AsyncTestClient) -> None:
resp = await async_client.get("/")
assert resp.status_code == 200
from litestar.testing import TestClient
def test_index(client: TestClient) -> None:
resp = client.get("/")
assert resp.status_code == 200
create_test_client and create_async_test_client
For isolated route handler, controller, or router tests without bootstrapping the full application factory, use create_async_test_client(route_handlers=..., **litestar_and_client_kwargs) (or create_test_client for sync tests). Both build a Litestar instance and return a configured test client.
import pytest
from litestar import get
from litestar.testing import create_async_test_client
@get("/health")
async def health_check() -> dict[str, str]:
return {"status": "ok"}
@pytest.mark.anyio
async def test_health_check() -> None:
async with create_async_test_client(route_handlers=health_check) as client:
resp = await client.get("/health")
assert resp.status_code == 200
assert resp.json() == {"status": "ok"}
anyio vs pytest-asyncio Setup
# conftest.py
import pytest
@pytest.fixture(scope="session")
def anyio_backend() -> str:
return "asyncio"
Prefer @pytest.mark.anyio because Litestar's internal concurrency model is built on AnyIO. Do not mix @pytest.mark.anyio and @pytest.mark.asyncio in the same test module.
App + Lifespan Fixture
# conftest.py
from collections.abc import AsyncGenerator
import pytest
from litestar import Litestar
from litestar.testing import AsyncTestClient
from app import create_app
@pytest.fixture
async def app() -> Litestar:
return create_app()
@pytest.fixture
async def async_client(app: Litestar) -> AsyncGenerator[AsyncTestClient[Litestar], None]:
async with AsyncTestClient(app=app) as client:
yield client
async with AsyncTestClient(...) enters LifeSpanHandler, firing on_startup / on_shutdown hooks and plugin lifespan context managers (Vite, SAQ, SQLAlchemy, Channels, etc.). Without the context manager, implicit startup emits a DeprecationWarning and shutdown hooks never run.
Mocking Guards & Overriding DI Dependencies (Match Your Stack)
Guards are functions of (connection: ASGIConnection, route_handler: BaseRouteHandler) -> None | Awaitable[None]. Test the real guard with fake identity or authorization providers, or unit-test the guard directly with RequestFactory. Build a fresh app with replacement providers; Litestar has no mutable app.dependency_overrides registry.
- Option A — Litestar Built-in DI (
Provide+NamedDependency): Pass replacementProvideentries tocreate_app(dependencies=...)orcreate_async_test_client(..., dependencies=...). Handler parameters resolved by name must useNamedDependency[T]. For synchronous test providers, always specifysync_to_thread=False(orTrue) to avoidLitestarWarning. - Option B — Dishka DI (
Provider+make_async_container): SubclassProviderin tests and pass the test provider afterLitestarProvider()and production providers inmake_async_container(LitestarProvider(), AppProvider(), FakeEmailProvider(mock_email))— later providers override earlier ones for matching return types. Route handlers usingFromDishka[T]must be decorated with@inject(or@inject_websocket, or registered on aDishkaRouter) before callingsetup_dishka(container=container, app=app). See Async Testing for fullFakeEmailProvideranddishka_clientfixture patterns.
from collections.abc import AsyncGenerator
from unittest.mock import AsyncMock
import pytest
from litestar import post
from litestar.di import NamedDependency, Provide
from litestar.testing import AsyncTestClient, create_async_test_client
@post("/notify")
async def notify_handler(email_service: NamedDependency[AsyncMock]) -> dict[str, bool]:
await email_service.send("user@example.com")
return {"sent": True}
@pytest.fixture
async def client_with_email() -> AsyncGenerator[tuple[AsyncTestClient, AsyncMock], None]:
fake_email = AsyncMock()
async with create_async_test_client(
route_handlers=[notify_handler],
dependencies={
"email_service": Provide(lambda: fake_email, sync_to_thread=False),
},
) as client:
yield client, fake_email
Session Testing (set_session_data and get_session_data)
Pass the same session_config (ServerSideSessionConfig or CookieBackendConfig) to both middleware=[session_config.middleware] and session_config=session_config on the test client (omitting session_config on the client raises ImproperlyConfiguredException). On AsyncTestClient, await client.set_session_data(data) and await client.get_session_data() are async; on TestClient, they are sync.
import pytest
from litestar import Request, get, post
from litestar.middleware.session.server_side import ServerSideSessionConfig
from litestar.testing import create_async_test_client
session_config = ServerSideSessionConfig()
@get("/me")
async def read_session(request: Request) -> dict[str, str]:
return dict(request.session)
@post("/login")
async def write_session(request: Request, data: dict[str, str]) -> None:
request.session["user_id"] = data["user_id"]
@pytest.mark.anyio
async def test_session_roundtrip() -> None:
async with create_async_test_client(
route_handlers=[read_session, write_session],
middleware=[session_config.middleware],
session_config=session_config,
) as client:
await client.set_session_data({"user_id": "u-123"})
assert (await client.get("/me")).json() == {"user_id": "u-123"}
await client.post("/login", json={"user_id": "u-456"})
assert await client.get_session_data() == {"user_id": "u-456"}
WebSocket, SSE (ServerSentEvent), and ChannelsPlugin Testing
- WebSockets (
websocket_connect): OnAsyncTestClient,websocket_connectisasync def(must be awaited), while the returnedWebSocketTestSessionis always a synchronous context manager (with await client.websocket_connect(...) as ws:) with synchronous methods (ws.send_json(...),ws.receive_json(...),ws.close(...)). Server-initiated close causesws.receive*()to raiselitestar.exceptions.WebSocketDisconnect. - SSE (
ServerSentEvent): Stream events withasync with client.stream("GET", "/sse") as resp:and iterateresp.aiter_lines(). ChannelsPlugin: ConfigureChannelsPlugin(backend=MemoryChannelsBackend(), channels=["alerts"], create_ws_route_handlers=True)and enterasync with create_async_test_client(plugins=[channels_plugin]) as client:. Publish viachannels_plugin.publish(data, channels=["alerts"])and consume viawebsocket_connect.
from collections.abc import AsyncGenerator
import pytest
from litestar import get, websocket_listener
from litestar.channels import ChannelsPlugin
from litestar.channels.backends.memory import MemoryChannelsBackend
from litestar.response.sse import ServerSentEvent, ServerSentEventMessage
from litestar.testing import create_async_test_client
@websocket_listener("/ws")
async def echo_ws(data: dict[str, str]) -> dict[str, str]:
return {"echo": data["msg"]}
@get("/events")
async def stream_events() -> ServerSentEvent:
async def generator() -> AsyncGenerator[ServerSentEventMessage, None]:
yield ServerSentEventMessage(data="ready", event="status")
return ServerSentEvent(generator())
@pytest.mark.anyio
async def test_ws_sse_and_channels() -> None:
channels = ChannelsPlugin(backend=MemoryChannelsBackend(), channels=["alerts"], create_ws_route_handlers=True)
async with create_async_test_client(route_handlers=[echo_ws, stream_events], plugins=[channels]) as client:
with await client.websocket_connect("/ws") as ws:
ws.send_json({"msg": "hello"})
assert ws.receive_json() == {"echo": "hello"}
async with client.stream("GET", "/events") as resp:
lines = [line async for line in resp.aiter_lines() if line]
assert lines == ["event: status", "data: ready"]
with await client.websocket_connect("/alerts") as ws:
channels.publish({"msg": "fired"}, channels=["alerts"])
assert ws.receive_json() == {"msg": "fired"}
Unit Testing with RequestFactory & Live Subprocess Clients
RequestFactory: Construct reallitestar.connection.Requestinstances for unit-testing Guards or dependencies without an ASGI transport (factory = RequestFactory(); req = factory.get("/admin", user={"role": "viewer"})). In Litestar,connection.appreadsrequest.scope["litestar_app"](notrequest.scope["app"]);RequestFactorypopulatesscope["litestar_app"]automatically.subprocess_async_client/subprocess_sync_client: Verifylitestar --app <app> runCLI startup and real socket binding viaasync with subprocess_async_client(workdir=tmp_path, app="main:app") as client:. See Async Testing for complete examples.
Integration with pytest-databases
Combine pytest-databases fixtures with the app fixture. See ../pytest-databases/SKILL.md.
# conftest.py
pytest_plugins = ["pytest_databases.docker.postgres"]
@pytest.fixture
async def app(postgres_service) -> Litestar:
from app import create_app
from app.config import Settings
settings = Settings(
database_url=f"postgresql+asyncpg://{postgres_service.user}:{postgres_service.password}@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}"
)
return create_app(settings=settings)
The postgres_service fixture starts a Postgres container. Inject its connection details into the app config.
Request Bodies
| Body Type | Pass via |
|---|---|
| JSON | client.post("/", json={...}) |
| Form | client.post("/", data={...}) |
| Multipart (file upload) | client.post("/", files={"file": ("name.txt", b"content", "text/plain")}) |
| Raw bytes | client.post("/", content=b"...") |
| Custom content-type | client.post("/", content=b"...", headers={"Content-Type": "..."}) |
async def test_create_user(async_client: AsyncTestClient) -> None:
resp = await async_client.post(
"/api/users",
json={"name": "Alice", "email": "alice@example.com"},
)
assert resp.status_code == 201
body = resp.json()
assert body["name"] == "Alice"
Headers, Cookies, Auth, HTMX, and Response Assertions
resp = await async_client.get(
"/items/list",
headers={"Authorization": "Bearer token", "HX-Request": "true", "HX-Target": "#item-list"},
cookies={"session": "abc123"},
)
assert resp.status_code == 200
assert "HX-Trigger" in resp.headers
assert "<ul" in resp.text
Parametrize
import pytest
@pytest.mark.parametrize(
"payload, expected_status",
[
({"name": "valid", "email": "a@b.co"}, 201),
({"name": "", "email": "a@b.co"}, 400),
({"name": "valid", "email": "not-email"}, 400),
],
)
@pytest.mark.anyio
async def test_create_user_validation(async_client, payload, expected_status):
resp = await async_client.post("/api/users", json=payload)
assert resp.status_code == expected_status
Coverage
pytest --cov=src --cov-report=html
pytest --cov=src --cov-fail-under=90
References Index
- Async Testing — anyio setup, async fixtures,
create_async_test_client, session/WebSocket/RequestFactory/subprocess helpers, and common pitfalls. - litestar — Litestar fundamentals.
- pytest-databases — Container-based DB fixtures.
- polyfactory — Model, dataclass, and msgspec test data factories.
- litestar-email —
backend="memory"andInMemoryBackendfor email tests. - litestar-saq — Mocking task queues.
Official References
- https://docs.litestar.dev/2/usage/testing.html
- https://github.com/litestar-org/litestar
- https://docs.pytest.org/en/stable/
- https://anyio.readthedocs.io/en/stable/testing.html
Shared Styleguide Baseline
Files (litestar-skills)
-
references
-
async_testing.md 15.3 KB
Loading…
-
-
SKILL.md 23.1 KB
--- name: litestar-testing description: "Use when working with test_*.py, conftest.py, litestar.testing, TestClient, AsyncTestClient, create_test_client, create_async_test_client, anyio, Guard mocks, or DI overrides. Not for generic pytest." --- # litestar-testing Litestar-specific testing patterns built on pytest + anyio. Covers: - `TestClient` vs `AsyncTestClient` — constructor options, lifespan, and when to use each - `create_test_client` and `create_async_test_client` — inline app factories for isolated handler/controller tests - `@pytest.mark.anyio` setup and `pytest-asyncio` coexistence rules - App + lifespan fixtures (`on_startup` / `on_shutdown` / `lifespan`) - Mocking Guards and overriding DI dependencies (native `Provide` and Dishka `Provider`) - Session testing with `set_session_data` and `get_session_data` - WebSocket testing with `websocket_connect` and `WebSocketTestSession` - Unit-testing Guards and dependencies with `RequestFactory` - Live server subprocess testing with `subprocess_async_client` and `subprocess_sync_client` - Integration with `pytest-databases` (see `../pytest-databases/SKILL.md`) and `polyfactory` (see `../polyfactory/SKILL.md`) - Autowire discovery and cache isolation (see `../litestar-autowire/references/testing.md`) For JS-side testing (Vitest, Testing Library, Playwright), use the upstream Vitest docs and Litestar's own JS examples. Out of scope here. ## Code Style Rules - PEP 604 unions: `T | None`, never `Optional[T]` - Test modules MAY use `from __future__ import annotations` — they are pure consumer code. - Function-based tests (not class-based) - One assertion concern per test - Async Litestar tests use `@pytest.mark.anyio` by default; do not mix AnyIO and `pytest-asyncio` auto modes. - Prefer `AsyncTestClient` for new code; `TestClient` only for legacy / sync-only flows. - Always enter test clients as context managers (`async with AsyncTestClient(...)` / `with TestClient(...)`) — implicit lifespan startup without a context manager emits `DeprecationWarning` and is removed in Litestar 3.0. ## Quick Reference ### TestClient vs AsyncTestClient | Client | Base Class | Context Manager | Session Helpers | WebSocket Connect | | --- | --- | --- | --- | --- | | `AsyncTestClient` | `httpx.AsyncClient`, `BaseTestClient` | `async with AsyncTestClient(app=app) as client:` | `await client.set_session_data(...)` / `await client.get_session_data()` | `with await client.websocket_connect("/ws") as ws:` | | `TestClient` | `httpx.Client`, `BaseTestClient` | `with TestClient(app=app) as client:` | `client.set_session_data(...)` / `client.get_session_data()` | `with client.websocket_connect("/ws") as ws:` | Both clients accept the same constructor parameters: ```python from litestar.testing import AsyncTestClient, TestClient AsyncTestClient( app=app, base_url="http://testserver.local", # Must contain a dot ('.') or UserWarning is emitted raise_server_exceptions=True, # False wraps unhandled server exceptions as HTTP 500 responses root_path="", backend="asyncio", # "asyncio" | "trio" backend_options=None, session_config=None, # Required for get_session_data() / set_session_data() timeout=None, cookies=None, ) ``` Both set `follow_redirects=True` and `headers={"user-agent": "testclient"}` by default. When testing template responses, `TestClientTransport` populates `response.template` and `response.context` on the returned `httpx.Response`. ```python from litestar.testing import AsyncTestClient async def test_index(async_client: AsyncTestClient) -> None: resp = await async_client.get("/") assert resp.status_code == 200 ``` ```python from litestar.testing import TestClient def test_index(client: TestClient) -> None: resp = client.get("/") assert resp.status_code == 200 ``` ### `create_test_client` and `create_async_test_client` For isolated route handler, controller, or router tests without bootstrapping the full application factory, use `create_async_test_client(route_handlers=..., **litestar_and_client_kwargs)` (or `create_test_client` for sync tests). Both build a `Litestar` instance and return a configured test client. ```python import pytest from litestar import get from litestar.testing import create_async_test_client @get("/health") async def health_check() -> dict[str, str]: return {"status": "ok"} @pytest.mark.anyio async def test_health_check() -> None: async with create_async_test_client(route_handlers=health_check) as client: resp = await client.get("/health") assert resp.status_code == 200 assert resp.json() == {"status": "ok"} ``` ### anyio vs pytest-asyncio Setup ```python # conftest.py import pytest @pytest.fixture(scope="session") def anyio_backend() -> str: return "asyncio" ``` Prefer `@pytest.mark.anyio` because Litestar's internal concurrency model is built on AnyIO. Do not mix `@pytest.mark.anyio` and `@pytest.mark.asyncio` in the same test module. ### App + Lifespan Fixture ```python # conftest.py from collections.abc import AsyncGenerator import pytest from litestar import Litestar from litestar.testing import AsyncTestClient from app import create_app @pytest.fixture async def app() -> Litestar: return create_app() @pytest.fixture async def async_client(app: Litestar) -> AsyncGenerator[AsyncTestClient[Litestar], None]: async with AsyncTestClient(app=app) as client: yield client ``` `async with AsyncTestClient(...)` enters `LifeSpanHandler`, firing `on_startup` / `on_shutdown` hooks and plugin `lifespan` context managers (Vite, SAQ, SQLAlchemy, Channels, etc.). Without the context manager, implicit startup emits a `DeprecationWarning` and shutdown hooks never run. ### Mocking Guards & Overriding DI Dependencies (Match Your Stack) Guards are functions of `(connection: ASGIConnection, route_handler: BaseRouteHandler) -> None | Awaitable[None]`. Test the real guard with fake identity or authorization providers, or unit-test the guard directly with `RequestFactory`. Build a fresh app with replacement providers; Litestar has no mutable `app.dependency_overrides` registry. - **Option A — Litestar Built-in DI (`Provide` + `NamedDependency`)**: Pass replacement `Provide` entries to `create_app(dependencies=...)` or `create_async_test_client(..., dependencies=...)`. Handler parameters resolved by name must use `NamedDependency[T]`. For synchronous test providers, always specify `sync_to_thread=False` (or `True`) to avoid `LitestarWarning`. - **Option B — Dishka DI (`Provider` + `make_async_container`)**: Subclass `Provider` in tests and pass the test provider *after* `LitestarProvider()` and production providers in `make_async_container(LitestarProvider(), AppProvider(), FakeEmailProvider(mock_email))` — later providers override earlier ones for matching return types. Route handlers using `FromDishka[T]` must be decorated with `@inject` (or `@inject_websocket`, or registered on a `DishkaRouter`) before calling `setup_dishka(container=container, app=app)`. See [Async Testing](references/async_testing.md) for full `FakeEmailProvider` and `dishka_client` fixture patterns. ```python from collections.abc import AsyncGenerator from unittest.mock import AsyncMock import pytest from litestar import post from litestar.di import NamedDependency, Provide from litestar.testing import AsyncTestClient, create_async_test_client @post("/notify") async def notify_handler(email_service: NamedDependency[AsyncMock]) -> dict[str, bool]: await email_service.send("user@example.com") return {"sent": True} @pytest.fixture async def client_with_email() -> AsyncGenerator[tuple[AsyncTestClient, AsyncMock], None]: fake_email = AsyncMock() async with create_async_test_client( route_handlers=[notify_handler], dependencies={ "email_service": Provide(lambda: fake_email, sync_to_thread=False), }, ) as client: yield client, fake_email ``` ### Session Testing (`set_session_data` and `get_session_data`) Pass the same `session_config` (`ServerSideSessionConfig` or `CookieBackendConfig`) to both `middleware=[session_config.middleware]` and `session_config=session_config` on the test client (omitting `session_config` on the client raises `ImproperlyConfiguredException`). On `AsyncTestClient`, `await client.set_session_data(data)` and `await client.get_session_data()` are **async**; on `TestClient`, they are **sync**. ```python import pytest from litestar import Request, get, post from litestar.middleware.session.server_side import ServerSideSessionConfig from litestar.testing import create_async_test_client session_config = ServerSideSessionConfig() @get("/me") async def read_session(request: Request) -> dict[str, str]: return dict(request.session) @post("/login") async def write_session(request: Request, data: dict[str, str]) -> None: request.session["user_id"] = data["user_id"] @pytest.mark.anyio async def test_session_roundtrip() -> None: async with create_async_test_client( route_handlers=[read_session, write_session], middleware=[session_config.middleware], session_config=session_config, ) as client: await client.set_session_data({"user_id": "u-123"}) assert (await client.get("/me")).json() == {"user_id": "u-123"} await client.post("/login", json={"user_id": "u-456"}) assert await client.get_session_data() == {"user_id": "u-456"} ``` ### WebSocket, SSE (`ServerSentEvent`), and `ChannelsPlugin` Testing - **WebSockets (`websocket_connect`)**: On `AsyncTestClient`, `websocket_connect` is `async def` (must be awaited), while the returned `WebSocketTestSession` is always a **synchronous** context manager (`with await client.websocket_connect(...) as ws:`) with synchronous methods (`ws.send_json(...)`, `ws.receive_json(...)`, `ws.close(...)`). Server-initiated close causes `ws.receive*()` to raise `litestar.exceptions.WebSocketDisconnect`. - **SSE (`ServerSentEvent`)**: Stream events with `async with client.stream("GET", "/sse") as resp:` and iterate `resp.aiter_lines()`. - **`ChannelsPlugin`**: Configure `ChannelsPlugin(backend=MemoryChannelsBackend(), channels=["alerts"], create_ws_route_handlers=True)` and enter `async with create_async_test_client(plugins=[channels_plugin]) as client:`. Publish via `channels_plugin.publish(data, channels=["alerts"])` and consume via `websocket_connect`. ```python from collections.abc import AsyncGenerator import pytest from litestar import get, websocket_listener from litestar.channels import ChannelsPlugin from litestar.channels.backends.memory import MemoryChannelsBackend from litestar.response.sse import ServerSentEvent, ServerSentEventMessage from litestar.testing import create_async_test_client @websocket_listener("/ws") async def echo_ws(data: dict[str, str]) -> dict[str, str]: return {"echo": data["msg"]} @get("/events") async def stream_events() -> ServerSentEvent: async def generator() -> AsyncGenerator[ServerSentEventMessage, None]: yield ServerSentEventMessage(data="ready", event="status") return ServerSentEvent(generator()) @pytest.mark.anyio async def test_ws_sse_and_channels() -> None: channels = ChannelsPlugin(backend=MemoryChannelsBackend(), channels=["alerts"], create_ws_route_handlers=True) async with create_async_test_client(route_handlers=[echo_ws, stream_events], plugins=[channels]) as client: with await client.websocket_connect("/ws") as ws: ws.send_json({"msg": "hello"}) assert ws.receive_json() == {"echo": "hello"} async with client.stream("GET", "/events") as resp: lines = [line async for line in resp.aiter_lines() if line] assert lines == ["event: status", "data: ready"] with await client.websocket_connect("/alerts") as ws: channels.publish({"msg": "fired"}, channels=["alerts"]) assert ws.receive_json() == {"msg": "fired"} ``` ### Unit Testing with `RequestFactory` & Live Subprocess Clients - **`RequestFactory`**: Construct real `litestar.connection.Request` instances for unit-testing Guards or dependencies without an ASGI transport (`factory = RequestFactory(); req = factory.get("/admin", user={"role": "viewer"})`). In Litestar, `connection.app` reads `request.scope["litestar_app"]` (not `request.scope["app"]`); `RequestFactory` populates `scope["litestar_app"]` automatically. - **`subprocess_async_client` / `subprocess_sync_client`**: Verify `litestar --app <app> run` CLI startup and real socket binding via `async with subprocess_async_client(workdir=tmp_path, app="main:app") as client:`. See [Async Testing](references/async_testing.md) for complete examples. ### Integration with pytest-databases Combine `pytest-databases` fixtures with the app fixture. See `../pytest-databases/SKILL.md`. ```python # conftest.py pytest_plugins = ["pytest_databases.docker.postgres"] @pytest.fixture async def app(postgres_service) -> Litestar: from app import create_app from app.config import Settings settings = Settings( database_url=f"postgresql+asyncpg://{postgres_service.user}:{postgres_service.password}@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}" ) return create_app(settings=settings) ``` The `postgres_service` fixture starts a Postgres container. Inject its connection details into the app config. ### Request Bodies | Body Type | Pass via | | --- | --- | | JSON | `client.post("/", json={...})` | | Form | `client.post("/", data={...})` | | Multipart (file upload) | `client.post("/", files={"file": ("name.txt", b"content", "text/plain")})` | | Raw bytes | `client.post("/", content=b"...")` | | Custom content-type | `client.post("/", content=b"...", headers={"Content-Type": "..."})` | ```python async def test_create_user(async_client: AsyncTestClient) -> None: resp = await async_client.post( "/api/users", json={"name": "Alice", "email": "alice@example.com"}, ) assert resp.status_code == 201 body = resp.json() assert body["name"] == "Alice" ``` ### Headers, Cookies, Auth, HTMX, and Response Assertions ```python resp = await async_client.get( "/items/list", headers={"Authorization": "Bearer token", "HX-Request": "true", "HX-Target": "#item-list"}, cookies={"session": "abc123"}, ) assert resp.status_code == 200 assert "HX-Trigger" in resp.headers assert "<ul" in resp.text ``` ### Parametrize ```python import pytest @pytest.mark.parametrize( "payload, expected_status", [ ({"name": "valid", "email": "a@b.co"}, 201), ({"name": "", "email": "a@b.co"}, 400), ({"name": "valid", "email": "not-email"}, 400), ], ) @pytest.mark.anyio async def test_create_user_validation(async_client, payload, expected_status): resp = await async_client.post("/api/users", json=payload) assert resp.status_code == expected_status ``` ### Coverage ```bash pytest --cov=src --cov-report=html pytest --cov=src --cov-fail-under=90 ``` <workflow> ## Workflow ### Step 1: Set Up anyio Backend Add `anyio_backend` fixture to `conftest.py` returning `"asyncio"`. Mark async tests with `@pytest.mark.anyio`. ### Step 2: App + Client Fixtures Build an `app` fixture that returns a fresh `Litestar` instance per test (or per session if no shared state). Build an `async_client` fixture that wraps the app in `AsyncTestClient` via `async with` (or use `create_async_test_client` for isolated handler/controller tests). ### Step 3: Add Database Fixtures If the app talks to a DB, layer in `pytest-databases` (`postgres_service`, `mysql_service`, etc.) and pass connection details into the app config. See `../pytest-databases/SKILL.md`. ### Step 4: Override DI for Externals Mock `EmailService`, HTTP clients, and other side-effect-laden dependencies by constructing a fresh app or test client with replacement `Provide` instances (or a Dishka override `Provider` passed to `make_async_container`). Avoid real network calls in tests. ### Step 5: Test Guards and Sessions Build a fresh app with fake identity providers, use `RequestFactory` to unit-test Guards directly, and pass `session_config` to the test client when seeding or asserting session state via `set_session_data` / `get_session_data`. ### Step 6: Write Tests - One assertion concern per test. - Use `@pytest.mark.parametrize` for input variations. - Use `AsyncTestClient` for new code (`with await client.websocket_connect(...) as ws:` for WebSockets). - Include HTMX / Inertia headers when testing those paths. ### Step 7: Verify Coverage `pytest --cov=src --cov-fail-under=90`. Cover handlers, services, Guards, and at least one happy-path + one error-path per route. </workflow> <guardrails> ## Guardrails - **Use `@pytest.mark.anyio` for new Litestar async tests** — keep `pytest-asyncio` only when a project already uses it explicitly, and never mix auto modes. - **Always enter `AsyncTestClient` / `TestClient` as a context manager** — without `async with` / `with`, plugin lifespans (Vite, SAQ, SQLAlchemy) do not run cleanly and Litestar emits a `DeprecationWarning` for implicit startup (removed in 3.0). - **Prefer `AsyncTestClient` over `TestClient`** for new tests — the async client matches Litestar's runtime model. - **Pass `session_config` to the client when using `get_session_data` / `set_session_data`** — omitting `session_config` raises `ImproperlyConfiguredException`. - **Await `websocket_connect` on `AsyncTestClient`, then enter `WebSocketTestSession` with sync `with`** — `with await async_client.websocket_connect("/ws") as ws:`; `WebSocketTestSession` methods (`send_json`, `receive_json`, etc.) are synchronous. - **Mock side effects via DI override**, not patching — keeps tests isolated from import order and global state. - **Build a fresh app for dependency replacements** — Litestar has no mutable dependency-override registry, and shared app mutation races under parallel tests. - **Use `pytest-databases` for real DB testing** — never mock SQLAlchemy / sqlspec internals; assertions on mocked queries don't catch real bugs. - **Function-based tests** — no class-based test containers unless absolutely needed for shared setup. - **One assertion concern per test** — failures should pinpoint a single behavior. - **Don't share state between tests** — fresh app + fresh DB per test (or per module with explicit cleanup). - **Test the HTMX path with `HX-Request: true`** — handlers that branch on `request.htmx` need both branches covered. - **Mock email via `backend="memory"` / `InMemoryBackend`** — see `../litestar-email/SKILL.md`. </guardrails> <validation> ### Validation Checkpoint Before delivering Litestar tests, verify: - [ ] `anyio_backend` fixture returns `"asyncio"` - [ ] Async tests use `@pytest.mark.anyio` (no mixed AnyIO / `pytest-asyncio` auto modes) - [ ] `AsyncTestClient` / `create_async_test_client` is wrapped in `async with` (lifespan fires) - [ ] `session_config` is passed to the test client whenever `get_session_data` / `set_session_data` is called - [ ] WebSocket tests on `AsyncTestClient` use `with await client.websocket_connect(...) as ws:` - [ ] DI dependencies (email, HTTP clients) are overridden via `Provide` or Dishka `Provider`, not patched - [ ] DB-dependent tests use `pytest-databases` fixtures - [ ] Guards either pass real auth, use a fresh app with fake identity providers, or are unit-tested with `RequestFactory` - [ ] One assertion concern per test; parametrize for input variations - [ ] HTMX-targeted handlers have tests with `HX-Request: true` - [ ] Coverage gate (`--cov-fail-under`) is set in CI </validation> <example> ## Example **Task:** Test an account creation endpoint that hits Postgres, sends a welcome email via SAQ, and is guarded by an auth check. ```python # conftest.py from collections.abc import AsyncGenerator from unittest.mock import AsyncMock, Mock import pytest from litestar import Litestar from litestar.di import Provide from litestar.testing import AsyncTestClient pytest_plugins = ["pytest_databases.docker.postgres"] @pytest.fixture def anyio_backend() -> str: return "asyncio" @pytest.fixture async def app(postgres_service) -> tuple[Litestar, AsyncMock]: from app import create_app from app.config import Settings fake_queue = AsyncMock() fake_task_queues = Mock() fake_task_queues.get.return_value = fake_queue async def provide_fake_task_queues() -> Mock: return fake_task_queues settings = Settings( database_url=( f"postgresql+asyncpg://{postgres_service.user}:{postgres_service.password}" f"@{postgres_service.host}:{postgres_service.port}/{postgres_service.database}" ), ) return ( create_app( settings=settings, dependencies={ "task_queues": Provide(provide_fake_task_queues), }, ), fake_queue, ) @pytest.fixture async def async_client( app: tuple[Litestar, AsyncMock], ) -> AsyncGenerator[tuple[AsyncTestClient, AsyncMock], None]: test_app, fake_queue = app async with AsyncTestClient(app=test_app) as client: yield client, fake_queue ``` ```python # tests/test_accounts.py import pytest @pytest.mark.anyio async def test_create_account_persists_and_queues_email(async_client): client, fake_queue = async_client resp = await client.post( "/api/accounts", json={"email": "alice@example.com", "name": "Alice"}, ) assert resp.status_code == 201 body = resp.json() assert body["email"] == "alice@example.com" fake_queue.enqueue.assert_awaited_once() args, kwargs = fake_queue.enqueue.await_args assert args[0] == "send_welcome_email" assert kwargs["email"] == "alice@example.com" @pytest.mark.anyio @pytest.mark.parametrize( "payload, expected_status", [ ({"email": "valid@example.com", "name": "Valid"}, 201), ({"email": "", "name": "Valid"}, 400), ({"email": "valid@example.com", "name": ""}, 400), ], ) async def test_create_account_validation(async_client, payload, expected_status): client, _ = async_client resp = await client.post("/api/accounts", json=payload) assert resp.status_code == expected_status ``` </example> --- ## References Index - **[Async Testing](references/async_testing.md)** — anyio setup, async fixtures, `create_async_test_client`, session/WebSocket/`RequestFactory`/subprocess helpers, and common pitfalls. - **[litestar](../litestar/SKILL.md)** — Litestar fundamentals. - **[pytest-databases](../pytest-databases/SKILL.md)** — Container-based DB fixtures. - **[polyfactory](../polyfactory/SKILL.md)** — Model, dataclass, and msgspec test data factories. - **[litestar-email](../litestar-email/SKILL.md)** — `backend="memory"` and `InMemoryBackend` for email tests. - **[litestar-saq](../litestar-saq/SKILL.md)** — Mocking task queues. ## Official References - <https://docs.litestar.dev/2/usage/testing.html> - <https://github.com/litestar-org/litestar> - <https://docs.pytest.org/en/stable/> - <https://anyio.readthedocs.io/en/stable/testing.html> ## Shared Styleguide Baseline - [General Principles](../litestar-styleguide/references/general.md) - [Testing](../litestar-styleguide/references/testing.md) - [Python](../litestar-styleguide/references/python.md) - [Litestar](../litestar-styleguide/references/litestar.md)
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.