Playwright E2E Testing

Install

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

Config (playwright.config.ts)

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

const baseURL = process.env.PLAYWRIGHT_BASE_URL ?? "http://localhost:3000";

export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  use: { baseURL, trace: "on-first-retry" },
  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
  webServer: {
    command: process.env.CI ? "npm run build && npm run start" : "npm run dev",
    url: baseURL,
    reuseExistingServer: !process.env.CI,
    timeout: 180_000,
  },
});

Package scripts

"test:e2e": "playwright test"

Basic spec

import { test, expect } from "@playwright/test";

test("homepage navigates to signup", async ({ page }) => {
  await page.goto("/");
  await page.getByRole("link", { name: /Get Started/i }).click();
  await expect(page).toHaveURL(/\/signup/);
});

Prefer getByRole, getByLabel over CSS selectors.

Seed client state (localStorage)

// e2e/helpers/seed-store.ts
export async function seedStore(page: Page, snapshot: object) {
  await page.addInitScript((data) => {
    localStorage.setItem("app-storage-key", JSON.stringify({ state: data, version: 0 }));
  }, snapshot);
}

Use before goto for dashboard tests requiring completed setup.

Accessibility scan

npm install -D @axe-core/playwright

import AxeBuilder from "@axe-core/playwright";

const results = await new AxeBuilder({ page }).withTags(["wcag2aa"]).analyze();
expect(results.violations).toEqual([]);

CI (GitHub Actions)

- run: npx playwright install chromium --with-deps
- run: npm run test:e2e
  env:
    CI: true

Run build && start in CI via webServer config — avoids dev-server flakiness.

Tips

Anti-patterns

• Hard-coded waitForTimeout instead of assertions
• Testing implementation details (class names) over roles
• Sharing mutable state between parallel tests
• Skipping browser install step in CI

Pair with: web-accessibility-wcag, vitest-unit-testing.