Test Playwright

Use this skill when working with Playwright tests.

Requires

• test-automation-guidelines

See Also

• test-accessibility — apply when the suite should include automated a11y scanning (@axe-core/playwright) or when reviewing/writing accessible selector strategy.

Playwright Rules

Async Model

• Use async/await consistently

Selectors

Prefer stable, intentional selectors (attributes or accessibility hooks) as your primary choice. Text-based selectors are brittle — they can break with copy changes, translations, or small wording edits — so treat them as a fallback only when no stable attributes exist.

Primary (preferred):

page.getByTestId("...");
page.getByRole("button", { name: "Submit" });

Fallback (use only if no stable attributes are available):

page.getByText("Submit");

Waiting

Do not use:

await page.waitForTimeout(1000);

Use:

• locator auto-waiting
• expect(...)

Assertions

await expect(page.getByTestId("...")).toBeVisible();

Authentication

• Use storageState
• Avoid UI login per test

test.use({ storageState: "storageState.json" });

Network Control

await page.route('/api/...', route => route.fulfill(...));

Mocking

await page.route("/api/products", (route) =>
  route.fulfill({ path: "fixtures/products.json" }),
);

Visual Testing

• Use expect(page).toHaveScreenshot() for UI regression testing

Debugging

• Use traces and video recordings in CI for easy triage

Parallelism

• Tests must be parallel-safe
• Avoid shared state across tests

Anti-Patterns

• waitForTimeout usage
• Global shared state
• Overuse of page.evaluate