When this skill is activated, always start your first response with the 🧢 emoji.

Playwright Testing

Playwright runs real Chromium, Firefox, and WebKit browsers from a single API with auto-waiting, network interception, and built-in assertions. This skill focuses on what Claude gets wrong by default: auth state management, flaky test diagnosis, CI optimization, and the subtle gotchas that burn hours. For basic "write a test" tasks, Claude already knows the API - this skill adds the battle-tested patterns that prevent production pain.

When to use this skill

Trigger this skill when the user:

• Debugs flaky Playwright tests or intermittent CI failures
• Sets up authentication (storageState, global setup, multi-role projects)
• Configures CI pipelines with sharding, caching, or Docker containers
• Implements visual regression / screenshot diffing
• Mocks API routes or intercepts network in complex scenarios (iframes, service workers)
• Writes test infrastructure: custom fixtures, page objects, shared utilities
• Sets up Playwright Component Testing (CT) for React/Vue/Svelte
• Migrates from Cypress, Puppeteer, or Selenium to Playwright

Do NOT trigger this skill for:

• Unit testing with Jest/Vitest when Playwright isn't involved
• Generic Puppeteer scripting unrelated to test automation

First-time project setup

On first activation, check if config.json exists in this skill's directory. If not, ask the user these questions and save the answers:

{
  "baseURL": "http://localhost:3000",
  "testDir": "./tests",
  "authStrategy": "storageState | none | per-test-login",
  "ciProvider": "github-actions | gitlab-ci | circle-ci | other",
  "browsers": ["chromium", "firefox", "webkit"],
  "screenshotBaseline": "linux | macos | docker"
}

Use these values to generate correct config snippets without asking the user to repeat themselves every session.

Gotchas - the stuff that actually burns you

This is the highest-value section. These are patterns Claude will get wrong without this skill.

1. storageState does NOT include sessionStorage

context.storageState() saves cookies and localStorage. It silently ignores sessionStorage. If your app stores auth tokens in sessionStorage (many SPAs do), the saved state file looks valid but tests fail with unauthenticated redirects. Fix: use page.evaluate() in global setup to also dump sessionStorage, then restore it via addInitScript in a custom fixture.

2. page.route() does NOT intercept iframe requests

page.route('**/api/*', handler) only intercepts requests from the top-level page. API calls from <iframe> elements are invisible to it. You need context.route() to intercept at the browser context level. This bites hard with embedded payment forms (Stripe Elements, PayPal) and third-party widgets.

3. Screenshot baselines are OS + browser + DPI specific

Snapshots generated on macOS will fail in Linux CI due to font rendering, sub-pixel antialiasing, and DPI differences. Always generate baselines in the same environment CI uses. Best practice: run --update-snapshots inside the same Docker container CI uses, commit the results.

4. fullyParallel + shared database = silent data corruption

With fullyParallel: true, tests within the same file run concurrently. If two tests create a user with the same email, one fails with a duplicate key error that looks like a test bug. Fix: generate unique test data per test (crypto.randomUUID() in email prefix) or use per-test database transactions that roll back.

5. Workers vs shards - they don't do the same thing

workers: 4 = 4 threads on one machine sharing memory/DB. --shard=1/4 = 4 separate machines. Setting workers: 1 does NOT prevent shard conflicts. If tests share global state (a single test user, a shared API key), they'll conflict across shards even with one worker per shard.

6. Hydration kills your click handlers

In SSR apps (Next.js, Nuxt), Playwright finds the server-rendered button and clicks it. But React hasn't hydrated yet - the click handler isn't attached. The click silently does nothing. Playwright's auto-wait checks visibility and stability, NOT hydration. Fix: add a data-hydrated attribute after hydration and wait for it, or use page.waitForFunction(() => document.querySelector('[data-hydrated]')).

7. page.clock requires explicit install

page.clock.install() must be called BEFORE navigating to the page. If you call it after page.goto(), timers already scheduled by the app aren't captured. The clock also doesn't affect Web Workers - timers in workers still use real time.

8. expect(locator).toHaveText() does substring matching by default

await expect(locator).toHaveText('Hello') passes if the element contains "Hello World". This is different from Jest's toBe. For exact match, use toHaveText('Hello', { exact: true }) or pass a regex: toHaveText(/^Hello$/). Claude's default is to write the non-exact form, which leads to false passes.

9. route.fulfill() with json option silently sets content-type

When using route.fulfill({ json: data }), Playwright automatically sets Content-Type: application/json. If you also pass contentType: manually, the manual value wins but the json is still stringified. If you pass body: as a string AND json:, the json option takes precedence. These precedence rules aren't obvious from the types.

10. Test isolation breaks when using browser.newPage() directly

If you create a page via browser.newPage() instead of using the page fixture, Playwright does NOT create an isolated BrowserContext. Your page shares cookies, localStorage, and cache with other pages from the same browser. Always use browser.newContext() first, then context.newPage().

Non-obvious patterns

Auth with multi-role project dependencies

// playwright.config.ts
export default defineConfig({
  projects: [
    {
      name: 'auth-setup',
      testMatch: /.*\.setup\.ts/,
    },
    {
      name: 'admin',
      dependencies: ['auth-setup'],
      use: { storageState: '.auth/admin.json' },
    },
    {
      name: 'member',
      dependencies: ['auth-setup'],
      use: { storageState: '.auth/member.json' },
    },
  ],
})

See references/auth-patterns.md for the full setup including token refresh and OAuth mocking.

Waiting for network + action atomically

// WRONG: race condition - response might arrive before waitForResponse registers
await page.getByRole('button', { name: 'Save' }).click()
const response = await page.waitForResponse('**/api/save')

// RIGHT: register the wait BEFORE the action triggers the request
const [response] = await Promise.all([
  page.waitForResponse('**/api/save'),
  page.getByRole('button', { name: 'Save' }).click(),
])
expect(response.status()).toBe(200)

Modifying a response without replacing it

await page.route('**/api/products', async (route) => {
  const response = await route.fetch()
  const json = await response.json()
  json.items = json.items.slice(0, 2) // trim to 2 items for test
  await route.fulfill({ response, json })
})

Disabling animations globally for stable tests

// playwright.config.ts
export default defineConfig({
  use: {
    // Tells the browser to prefer reduced motion
    contextOptions: { reducedMotion: 'reduce' },
  },
})

For apps that ignore prefers-reduced-motion, inject CSS:

// global-setup or fixture
await page.addStyleTag({
  content: '*, *::before, *::after { animation-duration: 0s !important; transition-duration: 0s !important; }',
})

/careful - destructive command guard

When the user invokes /careful, wrap the following commands with a confirmation prompt before executing: