Ekklesia/docs/development/testing.md

Testing

Ekklesia separates fast code-level evidence from live infrastructure evidence.

Unit and repository verification

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:

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:

CI / migration-smoke (pull_request)

Safe troubleshooting

Confirm the prerequisites without printing configuration:

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.