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.