Testes de Aplicações Web

Para testar aplicações web locais, escreva scripts nativos em Python com Playwright.

Scripts Auxiliares Disponíveis:

• scripts/with_server.py - Gerencia o ciclo de vida do servidor (suporta múltiplos servidores)

Sempre execute os scripts com --help primeiro para ver o uso. NÃO leia o código fonte antes de tentar executar o script primeiro e descobrir que uma solução personalizada é absolutamente necessária. Esses scripts podem ser muito grandes e, portanto, poluir sua janela de contexto. Eles existem para serem chamados diretamente como scripts de caixa preta, em vez de serem ingeridos em sua janela de contexto.

Árvore de Decisão: Escolhendo Sua Abordagem

User task → Is it static HTML?
    ├─ Yes → Read HTML file directly to identify selectors
    │         ├─ Success → Write Playwright script using selectors
    │         └─ Fails/Incomplete → Treat as dynamic (below)
    │
    └─ No (dynamic webapp) → Is the server already running?
        ├─ No → Run: python scripts/with_server.py --help
        │        Then use the helper + write simplified Playwright script
        │
        └─ Yes → Reconnaissance-then-action:
            1. Navigate and wait for networkidle
            2. Take screenshot or inspect DOM
            3. Identify selectors from rendered state
            4. Execute actions with discovered selectors

Exemplo: Usando with_server.py

Para iniciar um servidor, execute --help primeiro e depois use o auxiliar:

Servidor único:

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

Múltiplos 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 automação, inclua apenas a lógica do Playwright (servidores são gerenciados automaticamente):

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode
    page = browser.new_page()
    page.goto('http://localhost:5173') # Server already running and ready
    page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute
    # ... your automation logic
    browser.close()

Padrão Reconhecimento-Então-Ação

1. Inspecione o DOM renderizado:

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

2. Identifique seletores a partir dos resultados da inspeção

3. Execute ações usando os seletores descobertos

Armadilha Comum

❌ Não inspecione o DOM antes de esperar por networkidle em aplicações dinâmicas ✅ Faça espere por page.wait_for_load_state('networkidle') antes da inspeção

Melhores Práticas

• Use scripts empacotados como caixas pretas - Para realizar uma tarefa, considere se um dos scripts disponíveis em scripts/ pode ajudar. Esses scripts lidam com fluxos de trabalho comuns e complexos de forma confiável, sem poluir a janela de contexto. Use --help para ver o uso e, em seguida, invoque diretamente.
• Use sync_playwright() para scripts síncronos
• Sempre feche o navegador quando terminar
• Use seletores descritivos: text=, role=, seletores CSS ou IDs
• Adicione esperas apropriadas: page.wait_for_selector() ou page.wait_for_timeout()

Arquivos de Referência

• examples/ - Exemplos mostrando padrões comuns:
  • element_discovery.py - Descobrindo botões, links e campos de entrada em uma página
  • static_html_automation.py - Usando URLs file:// para HTML local
  • console_logging.py - Capturando logs do console durante a automação

Quando Usar

Esta habilidade é aplicável para executar o fluxo de trabalho ou as ações descritas na visão geral.

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação específica do ambiente, testes ou revisão de especialistas.
• Pare e peça esclarecimentos se os inputs necessários, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.