Skip to content

Fully autonomous AI Agents system capable of performing complex penetration testing tasks

feat(e2e): Playwright scaffold with a hermetic mock gate

Sergey Kozyrenko67266c9316f7
diff --git a/.github/workflows/e2e-report.yml b/.github/workflows/e2e-report.yml
new file mode 100644
index 00000000..560aba5e
--- /dev/null
+++ b/.github/workflows/e2e-report.yml
@@ -0,0 +1,96 @@
+# Posts the sticky E2E PR comment. Runs in base-repo context (writable token)
+# after the fork-safe E2E workflow completes. Never checks out or executes PR
+# code; the only artifact-derived values rendered are numeric counts.
+name: E2E report
+
+on:
+ workflow_run:
+ workflows: ["E2E"]
+ types:
+ - completed
+
+permissions:
+ actions: read
+ pull-requests: write
+
+jobs:
+ comment:
+ if: github.event.workflow_run.event == 'pull_request'
+ runs-on: ubuntu-latest
+ steps:
+ - name: Download results
+ continue-on-error: true
+ uses: actions/download-artifact@v4
+ with:
+ name: e2e-results
+ path: results
+ run-id: ${{ github.event.workflow_run.id }}
+ github-token: ${{ github.token }}
+
+ - name: Post sticky comment
+ uses: actions/github-script@v7
+ with:
+ script: |
+ const fs = require('fs');
+ const run = context.payload.workflow_run;
+
+ // workflow_run.pull_requests is empty for fork PRs — resolve by head SHA.
+ let prNumber = run.pull_requests[0]?.number;
+ if (!prNumber) {
+ const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ commit_sha: run.head_sha,
+ });
+ prNumber = prs[0]?.number;
+ }
+ if (!prNumber) {
+ core.info(`No PR found for ${run.head_sha}; skipping comment.`);
+ return;
+ }
+
+ let statsLine = 'The run produced no results file (it likely failed before the tests started).';
+ try {
+ const report = JSON.parse(fs.readFileSync('results/results.json', 'utf8'));
+ const n = (value) => Number(value) || 0;
+ const { expected, unexpected, flaky, skipped } = report.stats ?? {};
+ statsLine = `**${n(expected)} passed**, ${n(unexpected)} failed, ${n(flaky)} flaky, ${n(skipped)} skipped.`;
+ } catch (error) {
+ core.info(`results.json unavailable: ${error}`);
+ }
+
+ const conclusion = run.conclusion === 'success' ? '✅' : '❌';
+ const marker = '<!-- e2e-report -->';
+ const body = [
+ marker,
+ `### ${conclusion} E2E (mock tier)`,
+ '',
+ statsLine,
+ '',
+ `[Run + report/trace artifacts](${run.html_url}) · commit ${run.head_sha.slice(0, 7)}`,
+ '',
+ 'Debug a red run locally: download the `e2e-report` artifact and open the trace with `pnpm exec playwright show-trace <trace.zip>`.',
+ ].join('\n');
+
+ const { data: comments } = await github.rest.issues.listComments({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: prNumber,
+ });
+ const existing = comments.find((comment) => comment.body?.startsWith(marker));
+
+ if (existing) {
+ await github.rest.issues.updateComment({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ comment_id: existing.id,
+ body,
+ });
+ } else {
+ await github.rest.issues.createComment({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: prNumber,
+ body,
+ });
+ }
diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
new file mode 100644
index 00000000..11d71362
--- /dev/null
+++ b/.github/workflows/e2e.yml
@@ -0,0 +1,74 @@
+# The fork-safe gate: read-only permissions, no secrets, no write steps.
+# PR comments are posted by e2e-report.yml (workflow_run) which runs in
+# base-repo context — a fork PR's GITHUB_TOKEN cannot write comments.
+name: E2E
+
+on:
+ pull_request:
+ push:
+ branches:
+ - main
+ tags:
+ - "v[0-9]+.[0-9]+.[0-9]+"
+ schedule:
+ - cron: "0 3 * * *"
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: e2e-${{ github.head_ref || github.run_id }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+ e2e-mock:
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v6
+
+ - name: Install pnpm
+ uses: pnpm/action-setup@v4
+ with:
+ package_json_file: frontend/package.json
+
+ - name: Set up Node.js
+ uses: actions/setup-node@v6
+ with:
+ node-version-file: frontend/.nvmrc
+ cache: "pnpm"
+ cache-dependency-path: "frontend/pnpm-lock.yaml"
+
+ - name: Install dependencies
+ working-directory: frontend
+ run: pnpm install --frozen-lockfile
+
+ - name: Install Playwright browsers
+ working-directory: frontend
+ run: pnpm exec playwright install --with-deps chromium
+
+ - name: Run E2E (mock tier, production bundle)
+ working-directory: frontend
+ run: pnpm e2e
+
+ - name: Upload results.json
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: e2e-results
+ path: frontend/e2e/test-results/results.json
+ retention-days: 7
+ if-no-files-found: ignore
+
+ - name: Upload report and traces
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: e2e-report
+ path: |
+ frontend/e2e/blob-report
+ frontend/e2e/test-results
+ retention-days: 7
+ if-no-files-found: ignore
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c4b4c59c..d9f2140b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -62,6 +62,13 @@ License reports are automatically generated during Docker builds:
- `licenses.json` - Detailed license data
- `licenses.csv` - License summary
+## Testing Your Changes
+
+Frontend changes are covered by unit tests (`cd frontend && pnpm test`) and
+end-to-end tests that run fully offline — no backend, keys, or secrets needed,
+including on fork PRs. See [frontend/docs/e2e.md](frontend/docs/e2e.md) for the
+one-time bootstrap, running locally, and debugging a red CI run.
+
## Questions?
diff --git a/frontend/.gitignore b/frontend/.gitignore
index aaa05ede..2e4d9116 100644
--- a/frontend/.gitignore
+++ b/frontend/.gitignore
@@ -22,3 +22,9 @@ ssl
*.njsproj
*.sln
*.sw?
+
+# Playwright
+e2e/test-results/
+e2e/playwright-report/
+e2e/blob-report/
+playwright/.auth/
diff --git a/frontend/.prettierignore b/frontend/.prettierignore
new file mode 100644
index 00000000..8bbde193
--- /dev/null
+++ b/frontend/.prettierignore
@@ -0,0 +1,2 @@
+e2e/test-results/
+e2e/playwright-report/
diff --git a/frontend/docs/e2e.md b/frontend/docs/e2e.md
new file mode 100644
index 00000000..1e861cea
--- /dev/null
+++ b/frontend/docs/e2e.md
@@ -0,0 +1,83 @@
+# Frontend E2E tests (Playwright)
+
+End-to-end tests for the PentAGI UI. The default tier runs fully offline against
+network mocks — **no backend, no secrets, no VPN, no LLM keys** — so anyone
+(including fork-PR authors) can run it, and CI runs it on every pull request.
+
+## One-time bootstrap
+
+```bash
+cd frontend
+corepack enable # once per machine, activates the pinned pnpm
+pnpm install
+pnpm e2e:setup # downloads the Chromium build (~300MB)
+```
+
+On Linux, browser system dependencies may be needed once:
+`pnpm exec playwright install --with-deps chromium` (requires sudo).
+On Windows, use WSL — native Windows is untested.
+
+## Running
+
+```bash
+pnpm e2e # mock tier (default): builds the production bundle,
+ # serves it via `vite preview`, mocks the whole API
+pnpm e2e:ui # same, in Playwright UI mode (watch/debug)
+CI=1 pnpm e2e # byte-identical reproduction of a CI run
+ # (same retries and trace policy; CI-style reporters)
+
+E2E_TIER=local pnpm e2e # against the local docker stack (https://localhost:8443)
+E2E_TIER=stand E2E_BASE_URL=https://… pnpm e2e # against a live stand
+```
+
+Tips for the mock tier: `vite preview` is reused between runs if you keep it
+running (`reuseExistingServer`), so only the first run pays the build.
+
+## Tiers
+
+| Tier | Backend | Needs | Used for |
+|---|---|---|---|
+| `mock` (default) | Playwright route/WS mocks replaying cassettes against the **production bundle** | nothing | the PR gate; every functional spec |
+| `local` | `docker compose` stack | docker | fidelity checks, real backend paths |
+| `stand` | a live stand | `E2E_BASE_URL` + creds | deploy smoke, version-skew checks |
+
+## Debugging a red CI run
+
+1. Open the failed run (link in the PR comment) and download the `e2e-report`
+ artifact.
+2. `pnpm exec playwright show-trace <path-to>/trace.zip` — full timeline,
+ network, console, and DOM snapshots for each failed test.
+3. Reproduce locally with `CI=1 pnpm e2e`.
+
+A test failing with `every API call the app made must have a cassette entry`
+means the app issued a request the cassette does not cover — the failure lists
+the exact method/operation. Add the missing entry to the spec's cassette.
+
+## Layout
+
+```
+e2e/
+ playwright.config.ts # tiers via E2E_TIER; mock tier builds+serves the prod bundle
+ fixtures/ # merged `test`: backend/cassette options, auth seeding, error log
+ mocks/ # cassette-driven GraphQL + REST + graphql-ws mock engine
+ cassettes/ # typed cassettes (checked by `pnpm typescript`)
+ helpers/ # shared asserts (page errors, …)
+ specs/ # *.spec.ts, tagged (@smoke, …)
+```
+
+Key conventions:
+
+- **Selectors:** `getByRole`/`getByLabel` first; `data-testid` only where no
+ accessible name exists (add it to the component in the same PR).
+- **Cassettes are TypeScript modules** typed against the generated GraphQL
+ types — schema or operation drift fails `pnpm typescript`, not the runtime.
+- **The clock is pinned** (UTC, fixed epoch) on the mock tier: keep cassette
+ timestamps on the `CASSETTE_EPOCH` day or date renders change under you.
+- **Unmatched calls fail the test** — the mock tier is hermetic by design;
+ nothing ever leaks to a real backend.
+- Assert errors via `pageerror`/`unhandledrejection` (`expectCleanPage`): the
+ production bundle strips app console output, so console-based asserts are
+ meaningless on the mock tier.
+
+The full design (tiers, CI topology, mocking contract, roadmap) lives in the
+team's E2E testing plan; scenario coverage maps 1:1 to the scenario catalog IDs.
diff --git a/frontend/e2e/fixtures/auth.ts b/frontend/e2e/fixtures/auth.ts
new file mode 100644
index 00000000..9d7f17e0
--- /dev/null
+++ b/frontend/e2e/fixtures/auth.ts
@@ -0,0 +1,64 @@
+import type { Page } from '@playwright/test';
+
+import { test as base } from '@playwright/test';
+
+import type { AuthInfo } from '@/models/info';
+import type { User } from '@/models/user';
+
+import type { RestCassetteEntry } from '../mocks/cassette.ts';
+
+import { CASSETTE_EPOCH } from './backend.ts';
+
+// Mirrors AUTH_STORAGE_KEY in src/providers/user-provider.tsx.
+const AUTH_STORAGE_KEY = 'auth';
+
+export const SEEDED_USER = {
+ created_at: '2026-01-10T09:00:00Z',
+ hash: 'e2e-user-hash',
+ id: 1,
+ name: 'admin',
+ password_change_required: false,
+ role_id: 1,
+ status: 'active',
+ type: 'local',
+} satisfies User;
+
+export const seededAuthInfo = (): AuthInfo => ({
+ expires_at: new Date(CASSETTE_EPOCH.getTime() + 12 * 60 * 60 * 1000).toISOString(),
+ privileges: [],
+ role: { id: 1, name: 'admin' },
+ type: 'user',
+ user: SEEDED_USER,
+});
+
+export const authenticatedInfoEntry = (): RestCassetteEntry => ({
+ body: { data: seededAuthInfo(), status: 'success' },
+});
+
+export const guestInfoEntry = (): RestCassetteEntry => ({
+ body: { data: { type: 'guest' }, status: 'success' },
+});
+
+export const seedAuthenticated = async (page: Page): Promise<void> => {
+ await page.addInitScript(
+ ([key, value]) => {
+ window.localStorage.setItem(String(key), String(value));
+ },
+ [AUTH_STORAGE_KEY, JSON.stringify(seededAuthInfo())] as const,
+ );
+};
+
+export const test = base.extend<{ _seedAuth: void; isAuthSeeded: boolean }>({
+ _seedAuth: [
+ async ({ isAuthSeeded, page }, use) => {
+ if (isAuthSeeded) {
+ await seedAuthenticated(page);
+ }
+
+ await use();
+ },
+ { auto: true },
+ ],
+ isAuthSeeded: [true, { option: true }],
+});
diff --git a/frontend/e2e/fixtures/backend.ts b/frontend/e2e/fixtures/backend.ts
new file mode 100644
index 00000000..c1f9abf2
--- /dev/null
+++ b/frontend/e2e/fixtures/backend.ts
@@ -0,0 +1,51 @@
+import { test as base, expect } from '@playwright/test';
+
+import type { Cassette } from '../mocks/cassette.ts';
+
+import { installMockRoutes } from '../mocks/install.ts';
+import { MockWorld } from '../mocks/world.ts';
+
+export interface BackendConfig {
+ installMocks: boolean;
+ tier: BackendTier;
+}
+
+export interface BackendOptions {
+ backend: BackendConfig;
+ cassette: Cassette;
+}
+
+export type BackendTier = 'local' | 'mock' | 'stand';
+
+/**
+ * All cassette timestamps must stay on this (UTC) day: `formatDate` branches on
+ * isToday/isThisYear, so an unpinned clock rots date renders within 24h.
+ */
+export const CASSETTE_EPOCH = new Date('2026-01-15T12:00:00Z');
+
+interface BackendFixtures {
+ world: MockWorld;
+}
+
+export const test = base.extend<BackendFixtures & BackendOptions & { _installMocks: void }>({
+ _installMocks: [
+ async ({ backend, page, world }, use) => {
+ if (!backend.installMocks) {
+ await use();
+
+ return;
+ }
+
+ await page.clock.install({ time: CASSETTE_EPOCH });
+ await installMockRoutes(page, world);
+ await use();
+ expect(world.unmatched, 'every API call the app made must have a cassette entry').toEqual([]);
+ },
+ { auto: true },
+ ],
+ backend: [{ installMocks: true, tier: 'mock' }, { option: true }],
+ cassette: [{}, { option: true }],
+ world: async ({ cassette }, use) => {
+ await use(new MockWorld(cassette));
+ },
+});
diff --git a/frontend/e2e/fixtures/test.ts b/frontend/e2e/fixtures/test.ts
new file mode 100644
index 00000000..bd754072
--- /dev/null
+++ b/frontend/e2e/fixtures/test.ts
@@ -0,0 +1,17 @@
+import { test as base, mergeTests } from '@playwright/test';
+
+import type { PageErrorLog } from '../helpers/errors.ts';
+
+import { watchPageErrors } from '../helpers/errors.ts';
+import { test as authTest } from './auth.ts';
+import { test as backendTest } from './backend.ts';
+
+const errorsTest = base.extend<{ pageErrorLog: PageErrorLog }>({
+ pageErrorLog: async ({ page }, use) => {
+ await use(watchPageErrors(page));
+ },
+});
+
+export const test = mergeTests(backendTest, authTest, errorsTest);
+
+export { expect } from '@playwright/test';
diff --git a/frontend/e2e/helpers/errors.ts b/frontend/e2e/helpers/errors.ts
new file mode 100644
index 00000000..0195b1a1
--- /dev/null
+++ b/frontend/e2e/helpers/errors.ts
@@ -0,0 +1,32 @@
+import type { Page } from '@playwright/test';
+
+import { expect } from '@playwright/test';
+
+export interface PageErrorLog {
+ consoleErrors: string[];
+ pageErrors: string[];
+}
+
+/**
+ * The mock tier runs the production bundle where terser drops app console
+ * output, so `pageerror` (uncaught exceptions + unhandled rejections) is the
+ * load-bearing assert; console errors still catch browser-generated failures
+ * such as failed resource loads.
+ */
+export const expectCleanPage = (log: PageErrorLog): void => {
+ expect(log.pageErrors, 'no uncaught page errors').toEqual([]);
+ expect(log.consoleErrors, 'no browser console errors').toEqual([]);
+};
+
+export const watchPageErrors = (page: Page): PageErrorLog => {
+ const log: PageErrorLog = { consoleErrors: [], pageErrors: [] };
+
+ page.on('pageerror', (error) => log.pageErrors.push(String(error)));
+ page.on('console', (message) => {
+ if (message.type() === 'error') {
+ log.consoleErrors.push(message.text());
+ }
+ });
+
+ return log;
+};
diff --git a/frontend/e2e/mocks/cassette.ts b/frontend/e2e/mocks/cassette.ts
new file mode 100644
index 00000000..bcef1a47
--- /dev/null
+++ b/frontend/e2e/mocks/cassette.ts
@@ -0,0 +1,48 @@
+export interface Cassette {
+ mutations?: Record<string, GraphQLCassetteEntry[]>;
+ queries?: Record<string, GraphQLCassetteEntry[]>;
+ /** Keyed as `"<METHOD> <pathname>"`, e.g. `"GET /api/v1/info"`. */
+ rest?: Record<string, RestCassetteEntry[]>;
+ subscriptions?: Record<string, SubscriptionCassetteEntry[]>;
+}
+
+export interface CassetteFrame {
+ delayMs?: number;
+ payload: GraphQLPayload;
+}
+
+export interface GraphQLCassetteEntry extends GraphQLPayload, WorldFlagged {
+ variables?: Record<string, unknown>;
+}
+
+export interface GraphQLPayload {
+ data?: unknown;
+ errors?: Array<{ message: string }>;
+}
+
+export interface RestCassetteEntry extends WorldFlagged {
+ body?: unknown;
+ status?: number;
+}
+
+export interface SubscriptionCassetteEntry {
+ /**
+ * Streams stay open by default: the real server never completes live
+ * subscriptions, and completing them closes the lazy graphql-ws client's
+ * socket, making the reconnect path untestable. Opt in per stream.
+ */
+ complete?: boolean;
+ frames: CassetteFrame[];
+ variables?: Record<string, unknown>;
+}
+
+/**
+ * Minimal world state: an entry can raise a flag when served (`setFlag`) and be
+ * eligible only after one is raised (`whenFlag`). Flagged entries outrank
+ * unflagged ones, so `GET /info` can flip guest→user after the login mutation
+ * without depending on call order.
+ */
+export interface WorldFlagged {
+ setFlag?: string;
+ whenFlag?: string;
+}
diff --git a/frontend/e2e/mocks/cassettes/smoke.ts b/frontend/e2e/mocks/cassettes/smoke.ts
new file mode 100644
index 00000000..3b69bd4b
--- /dev/null
+++ b/frontend/e2e/mocks/cassettes/smoke.ts
@@ -0,0 +1,66 @@
+import type { ResultOf } from '@graphql-typed-document-node/core';
+
+import type {
+ FlowsDocument,
+ FlowTemplatesDocument,
+ ProvidersDocument,
+ SettingsDocument,
+ SettingsUserDocument,
+} from '@/graphql/types';
+
+import type { Cassette } from '../cassette.ts';
+
+import { authenticatedInfoEntry, guestInfoEntry } from '../../fixtures/auth.ts';
+
+const flows: ResultOf<typeof FlowsDocument> = { flows: [] };
+
+const flowTemplates: ResultOf<typeof FlowTemplatesDocument> = { flowTemplates: [] };
+
+const providers: ResultOf<typeof ProvidersDocument> = { providers: [] };
+
+const settings: ResultOf<typeof SettingsDocument> = {
+ settings: {
+ askUser: false,
+ assistantUseAgents: false,
+ debug: false,
+ dockerInside: false,
+ isDevelopMode: false,
+ version: 'e2e',
+ },
+};
+
+const settingsUser: ResultOf<typeof SettingsUserDocument> = {
+ settingsUser: {
+ favoriteFlows: [],
+ id: '1',
+ },
+};
+
+const queries: Cassette['queries'] = {
+ flows: [{ data: flows }],
+ flowTemplates: [{ data: flowTemplates }],
+ providers: [{ data: providers }],
+ settings: [{ data: settings }],
+ settingsUser: [{ data: settingsUser }],
+};
+
+const resourcesEntry = { body: { data: { items: [] }, status: 'success' } };
+
+/** Seeded-session smoke: every request answers as an authenticated user. */
+export const smokeCassette: Cassette = {
+ queries,
+ rest: {
+ 'GET /api/v1/info': [authenticatedInfoEntry()],
+ 'GET /api/v1/resources/': [resourcesEntry],
+ },
+};
+
+/** Login-form journey: /info serves guest until the login mutation raises the flag. */
+export const loginJourneyCassette: Cassette = {
+ queries,
+ rest: {
+ 'GET /api/v1/info': [guestInfoEntry(), { ...authenticatedInfoEntry(), whenFlag: 'authenticated' }],
+ 'GET /api/v1/resources/': [resourcesEntry],
+ 'POST /api/v1/auth/login': [{ body: { data: {}, status: 'success' }, setFlag: 'authenticated' }],
+ },
+};
diff --git a/frontend/e2e/mocks/install.ts b/frontend/e2e/mocks/install.ts
new file mode 100644
index 00000000..ca774a2a
--- /dev/null
+++ b/frontend/e2e/mocks/install.ts
@@ -0,0 +1,61 @@
+import type { Page } from '@playwright/test';
+
+import type { MockWorld } from './world.ts';
+
+import { installWsMock } from './ws-graphql.ts';
+
+const GRAPHQL_PATH = '/api/v1/graphql';
+
+export const installMockRoutes = async (page: Page, world: MockWorld): Promise<void> => {
+ await installWsMock(page, world);
+
+ // Single catch-all over the whole API surface: anything without a cassette
+ // entry fails fast (501 + recorded in world.unmatched, asserted at teardown)
+ // instead of leaking through the vite preview proxy to a live backend.
+ await page.route('**/api/v1/**', async (route) => {
+ const request = route.request();
+ const { pathname } = new URL(request.url());
+
+ if (pathname === GRAPHQL_PATH && request.method() === 'POST') {
+ const body = request.postDataJSON() as {
+ operationName?: string;
+ variables?: Record<string, unknown>;
+ };
+ const operationName = body.operationName ?? '(anonymous)';
+ const entry = world.matchGraphQL(operationName, body.variables);
+
+ if (entry) {
+ await route.fulfill({
+ json: entry.errors ? { errors: entry.errors } : { data: entry.data },
+ });
+
+ return;
+ }
+
+ world.reportUnmatched(`graphql ${operationName} ${JSON.stringify(body.variables ?? {})}`);
+ await route.fulfill({
+ json: { errors: [{ message: `e2e: no cassette entry for operation "${operationName}"` }] },
+ status: 501,
+ });
+
+ return;
+ }
+
+ const entry = world.matchRest(request.method(), pathname);
+
+ if (entry) {
+ await route.fulfill({
+ json: entry.body ?? {},
+ status: entry.status ?? 200,
+ });
+
+ return;
+ }
+
+ world.reportUnmatched(`${request.method()} ${pathname}`);
+ await route.fulfill({
+ json: { error: `e2e: no cassette entry for ${request.method()} ${pathname}`, status: 'error' },
+ status: 501,
+ });
+ });
+};
diff --git a/frontend/e2e/mocks/world.ts b/frontend/e2e/mocks/world.ts
new file mode 100644
index 00000000..360db7e8
--- /dev/null
+++ b/frontend/e2e/mocks/world.ts
@@ -0,0 +1,115 @@
+import type { WebSocketRoute } from '@playwright/test';
+
+import type {
+ Cassette,
+ GraphQLCassetteEntry,
+ RestCassetteEntry,
+ SubscriptionCassetteEntry,
+ WorldFlagged,
+} from './cassette.ts';
+
+const isSubsetMatch = (expected?: Record<string, unknown>, actual?: Record<string, unknown>): boolean =>
+ !expected ||
+ Object.entries(expected).every(([key, value]) => JSON.stringify(actual?.[key]) === JSON.stringify(value));
+
+export class MockWorld {
+ readonly unmatched: string[] = [];
+
+ private readonly consumed = new Map<string, number>();
+ private readonly flags = new Set<string>();
+ private readonly frameCursors = new Map<string, number>();
+ private readonly sockets = new Set<WebSocketRoute>();
+
+ constructor(private readonly cassette: Cassette) {}
+
+ advanceFrameCursor(streamKey: string): void {
+ this.frameCursors.set(streamKey, this.frameCursor(streamKey) + 1);
+ }
+
+ dropSockets(code = 1001, reason = 'e2e: forced drop'): void {
+ // 1001 is retryable for graphql-ws; 4400+/1011 would kill the client for good.
+ for (const socket of this.sockets) {
+ socket.close({ code, reason });
+ }
+ }
+
+ /** Frames already delivered for a stream survive reconnects — replay is delta-only, matching the real server. */
+ frameCursor(streamKey: string): number {
+ return this.frameCursors.get(streamKey) ?? 0;
+ }
+
+ matchGraphQL(operationName: string, variables?: Record<string, unknown>): GraphQLCassetteEntry | undefined {
+ const sections = [this.cassette.queries, this.cassette.mutations];
+
+ for (const section of sections) {
+ const candidates = this.eligible(
+ section?.[operationName]?.filter((entry) => isSubsetMatch(entry.variables, variables)),
+ );
+
+ if (candidates?.length) {
+ return this.nextEntry(`gql:${operationName}:${JSON.stringify(variables ?? {})}`, candidates);
+ }
+ }
+
+ return undefined;
+ }
+
+ matchRest(method: string, pathname: string): RestCassetteEntry | undefined {
+ const normalized = pathname.replace(/\/+$/, '');
+ const key = Object.keys(this.cassette.rest ?? {}).find((candidate) => {
+ const [candidateMethod, candidatePath = ''] = candidate.split(' ');
+
+ return candidateMethod === method && candidatePath.replace(/\/+$/, '') === normalized;
+ });
+ const candidates = this.eligible(key ? this.cassette.rest?.[key] : undefined);
+
+ return candidates?.length ? this.nextEntry(`rest:${method}:${normalized}`, candidates) : undefined;
+ }
+
+ matchSubscription(
+ operationName: string,
+ variables?: Record<string, unknown>,
+ ): undefined | { entry: SubscriptionCassetteEntry; streamKey: string } {
+ const entry = this.cassette.subscriptions?.[operationName]?.find((candidate) =>
+ isSubsetMatch(candidate.variables, variables),
+ );
+
+ return entry
+ ? { entry, streamKey: `sub:${operationName}:${JSON.stringify(entry.variables ?? {})}` }
+ : undefined;
+ }
+
+ registerSocket(socket: WebSocketRoute): void {
+ this.sockets.add(socket);
+ }
+
+ reportUnmatched(description: string): void {
+ this.unmatched.push(description);
+ }
+
+ unregisterSocket(socket: WebSocketRoute): void {
+ this.sockets.delete(socket);
+ }
+
+ /** Entries gated on an unraised flag are invisible; raised-flag entries outrank unflagged ones. */
+ private eligible<T extends WorldFlagged>(candidates?: T[]): T[] | undefined {
+ const open = candidates?.filter((entry) => !entry.whenFlag || this.flags.has(entry.whenFlag));
+
+ return open?.some((entry) => entry.whenFlag) ? open.filter((entry) => entry.whenFlag) : open;
+ }
+
+ /** Sequenced responses: entries for the same match key are consumed in order; the last one repeats. */
+ private nextEntry<T extends WorldFlagged>(key: string, candidates: T[]): T {
+ const index = this.consumed.get(key) ?? 0;
+
+ this.consumed.set(key, index + 1);
+
+ const entry = candidates[Math.min(index, candidates.length - 1)] as T;
+
+ if (entry.setFlag) {
+ this.flags.add(entry.setFlag);
+ }
+
+ return entry;
+ }
+}
diff --git a/frontend/e2e/mocks/ws-graphql.ts b/frontend/e2e/mocks/ws-graphql.ts
new file mode 100644
index 00000000..c55c003a
--- /dev/null
+++ b/frontend/e2e/mocks/ws-graphql.ts
@@ -0,0 +1,103 @@
+import type { Page } from '@playwright/test';
+
+import type { MockWorld } from './world.ts';
+
+type ClientMessage =
+ | { id: string; payload: SubscribePayload; type: 'subscribe' }
+ | { id: string; type: 'complete' }
+ | { payload?: unknown; type: 'connection_init' }
+ | { type: 'ping' }
+ | { type: 'pong' };
+
+interface SubscribePayload {
+ operationName: string;
+ query: string;
+ variables?: Record<string, unknown>;
+}
+
+export const installWsMock = async (page: Page, world: MockWorld): Promise<void> => {
+ await page.routeWebSocket('**/api/v1/graphql', (ws) => {
+ world.registerSocket(ws);
+
+ const timers = new Set<ReturnType<typeof setTimeout>>();
+ let isOpen = true;
+
+ const send = (message: Record<string, unknown>) => {
+ if (isOpen) {
+ ws.send(JSON.stringify(message));
+ }
+ };
+
+ const schedule = (delayMs: number, action: () => void) => {
+ const timer = setTimeout(() => {
+ timers.delete(timer);
+ action();
+ }, delayMs);
+
+ timers.add(timer);
+ };
+
+ ws.onMessage((raw) => {
+ const message = JSON.parse(String(raw)) as ClientMessage;
+
+ switch (message.type) {
+ case 'connection_init': {
+ // Ack immediately and never send any frame before it: a pre-ack frame
+ // throws inside graphql-ws, and this app's shouldRetry:()=>true turns
+ // that into an infinite reconnect storm.
+ send({ type: 'connection_ack' });
+ break;
+ }
+
+ case 'ping': {
+ send({ type: 'pong' });
+ break;
+ }
+
+ case 'subscribe': {
+ const { id, payload } = message;
+ const match = world.matchSubscription(payload.operationName, payload.variables);
+
+ if (!match) {
+ // Unmatched subscriptions get ack'd silence and stay open: a flow page
+ // opens ~15 at once, and `error`/`complete` would poison the client.
+ break;
+ }
+
+ const { entry, streamKey } = match;
+ const pending = entry.frames.slice(world.frameCursor(streamKey));
+ let elapsed = 0;
+
+ for (const frame of pending) {
+ elapsed += frame.delayMs ?? 0;
+ schedule(elapsed, () => {
+ world.advanceFrameCursor(streamKey);
+ send({ id, payload: frame.payload, type: 'next' });
+ });
+ }
+
+ if (entry.complete) {
+ schedule(elapsed, () => send({ id, type: 'complete' }));
+ }
+
+ break;
+ }
+
+ default: {
+ break;
+ }
+ }
+ });
+
+ ws.onClose(() => {
+ isOpen = false;
+
+ for (const timer of timers) {
+ clearTimeout(timer);
+ }
+
+ timers.clear();
+ world.unregisterSocket(ws);
+ });
+ });
+};
diff --git a/frontend/e2e/playwright.config.ts b/frontend/e2e/playwright.config.ts
new file mode 100644
index 00000000..7676f675
--- /dev/null
+++ b/frontend/e2e/playwright.config.ts
@@ -0,0 +1,75 @@
+import { defineConfig, devices } from '@playwright/test';
+import { fileURLToPath } from 'node:url';
+
+import type { BackendOptions } from './fixtures/backend.ts';
+
+export type BackendTier = 'local' | 'mock' | 'stand';
+
+const tier = (process.env.E2E_TIER ?? 'mock') as BackendTier;
+const isCI = Boolean(process.env.CI);
+
+// `vite preview` listens on VITE_PORT + 100 and reuses the dev proxy config.
+const PREVIEW_PORT = 8100;
+
+// Reporter paths resolve against the process cwd, not the config file — pin them
+// so CI artifact uploads have one deterministic location.
+const here = (relative: string) => fileURLToPath(new URL(relative, import.meta.url));
+
+const TIERS: Record<BackendTier, { baseURL: string; installMocks: boolean }> = {
+ local: { baseURL: process.env.E2E_BASE_URL ?? 'https://localhost:8443', installMocks: false },
+ mock: { baseURL: `http://localhost:${PREVIEW_PORT}`, installMocks: true },
+ stand: { baseURL: process.env.E2E_BASE_URL ?? '', installMocks: false },
+};
+
+if (tier === 'stand' && !TIERS.stand.baseURL) {
+ throw new Error('E2E_TIER=stand requires E2E_BASE_URL');
+}
+
+export default defineConfig<BackendOptions>({
+ forbidOnly: isCI,
+ fullyParallel: true,
+ globalTimeout: isCI ? 10 * 60_000 : undefined,
+ outputDir: './test-results',
+ projects: [
+ {
+ name: `${tier}-chromium`,
+ use: { ...devices['Desktop Chrome'] },
+ },
+ ],
+ reporter: isCI
+ ? [
+ ['blob', { outputDir: here('./blob-report') }],
+ ['json', { outputFile: here('./test-results/results.json') }],
+ ['github'],
+ ['list'],
+ ]
+ : [['html', { open: 'never', outputFolder: here('./playwright-report') }], ['list']],
+ // Retries and trace policy are intentionally identical local vs CI so a red CI
+ // run reproduces byte-identically with `CI=1 pnpm e2e`.
+ retries: 1,
+ testDir: './specs',
+ use: {
+ backend: { installMocks: TIERS[tier].installMocks, tier },
+ baseURL: TIERS[tier].baseURL,
+ ignoreHTTPSErrors: tier === 'local',
+ locale: 'en-US',
+ screenshot: 'only-on-failure',
+ timezoneId: 'UTC',
+ trace: 'on-first-retry',
+ video: 'retain-on-failure',
+ },
+ // The gate must test the shipped artifact: keep this on the production build,
+ // never a dev server.
+ webServer:
+ tier === 'mock'
+ ? {
+ command: 'pnpm run build && pnpm exec vite preview',
+ cwd: fileURLToPath(new URL('..', import.meta.url)),
+ env: { VITE_PORT: '8000', VITE_USE_HTTPS: 'false' },
+ reuseExistingServer: !isCI,
+ timeout: 240_000,
+ url: `http://localhost:${PREVIEW_PORT}`,
+ }
+ : undefined,
+ workers: isCI ? 1 : undefined,
+});
diff --git a/frontend/e2e/specs/smoke.spec.ts b/frontend/e2e/specs/smoke.spec.ts
new file mode 100644
index 00000000..e553b23f
--- /dev/null
+++ b/frontend/e2e/specs/smoke.spec.ts
@@ -0,0 +1,40 @@
+import { SEEDED_USER } from '../fixtures/auth.ts';
+import { expect, test } from '../fixtures/test.ts';
+import { expectCleanPage } from '../helpers/errors.ts';
+import { loginJourneyCassette, smokeCassette } from '../mocks/cassettes/smoke.ts';
+
+test.describe('smoke', { tag: '@smoke' }, () => {
+ test.describe('unauthenticated', () => {
+ test.use({ cassette: loginJourneyCassette, isAuthSeeded: false });
+
+ test('redirects a protected route to /login with returnUrl', async ({ page }) => {
+ await page.goto('/flows');
+
+ await expect(page).toHaveURL(/\/login\?returnUrl=%2Fflows/);
+ await expect(page.getByRole('button', { name: 'Sign in' })).toBeVisible();
+ });
+
+ test('logs in through the form and lands on the flows list', async ({ page, pageErrorLog }) => {
+ await page.goto('/flows');
+ await page.getByLabel('Login').fill(SEEDED_USER.mail);
+ await page.getByRole('textbox', { name: 'Password' }).fill('e2e-password');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+
+ await expect(page).toHaveURL(/\/flows$/);
+ await expect(page.getByText(SEEDED_USER.mail)).toBeVisible();
+ expectCleanPage(pageErrorLog);
+ });
+ });
+
+ test.describe('authenticated', () => {
+ test.use({ cassette: smokeCassette });
+
+ test('renders the flows list with a clean page and no unmatched calls', async ({ page, pageErrorLog }) => {
+ await page.goto('/flows');
+
+ await expect(page).toHaveURL(/\/flows$/);
+ await expect(page.getByText(SEEDED_USER.mail)).toBeVisible();
+ expectCleanPage(pageErrorLog);
+ });
+ });
+});
diff --git a/frontend/e2e/tsconfig.json b/frontend/e2e/tsconfig.json
new file mode 100644
index 00000000..a8e4ddb3
--- /dev/null
+++ b/frontend/e2e/tsconfig.json
@@ -0,0 +1,30 @@
+{
+ "compilerOptions": {
+ /* Base Options: */
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "target": "es2022",
+ "resolveJsonModule": true,
+ "moduleDetection": "force",
+ "isolatedModules": true,
+ "verbatimModuleSyntax": true,
+ "allowImportingTsExtensions": true,
+ "types": ["node"],
+
+ /* Strictness */
+ "strict": true,
+ "noUncheckedIndexedAccess": true,
+ "noImplicitOverride": true,
+
+ "module": "preserve",
+ "noEmit": true,
+
+ /* Specs run in Node, but page.evaluate/addInitScript callbacks run in the DOM. */
+ "lib": ["es2023", "dom", "dom.iterable"],
+
+ "paths": {
+ "@/*": ["../src/*"]
+ }
+ },
+ "include": ["./**/*.ts"]
+}
diff --git a/frontend/eslint.config.mjs b/frontend/eslint.config.mjs
index fe438889..06302f37 100644
--- a/frontend/eslint.config.mjs
+++ b/frontend/eslint.config.mjs
@@ -93,7 +93,21 @@ const eslintConfig = [
},
perfectionist.configs['recommended-natural'],
{
- ignores: ['node_modules/**', 'dist/**', 'build/**', 'public/mockServiceWorker.js', 'src/graphql/types.ts'],
+ // Playwright fixtures take a `use` callback that the React hooks rule
+ // mistakes for a hook call; there is no React under e2e/.
+ files: ['e2e/**/*.ts'],
+ rules: { 'react-hooks/rules-of-hooks': 'off' },
+ },
+ {
+ ignores: [
+ 'node_modules/**',
+ 'dist/**',
+ 'build/**',
+ 'public/mockServiceWorker.js',
+ 'src/graphql/types.ts',
+ 'e2e/test-results/**',
+ 'e2e/playwright-report/**',
+ ],
},
];
diff --git a/frontend/package.json b/frontend/package.json
index de8c725d..97e9214b 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -5,11 +5,14 @@
"scripts": {
"build": "tsc -b && vite build",
"dev": "vite",
+ "e2e": "playwright test -c e2e/playwright.config.ts",
+ "e2e:setup": "playwright install chromium",
+ "e2e:ui": "playwright test -c e2e/playwright.config.ts --ui",
"graphql:generate": "graphql-codegen --config graphql-codegen.ts",
- "lint": "eslint \"src/**/*.{ts,tsx,js,jsx}\"",
- "lint:fix": "eslint \"src/**/*.{ts,tsx,js,jsx}\" --fix",
- "prettier": "prettier --check \"src/**/*.{ts,tsx,js,jsx,json,css,scss}\"",
- "prettier:fix": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,css,scss}\"",
+ "lint": "eslint \"{src,e2e}/**/*.{ts,tsx,js,jsx}\"",
+ "lint:fix": "eslint \"{src,e2e}/**/*.{ts,tsx,js,jsx}\" --fix",
+ "prettier": "prettier --check \"{src,e2e}/**/*.{ts,tsx,js,jsx,json,css,scss}\"",
+ "prettier:fix": "prettier --write \"{src,e2e}/**/*.{ts,tsx,js,jsx,json,css,scss}\"",
"ssl:generate": "tsx --eval 'import { generateCertificates } from \"./scripts/generate-ssl.ts\"; generateCertificates();'",
"test": "vitest run",
"test:coverage": "vitest run --coverage",
@@ -96,6 +99,7 @@
"@graphql-codegen/cli": "^7.1.3",
"@graphql-codegen/typed-document-node": "^7.0.3",
"@graphql-codegen/typescript-operations": "^6.0.4",
+ "@playwright/test": "1.61.1",
"@prettier/plugin-xml": "^3.4.2",
"@tailwindcss/postcss": "^4.3.1",
"@tailwindcss/typography": "^0.5.20",
diff --git a/frontend/pnpm-lock.yaml b/frontend/pnpm-lock.yaml
index 46d17003..78a2b3f5 100644
--- a/frontend/pnpm-lock.yaml
+++ b/frontend/pnpm-lock.yaml
@@ -243,6 +243,9 @@ importers:
'@graphql-codegen/typescript-operations':
specifier: ^6.0.4
version: 6.0.4([email protected])
+ '@playwright/test':
+ specifier: 1.61.1
+ version: 1.61.1
'@prettier/plugin-xml':
specifier: ^3.4.2
version: 3.4.2([email protected])
@@ -1235,6 +1238,11 @@ packages:
'@oxc-project/[email protected]':
resolution: {integrity: sha512-KzkdCd6Uxqnf6l3HOw1xfatAlUURA0g14cvBYFyJ5SaNOQbOUvBr9PKArcPcrNIeRsBdgcUzOGrhKveVpvOIGA==}
+ '@playwright/[email protected]':
+ resolution: {integrity: sha512-8nKv6+0RJSL9FE4jYOEGXnPeM/Hg12qZpmqzZjRh3qM0Y7c3z1mrOTfFLids72RDQYVh9WpLEfR5WdpNX4fkig==}
+ engines: {node: '>=18'}
+ hasBin: true
+
'@prettier/[email protected]':
resolution: {integrity: sha512-/UyNlHfkuLXG6Ed85KB0WBF283xn2yavR+UtRibBRUcvEJId2DSLdGXwJ/cDa1X++SWDPzq3+GSFniHjkNy7yg==}
peerDependencies:
@@ -3444,6 +3452,11 @@ packages:
resolution: {integrity: sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ==}
engines: {node: '>=12'}
+ resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
+ engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+ os: [darwin]
+
resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
@@ -4508,6 +4521,16 @@ packages:
resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
engines: {node: '>=12'}
+ resolution: {integrity: sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==}
+ engines: {node: '>=18'}
+ hasBin: true
+
+ resolution: {integrity: sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ==}
+ engines: {node: '>=18'}
+ hasBin: true
+
resolution: {integrity: sha512-GdzJuUMc6ZSpxFJWVxtOH1bzYHym+TOnveqUjb+VJIbZWbZzyiRGFiKhbiielfpYbgMlhHVhsJ0FTazfuRFkMA==}
@@ -6607,6 +6630,10 @@ snapshots:
'@oxc-project/[email protected]': {}
+ '@playwright/[email protected]':
+ dependencies:
+ playwright: 1.61.1
+
dependencies:
'@xml-tools/parser': 1.0.11
@@ -8970,6 +8997,9 @@ snapshots:
jsonfile: 6.2.1
universalify: 2.0.1
+ optional: true
+
optional: true
@@ -10246,6 +10276,14 @@ snapshots:
+
+ dependencies:
+ playwright-core: 1.61.1
+ optionalDependencies:
+ fsevents: 2.3.2
+
dependencies:
fflate: 0.8.3
diff --git a/frontend/tsconfig.json b/frontend/tsconfig.json
index c173857b..6b5c737b 100644
--- a/frontend/tsconfig.json
+++ b/frontend/tsconfig.json
@@ -1,6 +1,10 @@
{
"files": [],
- "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }],
+ "references": [
+ { "path": "./tsconfig.app.json" },
+ { "path": "./tsconfig.node.json" },
+ { "path": "./e2e/tsconfig.json" }
+ ],
"compilerOptions": {
"paths": {
"@/*": ["./src/*"]