Agent-Skills.md

Agent Skills: Playwright Best Practices

Provides Playwright test patterns for resilient locators, Page Object Models, fixtures, web-first assertions, and network mocking. Must use when writing or modifying Playwright tests (.spec.ts, .test.ts files with @playwright/test imports).

UncategorizedID: 0xbigboss/claude-code/playwright-best-practices

Repository

0xbigboss/claude-code
0xBigBossLicense: Apache-2.0
354

Install this agent skill to your local

pnpm dlx add-skill https://github.com/0xBigBoss/claude-code/tree/HEAD/.claude/skills/playwright-best-practices

Skill Files

Browse the full folder contents for playwright-best-practices.

Download Skill

Loading file tree…

.claude/skills/playwright-best-practices/SKILL.md

Skill Metadata

Name
playwright-best-practices
Description
Use when writing or modifying Playwright tests (.spec.ts, .test.ts with @playwright/test imports).

Playwright Best Practices

CLI Context: Prevent Context Overflow

When running Playwright tests from Claude Code or any CLI agent, always use minimal reporters to prevent verbose output from consuming the context window.

Use --reporter=line or --reporter=dot for CLI test runs. Configure playwright.config.ts to default to minimal reporters when CI or CLAUDE env vars are set — see playwright-patterns.md for the config snippet.

Locator Priority (Most to Least Resilient)

Always prefer user-facing attributes:

  1. page.getByRole('button', { name: 'Submit' }) — accessibility roles
  2. page.getByLabel('Email') — form control labels
  3. page.getByPlaceholder('Search...') — input placeholders
  4. page.getByText('Welcome') — visible text (non-interactive)
  5. page.getByAltText('Logo') — image alt text
  6. page.getByTitle('Settings') — title attributes
  7. page.getByTestId('submit-btn') — explicit test contracts
  8. CSS/XPath — last resort, avoid

Core Rules

  • Web-first assertions: always await expect(locator).toBeVisible(), never expect(await locator.isVisible()).toBe(true) — web-first matchers auto-wait and retry
  • Test isolation: each test creates its own data; never share state between tests
  • Auth state reuse: save authenticated state via setup project + storageState; never log in via UI in every test
  • Fixtures over beforeEach: fixtures encapsulate setup + teardown, run on-demand, and compose

Anti-Patterns

  • page.waitForTimeout(ms) — use auto-waiting locators instead
  • page.locator('.class') — use role/label/testid
  • XPath selectors — fragile, use user-facing attributes
  • Shared state between tests — each test creates own data
  • UI login in every test — use setup project + storageState
  • Manual assertions without await — use web-first assertions
  • Hardcoded waits — rely on Playwright's auto-waiting
  • Default reporter in CI/agent — use --reporter=line or --reporter=dot

Checklist

  • [ ] Locators use role/label/testid, not CSS classes or XPath
  • [ ] All assertions use await expect() web-first matchers
  • [ ] Page objects define locators in constructor
  • [ ] No page.waitForTimeout() — use auto-waiting
  • [ ] Tests isolated — no shared state
  • [ ] Auth state reused via setup project
  • [ ] Network mocks set up before navigation
  • [ ] Test data created per-test or via fixtures
  • [ ] Debug logging added for complex flows
  • [ ] Minimal reporter (line/dot) used in CI/agent contexts

See playwright-patterns.md for Page Object Model, fixtures, network mocking, and configuration examples.