Running tests locally

Prerequisites

Node 20+ and pnpm (corepack enable && corepack prepare pnpm@9 --activate).
Docker Desktop (Mac/Windows) or the Docker daemon (Linux) — testcontainers needs it.

Fast, no Docker:


pnpm test          # one run
pnpm test:watch    # watch mode

Vitest picks up only files under tests/unit/**/*.test.ts.

Spins up a real Postgres 16 container per worker via testcontainers, runs every drizzle/*.sql migration once, then your tests:


pnpm test:integration

First run pulls postgres:16-alpine (~80 MB); subsequent runs reuse the cached image.

If integration tests hang on container startup, your Docker daemon is unreachable. Verify:


docker info

On Linux you may need to add yourself to the docker group (sudo usermod -aG docker $USER, log out and back in).


pnpm test:ci

Coverage report lands at coverage/index.html. Thresholds enforced per test-strategy.md.

Vitest supports a name filter:


pnpm test -- --reporter=verbose --testNamePattern='loadEnv'
pnpm test:integration -- migrate.test.ts

Containers leak on Ctrl+C panic. docker ps -a --filter "label=org.testcontainers" -q | xargs -r docker rm -f to clean up.
Slow first run on macOS. Docker Desktop’s filesystem virtualisation is slow on the first volume mount. Patience.
CI parity. GitHub Actions runs Postgres via testcontainers, identical to local. No services: block is needed.