Luiz Silva 1a8adfc2dc feat(testes): padronizar uso de --session <modulo>_<contexto?> no agent-browser para isolamento de tokens

2026-10-08 14:47:46 -03:00

9.7 KiB

Raw Blame History

name	description	scope
testar-interface-agent-browser	Executar testes automatizados de interface (E2E), navegação e validação visual no frontend utilizando a CLI agent-browser, com janela sempre visível (--headed) e isolamento mandatório de sessão por módulo e contexto (--session <modulo>_<contexto?>) para evitar mistura de tokens e cookies entre acessos.	global

Skill: Testar Interface com agent-browser

Objetivo

Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuário, preencher formulários, inspecionar componentes gráficos e validar fluxos no frontend de maneira rápida, determinística e econômica em tokens, garantindo isolamento total entre processos e visualização em tempo real pelo operador humano.

🔒 Princípio de Isolamento de Sessão por Módulo e Contexto (`--session <modulo>_<contexto?>`)

O daemon do agent-browser utiliza sockets Unix independentes por sessão (/run/user/1000/agent-browser/<sessao>.sock). Em sistemas que possuem diferentes perfis de acesso, separar o contexto na flag de sessão é indispensável para prevenir mistura de tokens JWT, cookies de autenticação e dados de LocalStorage:

Todo comando DEVE ser acompanhado da flag --session <modulo>_<contexto?> (onde <modulo> é o modulo-id canônico de memorias-ia/modulo.yml e <contexto> é o perfil sob teste), ou garantir no ambiente export AGENT_BROWSER_SESSION=<modulo>_<contexto>.
Contextos Padronizados:
- interno: Acesso de analistas, fiscais, operadores internos ou administradores.
- externo: Acesso de requerentes externos, cidadãos cadastrados ou contribuintes logados.
- anonimo: Acesso público / não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). Garante sessão limpa sem resíduo de autenticações anteriores.
- cliente: Acesso de clientes ou empresas em plataformas multi-tenant ou B2B.
- Aplicações de contexto único sem múltiplos acessos podem utilizar apenas <modulo> ou <modulo>_default.
Sub-isolamento Concorrente: Caso múltiplos fluxos concorrentes rodem no mesmo contexto: --session "${MODULO}_${CONTEXTO}-${slug_ou_pid}".

⚠️ Princípio Fundamental: Navegador Sempre Visível ao Operador

Todo teste de interface executado pela IA DEVE ABRIR A JANELA VISÍVEL na área de trabalho do operador:

Usar sempre a flag --headed na abertura:

agent-browser --session "${MODULO}_${CONTEXTO}" open --headed <url>

Ou exportar no ambiente:
```
export AGENT_BROWSER_HEADED=true
```
Nunca executar em modo headless silencioso, a menos que o operador humano solicite expressamente essa exceção.

Pré-requisitos e Instalação

# Verificar se o agent-browser já está instalado
which agent-browser || bun i -g agent-browser

# Baixar o binário do Chromium gerenciado pelo daemon (na primeira vez)
agent-browser install

Documentação oficial: https://agent-browser.dev/

Fluxo Operacional Passo a Passo

1. Iniciar Sessão Visível e Isolada por Módulo e Contexto

Abra a aplicação frontend mantendo a janela visível e isolada:

# Obter 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}"

agent-browser --session "$SESSAO" open --headed http://localhost:8080

2. Obter Snapshot Interativo

Gere a árvore de acessibilidade enxuta com referências numéricas:

agent-browser --session "$SESSAO" snapshot -i

Saída de exemplo:

- heading "Qualificação de Fornecedores" [ref=e1]
- textbox "CNPJ" [ref=e2]
- textbox "Razão Social" [ref=e3]
- button "Pesquisar" [ref=e4]

3. Interagir com Determinismo

Utilize as referências identificadas (@e1, @e2, etc.):

# Preenchimento de campos de texto
agent-browser --session "$SESSAO" fill @e2 "12.345.678/0001-90"
agent-browser --session "$SESSAO" fill @e3 "Indústria Modelo LTDA"

# Acionamento de botões e links
agent-browser --session "$SESSAO" click @e4

4. Aguardar Transição e Validar Estado

Se a ação disparar chamada assíncrona ou animação, aguarde a estabilização:

# Aguardar 1 a 2 segundos
agent-browser --session "$SESSAO" wait 1500

# Capturar novo snapshot para verificar se a lista ou mensagem apareceu
agent-browser --session "$SESSAO" snapshot -i

5. Verificar Logs de Erro no Console e Rede

Assegure que nenhum erro de script ou requisição 500 ocorreu silenciosamente:

# Inspecionar mensagens do console do browser
agent-browser --session "$SESSAO" console

# Verificar requisições de rede falhadas
agent-browser --session "$SESSAO" network

6. Registrar Evidência Visual

