Skip to content

# Pytest

Testing helpers for FastAPI applications with async client, database sessions, and parallel worker support.

## Installation

uvpip

    uv add "fastapi-toolsets[pytest]"

    pip install "fastapi-toolsets[pytest]"

## Overview

The `pytest` module provides utilities for setting up async test clients, managing test database sessions, and supporting parallel test execution with `pytest-xdist`.

## Creating an async client

Use `create_async_client` to get an `httpx.AsyncClient` configured for your FastAPI app:

    from fastapi_toolsets.pytest import create_async_client

    @pytest.fixture
    async def http_client(db_session):
        async def _override_get_db():
            yield db_session

        async with create_async_client(
            app=app,
            base_url="http://127.0.0.1/api/v1",
            dependency_overrides={get_db: _override_get_db},
        ) as c:
            yield c

## Database sessions in tests

Use `create_db_session` to create an isolated `AsyncSession` for a test, combined with `create_worker_database` to set up a per-worker database:

    from fastapi_toolsets.pytest import create_worker_database, create_db_session

    @pytest.fixture(scope="session")
    async def worker_db_url():
        async with create_worker_database(
            database_url=str(settings.SQLALCHEMY_DATABASE_URI)
        ) as url:
            yield url

    @pytest.fixture
    async def db_session(worker_db_url):
        async with create_db_session(
            database_url=worker_db_url, base=Base, cleanup=True
        ) as session:
            yield session

Info

In this example, the database is reset between each test using the argument `cleanup=True`.

Use `worker_database_url` to derive the per-worker URL manually if needed:

    from fastapi_toolsets.pytest import worker_database_url

    url = worker_database_url("postgresql+asyncpg://user:pass@localhost/test_db", default_test_db="test")
    # e.g. "postgresql+asyncpg://user:pass@localhost/test_db_gw0" under xdist

## Parallel testing with pytest-xdist

The examples above are already compatible with parallel test execution with `pytest-xdist`.

## Cleaning up tables

If you want to manually clean up a database you can use `cleanup_tables`, this will truncate all tables between tests for fast isolation:

    from fastapi_toolsets.db import cleanup_tables

    @pytest.fixture(autouse=True)
    async def clean(db_session):
        yield
        await cleanup_tables(session=db_session, base=Base)

API Reference