e2e-video

What this skill does

# E2E Video Room Tests

Playwright test suite for Constellation v3 video room features. Tests the video room API routes (create room, generate token, auth guards), the prejoin screen (device selection, camera preview, join flow), and the in-room controls bar (mute, camera, screenshare, leave). Uses `page.route()` to mock LiveKit Cloud API calls so tests run without a real LiveKit server.

## When to Use This Skill

Use this skill when the user says:
- "test video rooms"
- "add video e2e tests"
- "e2e video"
- "test livekit ui"
- "playwright video tests"
- "test video controls"

## Prerequisites

- Next.js app with App Router
- `e2e` skill installed (Playwright configured with `playwright.config.ts`)
- `video-room` skill installed (API routes at `/api/video/rooms` and `/api/video/token`)
- `video-ui` skill installed (prejoin screen, controls bar components)
- `auth-dev` skill installed (seed users for authentication)
- Dev server running on `localhost:3000`

## Installation

No additional packages required. The `e2e` skill provides `@playwright/test` and the Playwright configuration.

## What Gets Created

```
e2e/
├── fixtures/
│   └── mock-livekit.ts         # LiveKit API mock helpers using page.route()
├── helpers/
│   └── video-auth.ts           # Reusable sign-in helper for video tests
├── video-room.spec.ts          # API route tests (create room, token, auth)
├── video-controls.spec.ts      # Controls bar UI tests (mute, camera, leave)
└── video-prejoin.spec.ts       # Prejoin screen tests (devices, preview, join)
```

## Setup Steps

### Step 1: Create `e2e/fixtures/mock-livekit.ts`

This helper intercepts LiveKit Cloud API calls and returns consistent mock data so tests never hit a real LiveKit server.

```typescript
import type { Page } from "@playwright/test";

/**
 * Mock data for a LiveKit room.
 * Matches the VideoRoom type from lib/video/types.ts.
 */
export const mockRoom = {
  name: "test-room",
  sid: "RM_test123abc",
  numParticipants: 0,
  maxParticipants: 20,
  creationTime: 1708300800,
  metadata: "",
} as const;

/**
 * Mock data for a LiveKit participant.
 * Matches the VideoParticipant type from lib/video/types.ts.
 */
export const mockParticipant = {
  sid: "PA_participant456",
  identity: "user-1",
  name: "Admin User",
  metadata: JSON.stringify({ userId: "user-1", email: "[email protected]" }),
  joinedAt: 1708300900,
  isSpeaking: false,
  connectionQuality: "excellent",
} as const;

/**
 * A mock JWT token string for testing.
 * This is NOT a valid JWT — it is only used to verify the token route
 * returns a string in the expected shape.
 */
export const mockToken =
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLTEiLCJyb29tIjoidGVzdC1yb29tIn0.mock-signature";

/**
 * Intercepts outgoing requests to the LiveKit Cloud REST API and
 * returns mock responses. Call this in test.beforeEach to ensure
 * no real LiveKit calls are made.
 *
 * Intercepts:
 * - POST /api/video/rooms   -> returns mockRoom
 * - GET  /api/video/rooms   -> returns [mockRoom]
 * - POST /api/video/token   -> returns { token, url }
 */
export async function interceptLiveKitApi(page: Page): Promise<void> {
  // Mock the room creation endpoint
  await page.route("**/api/video/rooms", async (route) => {
    const method = route.request().method();

    if (method === "POST") {
      const body = route.request().postDataJSON() as { name?: string };
      await route.fulfill({
        status: 201,
        contentType: "application/json",
        body: JSON.stringify({
          room: {
            ...mockRoom,
            name: body?.name ?? mockRoom.name,
          },
        }),
      });
      return;
    }

    if (method === "GET") {
      await route.fulfill({
        status: 200,
        contentType: "application/json",
        body: JSON.stringify({
          rooms: [mockRoom],
        }),
      });
      return;
    }

    await route.continue();
  });

  // Mock the token generation endpoint
  await page.route("**/api/video/token", async (route) => {
    const method = route.request().method();

    if (method === "POST") {
      await route.fulfill({
        status: 200,
        contentType: "application/json",
        body: JSON.stringify({
          token: mockToken,
          url: "wss://mock-livekit.example.com",
        }),
      });
      return;
    }

    await route.continue();
  });
}

/**
 * Intercepts LiveKit WebSocket connections so tests don't attempt
 * real signaling. Returns a mock response that prevents connection errors.
 */
export async function interceptLiveKitWebSocket(page: Page): Promise<void> {
  await page.route("**/rtc**", async (route) => {
    await route.abort("connectionrefused");
  });

  await page.route("wss://**livekit**", async (route) => {
    await route.abort("connectionrefused");
  });
}
```

