claude-plugins/dev-tools/skills/webapp-testing/SKILL.md

name, description

name	description
webapp-testing	Testes e automacao de aplicacoes web locais com Playwright — verificacao de frontend, debug de UI, screenshots, logs de consola e gestao de ciclo de vida de servidores.

Web Application Testing

Testar aplicacoes web locais escrevendo scripts Python nativos com Playwright.

Complementaridade com /chrome: Esta skill foca-se em scripts Playwright headless para testes automatizados e CI/CD. Para automacao de browser com sessao activa (sites autenticados, GIF recording, debug visual interactivo), usar a skill /chrome que integra os MCPs chrome-devtools e claude-in-chrome.

Cenario	Skill
Testes automatizados headless	/webapp-testing (Playwright)
CI/CD pipeline testing	/webapp-testing (Playwright)
Debug visual com sessao activa	/chrome (MCP backends)
Performance traces (LCP/TBT/CLS)	/chrome (DevTools MCP)
Sites autenticados (Google, CRMs)	/chrome (Chrome extensao)
Scraping com interaccao DOM programatica	/webapp-testing (Playwright)

Scripts auxiliares disponiveis:

• scripts/with_server.py - Gestao de ciclo de vida de servidores (suporta multiplos servidores)

Executar sempre scripts com --help primeiro para ver utilizacao. NAO ler o codigo fonte ate tentar executar o script e confirmar que uma solucao personalizada e absolutamente necessaria. Estes scripts podem ser extensos e poluir a context window. Existem para ser invocados como black-box.

Arvore de decisao: Escolher abordagem

Tarefa -> E HTML estatico?
    |-- Sim -> Ler ficheiro HTML directamente para identificar selectores
    |          |-- Sucesso -> Escrever script Playwright com selectores
    |          |-- Falha/Incompleto -> Tratar como dinamico (abaixo)
    |
    |-- Nao (webapp dinamica) -> Servidor ja esta a correr?
        |-- Nao -> Executar: python scripts/with_server.py --help
        |           Depois usar helper + escrever script Playwright simplificado
        |
        |-- Sim -> Reconhecimento-depois-accao:
            1. Navegar e esperar por networkidle
            2. Tirar screenshot ou inspeccionar DOM
            3. Identificar selectores a partir do estado renderizado
            4. Executar accoes com selectores descobertos

Exemplo: Usar with_server.py

Iniciar um servidor: executar --help primeiro, depois usar o helper.

Servidor unico:

python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py

Multiplos servidores (ex: backend + frontend):

python scripts/with_server.py \
  --server "cd backend && python server.py" --port 3000 \
  --server "cd frontend && npm run dev" --port 5173 \
  -- python your_automation.py

Para criar um script de automacao, incluir apenas logica Playwright (servidores sao geridos automaticamente):

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True) # Sempre lancar chromium em modo headless
    page = browser.new_page()
    page.goto('http://localhost:5173') # Servidor ja a correr e pronto
    page.wait_for_load_state('networkidle') # CRITICO: Esperar JS executar
    # ... logica de automacao
    browser.close()

Padrao reconhecimento-depois-accao

1. Inspeccionar DOM renderizado:

   page.screenshot(path='/tmp/inspect.png', full_page=True)
   content = page.content()
   page.locator('button').all()
   

2. Identificar selectores a partir dos resultados da inspeccao

3. Executar accoes usando selectores descobertos

Erro comum

NAO inspeccionar o DOM antes de esperar por networkidle em apps dinamicas SIM esperar por page.wait_for_load_state('networkidle') antes de inspeccionar

Boas praticas

• Usar scripts bundled como black boxes - Para cumprir uma tarefa, considerar se um dos scripts em scripts/ pode ajudar. Estes scripts tratam workflows comuns e complexos de forma fiavel sem poluir a context window. Usar --help para ver utilizacao, depois invocar directamente.
• Usar sync_playwright() para scripts sincronos
• Fechar sempre o browser quando terminar
• Usar selectores descritivos: text=, role=, selectores CSS, ou IDs
• Adicionar waits apropriados: page.wait_for_selector() ou page.wait_for_timeout()
• Screenshots guardar em /tmp/ (nunca em directorio de projecto)
• Para testes de aplicacoes Descomplicar: verificar localhost:3000 (Next.js) ou localhost:5173 (Vite)

Ficheiros de referencia

• examples/ - Exemplos com padroes comuns:
  • element_discovery.py - Descobrir botoes, links e inputs numa pagina
  • static_html_automation.py - Usar URLs file:// para HTML local
  • console_logging.py - Capturar logs de consola durante automacao

Integracao Descomplicar

MCPs complementares

MCP	Uso com webapp-testing
chrome-devtools	Performance traces, network inspection, DOM/CSS debugging — usar via skill /chrome
claude-in-chrome	Testes em sites autenticados com sessao activa — usar via skill /chrome
lighthouse	Auditorias completas de performance, SEO, a11y — complementa testes Playwright
puppeteer	Alternativa headless para automacao simples sem Playwright

Workflow tipico Descomplicar

1. Desenvolvimento local: Playwright (esta skill) para testes funcionais headless
2. Debug visual: /chrome (DevTools MCP) para inspeccao DOM/CSS/network em tempo real
3. Performance: /chrome (DevTools MCP traces) + MCP lighthouse para auditorias
4. CI/CD: Scripts Playwright commitados no repositorio, executados em pipeline Gitea Actions

Executar no servidor dev (regra #48)

Para testes que requerem Node.js/Python:

# Via SSH MCP para o servidor dev
mcp__ssh-unified__ssh_execute server="dev" command="cd /root/Dev/projecto && python test_automation.py"

Instalacao Playwright (se necessario)

pip install playwright
playwright install chromium

No servidor dev, Playwright ja esta disponivel em /root/Dev.

---

Versao: 1.0.0 | Autor: Descomplicar®