test: standalone test container, isolated from the live prod stack

Adds a `test` stage to the Dockerfile (prod deps + pytest + aiosqlite via
the `dev` extras, never shipped) and a docker-compose.test.yml that runs
it under its own Compose project name (`cassandra-test`). The project-name
isolation matters because this host runs prod — a wrong `compose up` would
otherwise recreate the live `app` container; namespaced project means the
test container can't touch any prod container/network/volume.

Tests use an in-memory aiosqlite DB (per tests/conftest.py) so the
container has no MariaDB / Redis dependency and nothing on the prod DB
is observed or mutated.

Also adds aiosqlite to dev extras — tests have always implicitly needed
it (the conftest pins DATABASE_URL to sqlite+aiosqlite:///:memory:); the
declaration was just missing.

Usage:
  docker compose -f docker-compose.test.yml run --rm test
  docker compose -f docker-compose.test.yml run --rm test pytest -k unsubscribe

Dockerfile

@@ -32,3 +32,29 @@ COPY alembic.ini ./
 # Default command is the web app; scheduler container overrides via `command:`.
 EXPOSE 8000
 CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]
+
+
+# ---------------------------------------------------------------------------
+# Test stage — same Python, same prod deps, plus dev extras (pytest +
+# aiosqlite). Built and run only via docker-compose.test.yml; never shipped.
+# ---------------------------------------------------------------------------
+FROM python:3.13-slim AS test
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PATH="/opt/venv/bin:$PATH" \
+    TZ=UTC \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1
+
+COPY --from=builder /opt/venv /opt/venv
+WORKDIR /app
+COPY pyproject.toml ./
+COPY app ./app
+COPY alembic ./alembic
+COPY alembic.ini ./
+COPY tests ./tests
+
+RUN /opt/venv/bin/pip install ".[dev]"
+
+CMD ["pytest", "tests/", "-v"]

docker-compose.test.yml

@@ -0,0 +1,46 @@
+# Ad-hoc test runner.
+#
+# STANDALONE — do not combine with docker-compose.yml. The `name:` field
+# below puts the test container in its own Compose project (`cassandra-test`)
+# so it CANNOT collide with the live prod stack on this host (containers,
+# networks, volumes are all namespaced by project).
+#
+# Usage:
+#   # Run the full suite:
+#   docker compose -f docker-compose.test.yml run --rm test
+#
+#   # Run a specific file or test:
+#   docker compose -f docker-compose.test.yml run --rm test pytest tests/test_email_digest_job.py -v
+#   docker compose -f docker-compose.test.yml run --rm test pytest -k unsubscribe
+#
+#   # Open a shell in the test image (e.g. to poke around with pytest --pdb):
+#   docker compose -f docker-compose.test.yml run --rm test bash
+#
+#   # Rebuild after a pyproject.toml change:
+#   docker compose -f docker-compose.test.yml build test
+#
+# Tests use an in-memory aiosqlite DB (see tests/conftest.py), so there is
+# no MariaDB / Redis dependency and nothing touches the prod database.
+
+name: cassandra-test
+
+services:
+  test:
+    build:
+      context: .
+      target: test
+    # Same volume mounts as the dev override — edits on the host take effect
+    # on the next `run` without rebuilding the image.
+    volumes:
+      - ./app:/app/app
+      - ./tests:/app/tests
+      - ./alembic:/app/alembic
+      - ./alembic.ini:/app/alembic.ini:ro
+      - ./config:/app/config:ro
+      - ./pyproject.toml:/app/pyproject.toml:ro
+    environment:
+      # Sentinels so app.config can be imported without a real .env / DB.
+      # tests/conftest.py also sets these defensively.
+      DATABASE_URL: "sqlite+aiosqlite:///:memory:"
+      CASSANDRA_MOCK: "1"
+      PYTHONDONTWRITEBYTECODE: "1"

pyproject.toml

@@ -30,6 +30,7 @@ dev = [
     "pytest>=8.3",
     "pytest-asyncio>=0.24",
     "pytest-httpx>=0.34",
+    "aiosqlite>=0.20",
     "ruff>=0.7",
 ]