Playwright E2E skill for Claude Code

A good E2E suite tests a few critical user journeys the way a user experiences them, finds elements the way assistive technology does, never sleeps, and gives a trace for every failure. If a test needs waitForTimeout to pass, it is broken.

Ground rules

• Locate by role and accessible name first. CSS/XPath selectors are a last resort.
• Assert with web-first assertions (await expect(locator).toHaveText(...)); they retry until timeout. Never assert on a value you read once with textContent().
• No page.waitForTimeout() in committed tests. Wait for a condition instead.
• Each test owns its data and can run alone, in any order, in parallel.
• Log in once per worker or per run via storageState, not through the UI in every test.
• Keep E2E for journeys. Push branch-level logic into unit and component tests.

Workflow

- [ ] 1. Check the existing config, Playwright version, and test layout
- [ ] 2. Pick the journeys worth an E2E test
- [ ] 3. Set up config: baseURL, webServer, projects, trace, retries
- [ ] 4. Add auth setup project and fixtures
- [ ] 5. Write tests with role locators and web-first assertions
- [ ] 6. Run locally in UI mode, then headless with repeats
- [ ] 7. Wire CI with sharding and trace artifacts

1. Inspect first

npx playwright --version
cat playwright.config.ts
ls tests e2e 2>/dev/null
npx playwright test --list | head -30

New project: npm init playwright@latest. Upgrade: bump @playwright/test, then npx playwright install --with-deps so browser binaries match the package.

2. Choose journeys

E2E is expensive. Cover: sign-up/login, the primary revenue path (checkout, create project), one representative CRUD flow, and anything that broke in production before. Ten solid journeys beat two hundred brittle page-pokes.

3. Config baseline

// 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 ? '50%' : undefined,
  reporter: process.env.CI ? [['blob'], ['github']] : [['html', { open: 'never' }]],
  use: {
    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/user.json' },
      dependencies: ['setup'],
    },
  ],
  webServer: {
    command: 'npm run build && npm run start',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },
});

Add playwright/.auth/ to .gitignore. Add Firefox/WebKit projects only when the product supports them and the CI budget allows; run them nightly if too slow per-PR.

4. Auth state and fixtures

// e2e/auth.setup.ts
import { test as setup, expect } from '@playwright/test';

setup('authenticate', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill(process.env.E2E_USER!);
  await page.getByLabel('Password').fill(process.env.E2E_PASSWORD!);
  await page.getByRole('button', { name: 'Sign in' }).click();
  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
  await page.context().storageState({ path: 'playwright/.auth/user.json' });
});

If tests mutate account-level state, give each worker its own account (worker-scoped fixture keyed on test.info().parallelIndex) instead of sharing one user.

Prefer fixtures over page-object singletons; they compose and tear down automatically:

// e2e/fixtures.ts
import { test as base, expect } from '@playwright/test';

type Fixtures = { project: { id: string; name: string } };

export const test = base.extend<Fixtures>({
  project: async ({ request }, use) => {
    const res = await request.post('/api/projects', { data: { name: `e2e-${Date.now()}` } });
    expect(res.ok()).toBeTruthy();
    const project = await res.json();
    await use(project);
    await request.delete(`/api/projects/${project.id}`);
  },
});
export { expect };

Seed data through the API (request fixture) rather than clicking through setup UI.

5. Locators and assertions

Need	Use
Buttons, links, headings, checkboxes, rows	getByRole('button', { name: 'Save' })
Form fields	getByLabel('Email')
Static text	getByText('No results', { exact: true })
Elements with no accessible role/name	getByTestId('chart-canvas') (set testIdAttribute if not data-testid)
Scope within a region	page.getByRole('dialog').getByRole('button', { name: 'Confirm' })
Pick a row	page.getByRole('row').filter({ hasText: 'Invoice 42' })

import { test, expect } from './fixtures';

test('renames a project', { tag: '@smoke' }, async ({ page, project }) => {
  await page.goto(`/projects/${project.id}/settings`);
  await page.getByLabel('Project name').fill('Renamed');
  await page.getByRole('button', { name: 'Save' }).click();
  await expect(page.getByRole('status')).toHaveText('Saved');
  await expect(page).toHaveTitle(/Renamed/);
});

• Strict mode: a locator matching several elements throws on action. Narrow it; do not reach for .first() unless “first” is the actual requirement.
• Waiting for a backend call: const resp = page.waitForResponse('**/api/save'); before the click, then await resp.
• Values that settle eventually but are not on a locator: await expect.poll(() => getCount()).toBe(3).
• Mock third-party or slow endpoints: await page.route('**/api/recommendations', r => r.fulfill({ json: [] }));
• Time-dependent UI: use page.clock (await page.clock.install({ time: new Date('2026-01-01T09:00:00Z') })) instead of waiting for real time.

6. Run and debug

npx playwright test --ui                         # interactive watch + time travel
npx playwright test e2e/projects.spec.ts --headed --project=chromium
npx playwright test --debug -g "renames a project"
npx playwright test --repeat-each=20 --workers=4 -g "renames"   # flake check
npx playwright test --last-failed
npx playwright codegen http://localhost:3000     # locator discovery, not final code
npx playwright show-trace test-results/**/trace.zip
npx playwright show-report

Debug from the trace before changing code: check the action log, the DOM snapshot at the failing step, the network tab, and console errors. Most “flaky” failures are a missing wait for a network response or a locator that matched a stale element.

7. CI

Shard across machines with the blob reporter and merge afterwards. A full GitHub Actions workflow with sharding, caching, and report merging is in references/ci-sharding.md; read it when setting up or fixing CI.

npx playwright test --shard=2/4
npx playwright merge-reports --reporter html ./all-blob-reports

Gotchas

• retries hides flakes. Treat any test marked “flaky” in the report as a bug; see flaky-test-triage.
• reuseExistingServer: true in CI tests whatever is on the port, possibly a stale build.
• storageState expires when the session does. If tests start failing at login mid-run, shorten the run or refresh the state in setup.
• page.goto waits for load by default; SPAs may still be fetching. Assert on visible content, not on navigation completion.
• Hover menus and animations: click() auto-waits for actionability, but CSS transitions can still move targets. Disable animations in test env if they cause flakes.
• Do not share a page across tests via beforeAll; it breaks isolation and parallelism.
• Version drift: the Docker image tag (mcr.microsoft.com/playwright:v1.xx.x-noble) must match the installed @playwright/test version.

Output

When delivering E2E work, report:

**Journeys covered:** login, checkout with saved card, project rename
**Files:** e2e/auth.setup.ts, e2e/fixtures.ts, e2e/checkout.spec.ts
**Stability:** `--repeat-each=20 --workers=4` → 60/60 passed
**CI:** 4 shards, blob reports merged, traces uploaded on failure
**Not covered by E2E (pushed down):** coupon validation rules → unit tests