test(web): add integration specs, fixtures, and docs for issue #75

Add the Playwright-side of the full-stack integration test suite:

- ServerMocks fixture class with auto-reset before/after each spec;
  extends Playwright base with serverMocks, authedPage, and dashboard
- 6 spec files: api-token-guard (4 HTTP), config-service (3 HTTP),
  start-stop (2 browser), status-polling (1 browser),
  error-propagation (1 HTTP), can-run (skipped placeholder)
- Integration spec index re-exporting the extended test/expect
- Vite integration config: embed VITE_STATUS_POLL_MS=3000 so status
  poller fires every 3s rather than 20s during integration runs
- Playwright integration config: raise Nest startup timeout 30s→120s
  to accommodate ESM loading latency on WSL2/DrvFs (~50s observed)
- gitignore: exclude dist-integration/ build artifacts
- CLAUDE.md: promote two-tier table to three-tier; add integration
  test conventions section; update reference docs table
- docs/docs/components/integration-tests.md: full architecture doc

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: CoderCoco

.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/packages/web/e2e/fixtures/server-mocks.ts

@@ -0,0 +1,82 @@
+import { test as base } from '@playwright/test';
+import type { APIRequestContext, Page } from '@playwright/test';
+import { DashboardPage } from '../pages/DashboardPage.js';
+
+const SERVER_BASE = 'http://localhost:3002';
+const AUTH_HEADERS = { Authorization: 'Bearer test-token' };
+
+/** Shape matching the server-side MockResponse — one queued ECS command reply. */
+export interface MockResponse {
+  type: 'success' | 'error';
+  data?: unknown;
+  code?: string;
+  message?: string;
+}
+
+/**
+ * Playwright-side helper that pushes queued responses into the test server's
+ * MockStore via its HTTP control endpoints at `/api/test/mocks/*`. Each method
+ * maps to one ECS command type. Construct via the `serverMocks` fixture — it
+ * resets the store automatically before and after every test.
+ */
+export class ServerMocks {
+  constructor(private readonly request: APIRequestContext) {}
+
+  private async post(path: string, body?: unknown): Promise<void> {
+    const res = await this.request.post(`${SERVER_BASE}${path}`, {
+      headers: AUTH_HEADERS,
+      ...(body !== undefined ? { data: body } : {}),
+    });
+    if (!res.ok()) throw new Error(`Mock control call failed ${res.status()} ${path}`);
+  }
+
+  /** Clear all ECS command queues — called automatically before and after each test. */
+  async reset(): Promise<void> { await this.post('/api/test/mocks/reset'); }
+
+  /** Queue a response for the next ListTasksCommand call. */
+  async pushListTasks(r: MockResponse): Promise<void> { await this.post('/api/test/mocks/ecs/list-tasks', r); }
+
+  /** Queue a response for the next DescribeTasksCommand call. */
+  async pushDescribeTasks(r: MockResponse): Promise<void> { await this.post('/api/test/mocks/ecs/describe-tasks', r); }
+
+  /** Queue a response for the next RunTaskCommand call. */
+  async pushRunTask(r: MockResponse): Promise<void> { await this.post('/api/test/mocks/ecs/run-task', r); }
+
+  /** Queue a response for the next StopTaskCommand call. */
+  async pushStopTask(r: MockResponse): Promise<void> { await this.post('/api/test/mocks/ecs/stop-task', r); }
+}
+
+type IntegrationFixtures = {
+  /**
+   * Pre-seeded mock controller — resets the MockStore before and after each
+   * test so no queued responses leak between specs.
+   */
+  serverMocks: ServerMocks;
+  /**
+   * Page with `apiToken = 'test-token'` pre-seeded in localStorage so every
+   * navigation to the Vite preview starts authenticated.
+   */
+  authedPage: Page;
+  /** Dashboard page object backed by `authedPage`. */
+  dashboard: DashboardPage;
+};
+
+export const test = base.extend<IntegrationFixtures>({
+  serverMocks: async ({ request }, use) => {
+    const mocks = new ServerMocks(request);
+    await mocks.reset();
+    await use(mocks);
+    await mocks.reset();
+  },
+
+  authedPage: async ({ page }, use) => {
+    await page.addInitScript(() => {
+      localStorage.setItem('apiToken', 'test-token');
+    });
+    await use(page);
+  },
+
+  dashboard: async ({ authedPage }, use) => {
+    await use(new DashboardPage(authedPage));
+  },
+});

app/packages/web/e2e/integration-specs/api-token-guard.spec.ts

