api.ts · Source

api.tstests/integration/helpers/api.tsraw ← helpers16,578 B← Back to the app
1/**
2 * AI Software Factory — Integration app factory.
3 *
4 * Boots the real NestJS API against the Testcontainers infra:
5 *
6 *   1. Start (shared) Postgres + Redis containers (helpers/containers.ts).
7 *   2. Point the environment at them (DATABASE_URL, REDIS_URL, + random
8 *      secrets — no secrets ever come from a checked-in file).
9 *   3. Apply the Prisma schema (`prisma migrate deploy`) — the same
10 *      deployment path production uses, so drift is caught early.
11 *   4. Build the Nest application from the repo's AppModule (the production
12 *      app wiring, NOT a trimmed TestModule — guards, interceptors, the
13 *      BullMQ queue providers, and the WebSocket gateway all run).
14 *
15 * The returned handle gives specs:
16 *   - `baseUrl`: the app is listened on an ephemeral 127.0.0.1 port.
17 *   - `request`: fetch bound to baseUrl (JSON by default).
18 *   - `prisma`:  the live PrismaClient for side-effect assertions
19 *                (AuditLog rows, WebhookDelivery rows, …).
20 *   - `close()`: disconnect prisma + close the app (containers kept alive).
21 *
22 * Usage (top of each spec):
23 *   import { createTestApp, type TestAppHandle } from "../helpers/api";
24 *   let app: TestAppHandle;
25 *   beforeAll(async () => { app = await createTestApp(); }, 180_000);
26 *   afterAll(async () => { await app?.close(); });
27 */
28import { randomBytes } from "node:crypto";
29import { execFile } from "node:child_process";
30import { promisify } from "node:util";
31import * as path from "node:path";
32import { fileURLToPath } from "node:url";
33import { PrismaClient } from "@prisma/client";
34import { getDatabaseUrl, getRedisUrl, stopAllContainers } from "./containers";
35 
36const execFileAsync = promisify(execFile);
37const HERE = path.dirname(fileURLToPath(import.meta.url));
38 
39export interface TestAppHandle {
40  /** Base URL the API is listening on (http://127.0.0.1:<port>). */
41  baseUrl: string;
42  /** fetch-compatible request bound to baseUrl. `redirect` defaults to
43   *  "follow" (the fetch default); pass "manual" to observe 3xx redirects
44   *  instead of chasing them (e.g. the files download 302 → signed S3 URL). */
45  request: (
46    method: string,
47    urlPath: string,
48    opts?: { body?: unknown; headers?: Record<string, string>; redirect?: RequestRedirect },
49  ) => Promise<Response>;
50  /** Live PrismaClient (same DATABASE_URL as the app). */
51  prisma: PrismaClient;
52  /**
53   * Service token for the internal surface (`/internal/*`), always configured
54   * in the test app. Needed by the two-user seam (TASK-0095 S9): specs call
55   * `POST /internal/workspaces/:id/members` with `Authorization: Bearer
56   * <token>` to add a registered user without an invite mail (D3 unblock).
57   */
58  internalServiceToken: string;
59  /**
60   * Test-only debug events token (`X-Debug-Token` for `GET
61   * /api/v1/debug/events`) — set only in the test app (the route is 404
62   * unless NODE_ENV=test). Used by the E2E suite to assert stream events.
63   */
64  debugToken?: string;
65  /**
66   * The live public v1 route table (TASK-0127 contract test ground truth):
67   * introspects the booted Express router and returns `{ path, method }`
68   * for every route under the `api/v1` prefix (the internal service-token
69   * surface and the WebSocket upgrade are excluded). This is the SAME router
70   * the production app mounts, so the spec-vs-live comparison cannot drift
71   * from a re-scan of the sources.
72   */
73  liveRoutes: () => Array<{ path: string; method: string }>;
74  /**
75   * Access a service from the booted production AppModule (TASK-0133 audit
76   * completeness): drives an emitter that has no public HTTP surface for the
77   * catalog event (e.g. `SsoProvisioningService.provision()` for
78   * `sso.login.*`). Optional — most specs never need it.
79   */
80  get?: <T>(token: unknown) => T | null;
81  /** Close the app + release the Prisma client (does NOT stop containers). */
82  close: () => Promise<void>;
83}
84 
85/** Locate the repo root (tests/integration/helpers → three levels up). */
86function repoRoot(): string {
87  return path.resolve(HERE, "..", "..", "..");
88}
89 
90/**
91 * Run the production deployment path (`pnpm db:deploy` →
92 * `prisma migrate deploy`) from the repo root. Falls back to the local
93 * prisma CLI binary when pnpm is not on PATH.
94 *
95 * Exported so non-Nest integration specs (e.g. the worker search-index spec,
96 * TASK-0096) can apply the schema to their own Postgres container without
97 * booting the whole app.
98 */
99export async function deploySchema(databaseUrl: string): Promise<void> {
100  const root = repoRoot();
101  const env = { ...process.env, DATABASE_URL: databaseUrl };
102  try {
103    await execFileAsync("pnpm", ["db:deploy"], { cwd: root, env, timeout: 180_000 });
104  } catch (err) {
105    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
106      // pnpm missing — invoke the repo-local prisma CLI (default schema
107      // location is <root>/prisma/schema.prisma).
108      const cli = path.join(root, "node_modules", "prisma", "build", "index.js");
109      await execFileAsync(process.execPath, [cli, "migrate", "deploy"], {
110        cwd: root,
111        env,
112        timeout: 180_000,
113      });
114    } else {
115      throw new Error(`prisma migrate deploy failed: ${(err as Error).message}`);
116    }
117  }
118}
119 
120/**
121 * Import the production AppModule. Deferred (dynamic) import so the
122 * environment variables are set BEFORE Nest modules read them.
123 *
124 * Primary path: `@factory/api/src/app.module` — the API package exposes its
125 * app module for testing (index re-exports AppModule; see the api package's
126 * package.json exports). Fallback: the relative source path, which works
127 * regardless of the exports map.
128 */
129async function loadAppModule() {
130  try {
131    return await import("@factory/api/src/app.module");
132  } catch {
133    return await import(
134      /* webpackIgnore: true */ pathToFileURL(
135        path.join(repoRoot(), "apps", "api", "src", "app.module.ts"),
136      ).href
137    );
138  }
139}
140 
141function pathToFileURL(p: string): string {
142  return `file://${p.startsWith("/") ? p : `/${p}`}`;
143}
144 
145/**
146 * Create the full test app. Call once per test file; `close()` in afterAll.
147 * Containers are shared and long-lived — release them with
148 * stopAllContainers() (or createTestAppWithTeardown) for deterministic
149 * port release in long CI runs.
150 */
151export async function createTestApp(): Promise<TestAppHandle> {
152  // 1) Infra.
153  const [databaseUrl, redisUrl] = await Promise.all([
154    getDatabaseUrl(),
155    getRedisUrl(),
156  ]);
157 
158  // 2) Environment — canonical .env.example names, random secrets per run.
159  process.env.NODE_ENV = "test";
160  process.env.DATABASE_URL = databaseUrl;
161  process.env.REDIS_URL = redisUrl;
162  process.env.JWT_SECRET = randomBytes(48).toString("hex");
163  process.env.REFRESH_TOKEN_SECRET = randomBytes(48).toString("hex");
164  process.env.SESSION_SECRET = randomBytes(32).toString("hex");
165  process.env.MASTER_ENCRYPTION_KEY = randomBytes(32).toString("base64");
166  // Internal surface (TASK-0092) + the two-user test seam (TASK-0095 S9):
167  // the in-process app is the test surface, so the service-token-guarded
168  // `/internal/*` routes are opened — including `POST
169  // /internal/workspaces/:id/members` (the D3 seam, `INTERNAL_TEST_SEAM=1`).
170  // A random per-run token (never a checked-in secret).
171  const internalServiceToken = randomBytes(32).toString("hex");
172  process.env.INTERNAL_SERVICE_TOKEN = internalServiceToken;
173  process.env.INTERNAL_TEST_SEAM = "1";
174  // Phase 10 (TASK-0109): the test-only debug events endpoint
175  // (`GET /api/v1/debug/events`) — the E2E suite asserts domain events
176  // through it. A random per-run token (never a checked-in secret); the
177  // route also requires NODE_ENV=test (set above) — double-gated.
178  process.env.TEST_DEBUG_TOKEN = randomBytes(32).toString("hex");
179  process.env.JWT_EXPIRES_IN = process.env.JWT_EXPIRES_IN ?? "15m";
180  process.env.REFRESH_TOKEN_TTL_DAYS = process.env.REFRESH_TOKEN_TTL_DAYS ?? "30";
181  process.env.BCRYPT_ROUNDS = process.env.BCRYPT_ROUNDS ?? "12";
182  process.env.PORT = "4000";
183  // Rate limits: a single shared test app serves ALL specs' users over one
184  // loopback IP, and unauthenticated calls (register) key by IP — the
185  // production defaults (auth 10/min) self-throttle the suite. Raise to
186  // effectively-off; throttling behavior is unit-tested separately
187  // (common/__tests__), not exercised here.
188  process.env.RATE_LIMIT_AUTH = process.env.RATE_LIMIT_AUTH ?? "100000";
189  process.env.RATE_LIMIT_API = process.env.RATE_LIMIT_API ?? "100000";
190  // S3/Search are optional per spec; specs that need them set S3_* /
191  // SEARCH_* before calling this (the values are read here as-is).
192  if (process.env.S3_ENDPOINT) process.env.S3_FORCE_PATH_STYLE = "true";
193 
194  // 3) Schema (production deployment path).
195  await deploySchema(databaseUrl);
196 
197  // 4) App — production AppModule on an ephemeral local port.
198  const { NestFactory } = await import("@nestjs/core");
199  const { RequestMethod } = await import("@nestjs/common");
200  const AppModule = (await loadAppModule()).AppModule;
201  const { WEBHOOK_BODY_MAX_BYTES } = await import("@factory/shared");
202  const app = await NestFactory.create(AppModule, {
203    logger: ["error", "warn"], // keep test output readable
204    // Phase 11 (TASK-0110): match main.ts — capture the EXACT request bytes
205    // as `req.rawBody` for the incoming-webhook HMAC signature verification
206    // (the JSON-parsed `req.body` is re-serialized and would NOT match),
207    // and mount the JSON parser with the 256 KB webhook limit (body-parser's
208    // 100 KB default would wrongly 413 a valid large webhook body).
209    rawBody: true,
210    bodyParser: false,
211  });
212  const appWithParser = app as unknown as {
213    useBodyParser: (t: string, o: Record<string, unknown>) => unknown;
214  };
215  // T-165: mirrors main.ts — the route-scoped 2 MB parser for
216  // POST /api/v1/databases/:id/import/csv MUST mount before the global
217  // parsers (express runs middleware in registration order; Nest's parsers
218  // attach at init()).
219  const { csvImportBodyParser } = await import(
220    /* webpackIgnore: true */ pathToFileURL(
221      path.join(repoRoot(), "apps", "api", "src", "common", "csv-import-body.ts"),
222    )
223  );
224  (app.getHttpAdapter().getInstance() as unknown as { use: (m: unknown) => void }).use(
225    csvImportBodyParser,
226  );
227  // T-167: whiteboard canvas saves (mirrors main.ts — registered before the
228  // global JSON parser).
229  const { whiteboardBodyParser } = await import(
230    /* webpackIgnore: true */ pathToFileURL(
231      path.join(repoRoot(), "apps", "api", "src", "common", "whiteboard-body.ts"),
232    )
233  );
234  (app.getHttpAdapter().getInstance() as unknown as { use: (m: unknown) => void }).use(
235    whiteboardBodyParser,
236  );
237  appWithParser.useBodyParser("json", { limit: WEBHOOK_BODY_MAX_BYTES });
238  // TASK-0132: SCIM IdPs send `application/scim+json` (mirrors main.ts —
239  // body-parser's default json type only matches `application/json`).
240  appWithParser.useBodyParser("json", { type: "application/scim+json", limit: WEBHOOK_BODY_MAX_BYTES });
241  appWithParser.useBodyParser("urlencoded", { extended: true });
242  // TASK-0127: same raw-Express middleware as main.ts — deprecation headers
243  // (`Deprecation`/`Sunset`) on the DEPRECATED_ROUTES map.
244  const { deprecationMiddleware } = await import(
245    /* webpackIgnore: true */ pathToFileURL(
246      path.join(repoRoot(), "apps", "api", "src", "common", "deprecation.ts"),
247    )
248  );
249  (app.getHttpAdapter().getInstance() as unknown as { use: (m: unknown) => void }).use(
250    deprecationMiddleware,
251  );
252  // Same global prefix + non-v1 exclusions as main.ts bootstrap:
253  // public routes live under `api/v1`, the service-token surface under
254  // bare `internal/*`, and (TASK-0131) the SSO PROTOCOL surface under
255  // bare `saml/*` + `sso/*` (browser bindings — 302/form-POST, no JWT).
256  // (TASK-0101: added — the helper previously booted
257  // the module without the prefix, so every spec request 404'd.)
258  app.setGlobalPrefix("api/v1", {
259    exclude: [
260      { path: "internal/:path*", method: RequestMethod.ALL },
261      { path: "saml/:path*", method: RequestMethod.ALL },
262      { path: "sso/:path*", method: RequestMethod.ALL },
263      // TASK-0132: the SCIM 2.0 protocol surface (IdP binding, bearer-token
264      // auth) — mirrors main.ts's exclude list.
265      { path: "scim/:path*", method: RequestMethod.ALL },
266    ],
267  });
268  // Canonical error envelope, exactly as main.ts installs it (the test app
269  // otherwise returns Nest's default {statusCode,message} shape, not the
270  // {error:{code,message,...}} the API contract — and specs like files
271  // assert on `error.code`).
272  const { AllExceptionsFilter } = await import(
273    /* webpackIgnore: true */ pathToFileURL(
274      path.join(repoRoot(), "apps", "api", "src", "common", "filters", "all-exceptions.filter.ts"),
275    )
276  );
277  app.useGlobalFilters(new AllExceptionsFilter());
278  await app.init();
279  await app.listen(0, "127.0.0.1");
280  const addr = app.getHttpServer().address();
281  const baseUrl =
282    typeof addr === "object" && addr !== null
283      ? `http://127.0.0.1:${addr.port}`
284      : `http://127.0.0.1:${String(addr)}`;
285 
286  // TASK-0127: the live public v1 route table — introspect the real Express
287  // router (the `app.getHttpAdapter().getInstance()` IS the express app;
288  // Nest's platform-express mounts every controller as a router layer). The
289  // global prefix means a controller route `/workspaces` lives at express
290  // path `/api/v1/workspaces`. We strip that prefix to get the spec path.
291  const liveRoutes: TestAppHandle["liveRoutes"] = () => {
292    const expressApp = app.getHttpAdapter().getInstance() as unknown as {
293      _router: { stack: Array<Record<string, unknown>> };
294    };
295    const out: Array<{ path: string; method: string }> = [];
296    const seen = new Set<string>();
297    const PREFIX = "/api/v1";
298    const walk = (layer: Record<string, unknown>, base: string): void => {
299      const route = layer.route as
300        | { path: string; methods: Record<string, boolean> }
301        | undefined;
302      if (route) {
303        for (const m of Object.keys(route.methods)) {
304          if (!route.methods[m]) continue;
305          let full = (base + route.path).replace(/\/{2,}/g, "/");
306          full = full.length > 1 ? full.replace(/\/+$/, "") : full;
307          if (!full.startsWith(PREFIX)) continue; // internal/* + bare /health
308          const spec = full.slice(PREFIX.length) || "/";
309          // Nest normalizes trailing slashes; keep the canonical form.
310          const deduped = spec.length > 1 ? spec.replace(/\/+$/, "") : spec;
311          const key = `${m.toUpperCase()} ${deduped}`;
312          if (seen.has(key)) continue;
313          seen.add(key);
314          out.push({ path: deduped, method: m.toUpperCase() });
315        }
316        return;
317      }
318      const handle = layer.handle as { stack?: Array<Record<string, unknown>> } | undefined;
319      if (handle && Array.isArray(handle.stack)) {
320        const prefix = (layer.regexp as { prefix?: string } | undefined)?.prefix ?? "";
321        for (const l2 of handle.stack) walk(l2, (base + prefix).replace(/\/{2,}/g, "/"));
322      }
323    };
324    for (const l of expressApp._router.stack) walk(l, "");
325    return out.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
326  };
327 
328  const prisma = new PrismaClient({ datasources: { db: { url: databaseUrl } } });
329  await prisma.$connect();
330 
331  const request: TestAppHandle["request"] = (method, urlPath, opts) =>
332    fetch(`${baseUrl}${urlPath}`, {
333      method,
334      headers: { "Content-Type": "application/json", ...opts?.headers },
335      body: opts?.body !== undefined ? JSON.stringify(opts.body) : undefined,
336      redirect: opts?.redirect ?? "follow",
337    });
338 
339  return {
340    baseUrl,
341    request,
342    prisma,
343    internalServiceToken,
344    debugToken: process.env.TEST_DEBUG_TOKEN,
345    liveRoutes,
346    get: (token: unknown): unknown => {
347      try {
348        return app.get(token);
349      } catch {
350        return null; // service not provided (spec does not depend on it)
351      }
352    },
353    close: async () => {
354      await prisma.$disconnect().catch(() => {});
355      await app.close().catch(() => {});
356    },
357  };
358}
359 
360/**
361 * Convenience: full handle + guaranteed container shutdown (for runners
362 * that do not call stopAllContainers themselves).
363 */
364export async function createTestAppWithTeardown(): Promise<
365  TestAppHandle & { stop: () => Promise<void> }
366> {
367  const handle = await createTestApp();
368  const close = handle.close;
369  return {
370    ...handle,
371    stop: async () => {
372      await close();
373      await stopAllContainers();
374    },
375  };
376}
377