litestar-testing

Write pytest-based tests for Litestar applications using AsyncTestClient and anyio.

Updated Aug 17, 2026
One-click install
npx skills add https://github.com/renjianguo666/litecms --skill litestar-testing-renjianguo666
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: litestar-testing
Source: https://github.com/renjianguo666/litecms/tree/main/.agents/skills/litestar-testing
Command: npx skills add https://github.com/renjianguo666/litecms --skill litestar-testing-renjianguo666

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pytest, anyio, litestar, pytest-databases, and includes references (resource) components.

What problem does it solve? Testing Litestar applications requires framework-specific patterns that generic pytest knowledge does not cover: anyio instead of pytest-asyncio, lifespan-aware test clients, DI overrides for mocking, and Guard bypass strategies. This Skill provides the correct patterns so tests actually exercise the real application lifecycle. ## Core Features & Use Cases - TestClient vs AsyncTestClient guidance: Choose the right client and always trigger lifespan via async with so plugins like Vite, SAQ, and SQLAlchemy initialize. - Mocking patterns: Override DI dependencies and Guards cleanly instead of patching internals, keeping tests isolated from import order. - Database integration: Combine pytest-databases container fixtures with app fixtures for real Postgres-backed integration tests. - Use Case: You need to test an account creation endpoint that writes to Postgres, enqueues a welcome email via SAQ, and sits behind an auth Guard. This Skill shows the conftest.py fixtures, DI overrides, and parametrized test structure to cover happy paths and validation errors. ## Quick Start Ask the AI to write an async Litestar test for a specific endpoint using AsyncTestClient with anyio, including fixtures for the app, database, and mocked external services.

Frequently Asked Questions about litestar-testing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I test Litestar endpoints with pytest?▼

Use AsyncTestClient from litestar.testing wrapped in an async with block so application lifespan runs. Mark async tests with @pytest.mark.anyio and provide an anyio_backend fixture returning "asyncio" in conftest.py.

Should I use TestClient or AsyncTestClient for Litestar?▼

Prefer AsyncTestClient for new tests because it matches Litestar's async runtime and runs ASGI in the test event loop. TestClient is reserved for legacy or sync-only test bodies and runs ASGI in a thread pool.

Can I use pytest-asyncio with Litestar tests?▼

No, Litestar runs on anyio and pytest-asyncio conflicts with it. Use @pytest.mark.anyio instead of @pytest.mark.asyncio, and remove pytest-asyncio from the project to avoid event loop conflicts.

How do I mock authentication Guards in Litestar tests?▼

Prefer overriding the Guard's underlying service through app.dependencies rather than patching internals. For example, replace the users_service dependency with a fake implementation before creating the test client.

Why is my Litestar plugin not working in tests?▼

Plugin lifespans like Vite, SAQ, and SQLAlchemy session pools only run when AsyncTestClient is used as an async context manager. Writing AsyncTestClient(app=app) without async with leaves the app half-initialized.

How do I test Litestar endpoints against a real database?▼

Use pytest-databases fixtures such as postgres_service to start a container, then inject its connection details into your app settings fixture. Never mock SQLAlchemy internals, since mocked queries do not catch real bugs.