playwright-ts-template / rules

---
description: Playwright E2E testing rules for playwright-ts-template; the full skill lives in .agents/skills/playwright-e2e
globs: **/*.spec.ts,**/*.page.ts,**/fixtures/**,**/helpers/**
alwaysApply: false
---

# Playwright E2E Rules

Full guidance: read `.agents/skills/playwright-e2e/SKILL.md` and follow its decision tree before planning, generating, reviewing or debugging tests.

## MUST
- Use web-first assertions (`await expect(locator).toBeVisible()`)
- Use named timeout constants, not hardcoded numbers
- Wrap page object methods in `test.step()`
- Keep locators as readonly class properties on page objects
- Use short inner timeouts inside `toPass` blocks
- Tag tests with `{ tag: ['@smoke'] }` options, not in the title

## WON'T
- Use XPath selectors
- Use `page.waitForTimeout()` for synchronization
- Use `{ force: true }` on actions
- Use `networkidle` in `goto()` or `waitForLoadState()`
- Use deprecated APIs (`waitForNavigation`, `page.$`, `locator.type()`)
- Write custom retry/polling loops (use `toPass()` or `expect.poll()`)

## Selector Priority
1. `getByRole()` > 2. `getByLabel()` > 3. `getByText()` > 4. `getByTestId()` > 5. CSS selector

## Browser automation
Use the official `playwright-cli` skill (install with `npx playwright cli install --skills=agents`); debug failing tests with `npx playwright test --debug=cli` and `playwright-cli attach` as described in `.agents/skills/playwright-e2e/references/agent-debugging.md`.