chore: documentation (#76)

* chore: update docstring example to use python code block

* docs: add documentation

* feat: add docs build + fix other workdlows

* fix: add missing return type

docs/module/pytest.md

@@ -0,0 +1,81 @@
+# Pytest
+
+Testing helpers for FastAPI applications with async client, database sessions, and parallel worker support.
+
+## Installation
+
+=== "uv"
+    ``` bash
+    uv add "fastapi-toolsets[pytest]"
+    ```
+
+=== "pip"
+    ``` bash
+    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`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_async_client) to get an `httpx.AsyncClient` configured for your FastAPI app:
+
+```python
+from fastapi_toolsets.pytest import create_async_client
+
+@pytest.fixture
+async def client(app):
+    async with create_async_client(app=app) as c:
+        yield c
+```
+
+## Database sessions in tests
+
+Use [`create_db_session`](../reference/pytest.md#fastapi_toolsets.pytest.utils.create_db_session) to create an isolated `AsyncSession` for a test:
+
+```python
+from fastapi_toolsets.pytest import create_db_session
+
+@pytest.fixture
+async def db_session():
+    async with create_db_session(database_url=DATABASE_URL, base=Base, cleanup=True) as session:
+        yield session
+```
+
+## Parallel testing with pytest-xdist
+
+When running tests in parallel, each worker needs its own database. Use these helpers to create and identify worker databases:
+
+```python
+from fastapi_toolsets.pytest import create_worker_database, create_db_session
+
+# In conftest.py session-scoped fixture
+@pytest.fixture(scope="session")
+async def worker_db_url():
+    async with create_worker_database(database_url=DATABASE_URL) 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
+```
+
+## Cleaning up tables
+
+[`cleanup_tables`](../reference/pytest.md#fastapi_toolsets.pytest.utils.cleanup_tables) truncates all tables between tests for fast isolation:
+
+```python
+from fastapi_toolsets.pytest import cleanup_tables
+
+@pytest.fixture(autouse=True)
+async def clean(db_session):
+    yield
+    await cleanup_tables(session=db_session, base=Base)
+```
+
+---
+
+[:material-api: API Reference](../reference/pytest.md)