test: integration tier against real Postgres + Redis (Testcontainers): infra + auth/payments/isolation suites (#135)

.github/workflows/ci.yml

@@ -59,3 +59,11 @@ jobs:
         run: npx tsx scripts/audit-constraints.ts --json audit.json
       - run: npm run build
       - run: npm test
+      # Integration tier (#135): real Postgres 16 + Redis 7 from the service
+      # containers above. TEST_DATABASE_URL is the admin DB, used to clone a
+      # migrated template database per test file.
+      - name: Integration tests
+        run: npm run test:integration
+        env:
+          TEST_DATABASE_URL: postgresql://oracledesk:oracledesk@localhost:5432/postgres
+          TEST_REDIS_URL: redis://localhost:6379

CONTRIBUTING.md

@@ -121,3 +121,27 @@ in code, tests, fixtures or logs. Tests generate throwaway keys with
 `Keypair.random()`. New config goes in `.env.example` with an empty value. If you commit a secret by accident, tell a
 maintainer privately (see [SECURITY.md](SECURITY.md)) so it can be rotated;
 removing it in a later commit is not enough.
+
+## Tests
+
+There are two tiers:
+
+| Command | What runs | Needs |
+|---|---|---|
+| `npm test` | Unit tests (`tests/*.test.ts`), Prisma and Redis mocked | nothing |
+| `npm run test:integration` | `tests/integration/*.int.test.ts` against real Postgres 16 + Redis 7 | Docker, or `TEST_DATABASE_URL` + `TEST_REDIS_URL` |
+| `npm run test:all` | both | as above |
+
+Integration tests get services from Testcontainers locally, or from
+`TEST_DATABASE_URL` (an admin connection, used for `CREATE DATABASE`) and
+`TEST_REDIS_URL` when set, as in CI. A migrated template database is created
+once; each test file gets its own clone, and tests truncate all tables in
+`beforeEach`. Without Docker or the `TEST_*` URLs, the tier skips with a message.
+
+Writing an integration test:
+
+- Call `await integrationEnv('<label>')` in an async `before()` hook, **then**
+  dynamically import `src` modules (`config` and `prisma` read env at import).
+- Seed data with the factories in `tests/helpers/factories.ts`.
+- Use `withRedisPrefix()` from `tests/helpers/redis.ts` so parallel files don't
+  share Redis keys.

README.md

@@ -90,6 +90,8 @@ The full contract with the frontend, including request and response shapes, erro
 | `npm run dev` | Dev server with reload |
 | `npm run build` / `npm start` | Compile to `dist/` / build and run |
 | `npm test` | Compile and run `tests/*.test.ts` with `node:test` |
+| `npm run test:integration` | Integration tests against real Postgres + Redis (Docker or `TEST_DATABASE_URL`/`TEST_REDIS_URL`; see CONTRIBUTING.md) |
+| `npm run test:all` | Unit then integration tests |
 | `npm run sync:contracts` | Copy generated contract code from `contracts/` into `src/generated/` |
 | `npm run check:contracts` | Fail if `src/generated/` is stale (CI runs this) |
 | `npm run prisma:migrate` | `prisma migrate dev` |