ag-referencia-playwright

Skill: Playwright Patterns (Canonical 2026)

Referencia oficial para uso de Playwright em testes E2E, QAT, e automacao browser. Baseado em playwright.dev/docs/best-practices + observacoes de producao em raiz-platform, profdigital, jusraiz.

Quando ativar

• Spec QAT, E2E, smoke test
• Debug de fluxo browser (Playwright MCP)
• Configuracao de playwright.config.ts
• Refactor de teste flaky
• Setup de novo projeto com testes

Decisoes canonicas (sem ambiguidade)

1. Browser channel: SEMPRE Chromium isolado

// ✅ Default — sem channel
test('flow', async ({ page }) => { ... })

// ❌ NAO usar salvo regression policy/codecs/enterprise
test.use({ channel: 'chrome' })

Razoes oficiais (playwright.dev):

• Chromium fica a frente do Chrome estavel — pega regressoes antes
• Reproducibilidade: nao depende do que esta instalado no Mac
• Setup mais simples, sem licencas de codecs

2. Modo: headless default, headed para debug

// playwright.config.ts — default
use: { headless: true }

// CLI debug ad-hoc
npx playwright test --headed --debug

3. Isolation: 1 contexto por teste

// ✅ Default Playwright — cada test ganha context novo
test('a', async ({ page }) => { ... })  // context isolado
test('b', async ({ page }) => { ... })  // outro context

// ✅ Multi-user no mesmo teste
test('admin + user', async ({ browser }) => {
  const adminCtx = await browser.newContext()
  const userCtx = await browser.newContext()
  // ...
})

4. Persistent context: APENAS para QAT manual com login

// Usar SO em workflow exploratorio com login repetido
import { chromium } from 'playwright'

const ctx = await chromium.launchPersistentContext(
  '~/.cache/playwright-claude/<projeto>',
  { channel: 'chromium', headless: true }
)

NUNCA usar persistent context em CI — perde isolation.

Web-first assertions (eliminar flakiness)

❌ Anti-pattern: waitForTimeout

await page.click('button')
await page.waitForTimeout(2000)        // ❌ flaky, lento, nao-deterministico
const text = await page.textContent('.result')
expect(text).toBe('OK')