ComposioHQ/webapp-testing

Teste de Aplicações Web

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

Scripts auxiliares disponíveis:

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

Sempre execute scripts com --help primeiro para ver o uso. NÃO leia o código-fonte até que você tenha tentado executar o script primeiro e descoberto que uma solução personalizada é absolutamente necessária. Estes 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 na sua janela de contexto.

Árvore de Decisão: Escolhendo Sua Abordagem

Tarefa do usuário → É HTML estático?
    ├─ Sim → Ler arquivo HTML diretamente para identificar seletoras
    │         ├─ Sucesso → Escrever script Playwright usando seletoras
    │         └─ Falha/Incompleto → Tratar como dinâmico (abaixo)
    │
    └─ Não (webapp dinâmico) → O servidor já está em execução?
        ├─ Não → Executar: python scripts/with_server.py --help
        │        Em seguida, usar o helper + escrever script Playwright simplificado
        │
        └─ Sim → Padrão de reconhecimento-então-ação:
            1. Navegar e aguardar networkidle
            2. Capturar screenshot ou inspecionar DOM
            3. Identificar seletoras a partir do estado renderizado
            4. Executar ações com as seletoras descobertas

Exemplo: Usando with_server.py

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

Servidor único:

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

Múltiplos servidores (por exemplo, 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 Playwright (os servidores são gerenciados automaticamente):

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True) # Sempre iniciar chromium em modo headless
    page = browser.new_page()
    page.goto('http://localhost:5173') # Servidor já em execução e pronto
    page.wait_for_load_state('networkidle') # CRÍTICO: Aguardar execução do JS
    # ... sua lógica de automação
    browser.close()

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

1. Inspecionar o DOM renderizado:

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

2. Identificar seletoras a partir dos resultados da inspeção

3. Executar ações usando as seletoras descobertas

Armadilha Comum

❌ Não inspecione o DOM antes de aguardar networkidle em aplicativos dinâmicos ✅ Sim aguarde 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 complexos e comuns 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 seletoras descritivas: text=, role=, seletoras 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 inputs 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