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:
| Command | Risk | |---|---| | npx playwright test --update-snapshots | Overwrites all baseline screenshots | | rm -rf test-results/ | Deletes trace and scree