test: add PostgreSQL migration integration coverage

2026-07-21 09:37:15 -05:00
parent b38f85f438
commit 831a48187c
16 changed files with 1690 additions and 96 deletions
@@ -0,0 +1,60 @@
+# Testing
+
+Ekklesia separates fast code-level evidence from live infrastructure evidence.
+
+## Unit and repository verification
+
+```bash
+pnpm test
+pnpm verify
+```
+
+These commands exercise package tests, repository boundaries, type checking, offline module and
+migration discovery, formatting, linting, and builds. Migration-runner unit tests use a narrow
+database/session port to prove deterministic planning, approval, transaction orchestration,
+cleanup, and sanitized errors. They do not claim to prove PostgreSQL behavior.
+
+`pnpm verify` is intentionally Docker-free. It never plans or applies migrations against a live
+database.
+
+## Live PostgreSQL migration evidence
+
+Docker and the Docker Compose plugin are required for the live suite:
+
+```bash
+pnpm test:migrations:integration
+```
+
+The command starts the repository's pinned PostgreSQL image in a unique Compose project, waits for
+bounded health readiness, runs the production PostgreSQL adapter and migration services, and then
+removes the container, network, and volume. Each scenario also receives a safely named disposable
+database. Direct host runs use a Docker-assigned random port bound only to `127.0.0.1`; a
+containerized Gitea job joins the isolated Compose network and uses the PostgreSQL service name.
+
+The live suite proves fresh read-only planning, initial and incremental application, genuine
+no-op behavior, exact applied checksums and history, edited or corrupt history rejection,
+whole-batch DDL rollback, Drizzle breakpoint execution, real advisory-lock concurrency and
+timeouts, lock release after failure, exact destructive approvals, and public-error sanitization.
+It does not make migrations automatic during Core startup.
+
+CI runs the same command in the dedicated `migration-smoke` job. After this change is merged, add
+the following pull-request status context to `main` branch protection:
+
+```text
+CI / migration-smoke (pull_request)
+```
+
+## Safe troubleshooting
+
+Confirm the prerequisites without printing configuration:
+
+```bash
+docker info
+docker compose version
+```
+
+Then rerun `pnpm test:migrations:integration`. The harness emits fixed failure messages and does
+not dump PostgreSQL logs, SQL, container inspection output, or the generated database URL. Do not
+enable query logging, print the test environment, run `docker compose config` without redaction,
+or paste Docker inspection output into an issue. If the Docker daemon itself stopped during
+cleanup, restore it before rerunning so the harness can create a fresh uniquely named project.