Playwright — End-to-End Testing in GE

OWNER: marije, judith ALSO_USED_BY: ashley (adversarial), antje LAST_VERIFIED: 2026-03-26 GE_STACK_VERSION: @playwright/test ^1.58.2

---

Overview

Playwright is the standard end-to-end (E2E) testing framework for all GE client projects. It tests real browser behavior — navigation, forms, API calls, visual rendering. Agents use this page when writing E2E tests, configuring CI, or debugging test failures.

---

GE E2E Testing Conventions

CHECK: An E2E test is being written. THEN: Tests live in e2e/ at project root. THEN: Page objects live in e2e/pages/. THEN: Fixtures live in e2e/fixtures/. THEN: Test files are named {feature}.spec.ts.

CHECK: What should be an E2E test vs a unit test. IF: Testing user-visible behavior across multiple components/pages. THEN: E2E test with Playwright. IF: Testing a single function or component in isolation. THEN: Unit test with Vitest.

---

Configuration

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"

export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 2 : undefined,
  reporter: [
    ["html", { open: "never" }],
    ["list"],
  ],
  use: {
    baseURL: process.env.BASE_URL || "http://localhost:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
    video: "retain-on-failure",
  },
  projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
    },
    {
      name: "firefox",
      use: { ...devices["Desktop Firefox"] },
    },
    {
      name: "webkit",
      use: { ...devices["Desktop Safari"] },
    },
    {
      name: "mobile-chrome",
      use: { ...devices["Pixel 7"] },
    },
  ],
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
  },
})

CHECK: Playwright config is being created. THEN: Enable fullyParallel: true — GE tests MUST be independent. THEN: Set retries: 2 in CI — catches transient failures without masking bugs. THEN: Enable trace: "on-first-retry" — traces only generated when debugging is needed. THEN: Configure webServer to auto-start the dev server.

---

Browser Matrix

GE tests against four targets by default:

Project	Device	Why
chromium	Desktop Chrome	Primary user base
firefox	Desktop Firefox	Catch rendering differences
webkit	Desktop Safari	macOS/iOS compatibility
mobile-chrome	Pixel 7	Mobile responsive verification

CHECK: A client project only targets specific browsers. THEN: Narrow the project list — but never drop Chromium.

---

Running Tests

# Run all tests
npx playwright test

# Run specific test file
npx playwright test e2e/auth.spec.ts

# Run in headed mode (visible browser)
npx playwright test --headed

# Run specific project (browser)
npx playwright test --project=chromium

# Debug a test
npx playwright test --debug

# View test report
npx playwright show-report

---

Test Artifacts

On failure, Playwright generates: - Screenshots — captured at failure point - Videos — full test recording (retained on failure) - Traces — DOM snapshots, network, console logs (on first retry)

CHECK: A test failed in CI. THEN: Download the HTML report artifact. THEN: Open traces in Playwright Trace Viewer for step-by-step replay. THEN: Check screenshots for visual state at failure.

---

Cross-References

READ_ALSO: wiki/docs/stack/playwright/patterns.md READ_ALSO: wiki/docs/stack/playwright/pitfalls.md READ_ALSO: wiki/docs/stack/playwright/checklist.md READ_ALSO: wiki/docs/stack/vitest/index.md