testing-playwright-e2e

Playwright E2E Best Practices

Skill de testes end-to-end destilada do playwright-best-practices da Currents.dev. Usada por dev-qa e sites-qa (test design, gates de qualidade), dev-dev-delta e sites-dev-delta (hardening, caça a flakiness) e pelos implementers ao entregar testes junto com stories. Complementa dev-testing-strategy (pirâmide de testes) — esta skill cobre a camada E2E.

1. Locators (a fundação)

1.1 — Priority order: getByRole > getByLabel > getByPlaceholder > getByText > getByTestId > CSS/XPath (last resort).

// ❌ brittle — breaks on any DOM/style refactor
page.locator('.btn-primary > span')
page.locator('div:nth-child(3) button')

// ✅ resilient — tied to user-visible semantics
page.getByRole('button', { name: 'Submit order' })
page.getByLabel('Email address')
page.getByTestId('checkout-total') // when semantics don't identify it

1.2 — Locators are lazy and auto-retrying. Define once, reuse; never cache element handles (elementHandle is a legacy API).

1.3 — Filter and chain instead of complex selectors:

page.getByRole('listitem').filter({ hasText: 'Product A' }).getByRole('button', { name: 'Add' })

2. Assertions & Waiting (a causa nº 1 de flakiness)

2.1 — Use web-first assertions — they auto-wait and retry:

// ❌ reads state once, races the app
expect(await page.locator('.status').textContent()).toBe('Done')
// ✅ retries until timeout
await expect(page.getByTestId('status')).toHaveText('Done')

2.2 — NEVER page.waitForTimeout(). Hard sleeps are the top flakiness source and slow the suite. Wait for a condition instead:

// ❌ await page.waitForTimeout(3000)
// ✅
await expect(page.getByRole('alert')).toBeVisible()
await page.waitForURL('**/dashboard')
await page.waitForResponse(r => r.url().includes('/api/orders') && r.ok())

2.3 — Assert user-visible outcomes, not implementation (URL, visible text, enabled state — not internal store values).

2.4 — Signal-then-act: when a click triggers a request you need to await, register waitForResponse BEFORE the click: