Testing

Clawbolt uses pytest with FastAPI’s TestClient. Tests require a running PostgreSQL instance with a clawbolt_test database.

Run all tests

uv sync --all-extras
uv run pytest -v

Lint and format

uv run ruff check backend/ tests/
uv run ruff format --check backend/ tests/

Type checking

uv run ty check --python .venv backend/ tests/

Database setup

Tests connect to postgresql://clawbolt:clawbolt@localhost:5432/clawbolt_test. The conftest handles table creation and per-test transaction rollback automatically.

# Create the test database (one-time setup)
createdb -U clawbolt clawbolt_test

Test infrastructure

Store isolation

The _isolate_file_stores autouse fixture patches settings.data_dir and calls reset_stores() to clear cached store singletons between tests. Each test runs in a database transaction that is rolled back after the test completes.

Mock factories

All external services are mocked in tests. Mock factories live in tests/mocks/:

Mock	What it replaces
Telegram	Telegram Bot API calls
LLM	any-llm acompletion calls
Dropbox/Drive	Cloud storage operations
Storage	MockStorageBackend for file operations

Auth override

The get_current_user dependency is overridden in tests to return a fixed test user, bypassing authentication.

Definition of done

Every change should pass all checks:

uv run pytest -v                                  # tests pass
uv run ruff check backend/ tests/                 # lint passes
uv run ruff format --check backend/ tests/        # format passes
uv run ty check --python .venv backend/ tests/    # type checking passes

Bug fixes must include regression tests.