Integration Tests

API-level integration tests for AI Software Factory. Every test spins up the real stack — NestJS API + PostgreSQL + Redis (+ OpenSearch / MinIO per test) — via Testcontainers, then drives the NestJS application through its HTTP surface (supertest-style Request from Nest's testing module).

What "integration" means here

• Real infrastructure, not mocks: the NestJS app under test uses a Testcontainers-managed Postgres (Prisma schema applied via prisma migrate deploy), a real Redis (BullMQ + rate-limit state), and — where a spec needs it — a real MinIO (S3) and OpenSearch.
• Full HTTP contract: specs hit app.get(...) / app.post(...) etc. on the compiled Nest application, so routing, guards (authN + authZ), interceptors, validation pipes, and the domain layer all run.
• No browser (that's tests/e2e) and no unit-level isolation (that's packages/*/src/**/*.unit.test.ts).

Running

# From the repo root (after pnpm install):
pnpm --dir tests/integration test            # all specs, one shared DB
pnpm --dir tests/integration test -- auth    # filter by filename substring
pnpm --dir tests/integration test:watch      # watch mode (local dev)

Docker must be available (Testcontainers). In CI the e2e job's service containers are NOT used — integration tests manage their own containers.

Test environment convention

helpers/containers.ts is a shared module-level singleton: all specs in one vitest run share the same Postgres + Redis containers (started once in beforeAll via Vitest's setup in each file, deduped by the module cache). Isolation between specs is at the data level, not the container level:

• Each test file creates its own workspace(s) and users via the API.
• The shared app instance is created once per test file by helpers/api.ts (createTestApp()), with the Prisma client pointed at the Testcontainers DB URL.

Per-spec env overrides (e.g. a different S3 bucket) are read from process.env in the same .env.example variable names:

Modules covered (per AGENTS.md §Testing)

Adding a new integration spec

1. Drop <name>.integration.test.ts in this directory.
2. Get the app via createTestApp() from ./helpers/api (it handles container startup, schema deploy, and teardown).
3. Create your fixtures through the API (register users, create workspaces) — never write raw SQL, so the spec exercises the real authorization layer.
4. Assert on HTTP status + response body, plus DB state through the exported Prisma client when you need to verify a side effect (e.g. an AuditLog row, a WebhookDelivery row).
5. Clean up in afterAll where practical (delete workspaces you created). The container is destroyed at process exit regardless.

Notes

• Files spec mocks the storage layer (MinIO) at the repository boundary: the API contract (session → presigned → complete → status machine) is what is under test, not the object store. A real-MinIO variant lives in tests/e2e (the e2e stack runs MinIO).
• OpenSearch is not started by default (slow to boot); the search paths are covered in e2e against the dev stack. If a future spec needs it, start a container and export SEARCH_URL before createTestApp().
• The Prisma client is generated at build time (pnpm db:generate); specs import @prisma/client and reconfigure its datasource at runtime via the DATABASE_URL env var (Testcontainers' JDBC-style URL maps 1:1 to a postgres:// DSN).