publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
.agent/global/rules/testes-interface-agent-browser.md

9.7 KiB
Raw Blame History

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) e com isolamento por sessão e contexto (--session <modulo>_<contexto?>) para evitar mistura de tokens. global always_on 2026-10-08

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. Em aplicações que possuem múltiplos níveis de acesso (como áreas administrativas internas, portais de requerentes externos, consultas anônimas públicas e acessos de clientes corporativos), a ausência de isolamento por contexto gera mistura de tokens JWT, cookies de autenticação e dados de LocalStorage, provocando falsos positivos ou mascarando falhas de segurança.

Esta regra padroniza o uso da ferramenta CLI agent-browser com isolamento estrito por módulo e contexto de acesso (--session <modulo>_<contexto?>).

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 perfil 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> representa o perfil ou nível de acesso que está sendo testado), ou garantir no ambiente export AGENT_BROWSER_SESSION=<modulo>_<contexto>.
    • Contextos Padronizados de Acesso:
      • interno: Acesso restrito a servidores públicos, fiscais, analistas internos ou administradores.
      • externo: Acesso de requerentes externos, contribuintes ou cidadãos logados.
      • anonimo: Acesso público e não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). Obrigatório para assegurar ausência total de tokens ou cookies residuais de sessões anteriores.
      • cliente: Acesso de clientes ou empresas contratantes em plataformas multi-tenant ou B2B.
      • Aplicações de contexto único sem distinção de perfis podem utilizar apenas <modulo> ou <modulo>_default.
    • Prevenção de Mistura de Tokens e Cookies: Cada sessão do agent-browser possui daemon e socket Unix dedicados (ex: /run/user/1000/agent-browser/<modulo>_<contexto>.sock), mantendo cookie jar, cabeçalhos Authorization, LocalStorage e SessionStorage completamente estanques. Separar por <modulo>_<contexto> é estritamente obrigatório para que um teste anônimo não herde tokens de um teste interno, ou que credenciais de requerente externo não interfiram em fluxos administrativos.
    • Sub-isolamento Concorrente: Caso múltiplos testes concorrentes ocorram no mesmo módulo e contexto, adota-se o sufixo 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 e fechar sessão:
    • Registrar comprovações visuais com agent-browser --session <modulo>_<contexto> screenshot <arquivo.png>.
    • Encerrar graciosamente o navegador com agent-browser --session <modulo>_<contexto> close ao término do fluxo.
  6. Credenciais Canônicas de Teste por Contexto (modulo-acesso):
    • O agente DEVE OBRIGATORIAMENTE consultar modulo-acesso em memorias-ia/modulo.yml.
    • Se configurado com chaves específicas por contexto (interno, externo, cliente), extrair as credenciais do contexto sob teste.
    • Se configurado no formato plano direto (usuario e senha), utilizar como credencial padrão para o contexto principal/interno.
    • Para o contexto anonimo, o agente NÃO deve autenticar, validando a jornada como usuário não-logado na sessão isolada <modulo>_anonimo.
    • É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.

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, Definir Contexto 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}')

# Definir contexto sob teste: interno | externo | anonimo | cliente
CONTEXTO="interno" # ou externo, anonimo, cliente
SESSAO="${MODULO}_${CONTEXTO}"

# Abrir sempre visível ao operador humano na sessão isolada do módulo e contexto
agent-browser --session "$SESSAO" 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 "$SESSAO" snapshot -i

3. Interações por Referência Direta

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

4. Validação e Evidência

# Aguardar estabilização se houver transição assíncrona
agent-browser --session "$SESSAO" wait 1000

# Obter novo snapshot para verificar estado pós-ação
agent-browser --session "$SESSAO" snapshot -i

# Capturar evidência gráfica do teste
agent-browser --session "$SESSAO" screenshot evidencias/teste-login-sucesso.png

# Verificar erros no console do navegador
agent-browser --session "$SESSAO" console

5. Finalização

# Fechar a sessão isolada do navegador ao concluir o teste
agent-browser --session "$SESSAO" close

Boas Práticas e Proibições

Proibido ❌

  • Proibido executar sem a flag --session <modulo>_<contexto?> (ou sem AGENT_BROWSER_SESSION), evitando poluir sessões ou misturar tokens entre perfis.
  • Proibido abrir em modo headless silencioso sem flag --headed ou variável AGENT_BROWSER_HEADED=true.
  • Proibido testar fluxos anônimos em sessões já autenticadas, garantindo que testes públicos sempre rodem na sessão <modulo>_anonimo.
  • 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 <sessao> close).

Permitido e Recomendado ✅

  • Manter sessões persistentes 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 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: Previne contaminação entre sessões de administradores internos, cidadãos externos e consultas públicas anônimas.
  • Isolamento de Processos e Concorrência: Múltiplos agentes rodando testes E2E simultâneos não colidem abas nem encerram daemons de outros contextos.
  • 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