test: check migrations with pytest-alembic instead of a hand-written drift test

Author: lesnik512

.github/workflows/main.yml

@@ -30,6 +30,18 @@ jobs:
 
   pytest:
     runs-on: ubuntu-latest
+    name: pytest (${{ matrix.name }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: app
+            run: |
+              uv run alembic upgrade head
+              uv run pytest . --cov=. --cov-report xml
+          # pytest-alembic upgrades an empty database itself, so no `alembic upgrade` first.
+          - name: migrations
+            run: uv run pytest tests/migrations --override-ini=addopts=
     services:
       postgres:
         image: postgres:latest
@@ -52,8 +64,7 @@ jobs:
       - run: uv python pin 3.14
       - run: |
           uv sync --all-extras --all-groups --frozen --no-install-project
-          uv run alembic upgrade head
-          uv run pytest . --cov=. --cov-report xml
+          ${{ matrix.run }}
         env:
           SERVICE_ENVIRONMENT: ci
           PYTHONDONTWRITEBYTECODE: 1

AGENTS.md

@@ -13,6 +13,7 @@ The development workflow runs inside Docker via `just` (`just --list` / read the
 Things the recipe names don't make obvious:
 
 - `just test [args]` recreates a clean DB first (`alembic downgrade base` → `upgrade head`) and tears the stack down afterward; `[args]` are passed through to `pytest`.
+- `just test-migrations [args]` runs the `pytest-alembic` suite in `tests/migrations/` against an empty database: single head, upgrade, up/down consistency for every revision, and models matching the migrated schema (`alembic check` as a test). `just test` skips that directory (`--ignore` in `addopts`, `omit` in coverage) because it migrates the schema under the transaction-rollback fixture, so the recipe clears `addopts`.
 - `just run` applies migrations then starts the app on :8000.
 - `just lint` auto-fixes (eof-fixer + `ruff format` + `ruff check --fix` + `ty check`); CI (below) is the no-fix gate.
 
@@ -22,7 +23,7 @@ Running a single test (inside container or with DB available):
 uv run pytest tests/test_decks.py::test_get_decks -x
 ```
 
-CI (`.github/workflows/main.yml`) runs `ruff format --check`, `ruff check --no-fix`, `ty check`, then `alembic upgrade head` and `pytest` against a Postgres service. Match this locally before pushing.
+CI (`.github/workflows/main.yml`) runs `ruff format --check`, `ruff check --no-fix`, `ty check`, then two Postgres jobs: `alembic upgrade head` followed by `pytest`, and the `pytest-alembic` suite. Match this locally before pushing.
 
 ## Architecture
 

justfile

@@ -9,6 +9,9 @@ sh:
 test *args: down && down
     docker compose run application sh -c "sleep 1 && uv run alembic downgrade base && uv run alembic upgrade head && uv run pytest {{ args }}"
 
+test-migrations *args: down && down
+    docker compose run application sh -c "sleep 1 && uv run pytest tests/migrations --override-ini=addopts= {{ args }}"
+
 run:
     docker compose run --service-ports application sh -c "sleep 1 && uv run alembic upgrade head && uv run python -m app"
 

pyproject.toml

@@ -33,6 +33,7 @@ dev = [
     "pytest-cov",
     "pytest-asyncio",
     "asgi_lifespan",
+    "pytest-alembic",
 ]
 lint = [
     "ruff",
@@ -79,7 +80,7 @@ isort.no-lines-before = ["standard-library", "local-folder"]
 ]
 
 [tool.pytest.ini_options]
-addopts = "--cov=. --cov-report term-missing --cov-fail-under=100"
+addopts = "--cov=. --cov-report term-missing --cov-fail-under=100 --ignore=tests/migrations"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 
@@ -90,3 +91,4 @@ exclude_also = [
 
 [tool.coverage.run]
 concurrency = ["thread", "greenlet"]
+omit = ["tests/migrations/*"]

tests/migrations/__init__.py

@@ -0,0 +1,14 @@
+import typing
+
+import pytest
+from sqlalchemy import Engine, create_engine
+
+from app.settings import settings
+
+
+@pytest.fixture
+def alembic_engine() -> typing.Iterator[Engine]:
+    # Replaces pytest-alembic's default in-memory SQLite engine.
+    engine: typing.Final = create_engine(settings.db_dsn_parsed.set(drivername="postgresql+psycopg"))
+    yield engine
+    engine.dispose()

tests/migrations/conftest.py

@@ -0,0 +1,12 @@
+from pytest_alembic.tests import (
+    test_model_definitions_match_ddl,
+    test_single_head_revision,
+    test_up_down_consistency,
+    test_upgrade,
+)
+
+
+_ = test_single_head_revision
+_ = test_upgrade
+_ = test_model_definitions_match_ddl
+_ = test_up_down_consistency