Back to skills

skills/playwright-best-practices/SKILL.md

playwright-best-practices

Guides resilient Playwright test design and review. Use when writing, reviewing, or fixing Playwright tests for reliable user-focused coverage.

npx skills add https://github.com/flpbalada/fb-skills --skill playwright-best-practices
GitHub

Skill Docs

Write tests around user-visible behavior. Avoid implementation details.

When to Use

  • Writing Playwright tests
  • Reviewing test changes
  • Fixing flaky tests
  • Choosing locators, assertions, fixtures, or projects
  • Debugging browser test failures

Goal

Create deterministic tests that act like users and fail for useful reasons.

Rules

  • Prefer user-facing locators.
  • Use web-first assertions.
  • Trust Playwright auto-waiting.
  • Do not use fixed sleeps.
  • Keep tests isolated and order-independent.
  • Control test data and external services.
  • Mock third-party dependencies.
  • Add cross-browser projects only when risk justifies it.
  • Prefer clear duplication over clever abstraction.

Locator Order

  1. getByRole
  2. getByLabel
  3. getByPlaceholder
  4. getByText
  5. getByAltText
  6. getByTestId
  7. Scoped filter() chains

Avoid CSS classes, DOM position selectors, XPath, component names, and internal state.

Pattern

// Good
await page.getByRole('button', { name: 'Save for later' }).click()
await expect(page.getByRole('alert')).toHaveText('Saved')

// Bad
await page.locator('.buttonIcon').click()
await page.waitForTimeout(2000)
expect(await page.getByText('Saved').isVisible()).toBe(true)

Flow

  1. State user behavior under test.
  2. Create fresh state.
  3. Use user-facing locator.
  4. Perform user action.
  5. Assert visible result with await expect.
  6. Debug with trace, screenshot, video, or UI mode.
  7. Fix root cause.

Output

## Playwright Test Review

Behavior tested: [user behavior]
Locator quality: [good/issues]
Assertions: [web-first / issue]
Isolation: [fresh state / shared state issue]
Flake risk:
- [risk]

Fixes:
- [change]