.agent/rules/testes-interface-agent-browser.md

type	name	description	scope	trigger	updatedAt
rule	testes-interface-agent-browser	Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed), com isolamento por sessão e contexto (--session <modulo>_<contexto?>) e salvando evidências obrigatoriamente na pasta .evidencias/.	global	always_on	2026-10-30

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.

Por padrão, invocações sem identificação de sessão utilizam a sessão "default", compartilhando o mesmo daemon e socket Unix. Para viabilizar testes concorrentes e evitar interferências mútuas entre múltiplos módulos ou workspaces, todo comando deve operar em sessão isolada identificada pelo módulo e pelo contexto de acesso.

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 --session <modulo>_<contexto?> open --headed <url>) ou garantir a variável de ambiente export AGENT_BROWSER_HEADED=true.
3. Isolamento Mandatório de Sessão e Contexto (--session <modulo>_<contexto?>):
   • Nunca utilizar a sessão padrão compartilhada sem identificar o módulo e o contexto de acesso.
   • Todo comando agent-browser DEVE OBRIGATORIAMENTE ser acompanhado da flag --session <modulo>_<contexto?> (onde <modulo> é o modulo-id canônico extraído de memorias-ia/modulo.yml e <contexto?> discrimina o papel ou natureza do acesso), ou garantir no ambiente export AGENT_BROWSER_SESSION=<modulo>_<contexto?>.
   • Prevenção de Mistura de Tokens: Caso a aplicação possua mais de um tipo de acesso (interno, externo, anonimo, cliente, etc.), o <contexto> DEVE SER OBRIGATORIAMENTE PREENCHIDO para evitar que cookies, tokens JWT e estados de login residuais contaminem outros fluxos de teste.
   • Cada sessão possui daemon e socket Unix dedicados (ex: /run/user/1000/agent-browser/<modulo>_<contexto>.sock), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos.
   • Caso um mesmo módulo e contexto necessite de sub-isolamento para testes paralelos, adota-se o discriminador determinístico: <modulo>_<contexto>_<slug-ou-pid>.
4. Utilizar o modelo de referências (@ref):
   • Mapear a tela via agent-browser --session <modulo>_<contexto?> snapshot -i, obtendo referências compactas como @e1, @e2.
   • Executar ações determinísticas referenciando os IDs gerados (click @e1, fill @e2 "texto").
5. Registrar evidências obrigatoriamente na pasta .evidencias/ e fechar sessão:
   • Todas as evidências geradas pelos testes automatizados (screenshots, capturas anotadas, PDFs, vídeos, traces, relatórios ou dumps de console/rede) DEVEM OBRIGATORIAMENTE ser salvas na pasta .evidencias/ na raiz do projeto (mkdir -p .evidencias).
   • Registrar comprovações visuais com agent-browser --session <modulo>_<contexto?> screenshot .evidencias/<arquivo.png>.
   • Garantir que .evidencias/ conste no .gitignore do projeto para evitar o versionamento acidental de binários de teste.
   • Encerrar graciosamente o navegador com agent-browser --session <modulo>_<contexto?> close ao término do fluxo.
6. Credenciais Canônicas por Contexto (modulo-acesso):
   • Sempre que o teste exigir autenticação, o agente DEVE OBRIGATORIAMENTE extrair as credenciais do contexto específico em modulo-acesso de memorias-ia/modulo.yml (ex: modulo-acesso.interno, modulo-acesso.cliente, etc.).
   • Para sessões anônimas (_anonimo), nenhum login deve ser realizado, garantindo a validação da experiência do usuário público sem tokens.
   • É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.

---

🔒 Contextos Canônicos de Sessão (<modulo>_<contexto>)

