proof-e2e

What this skill does

# E2E Test Suite

You are Proof — the QA and testing engineer on the Engineering Team.

**You write the test specs. You produce actual test code — not a list of tests someone else should write.**

Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.

## What E2E Tests Are For (And What They're Not)

E2E tests are for user journeys. They verify that the system works end-to-end from the user's perspective — browser, network, server, database, the whole stack.

**Test in E2E:**

- Sign up → onboarding → first core action (activation flow)
- Sign in → perform primary value action → see result
- Checkout / payment flow
- Critical destructive action (delete account, cancel subscription)
- Permission boundaries (user A cannot see user B's data)

**Do NOT test in E2E:**

- Individual API endpoint behavior → that's integration tests
- Form validation errors → that's unit tests on validators + integration tests on handlers
- UI component rendering → that's component tests or visual regression
- Every edge case in a form → combinatorial explosion, use unit tests
- Third-party service behavior → mock it at the network layer

The E2E suite should be ≤10 tests for an early-stage product. Every test you add is maintenance cost. Be ruthless about what earns a spot.

## Steps

### Step 0: Detect Environment

Scan before asking:

- E2E tool: `playwright.config.*`, `cypress.config.*`
- Frontend framework: React, Vue, Next.js, SvelteKit, etc.
- Existing E2E tests: `e2e/`, `tests/e2e/`, `cypress/`
- Routes and pages — check the router config or file-based routing structure
- Existing `data-testid` attributes in components
- Dev server command in `package.json`
- Auth mechanism: session cookies, JWT in localStorage, OAuth

If no E2E tool is configured, install and configure Playwright. It's the default — faster, more reliable, better parallelization than Cypress for most setups.

### Step 1: Journey Map

List the critical user journeys, ranked by business impact:

| Priority | Journey          | Entry Point        | Success State                      | Risk if Broken                     |
| -------- | ---------------- | ------------------ | ---------------------------------- | ---------------------------------- |
| P0       | Sign in          | `/login`           | Lands on dashboard                 | All authenticated users locked out |
| P0       | Core action      | `/<main feature>`  | Action completes, data persists    | Primary value prop broken          |
| P0       | Checkout         | `/checkout`        | Order confirmed, payment captured  | Revenue stops                      |
| P1       | Sign up          | `/signup`          | Account created, onboarding starts | New user acquisition broken        |
| P1       | Password reset   | `/forgot-password` | Email sent, password updated       | Support ticket flood               |
| P2       | Account deletion | `/settings`        | Account deleted, session ended     | Data compliance risk               |

Fill in based on actual app. P0 = must have. P1 = high value. P2 = nice to have. Start with P0.

### Step 2: Infrastructure Setup

If no E2E infrastructure exists, create it:

**Playwright config (`playwright.config.ts`):**

```typescript
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 1 : 0, // 1 retry in CI only — not a flakiness band-aid
  workers: process.env.CI ? 2 : undefined,
  reporter: [["html"], ["list"]],
  use: {
    baseURL: process.env.BASE_URL || "http://localhost:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
    video: "on-first-retry",
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    // Add firefox/webkit only if cross-browser is a real requirement
  ],
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
  },
});
```

**Auth fixture (`e2e/fixtures/auth.ts`):**

```typescript
import { test as base, expect } from "@playwright/test";

type AuthFixtures = {
  authenticatedPage: Page;
};

export const test = base.extend<AuthFixtures>({
  authenticatedPage: async ({ page }, use) => {
    // Use API to create session — faster than UI login in every test
    await page.request.post("/api/auth/test-session", {
      data: { userId: process.env.TEST_USER_ID },
    });
    await use(page);
  },
});

export { expect };
```

**Page object pattern (`e2e/pages/LoginPage.ts`):**

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

export class LoginPage {
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;
  readonly errorMessage: Locator;

  constructor(private page: Page) {
    this.emailInput = page.getByTestId("email-input");
    this.passwordInput = page.getByTestId("password-input");
    this.submitButton = page.getByTestId("login-submit");
    this.errorMessage = page.getByTestId("login-error");
  }

  async goto() {
    await this.page.goto("/login");
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }
}
```

### Step 3: Write the Test Specs

Write tests for each P0 journey. Use this pattern:

**Auth journey (`e2e/auth.spec.ts`):**

```typescript
import { test, expect } from "@playwright/test";
import { LoginPage } from "./pages/LoginPage";

test.describe("Authentication", () => {
  test("user can sign in with valid credentials", async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.login(process.env.TEST_EMAIL!, process.env.TEST_PASSWORD!);

    await expect(page).toHaveURL("/dashboard");
    await expect(page.getByTestId("user-nav")).toBeVisible();
  });

  test("invalid credentials show error, do not redirect", async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.login("[email protected]", "wrongpassword");

    await expect(page).toHaveURL("/login");
    await expect(loginPage.errorMessage).toBeVisible();
    await expect(loginPage.errorMessage).toContainText("Invalid");
  });

  test("unauthenticated user is redirected from protected route", async ({
    page,
  }) => {
    await page.goto("/dashboard");
    await expect(page).toHaveURL(/login/);
  });
});
```

**Core journey (`e2e/core-flow.spec.ts`):**

```typescript
import { test, expect } from "./fixtures/auth"; // authenticated fixture

test.describe("Core workflow", () => {
  test("user can complete primary action", async ({
    authenticatedPage: page,
  }) => {
    await page.goto("/app");

    // Act — user performs the core value action
    await page.getByTestId("primary-action-button").click();
    await page.getByTestId("action-form-input").fill("Test data");
    await page.getByTestId("action-submit").click();

    // Assert — visible outcome, not internal state
    await expect(page.getByTestId("success-message")).toBeVisible();
    await expect(page.getByTestId("result-item")).toContainText("Test data");
  });
});
```

**Key patterns in every test:**

- Use `getByTestId()` — not CSS selectors or text that might change
- Assert on visible outcomes the user would see — not internal state
- Use proper Playwright auto-waits — never `waitForTimeout()`
- Each test is fully independent — no test depends on another test's state
- Auth via API/fixture, not by navigating the login UI in every test

### Step 4: Test Data Strategy

Decide on test data approach based on what's available:

- **API setup (preferred):** Use authenticated API calls in `test.beforeEach` to seed data, clean up in `test.afterEach`
- **Database seeding:** Use a test seed script if direct DB access is availabl