author

e2e:author — Playwright Spec Authoring Rules

You are about to write or modify a Playwright spec. These rules are non-negotiable unless the user explicitly overrides one — they encode lessons that took the Playwright community years to learn.

1. Locators

Priority order — use the first that works:

1. page.getByRole(role, { name }) — matches accessibility tree. Survives most refactors.
2. page.getByLabel(text) — for form fields with <label> association.
3. page.getByText(text, { exact }) — for prose, headings, links by visible text.
4. page.getByTestId(id) — only if the team uses data-testid and is committed to keeping them stable.
5. page.locator('css') — last resort. Comment why nothing above worked.

Never:

• XPath (unless wrapping a known-stable third-party widget)
• CSS class names that look like Tailwind/utility classes (.bg-blue-500) — they're transient
• Nth-child indexing into a list without anchoring on a sibling's text

Always:

• Chain locators when the element is inside a known parent: page.getByRole('navigation').getByRole('link', { name: 'Pricing' }). This survives a copy of the same locator appearing elsewhere on the page.
• Use { exact: true } on text matches when partial matches would be ambiguous.

2. Waits

Never write page.waitForTimeout(ms). It is always wrong. Replace with one of:

• await expect(locator).toBeVisible({ timeout }) — wait for the element to appear
• await expect(locator).toHaveText(value) — wait for the content to settle
• await page.waitForURL(predicate) — wait for navigation
• await page.waitForResponse(url) — wait for a specific API call

Auto-wait is built into expect() against locators — await expect(page.getByRole('button')).toBeEnabled() polls until true or times out. Use it.

The only exception: a documented animation that has no observable end state (no class change, no aria-hidden flip). In that case, comment WHY the timeout is unavoidable.

3. Structure

import { test, expect } from '@playwright/test';

test.describe('<feature or page>', () => {
  test.beforeEach(async ({ page }) => {
    // common setup (navigation, auth state already set via storageState)
  });

  test('<specific behavior>', async ({ page }) => {
    await test.step('<human-readable step>', async () => {
      // ...
    });

    await test.step('<next step>', async () => {
      // ...
    });
  });
});