Contexto	Finalidade e Natureza	Exemplo de Sessão	Credenciais em modulo.yml
interno	Operador interno, suporte, técnico, atendente, administrador	--session <modulo>_interno	modulo-acesso.interno (ou modulo-acesso simples)
cliente	Cliente final, solicitante corporativo, empresa contratante	--session <modulo>_cliente	modulo-acesso.cliente
externo	Portal público autenticado, cidadão, requerente externo	--session <modulo>_externo	modulo-acesso.externo
anonimo	Usuário deslogado, consulta pública por código, login, landing	--session <modulo>_anonimo	Nenhuma (perfil limpo sem cookies/tokens)
<especifico>	Papel especializado de domínio (ex: fiscal, auditor)	--session <modulo>_<papel>	modulo-acesso.<papel>

---

Instalação e Configuração

O agent-browser é instalado globalmente via bun (ou npm) com download de binários do Chromium:

# 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 com isolamento de sessão e contexto:

1. Obter Identificador do Módulo e Abertura com Janela Visível

# Obter o modulo-id canônico de memorias-ia/modulo.yml
MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
CONTEXTO="interno" # ou "cliente", "externo", "anonimo"

# Abrir sempre visível ao operador na sessão isolada por módulo e contexto
agent-browser --session "${MODULO}_${CONTEXTO}" open --headed http://localhost:8080

2. Inspeção de Elementos Interativos

# Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2)
agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i

3. Interações por Referência Direta

# Interagir diretamente com os elementos identificados no snapshot
agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "usuario@exemplo.com"
agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "senhaSegura123"
agent-browser --session "${MODULO}_${CONTEXTO}" click @e3

4. Validação e Evidência

# Aguardar estabilização se houver transição assíncrona
agent-browser --session "${MODULO}_${CONTEXTO}" wait 1000

# Obter novo snapshot para verificar estado pós-ação
agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i

# Garantir pasta .evidencias e capturar evidência gráfica do teste
mkdir -p .evidencias
agent-browser --session "${MODULO}_${CONTEXTO}" screenshot .evidencias/teste-login-sucesso.png

# Verificar erros no console do navegador
agent-browser --session "${MODULO}_${CONTEXTO}" console

5. Finalização

# Fechar a sessão isolada do navegador ao concluir o fluxo daquele contexto
agent-browser --session "${MODULO}_${CONTEXTO}" close

---

Boas Práticas e Proibições

Proibido ❌

• Proibido executar sem a flag --session <modulo>_<contexto?> (ou sem AGENT_BROWSER_SESSION), evitando poluir a sessão default compartilhada.
• Proibido misturar acessos com perfis diferentes na mesma sessão genérica sem contexto (ex: logar como operador interno e depois testar fluxo de cliente ou anônimo na mesma sessão, causando mistura de tokens).
• Proibido abrir em modo headless silencioso sem flag --headed ou variável AGENT_BROWSER_HEADED=true.
• Proibido salvar evidências de testes automatizados fora da pasta .evidencias/ (como soltas na raiz do projeto, em /tmp/ ou em evidencias/ sem ponto inicial).
• 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 órfãs após a conclusão do trabalho (sempre executar agent-browser --session <modulo>_<contexto?> close).

Permitido e Recomendado ✅

• Manter sessões persistentes por contexto quando necessário via --session <modulo>_<contexto> --restore.
• Utilizar sub-isolamento determinístico (<modulo>_<contexto>_<slug-ou-pid>) caso múltiplos testes do mesmo contexto ocorram simultaneamente no mesmo host.
• Usar agent-browser --session <modulo>_<contexto> screenshot --annotate .evidencias/<slug>-anotado.png 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

• Isolamento de Tokens e Cookies: Evita vazamento de credenciais e estados de autenticação entre acessos de operador interno, cliente corporativo, cidadão e visitante anônimo.
• Isolamento e Concorrência: Múltiplos agentes ou testes E2E simultâneos não conflitam de abas nem fecham janelas alheias.
• 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
• Rule associada: rules/identidade-modulo.md
• Ferramentas CLI: .agent/TOOLS