@@ -0,0 +1,40 @@
+import { test, expect } from './index.js';
+
+/** Base URL for direct calls to the Nest test server (bypasses the Vite proxy). */
+const ENV_URL = 'http://localhost:3002/api/env';
+
+test.describe('ApiTokenGuard', () => {
+  test('should reject requests with no Authorization header with 401', async ({ request, serverMocks: _ }) => {
+    void _;
+    const resp = await request.get(ENV_URL);
+    expect(resp.status()).toBe(401);
+  });
+
+  test('should reject requests with wrong token with 401', async ({ request, serverMocks: _ }) => {
+    void _;
+    const resp = await request.get(ENV_URL, {
+      headers: { Authorization: 'Bearer wrong-token' },
+    });
+    expect(resp.status()).toBe(401);
+    const body = await resp.json() as { error?: string };
+    expect(body.error).toBe('invalid bearer token');
+  });
+
+  test('should allow requests with valid Authorization: Bearer header', async ({ request, serverMocks: _ }) => {
+    void _;
+    const resp = await request.get(ENV_URL, {
+      headers: { Authorization: 'Bearer test-token' },
+    });
+    expect(resp.status()).toBe(200);
+    const body = await resp.json() as { region: string };
+    expect(body.region).toBe('us-east-1');
+  });
+
+  test('should allow requests with valid ?token= query param (SSE fallback)', async ({ request, serverMocks: _ }) => {
+    void _;
+    const resp = await request.get(`${ENV_URL}?token=test-token`);
+    expect(resp.status()).toBe(200);
+    const body = await resp.json() as { region: string };
+    expect(body.region).toBe('us-east-1');
+  });
+});

app/packages/web/e2e/integration-specs/can-run.spec.ts

@@ -0,0 +1,13 @@
+import { test } from './index.js';
+
+/**
+ * Placeholder for canRun() permission enforcement tests.
+ *
+ * TODO(#75): Add integration specs once the Discord module is wired into the
+ * test server. Each spec should verify that a guild not in `allowedGuilds`, a
+ * non-admin user, or a user without the required per-game action permission is
+ * rejected with the appropriate HTTP error.
+ */
+test.skip('canRun() permission enforcement — pending Discord integration', () => {
+  // placeholder
+});

app/packages/web/e2e/integration-specs/config-service.spec.ts

@@ -0,0 +1,40 @@
+import { test, expect } from './index.js';
+
+const BASE = 'http://localhost:3002';
+const HEADERS = { Authorization: 'Bearer test-token' };
+
+/**
+ * Verifies that ConfigService correctly reads from the synthetic tfstate fixture
+ * (`e2e/fixtures/tfstate.fixture.json`) injected via `TF_STATE_PATH` at
+ * test-server startup.
+ */
+test.describe('ConfigService — tfstate fixture', () => {
+  test('should return aws_region and domain from tfstate fixture', async ({ request, serverMocks: _ }) => {
+    void _;
+    const resp = await request.get(`${BASE}/api/env`, { headers: HEADERS });
+    expect(resp.status()).toBe(200);
+    const body = await resp.json() as { region: string; domain: string; environment: string };
+    expect(body.region).toBe('us-east-1');
+    expect(body.domain).toBe('test.example.com');
+    // 'PROD' is derived when domain_name is non-empty
+    expect(body.environment).toBe('PROD');
+  });
+
+  test('should return game names from tfstate fixture', async ({ request, serverMocks: _ }) => {
+    void _;
+    const resp = await request.get(`${BASE}/api/games`, { headers: HEADERS });
+    expect(resp.status()).toBe(200);
+    const body = await resp.json() as { games: string[] };
+    expect(body.games).toEqual(['minecraft', 'valheim']);
+  });
+
+  test('should return status entries for all games in tfstate fixture', async ({ request, serverMocks: _ }) => {
+    void _;
+    const resp = await request.get(`${BASE}/api/status`, { headers: HEADERS });
+    expect(resp.status()).toBe(200);
+    const statuses = await resp.json() as Array<{ game: string; state: string }>;
+    // Default mock state — no queued ListTasks responses → empty taskArns → stopped
+    expect(statuses.map((s) => s.game).sort()).toEqual(['minecraft', 'valheim']);
+    statuses.forEach((s) => expect(s.state).toBe('stopped'));
+  });
+});

app/packages/web/e2e/integration-specs/error-propagation.spec.ts

@@ -0,0 +1,37 @@
+import { test, expect } from './index.js';
+
+const BASE = 'http://localhost:3002';
+const HEADERS = { Authorization: 'Bearer test-token' };
+
+/**
+ * Verifies that AWS SDK errors surfaced by the mock store propagate through
+ * the Nest server as structured `{ success: false, message }` responses rather
+ * than crashing the server or returning an HTTP error status.
+ *
+ * The mock interceptor in `test-main.ts` throws an Error with the `name` field
+ * set to the `code` value, mirroring the real AWS SDK exception shape. Nest's
+ * `EcsService.start()` catch block converts that to the message string via
+ * `String(err)` → `"<name>: <message>"`.
+ */
+test.describe('Error propagation', () => {
+  test('should surface RunTask AccessDeniedException as a failed start response', async ({
+    request,
+    serverMocks,
+  }) => {
+    await serverMocks.pushRunTask({
+      type: 'error',
+      code: 'AccessDeniedException',
+      message: 'User is not authorized to perform ecs:RunTask',
+    });
+
+    // findRunningTask() uses the default empty-queue ListTasks response (no
+    // existing task), so start() proceeds to RunTask where the error fires.
+    const resp = await request.post(`${BASE}/api/start/minecraft`, { headers: HEADERS });
+
+    // Nest POST routes return 201 by default — the error is encoded in the body.
+    expect(resp.status()).toBe(201);
+    const body = await resp.json() as { success: boolean; message: string };
+    expect(body.success).toBe(false);
+    expect(body.message).toContain('AccessDeniedException');
+  });
+});

