litestar-testing

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