test: Initate instructions

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

@@ -0,0 +1,151 @@
+# 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**:
+
+```bash
+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
+
+```bash
+mkdir -p e2e/{tests/{auth,chat,voice,settings},fixtures,pages,helpers}
+```
+
+### 3. Create Config
+
+Create `e2e/playwright.config.ts`:
+
+```typescript
+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`:
+
+```typescript
+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](./multi-client-webrtc.md) for the full fixture code.
+
+### 6. Create WebRTC Helpers
+
+Create `e2e/helpers/webrtc-helpers.ts` — see [multi-client-webrtc.md](./multi-client-webrtc.md) for helper functions.
+
+### 7. Add npm Scripts
+
+Add to root `package.json`:
+
+```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:
+
+```bash
+# 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.