playwright-e2e

Playwright E2E Testing

Write end-to-end tests that survive UI churn, stay fast, and catch real bugs.

Locators — prefer user-facing, avoid brittle selectors

• Prefer getByRole, getByLabel, getByPlaceholder, getByText — they mirror how a user finds things and survive styling refactors.
• Use getByTestId only when no accessible handle exists; keep data-testid stable and semantic (not numbered or auto-generated).
• Never select by CSS class names, generated IDs, or XPath tied to layout or component internals.

Page Object Model

• One class per page or major component, under tests/pages/.
• Expose intent-level methods (login(user), addToCart(sku), checkout()), not raw clicks. The spec reads as a user story; the Page Object carries the mechanics.
• Return the next Page Object from navigation methods so flows compose naturally:

  const dashboard = await loginPage.signInAs(user); // returns DashboardPage
  await dashboard.navigateToOrders();
  

• Keep assertions out of Page Objects — they belong in the spec or a dedicated expect helper. A Page Object that throws because an element isn't visible is leaking test logic.

Waiting — assertions, never sleeps

• Use Playwright's web-first, auto-retrying assertions: await expect(locator).toBeVisible(), .toHaveText(), .toHaveValue(), .toHaveURL().
• Never call page.waitForTimeout() — it hard-codes a delay that will be wrong under load or on slow CI, and it's a flakiness factory.
• For a specific condition without an assertion use locator.waitFor({ state: 'visible' }) or page.waitForResponse(/api\/orders/) with a meaningful condition.
• Increase timeout on a specific assertion for genuinely slow operations; do not increase the global default to mask problems.