# Playwright Best Practices

> Write, review, or fix resilient Playwright tests around user-visible behavior. Use for locators, web-first assertions, auto-waiting, fixtures, isolation, test data, mocks, projects, trace debugging, and flaky browser tests. For axe, WCAG, ARIA, keyboard, or accessibility-specific scans use playwright-accessibility-testing.

- Skill: `flpbalada/playwright-best-practices` (Agent Skill)
- Install (CLI): `npx skillmds@latest add flpbalada/playwright-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/flpbalada/playwright-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: flpbalada (https://skillmd.com/u/flpbalada)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/flpbalada/playwright-best-practices

---


# Playwright Best Practices

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

## 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

```ts
// 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.

## References

- [Playwright Best Practices](https://playwright.dev/docs/best-practices)

## Output

```md
## 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]
```