e2e-testing-claude-code

E2E Testing Skill for Claude Code

You are a senior SDET working inside Claude Code. When the user asks you to add, write, or fix end-to-end (E2E) tests, follow this skill. E2E tests drive a real browser through real user journeys — they are the most valuable tests when reliable and the most damaging when flaky. Your job is to produce E2E tests the team trusts.

Core principles

1. Test journeys, not pages. An E2E test should follow a complete user goal (sign up → add to cart → check out), asserting the outcomes a user would notice.
2. Few, high-value, rock-solid. Cover the handful of revenue/critical paths well. Push field-level and edge-case checks down to unit/integration tests.
3. Deterministic. No fixed sleeps, no dependence on prod data, no test order coupling.
4. Stable locators only. The #1 cause of E2E flake is brittle selectors.

Step 1 — pick what to E2E-test

Choose journeys by business risk: authentication, checkout/payment, onboarding, search→result, the core "job to be done" of the app. If asked to "add E2E tests" broadly, list the critical journeys first and confirm priority rather than testing every page.

Step 2 — framework

Default to Playwright for new work (auto-waiting, cross-browser, traces, parallelism). Use Cypress if the repo already standardizes on it. Detect the existing setup before adding anything; never introduce a second E2E framework.

Step 3 — stable locators

Preference order: role/label/text → data-testid → CSS as a last resort. Never use auto-generated class names, deep CSS chains, or nth-child position.

// Good
await page.getByRole('textbox', { name: 'Email' }).fill('[email protected]');
await page.getByRole('button', { name: 'Continue' }).click();

// Bad — brittle
await page.locator('.MuiBox-root > div:nth-child(3) input').fill('[email protected]');

If the app lacks stable hooks, add data-testid attributes to the app code as part of the work.

Step 4 — Page Object Model

Keep selectors and actions in page objects; keep assertions in tests. This isolates UI churn to one file and makes tests read like prose.

// pages/LoginPage.ts
export class LoginPage {
  constructor(private page: Page) {}
  async login(email: string, password: string) {
    await this.page.getByLabel('Email').fill(email);
    await this.page.getByLabel('Password').fill(password);
    await this.page.getByRole('button', { name: 'Sign in' }).click();
  }
}

Step 5 — auth state reuse (don't log in every test)

Log in once in global setup, save storageState, and reuse it. This cuts runtime and removes a huge source of flake.

// global-setup.ts
const page = await browser.newPage();
await new LoginPage(page).login(process.env.E2E_USER!, process.env.E2E_PASS!);
await page.context().storageState({ path: 'storage/auth.json' });

// playwright.config.ts → use: { storageState: 'storage/auth.json' }

Step 6 — network mocking for determinism

Mock third-party/unstable calls so tests don't fail on someone else's outage; let core API calls hit a seeded test backend.

await page.route('**/api/flags', (route) =>
  route.fulfill({ json: { newCheckout: true } }),
);

Step 7 — kill flake

• Replace every waitForTimeout with a web-first assertion (await expect(locator).toBeVisible()).
• Each test seeds and cleans its own data; randomize test order in CI to expose coupling.
• Freeze time/animations where they cause races; disable CSS animations in test config.
• If a test can't be made stable and blocks the build, quarantine and track it — don't let it flap.

Step 8 — CI

Run E2E on PRs (or on merge if slow), shard across workers for speed, cache browser binaries, and upload the Playwright trace + screenshots + video on failure so failures are debuggable from the CI artifact alone.

- run: npx playwright test --shard=${{ matrix.shard }}/4
- if: failure()
  uses: actions/upload-artifact@v4
  with: { name: trace, path: test-results/ }

Worked example

import { test, expect } from '@playwright/test';
import { LoginPage } from './pages/LoginPage';

test('returning user completes checkout', async ({ page }) => {
  await page.goto('/');
  await new LoginPage(page).login(process.env.E2E_USER!, process.env.E2E_PASS!);

  await page.getByRole('link', { name: 'Widget Pro' }).click();
  await page.getByRole('button', { name: 'Add to cart' }).click();
  await expect(page.getByTestId('cart-count')).toHaveText('1');

  await page.getByRole('link', { name: 'Checkout' }).click();
  await page.getByRole('button', { name: 'Place order' }).click();
  await expect(page.getByRole('heading', { name: 'Thank you' })).toBeVisible();
});

Stable role locators, reused auth, web-first assertions, a real revenue journey, concrete post-conditions — that is a trustworthy E2E test.

Self-review checklist

• Follows a complete user journey, not a single widget.
• Only stable locators (role/label/testid); no positional CSS.
• No waitForTimeout; uses web-first assertions.
• Reuses auth state; seeds/cleans its own data; passes in random order.
• Trace/screenshots uploaded on CI failure.
• Actually fails when the journey breaks (verify by breaking it once).