Capture um screenshot para comprovação do resultado do teste:

# Screenshot padrão ou anotado com identificadores visuais
agent-browser --session "$SESSAO" screenshot evidencias/resultado-sucesso.png
# agent-browser --session "$SESSAO" screenshot --annotate evidencias/resultado-anotado.png

7. Encerrar Navegador

Finalize a sessão isolada limpando apenas os processos do seu contexto e módulo:

agent-browser --session "$SESSAO" close

Tabela Rápida de Comandos

Ação	Comando
Abrir tela (visível)	`agent-browser --session <modulo>_<contexto> open --headed <url>`
Snapshot de elementos	`agent-browser --session <modulo>_<contexto> snapshot -i`
Clicar elemento	`agent-browser --session <modulo>_<contexto> click @ref`
Preencher campo	`agent-browser --session <modulo>_<contexto> fill @ref "valor"`
Selecionar dropdown	`agent-browser --session <modulo>_<contexto> select @ref "opcao"`
Pressionar tecla	`agent-browser --session <modulo>_<contexto> press Enter`
Obter texto	`agent-browser --session <modulo>_<contexto> get text @ref`
Aguardar tempo	`agent-browser --session <modulo>_<contexto> wait <ms>`
Aguardar seletor	`agent-browser --session <modulo>_<contexto> wait --selector "<seletor>"`
Inspecionar console	`agent-browser --session <modulo>_<contexto> console`
Inspecionar rede	`agent-browser --session <modulo>_<contexto> network`
Screenshot	`agent-browser --session <modulo>_<contexto> screenshot <arquivo.png>`
Auditoria a11y (WCAG)	`agent-browser --session <modulo>_<contexto> a11y`
Fechar sessão	`agent-browser --session <modulo>_<contexto> close`

🔑 Autenticação e Credenciais Canônicas por Contexto (`modulo-acesso`)

Sempre que a aplicação exigir login, o agente DEVE consultar memorias-ia/modulo.yml para obter as credenciais canônicas configuradas em modulo-acesso para o contexto correspondente:

# Identificar módulo e contexto
MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
CONTEXTO="interno" # interno | externo | cliente | anonimo
SESSAO="${MODULO}_${CONTEXTO}"

if [ "$CONTEXTO" = "anonimo" ]; then
  # Contexto anônimo: navegação pública limpa sem autenticação
  echo "Iniciando sessão pública limpa: $SESSAO"
  agent-browser --session "$SESSAO" open --headed http://localhost:8080/consulta-publica
else
  # Contexto autenticado: obter credenciais do perfil ou usar fallback direto
  USUARIO=$(grep -A6 "modulo-acesso:" memorias-ia/modulo.yml | grep -A2 "${CONTEXTO}:" | grep "usuario:" | awk '{print $2}' || true)
  SENHA=$(grep -A6 "modulo-acesso:" memorias-ia/modulo.yml | grep -A2 "${CONTEXTO}:" | grep "senha:" | awk '{print $2}' || true)

  if [ -z "$USUARIO" ]; then
    USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')
    SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
  fi

  # Preenchimento determinístico no formulário de login na sessão isolada
  agent-browser --session "$SESSAO" open --headed http://localhost:8080/login
  agent-browser --session "$SESSAO" wait 1000
  agent-browser --session "$SESSAO" snapshot -i
  agent-browser --session "$SESSAO" fill @e1 "$USUARIO"
  agent-browser --session "$SESSAO" fill @e2 "$SENHA"
  agent-browser --session "$SESSAO" click @e3
fi

⚠️ Atenção: Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste.

Sessões Persistentes e Autenticação

Para fluxos que necessitam manter login ativo entre comandos com isolamento:

# Iniciar sessão nomeada com auto-restore no escopo do módulo e contexto
agent-browser --session "$SESSAO" --restore open --headed http://localhost:8080/login

# Verificar status da sessão isolada
agent-browser --session "$SESSAO" session info --json

Skills Nativas do agent-browser

O binário agent-browser possui guias aprofundados integrados que podem ser consultados a qualquer momento:

# Guia completo do core (todas as opções e referências)
agent-browser skills get core --full

# Guia para testes exploratórios e caça a bugs (dogfooding)
agent-browser skills get dogfood

Boas Práticas no Ecossistema Azteca (Vue 3 / Vuetify)

Campos Vuetify (v-text-field, v-select): O snapshot -i mapeia diretamente o textbox e o combobox. Utilize agent-browser --session "$SESSAO" fill @ref ou click @ref.
Modais e Diálogos: Após clicar no botão que abre o modal (v-dialog), execute agent-browser --session "$SESSAO" wait 500 && agent-browser --session "$SESSAO" snapshot -i para interagir com o conteúdo do diálogo.
Reporte de Teste: Apresente ao operador o roteiro executado, evidências de screenshot e verificação de logs do console.

9.7 KiB Raw Blame History