Skip to content

bluefox-test

Test infrastructure for FastAPI + async SQLAlchemy 2.x applications. Real databases via testcontainers, async factories, production safety gates, and zero-config developer experience.

uv add bluefox-test --group test

Three lines to test infrastructure

conftest.py
from bluefox_test import bluefox_test_setup
from app.models import Base

globals().update(bluefox_test_setup(base=Base))

You get: ephemeral Postgres + Redis containers, SAVEPOINT-wrapped sessions, safety gates, auto-discovered create_* factory fixtures, a wired FastAPI app, and an httpx client.

What a test looks like

src/users/tests/test_routes.py
async def test_get_user__returns_200(client, create_user):
    user = await create_user(name="Hugo")
    response = await client.get(f"/users/{user.id}")
    assert response.status_code == 200
    assert response.json()["name"] == "Hugo"

No setup, no teardown, no mocks. Real Postgres, real SQL, real HTTP.

What you get for free

  • Container lifecycle — Postgres and Redis start before tests, stop after. Random ports avoid conflicts.
  • Session isolation — every test gets a SAVEPOINT. Rolled back after. No data leaks.
  • Async factories — await create_user(name="Hugo") returns an object with a real .id.
  • Factory discovery — every tests/factories.py under src/ is imported automatically.
  • Safety gates — impossible to accidentally test against production.
  • Factory linting — warns when models lack factories or tests instantiate models directly.
  • Markers — e2e, slow, allow_network registered automatically.
  • E2E auth — authenticate once, cache JWT, inject into every client.

Next steps