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

---
name: webapp-testing
description: 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:**
```bash
python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py
```

**Multiplos servidores (ex: backend + frontend):**
```bash
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):
```python
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**:
   ```python
   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:
```bash
# 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)

```bash
pip install playwright
playwright install chromium
```

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

---
**Versao**: 1.0.0 | **Autor**: Descomplicar®