JantonioFC/skillsbank

Playwright Pro

Kit de teste Playwright de nível profissional para agentes de codificação de IA.

Comandos Disponíveis

Quando instalado como um plugin do Claude Code, estes comandos estão disponíveis como /pw::

Comando	O que faz
/pw:init	Configura o Playwright — detecta o framework, gera configuração, CI, primeiro teste
/pw:generate <spec>	Gera testes a partir de história de usuário, URL ou componente
/pw:review	Revisa testes em busca de antipadrões e lacunas de cobertura
/pw:fix <test>	Diagnostica e corrige testes com falha ou instáveis
/pw:migrate	Migra do Cypress ou Selenium para Playwright
/pw:coverage	Analisa o que está testado vs. o que está faltando
/pw:testrail	Sincroniza com TestRail — lê casos, envia resultados
/pw:browserstack	Executa no BrowserStack, obtém relatórios entre navegadores
/pw:report	Gera relatório de teste no formato de sua preferência

Fluxo de Trabalho de Início Rápido

A sequência recomendada para a maioria dos projetos:

1. /pw:init          → configura o scaffold: config, pipeline CI e um primeiro teste smoke
2. /pw:generate      → gera testes a partir da sua especificação ou URL
3. /pw:review        → valida a qualidade e sinaliza antipadrões      ← sempre execute após generate
4. /pw:fix <test>    → diagnostica e corrige quaisquer testes com falha/instáveis  ← execute quando o CI ficar vermelho

Pontos de verificação de validação:

• Após /pw:generate — sempre execute /pw:review antes de submeter; ele detecta automaticamente antipadrões de localizadores e asserções ausentes.
• Após /pw:fix — execute novamente a suíte completa localmente (npx playwright test) para confirmar que a correção não introduz regressões.
• Após /pw:migrate — execute /pw:coverage para confirmar paridade com a suíte antiga antes de descomissionar os testes Cypress/Selenium.

Exemplo: Gerar → Revisar → Corrigir

# 1. Gera testes a partir de uma história de usuário
/pw:generate "Como usuário, quero fazer login com e-mail e senha"

# Gerado: tests/auth/login.spec.ts
# → O Playwright Pro cria o arquivo usando o template de autenticação.

# 2. Revisa os testes gerados
/pw:review tests/auth/login.spec.ts

# → Sinaliza: um teste usou page.locator('input[type=password]') — sugere getByLabel('Password')
# → Correção aplicada automaticamente.

# 3. Executa localmente para confirmar
npx playwright test tests/auth/login.spec.ts --headed

# 4. Se um teste estiver instável no CI, diagnostique-o
/pw:fix tests/auth/login.spec.ts
# → Identifica asserção web-first ausente; substitui waitForTimeout(2000) por expect(locator).toBeVisible()

Regras de Ouro

1. getByRole() em vez de CSS/XPath — resiliente a mudanças de marcação
2. Nunca use page.waitForTimeout() — use asserções web-first
3. expect(locator) tenta novamente automaticamente; expect(await locator.textContent()) não
4. Isole cada teste — nenhum estado compartilhado entre testes
5. baseURL na config — zero URLs hardcoded
6. Retries: 2 no CI, 0 localmente
7. Traces: 'on-first-retry' — depuração rica sem lentidão
8. Fixtures em vez de globais — test.extend() para estado compartilhado
9. Um comportamento por teste — múltiplas asserções relacionadas são aceitáveis
10. Mock apenas serviços externos — nunca faça mock do seu próprio aplicativo

Prioridade de Localizadores

1. getByRole()        — botões, links, cabeçalhos, elementos de formulário
2. getByLabel()       — campos de formulário com rótulos
3. getByText()        — texto não interativo
4. getByPlaceholder() — inputs com placeholder
5. getByTestId()      — quando nenhuma opção semântica existe
6. page.locator()     — CSS/XPath como último recurso

O que está Incluído

• 9 habilidades com instruções passo a passo detalhadas
• 3 agentes especializados: arquiteto-de-testes, depurador-de-testes, planejador-de-migração
• 55 modelos de teste: autenticação, CRUD, checkout, busca, formulários, dashboard, configurações, onboarding, notificações, API, acessibilidade
• 2 servidores MCP (TypeScript): integrações TestRail e BrowserStack
• Hooks inteligentes: validação automática de qualidade de teste, detecção automática de projetos Playwright
• 6 documentos de referência: regras de ouro, localizadores, asserções, fixtures, armadilhas, testes instáveis
• Guias de migração: tabelas de mapeamento Cypress e Selenium

Configuração de Integração

TestRail (Opcional)

export TESTRAIL_URL="https://sua-instancia.testrail.io"
export TESTRAIL_USER="[email protected]"
export TESTRAIL_API_KEY="sua-chave-api"

BrowserStack (Opcional)

export BROWSERSTACK_USERNAME="seu-usuario"
export BROWSERSTACK_ACCESS_KEY="sua-chave-de-acesso"

Referência Rápida

Consulte o diretório reference/ para:

• golden-rules.md — As 10 regras inegociáveis
• locators.md — Prioridade completa de localizadores com folha de consulta
• assertions.md — Referência de asserções web-first
• fixtures.md — Fixtures personalizadas e padrões de storageState
• common-pitfalls.md — Top 10 erros e correções
• flaky-tests.md — Comandos de diagnóstico e correções rápidas

Consulte templates/README.md para o índice completo de modelos.

Quando Usar

Use esta habilidade quando precisar de orientação ou automação para playwright-pro.