feat: incluir agent-browser com modo visivel (--headed) obrigatorio no .agent

2026-09-16 23:42:27 -03:00 · 2026-09-16 23:42:27 -03:00 · f7ba75d0c3
commit f7ba75d0c3
parent f107814aa7
9 changed files with 629 additions and 7 deletions
--- a/rules/testes-interface-agent-browser.md
+++ b/rules/testes-interface-agent-browser.md
@ -0,0 +1,133 @@
+---
+type: rule
+name: testes-interface-agent-browser
+description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) ao operador.
+scope: global
+trigger: always_on
+updatedAt: "2026-09-16"
+---
+
+# Regra: Testes Automatizados de Interface e Navegação com agent-browser
+
+## Contexto
+
+Quando uma IA precisa testar o frontend, validar jornadas de usuário, inspecionar componentes gráficos ou simular interações na tela, é crucial utilizar uma ferramenta rápida, determinística e econômica em tokens. Além disso, o operador humano deve sempre ter visibilidade do que a IA está executando em tempo real na interface gráfica.
+
+Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA.
+
+---
+
+## Regra
+
+Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar realizar testes automatizados de interface (E2E), navegar no frontend ou inspecionar telas ativas, **DEVE OBRIGATORIAMENTE**:
+
+1. **Utilizar o `agent-browser`** como ferramenta oficial de automação de navegador.
+2. **Executar SEMPRE em Modo Visível (`--headed`)**:
+   - A janela do navegador **deve sempre aparecer na área de trabalho do operador**.
+   - É **terminantemente proibido** rodar testes ocultos (headless silencioso), a menos que o operador humano solicite expressamente essa exceção.
+   - Usar a flag `--headed` nos comandos de abertura (`agent-browser open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
+3. **Utilizar o modelo de referências (`@ref`)**:
+   - Mapear a tela via `agent-browser snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
+   - Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
+4. **Registrar evidências e fechar sessão**:
+   - Registrar comprovações visuais com `agent-browser screenshot <arquivo.png>`.
+   - Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo.
+
+---
+
+## Instalação e Configuração
+
+O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium:
+
+```bash
+# Instalação global via bun (recomendado)
+bun i -g agent-browser
+
+# Download do motor do navegador (primeira execução)
+agent-browser install
+```
+
+Documentação de referência: **https://agent-browser.dev/**
+
+---
+
+## Protocolo Operacional Padrão
+
+Todo teste ou navegação de interface executado pela IA deve seguir o fluxo:
+
+### 1. Abertura com Janela Visível
+
+```bash
+# Abrir sempre visível ao operador humano
+agent-browser open --headed http://localhost:8080
+```
+
+### 2. Inspeção de Elementos Interativos
+
+```bash
+# Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2)
+agent-browser snapshot -i
+```
+
+### 3. Interações por Referência Direta
+
+```bash
+# Interagir diretamente com os elementos identificados no snapshot
+agent-browser fill @e1 "usuario@exemplo.com"
+agent-browser fill @e2 "senhaSegura123"
+agent-browser click @e3
+```
+
+### 4. Validação e Evidência
+
+```bash
+# Aguardar estabilização se houver transição assíncrona
+agent-browser wait 1000
+
+# Obter novo snapshot para verificar estado pós-ação
+agent-browser snapshot -i
+
+# Capturar evidência gráfica do teste
+agent-browser screenshot evidencias/teste-login-sucesso.png
+
+# Verificar erros no console do navegador
+agent-browser console
+```
+
+### 5. Finalização
+
+```bash
+# Fechar a sessão do navegador ao concluir o teste
+agent-browser close
+```
+
+---
+
+## Boas Práticas e Proibições
+
+### Proibido ❌
+- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`.
+- **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`).
+- **Proibido navegar para URLs desconhecidas** ou inventadas pela IA fora do escopo aprovado do teste.
+- **Proibido deixar processos ou janelas orfãs** após a conclusão do trabalho (sempre executar `agent-browser close`).
+
+### Permitido e Recomendado ✅
+- Manter sessões persistentes quando necessário via `--session <nome>` e `--restore`.
+- Usar `agent-browser screenshot --annotate` para inspecionar layouts complexos com visão computacional.
+- Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`.
+
+---
+
+## Impacto
+
+- **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real.
+- **Eficiência de tokens**: A árvore de acessibilidade reduz o consumo de contexto em até 90% comparado a inspeções de DOM HTML bruto.
+- **Confiabilidade**: Interações determinísticas por `@ref` eliminam fragilidade de seletores CSS dinâmicos.
+
+---
+
+## Referências
+
+- Documentação Oficial: https://agent-browser.dev/
+- Skill associada: `skills/testar-interface-agent-browser/SKILL.md`
+- Ferramentas CLI: `.agent/TOOLS`