test: add full-stack integration test suite (real Nest + mocked AWS SDK) (#124)

Closes #75

## Summary

- Adds a **tier-2 integration test suite** (`npm run
app:test:integration`) where a real Nest server runs on `:3002`, AWS SDK
calls are intercepted by `aws-sdk-client-mock`, and the Vite preview on
`:4174` proxies `/api` to it — no real AWS required
- New `ServerMocks` Playwright fixture class + extended `test` object
that resets `MockStore` before/after each spec; mock responses pushed to
the server via `POST /api/test/mocks/*`
- 6 spec files covering API token guard (401/200 auth), ConfigService
tfstate parsing, start/stop browser flows, status-badge polling
transitions, and ECS error propagation; `canRun()` spec stubbed pending
Discord integration
- Integration Vite config injects `VITE_STATUS_POLL_MS=3000` so
poll-based assertions complete in < 10 s; Nest server startup timeout
raised to 120 s for WSL2/DrvFs ESM loading latency
- `CLAUDE.md` two-tier strategy table updated to three-tier; integration
conventions section added; reference docs table updated
- `docs/docs/components/integration-tests.md` added: architecture
diagram, key-file table, mock response reference, spec inventory, design
constraints

## Test plan

- [ ] `npm run app:test:integration` — 11 pass, 1 skip (`canRun.spec.ts`
placeholder)
- [ ] `npm run app:test` (unit) — all pass, unaffected
- [ ] `npm run app:test:e2e` (tier-1) — all pass, unaffected

🤖 Generated with [Claude Code](https://claude.ai/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: CoderCoco

.github/workflows/integration.yml

@@ -0,0 +1,36 @@
+name: Integration Tests
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install chromium --with-deps
+        working-directory: app/packages/web
+
+      - run: npm run app:test:integration
+
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: integration-playwright-report
+          path: app/packages/web/playwright-report/
+          retention-days: 30

.gitignore

@@ -38,5 +38,6 @@ app/packages/server/src/generated/tfstate.ts
 app/packages/web/test-results/
 app/packages/web/playwright-report/
 app/packages/web/playwright/.cache/
+app/packages/web/dist-integration/
 
 .make

CLAUDE.md

@@ -140,6 +140,7 @@ When working in a specific area, read the relevant doc rather than relying on wh
 | AWS IAM deploy policy | `docs/docs/setup.md` |
 | Terraform variables reference | `docs/docs/components/terraform.md` |
 | Full setup walkthrough | `docs/docs/setup.md` |
+| Integration test architecture | `docs/docs/components/integration-tests.md` |
 | Copilot review tuning | `.github/copilot-instructions.md` |
 | PR creation command | `.claude/commands/pr.md` |
 
@@ -161,14 +162,13 @@ Any time you add or remove Terraform variables, update **all four** of these in
 
 ### Two-tier browser testing strategy
 
-The test suite has two complementary tiers:
+The test suite has three complementary tiers:
 
 | Tier | Command | What runs | When to add specs |
 |------|---------|-----------|-------------------|
 | **Unit / integration** | `npm run app:test` | Vitest. Server-side logic, hooks, helpers run under the `node` environment; React component specs in `@gsd/web` run under `jsdom` via `environmentMatchGlobs`. No real network — AWS SDK mocked via `aws-sdk-client-mock`; the `@gsd/web` API client is stubbed via `vi.mock`. | Pure logic, hook behaviour, server controllers, **per-component React behaviour** (rendering, callbacks, internal state transitions). |
 | **E2E (tier 1 — #74)** | `npm run app:test:e2e` | Playwright against `vite build` + `vite preview`. Nest server never runs; every `/api/*` call is stubbed at the network layer via `page.route()`. | User-visible flows: routing, auth gate, button interactions, status-badge rendering, optimistic updates. |
-
-A planned **tier 2** (#75) will add full-stack specs (real Nest + mocked AWS SDK) for scenarios that require real HTTP contract validation between the client and server. Until that lands, all browser-facing specs belong in tier 1.
+| **Integration (tier 2 — #75)** | `npm run app:test:integration` | Playwright against `vite build (integration config)` + `vite preview` + real Nest server on `:3002`. AWS SDK intercepted by `aws-sdk-client-mock`. Mock state pushed via `ServerMocks` fixture to `/api/test/mocks/*`. | Real HTTP contract validation, `ApiTokenGuard` behaviour, `ConfigService` tfstate parsing, start/stop flows end-to-end, error propagation from ECS through the API response. |
 
 **React component unit tests (`@gsd/web`):**
 - Use **Vitest + jsdom + `@testing-library/react` + `@testing-library/user-event`**. `@testing-library/jest-dom` matchers (`toBeInTheDocument`, `toHaveTextContent`, etc.) are auto-loaded via `app/vitest.setup.ts`.
@@ -180,7 +180,7 @@ A planned **tier 2** (#75) will add full-stack specs (real Nest + mocked AWS SDK
 - Each routed page (`DashboardPage`, `CostsPage`, `DiscordPage`, `LogsPage`, `SettingsPage`) gets a co-located `*.test.tsx` that mounts the page through `renderPage()` (`app/packages/web/src/test-utils/renderPage.tsx`). The helper wraps children in `PollingProvider → GameStatusProvider → MemoryRouter` so the same provider stack the production app uses is exercised; pass `initialEntries` when the page reads `useLocation`.
 - Mock `../api.js` with `vi.mock` + `vi.hoisted` so the page drives off canned data instead of real fetches. Stub every method the page (and the GameStatusProvider above it) calls — at minimum `api.status` and `api.costsEstimate` — or the test will hang waiting for the polling registry to settle.
 - These tests are intentionally **complementary** to the e2e tier, not a replacement: the e2e specs prove the indicator + chrome render at the route level under a real Vite preview build; the unit tests pin the page's own provider wiring (e.g. that `<PollingIndicator />` resolves to "Updated …" once the mocked status poll resolves) and let us iterate on the page layout without spinning up Playwright.
-- Keep page-test scope tight: smoke-render each header section, exercise interactive controls that aren't already covered by a child component's unit test, and verify the polling indicator wiring. Anything that requires real HTTP belongs in the planned tier-2 specs (#75).
+- Keep page-test scope tight: smoke-render each header section, exercise interactive controls that aren't already covered by a child component's unit test, and verify the polling indicator wiring. Anything that requires real HTTP belongs in tier-2 integration specs (`e2e/integration-specs/`).
 
 **Playwright conventions:**
 - Specs live under `app/packages/web/e2e/specs/`.
@@ -191,6 +191,13 @@ A planned **tier 2** (#75) will add full-stack specs (real Nest + mocked AWS SDK
 - Use the `authedPage` fixture (token pre-seeded in localStorage) only when a spec needs raw `Page` access (e.g. to call `stubApis` or `addInitScript`); otherwise prefer the higher-level page-object fixtures.
 - Stubs must cover every `/api/*` endpoint the page hits, or the catch-all returns 404 and the test will surface the missing stub quickly.
 
+**Integration test conventions (tier 2):**
+- Specs live under `app/packages/web/e2e/integration-specs/`. Import `{ test, expect }` from `./index.js` (NOT from `@playwright/test`) — the extended `test` includes the `serverMocks`, `authedPage`, and `dashboard` fixtures.
+- `serverMocks` (`ServerMocks` from `e2e/fixtures/server-mocks.ts`) pushes queued responses to the test server via `POST /api/test/mocks/*`. Always include it in test parameters — it resets the MockStore before and after each spec automatically.
+- The test Nest server (`test-main.ts`) runs on `:3002`; the Vite integration preview (port 4174) proxies `/api` to it. Pure HTTP tests call `http://localhost:3002/api/...` directly (bypasses the proxy). Browser tests navigate to the `baseURL` (port 4174) and the proxy routes API calls.
+- `workers: 1` and `fullyParallel: false` in `playwright.integration.config.ts` are intentional — the shared in-process `MockStore` cannot be used concurrently.
+- The integration Vite build sets `VITE_STATUS_POLL_MS=3000` so pollers fire every 3 s instead of 20 s, keeping status-polling specs fast without busy-looping.
+
 ## Git & Branch Workflow
 
 `main` is a protected branch — direct pushes are blocked. All changes go through a PR, including trivial chores (`.gitignore` entries, config tweaks). Never commit directly to `main`.

app/eslint.config.js

@@ -28,6 +28,11 @@ export default tseslint.config(
       tsdoc,
     },
     rules: {
+      '@typescript-eslint/no-unused-vars': ['error', {
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+        caughtErrorsIgnorePattern: '^_',
+      }],
       'tsdoc/syntax': 'error',
       'jsdoc/require-jsdoc': ['error', {
         publicOnly: true,

app/packages/server/src/services/ConfigService.ts

@@ -7,33 +7,17 @@ import { EMBEDDED_TFSTATE } from '../generated/tfstate.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-/**
- * Probes candidate relative paths from __dirname in order and returns the
- * first that exists on disk.  Falls back to the first candidate when none
- * exist so callers get a deterministic (missing-file) path rather than
- * undefined behaviour.
- *
- * Needed because the depth from __dirname to the repo/workspace root differs
- * between environments:
- *   - local source tree  (src/services or dist/services inside repo): 5 levels up → repo root
- *   - Docker image       (dist/services inside /app):                  4 levels up → /app
- */
-function resolveRuntimePath(...relativeCandidates: string[]): string {
-  for (const rel of relativeCandidates) {
-    const resolved = join(__dirname, rel);
-    if (existsSync(resolved)) return resolved;
-  }
-  return join(__dirname, relativeCandidates[0]);
-}
+// dist/services/ → 4 hops up = app root (repo: app/, Docker: /workspace/app/)
+// 5 hops up = repo/workspace root, where terraform/ lives
+const APP_ROOT = join(__dirname, '..', '..', '..', '..');
+
+const TF_STATE_PATH =
+  process.env['TF_STATE_PATH'] ??
+  join(APP_ROOT, '..', 'terraform', 'terraform.tfstate');
 
-const TF_STATE_PATH = resolveRuntimePath(
-  '../../../../../terraform/terraform.tfstate',
-  '../../../../terraform/terraform.tfstate',
-);
-const CONFIG_PATH = resolveRuntimePath(
-  '../../../../../app/server_config.json',
-  '../../../../server_config.json',
-);
+const SERVER_CONFIG_PATH =
+  process.env['SERVER_CONFIG_PATH'] ??
+  join(APP_ROOT, 'server_config.json');
 
 /**
  * Shape of the subset of Terraform root outputs the management app consumes.
@@ -82,7 +66,8 @@ const DEFAULT_CONFIG: WatchdogConfig = {
  *    lazily and cached in-memory until {@link ConfigService.invalidateCache}
  *    is called.
  *  - `server_config.json` — the user-editable file holding the watchdog
- *    tunables and the optional API bearer token.
+ *    tunables and the optional API bearer token. Path resolved via
+ *    `SERVER_CONFIG_PATH` env var, defaulting to `<app-root>/server_config.json`.
  *  - A handful of process env vars (`AWS_DEFAULT_REGION`, `API_TOKEN`).
  *
  * Every other service injects this one instead of touching `process.env` or
@@ -196,9 +181,9 @@ export class ConfigService {
     if (env !== undefined) {
       return env.length > 0 ? env : null;
     }
-    if (!existsSync(CONFIG_PATH)) return null;
+    if (!existsSync(SERVER_CONFIG_PATH)) return null;
     try {
-      const raw = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')) as { api_token?: unknown };
+      const raw = JSON.parse(readFileSync(SERVER_CONFIG_PATH, 'utf-8')) as { api_token?: unknown };
       return typeof raw.api_token === 'string' && raw.api_token.length > 0 ? raw.api_token : null;
     } catch (err) {
       logger.warn('Could not read api_token from config file', { err });
@@ -225,9 +210,9 @@ export class ConfigService {
    * fresh object on every call — safe for callers to mutate.
    */
   getConfig(): WatchdogConfig {
-    if (!existsSync(CONFIG_PATH)) return { ...DEFAULT_CONFIG };
+    if (!existsSync(SERVER_CONFIG_PATH)) return { ...DEFAULT_CONFIG };
     try {
-      const saved = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')) as Partial<WatchdogConfig>;
+      const saved = JSON.parse(readFileSync(SERVER_CONFIG_PATH, 'utf-8')) as Partial<WatchdogConfig>;
       return { ...DEFAULT_CONFIG, ...saved };
     } catch (err) {
       logger.warn('Could not read config file, using defaults', { err });
@@ -241,7 +226,7 @@ export class ConfigService {
    * save here is not effective until the next `terraform apply`.
    */
   saveConfig(config: WatchdogConfig): void {
-    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+    writeFileSync(SERVER_CONFIG_PATH, JSON.stringify(config, null, 2));
     logger.info('Config saved', config);
   }
 }

app/packages/server/src/test-main.ts

@@ -0,0 +1,93 @@
+/**
+ * Integration-test entry point for the Nest server.
+ *
+ * Sets up aws-sdk-client-mock interceptors BEFORE creating the Nest
+ * application. EcsService creates its ECSClient lazily (on first request),
+ * so patching the prototype here is sufficient — all subsequent send() calls
+ * on any ECSClient instance will hit the mock.
+ *
+ * Run via: PORT=3002 NODE_ENV=test API_TOKEN=test-token
+ *           TF_STATE_PATH=<path> node dist/test-main.js
+ */
+import 'reflect-metadata';
+import { Module } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+import type { NestExpressApplication } from '@nestjs/platform-express';
+import { mockClient } from 'aws-sdk-client-mock';
+import {
+  ECSClient,
+  ListTasksCommand,
+  DescribeTasksCommand,
+  RunTaskCommand,
+  StopTaskCommand,
+} from '@aws-sdk/client-ecs';
+import { AppModule } from './app.module.js';
+import { TestMocksModule } from './test-mocks/test-mocks.module.js';
+import { mockStore } from './test-mocks/mock-store.js';
+import { logger } from './logger.js';
+
+// ── Patch ECSClient prototype before DI container creates any instances ──
+
+const ecsMock = mockClient(ECSClient);
+
+ecsMock.on(ListTasksCommand).callsFake(async () => {
+  const next = mockStore.dequeueListTasks();
+  if (next?.type === 'error') {
+    throw Object.assign(new Error(next.message ?? 'Mock ListTasks error'), {
+      name: next.code ?? 'ServiceException',
+    });
+  }
+  return (next?.data as object | undefined) ?? { taskArns: [] };
+});
+
+ecsMock.on(DescribeTasksCommand).callsFake(async () => {
+  const next = mockStore.dequeueDescribeTasks();
+  if (next?.type === 'error') {
+    throw Object.assign(new Error(next.message ?? 'Mock DescribeTasks error'), {
+      name: next.code ?? 'ServiceException',
+    });
+  }
+  return (next?.data as object | undefined) ?? { tasks: [] };
+});
+
+ecsMock.on(RunTaskCommand).callsFake(async () => {
+  const next = mockStore.dequeueRunTask();
+  if (next?.type === 'error') {
+    throw Object.assign(new Error(next.message ?? 'Mock RunTask error'), {
+      name: next.code ?? 'ServiceException',
+    });
+  }
+  return (next?.data as object | undefined) ?? {
+    tasks: [{ taskArn: 'arn:aws:ecs:us-east-1:123456789012:task/test-cluster/test-task-id' }],
+    failures: [],
+  };
+});
+
+ecsMock.on(StopTaskCommand).callsFake(async () => {
+  const next = mockStore.dequeueStopTask();
+  if (next?.type === 'error') {
+    throw Object.assign(new Error(next.message ?? 'Mock StopTask error'), {
+      name: next.code ?? 'ServiceException',
+    });
+  }
+  return (next?.data as object | undefined) ?? {};
+});
+
+// ── Boot the Nest application ──
+
+/** Wraps AppModule (real providers + global guard) and adds TestMocksModule. */
+@Module({ imports: [AppModule, TestMocksModule] })
+class TestAppModule {}
+
+const PORT = parseInt(process.env['PORT'] ?? '3002', 10);
+
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.create<NestExpressApplication>(TestAppModule, {
+    logger: ['error', 'warn'],
+  });
+  app.setGlobalPrefix('api');
+  await app.listen(PORT);
+  logger.info(`Integration test server running on http://localhost:${PORT}`, { port: PORT });
+}
+
+void bootstrap();

app/packages/server/src/test-mocks/mock-store.ts

@@ -0,0 +1,47 @@
+/** Shape of a single queued mock response. */
+export interface MockResponse {
+  /** 'success' returns `data`; 'error' throws an error with `code` and `message`. */
+  type: 'success' | 'error';
+  data?: unknown;
+  code?: string;
+  message?: string;
+}
+
+/**
+ * Singleton in-process store of queued AWS SDK mock responses.
+ * `test-main.ts` sets up `aws-sdk-client-mock` interceptors that read from
+ * this store via `dequeue*()`. Playwright tests push responses via the
+ * `TestMocksController` HTTP endpoints before exercising each flow.
+ *
+ * Default (empty queue) behaviour per command:
+ *  - ListTasks    → \{ taskArns: [] \}   (no running tasks)
+ *  - DescribeTasks → \{ tasks: [] \}
+ *  - RunTask      → \{ tasks: [\{ taskArn: 'arn:aws:ecs:us-east-1:123:task/test-cluster/test-task-id' \}] \}
+ *  - StopTask     → \{\}
+ */
+class MockStore {
+  private listTasksQueue: MockResponse[] = [];
+  private describeTasksQueue: MockResponse[] = [];
+  private runTaskQueue: MockResponse[] = [];
+  private stopTaskQueue: MockResponse[] = [];
+
+  pushListTasks(r: MockResponse): void     { this.listTasksQueue.push(r); }
+  pushDescribeTasks(r: MockResponse): void { this.describeTasksQueue.push(r); }
+  pushRunTask(r: MockResponse): void       { this.runTaskQueue.push(r); }
+  pushStopTask(r: MockResponse): void      { this.stopTaskQueue.push(r); }
+
+  dequeueListTasks(): MockResponse | null     { return this.listTasksQueue.shift() ?? null; }
+  dequeueDescribeTasks(): MockResponse | null { return this.describeTasksQueue.shift() ?? null; }
+  dequeueRunTask(): MockResponse | null       { return this.runTaskQueue.shift() ?? null; }
+  dequeueStopTask(): MockResponse | null      { return this.stopTaskQueue.shift() ?? null; }
+
+  /** Clear all queues — called between tests via `POST /api/test/mocks/reset`. */
+  reset(): void {
+    this.listTasksQueue = [];
+    this.describeTasksQueue = [];
+    this.runTaskQueue = [];
+    this.stopTaskQueue = [];
+  }
+}
+
+export const mockStore = new MockStore();

app/packages/server/src/test-mocks/test-mocks.controller.ts

@@ -0,0 +1,47 @@
+import { Body, Controller, Post } from '@nestjs/common';
+import { mockStore, type MockResponse } from './mock-store.js';
+
+/**
+ * HTTP endpoints for Playwright integration tests to control mock AWS SDK
+ * responses. Only registered in the test binary — never imported by AppModule.
+ *
+ * Protected by ApiTokenGuard (the global guard from AppModule applies to all
+ * routes) — callers must send `Authorization: Bearer test-token`.
+ */
+@Controller('test/mocks')
+export class TestMocksController {
+  /** Reset all queues between test scenarios. */
+  @Post('reset')
+  reset(): { ok: true } {
+    mockStore.reset();
+    return { ok: true };
+  }
+
+  /** Push a response for the next `ListTasksCommand` call. */
+  @Post('ecs/list-tasks')
+  pushListTasks(@Body() body: MockResponse): { ok: true } {
+    mockStore.pushListTasks(body);
+    return { ok: true };
+  }
+
+  /** Push a response for the next `DescribeTasksCommand` call. */
+  @Post('ecs/describe-tasks')
+  pushDescribeTasks(@Body() body: MockResponse): { ok: true } {
+    mockStore.pushDescribeTasks(body);
+    return { ok: true };
+  }
+
+  /** Push a response for the next `RunTaskCommand` call. */
+  @Post('ecs/run-task')
+  pushRunTask(@Body() body: MockResponse): { ok: true } {
+    mockStore.pushRunTask(body);
+    return { ok: true };
+  }
+
+  /** Push a response for the next `StopTaskCommand` call. */
+  @Post('ecs/stop-task')
+  pushStopTask(@Body() body: MockResponse): { ok: true } {
+    mockStore.pushStopTask(body);
+    return { ok: true };
+  }
+}

app/packages/server/src/test-mocks/test-mocks.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { TestMocksController } from './test-mocks.controller.js';
+
+/** Nest module exposing mock-control endpoints. Only imported by TestAppModule in test-main.ts. */
+@Module({
+  controllers: [TestMocksController],
+})
+export class TestMocksModule {}