### Step 2: Create `e2e/helpers/video-auth.ts`

Reusable helper that signs in as the dev admin user via the `/dev` page. Used by all video test files that require authentication.

```typescript
import type { Page } from "@playwright/test";
import { expect } from "@playwright/test";

/**
 * Signs in as the admin test user using the auth-dev quick sign-in flow.
 *
 * Steps:
 * 1. Navigate to /dev
 * 2. Click the "Seed Users" button to ensure users exist
 * 3. Click the "Sign In" button on the admin user card
 * 4. Wait for redirect to homepage
 *
 * Call this in test.beforeEach for any test that requires authentication.
 */
export async function signInAsTestUser(page: Page): Promise<void> {
  // Navigate to the dev console
  await page.goto("/dev");
  await expect(page.getByRole("heading", { name: /dev console/i })).toBeVisible({
    timeout: 10_000,
  });

  // Seed users to ensure they exist in the database
  const seedButton = page.getByRole("button", { name: /seed users/i });
  await seedButton.click();
  // Wait for seed to complete — the result message appears after seeding
  await expect(page.getByText(/seeded|exists|created/i)).toBeVisible({
    timeout: 15_000,
  });

  // Find the admin user card and click Sign In
  const adminCard = page.locator("div", {
    has: page.getByText("[email protected]"),
  });
  const signInButton = adminCard.getByRole("button", { name: /sign in/i });
  await signInButton.click();

  // Wait for redirect after successful sign-in
  await page.waitForURL(/\/(?!dev)/, { timeout: 15_000 });
}

/**
 * Signs out the current user by navigating to /dev and clicking sign out.
 */
export async function signOutTestUser(page: Page): Promise<void> {
  await page.goto("/dev");
  const signOutButton = page.getByRole("button", { name: /sign out/i });
  if (await signOutButton.isVisible()) {
    await signOutButton.click();
    await expect(page.getByText(/not signed in/i)).toBeVisible({
      timeout: 10_000,
    });
  }
}
```

### Step 3: Create `e2e/video-room.spec.ts`

Tests the video room API routes directly using `fetch` within Playwright. Validates room creation, token generation, and authentication guards.

```typescript
import { test, expect } from "@playwright/test";
import { signInAsTestUser, signOutTestUser } from "./helpers/video-auth";

test.describe("Video Room API Routes", () => {
  /**
   * Test: POST /api/video/rooms creates a room.
   *
   * This test mocks the internal LiveKit call by intercepting the route
   * at the browser level. The API route handler calls LiveKit server SDK,
   * so we intercept the outbound request from the Next.js server by
   * sending a direct fetch to the local API and verifying the response shape.
   *
   * Note: Since page.route() only intercepts browser-originated requests,
   * we test the API routes by calling them via the Playwright request context
   * which sends real HTTP requests. The Next.js server must be running with
   * valid (or mocked) LiveKit env vars.
   */
  test("POST /api/video/rooms creates a room and returns room object", async ({
    request,
  }) => {
    const response = await request.post("/api/video/rooms", {