app/packages/web/e2e/integration-specs/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-exports for integration specs. Import `test` and `expect` from here
+ * rather than from `@playwright/test` directly — `test` includes the
+ * `serverMocks`, `authedPage`, and `dashboard` fixtures that every integration
+ * spec needs.
+ */
+export { test, type MockResponse, ServerMocks } from '../fixtures/server-mocks.js';
+export { expect } from '@playwright/test';

app/packages/web/e2e/integration-specs/start-stop.spec.ts

@@ -0,0 +1,61 @@
+import { test, expect } from './index.js';
+
+/**
+ * ECS task ARN used as the mock "running task" across start/stop tests.
+ * The value itself doesn't matter — just needs to be a non-empty string.
+ */
+const TASK_ARN = 'arn:aws:ecs:us-east-1:123456789012:task/test-cluster/abc12345';
+
+test.describe('Start / Stop game server (browser)', () => {
+  /**
+   * Golden path: the dashboard loads, polls the real Nest server, and renders
+   * both games from the tfstate fixture as STOPPED (default mock behaviour —
+   * empty ListTasks queue → taskArns [] → stopped).
+   */
+  test('should display game cards from tfstate and show STOPPED status on initial load', async ({
+    dashboard,
+    serverMocks: _,
+  }) => {
+    void _;
+    await dashboard.goto();
+    await expect(dashboard.gameCardHeading('minecraft')).toBeVisible();
+    await expect(dashboard.gameCardHeading('valheim')).toBeVisible();
+    // At least one STOPPED badge must be visible (both games are stopped)
+    await expect(dashboard.statusBadge('STOPPED').first()).toBeVisible();
+  });
+
+  /**
+   * Seeds one game as RUNNING (one ListTasks response consumed by whichever
+   * game's status call executes first), then verifies that exactly one Stop
+   * button is rendered and that clicking it opens the confirm dialog.
+   *
+   * Two games call ListTasksCommand concurrently; the first dequeues the
+   * RUNNING ARN and the second falls through to the default (no task → stopped).
+   * The result is always one RUNNING + one STOPPED card, with exactly one Stop
+   * button visible.
+   */
+  test('should show confirm dialog when Stop is clicked on a running game', async ({
+    dashboard,
+    serverMocks,
+  }) => {
+    await serverMocks.pushListTasks({
+      type: 'success',
+      data: { taskArns: [TASK_ARN] },
+    });
+    await serverMocks.pushDescribeTasks({
+      type: 'success',
+      data: { tasks: [{ taskArn: TASK_ARN, lastStatus: 'RUNNING' }] },
+    });
+
+    await dashboard.goto();
+
+    // One game is running — its Stop button is the only one on the page
+    await expect(dashboard.stopButton()).toBeVisible();
+    await dashboard.stopButton().click();
+
+    // Confirmation dialog must appear with the game name in the heading.
+    // Radix AlertDialog renders with role="alertdialog", not "dialog".
+    await expect(dashboard.page.getByRole('alertdialog')).toBeVisible();
+    await expect(dashboard.page.getByRole('heading', { name: /Stop .+\?/ })).toBeVisible();
+  });
+});

app/packages/web/e2e/integration-specs/status-polling.spec.ts

@@ -0,0 +1,35 @@
+import { test, expect } from './index.js';
+
+const TASK_ARN = 'arn:aws:ecs:us-east-1:123456789012:task/test-cluster/abc12345';
+
+/**
+ * Verifies that the dashboard's status poller picks up AWS state changes
+ * without a page reload. The integration build sets VITE_STATUS_POLL_MS=3000
+ * so the test can push new mock responses after the initial load and observe
+ * the badge transition within a generous timeout.
+ */
+test.describe('Status polling', () => {
+  test('should update game badge from STOPPED to RUNNING after mock state changes', async ({
+    dashboard,
+    serverMocks,
+  }) => {
+    // Navigate — initial poll fires immediately on mount (default: no tasks → stopped)
+    await dashboard.goto();
+    await expect(dashboard.statusBadge('STOPPED').first()).toBeVisible();
+
+    // Push 2 RUNNING responses — one per game in the next concurrent poll
+    for (let i = 0; i < 2; i++) {
+      await serverMocks.pushListTasks({
+        type: 'success',
+        data: { taskArns: [TASK_ARN] },
+      });
+      await serverMocks.pushDescribeTasks({
+        type: 'success',
+        data: { tasks: [{ taskArn: TASK_ARN, lastStatus: 'RUNNING' }] },
+      });
+    }
+
+    // The next poll (≤3 s) consumes the RUNNING responses and updates the badges
+    await expect(dashboard.statusBadge('RUNNING').first()).toBeVisible({ timeout: 10_000 });
+  });
+});