Toju/.agents/skills/playwright-e2e/reference/project-setup.md

Project Setup — Playwright E2E for MetoYou

Before creating any tests or changing them read AGENTS.md for a understanding how the application works.

First-Time Scaffold

1. Install Dependencies

From the repository root:

npm install -D @playwright/test
npx playwright install --with-deps chromium

Only Chromium is needed — WebRTC fake media flags are Chromium-only. Add Firefox/WebKit later if needed for non-WebRTC tests.

2. Create Directory Structure

mkdir -p e2e/{tests/{auth,chat,voice,settings},fixtures,pages,helpers}

3. Create Config

Create e2e/playwright.config.ts:

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  timeout: 60_000,
  expect: { timeout: 10_000 },
  retries: process.env.CI ? 2 : 0,
  workers: 1,
  reporter: [['html', { outputFolder: '../test-results/html-report' }], ['list']],
  outputDir: '../test-results/artifacts',
  use: {
    baseURL: 'http://localhost:4200',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'on-first-retry',
    permissions: ['microphone', 'camera'],
  },
  projects: [
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        launchOptions: {
          args: [
            '--use-fake-device-for-media-stream',
            '--use-fake-ui-for-media-stream',
          ],
        },
      },
    },
  ],
  webServer: [
    {
      command: 'cd ../server && npm run dev',
      port: 3001,
      reuseExistingServer: !process.env.CI,
      timeout: 30_000,
    },
    {
      command: 'cd ../toju-app && npx ng serve',
      port: 4200,
      reuseExistingServer: !process.env.CI,
      timeout: 60_000,
    },
  ],
});

4. Create Base Fixture

Create e2e/fixtures/base.ts:

import { test as base } from '@playwright/test';

export const test = base.extend({
  // Add common fixtures here as the test suite grows
  // Examples: authenticated page, test data seeding, etc.
});

export { expect } from '@playwright/test';

5. Create Multi-Client Fixture

Create e2e/fixtures/multi-client.ts — see multi-client-webrtc.md for the full fixture code.

6. Create WebRTC Helpers

Create e2e/helpers/webrtc-helpers.ts — see multi-client-webrtc.md for helper functions.

7. Create Isolated Test Server Launcher

The app requires a signal server. Tests use an isolated instance with its own temporary database so test data never pollutes the dev environment.

Create e2e/helpers/start-test-server.js — a Node.js script that:

1. Creates a temp directory under the OS tmpdir
2. Writes a data/variables.json with serverPort: 3099, serverProtocol: "http"
3. Spawns ts-node server/src/index.ts with cwd set to the temp dir
4. Cleans up the temp dir on exit

The server's getRuntimeBaseDir() returns process.cwd(), so setting cwd to the temp dir makes the database go to <tmpdir>/data/metoyou.sqlite. Module resolution (require/import) uses __dirname, so server source and node_modules resolve correctly from the real server/ directory.

Playwright's webServer config calls this script and waits for port 3099 to be ready.

8. Create Test Endpoint Seeder

The Angular app reads signal endpoints from localStorage['metoyou_server_endpoints']. By default it falls back to production URLs in environment.ts. For tests, seed localStorage with a single endpoint pointing at http://localhost:3099.

Create e2e/helpers/seed-test-endpoint.ts — called automatically by the multi-client fixture after creating each browser context. The flow is:

1. Navigate to / (establishes the origin for localStorage)
2. Set metoyou_server_endpoints to [{ id: 'e2e-test-server', url: 'http://localhost:3099', ... }]
3. Set metoyou_removed_default_server_keys to suppress production endpoints
4. Reload the page so the app picks up the test endpoint

9. Add npm Scripts

Add to root package.json:

{
  "scripts": {
    "test:e2e": "cd e2e && npx playwright test",
    "test:e2e:ui": "cd e2e && npx playwright test --ui",
    "test:e2e:debug": "cd e2e && npx playwright test --debug",
    "test:e2e:report": "cd e2e && npx playwright show-report ../test-results/html-report"
  }
}

8. Update .gitignore

Add to .gitignore:

# Playwright
test-results/
e2e/playwright-report/

9. Generate Test Audio Fixture (Optional)

For voice tests with controlled audio input:

# Requires ffmpeg
ffmpeg -f lavfi -i "sine=frequency=440:duration=5" -ar 48000 -ac 1 e2e/fixtures/test-tone-440hz.wav

Existing Dev Stack Integration

The tests assume the standard MetoYou dev stack:

• Signaling server at http://localhost:3001 (via server/npm run dev)
• Angular dev server at http://localhost:4200 (via toju-app/npx ng serve)

The webServer config in playwright.config.ts starts these automatically if not already running. When running npm run dev (full Electron stack) separately, tests will reuse the existing servers.

Test Data Requirements

E2E tests need user accounts to log in with. Options:

1. Seed via API — create users in test.beforeAll via the server REST API
2. Pre-seeded database — maintain a test SQLite database with known accounts
3. Register in test — use the /register flow as a setup step (slower but self-contained)

Recommended: Option 3 for initial setup, migrate to Option 1 as the test suite grows.