Luiz Silva 2e6db7dda6 chore(agent): padronizar salvamento obrigatorio de evidencias de testes em .evidencias

2026-10-30 11:02:09 -03:00

10 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), isolamento mandatório de sessão e contexto (--session <modulo>_<contexto?>) e salvamento obrigatório das evidências na pasta .evidencias/.	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 de cookies, tokens e processos, com visualização em tempo real pelo operador humano.

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

O daemon do agent-browser aloca sockets Unix dedicados e armazena cookies HTTP, tokens JWT (em cabeçalhos, cookies ou localStorage/sessionStorage) e estados de autenticação independentes por sessão.

Para evitar contaminação cruzada de credenciais, interferência mútua entre módulos ou encerramento indevido de processos via agent-browser close:

Todo comando DEVE ser acompanhado da flag --session <modulo>_<contexto?> (onde <modulo> é o modulo-id canônico de memorias-ia/modulo.yml e <contexto?> identifica o papel ou perfil de acesso), ou garantir no ambiente export AGENT_BROWSER_SESSION=<modulo>_<contexto?>.
Prevenção Obrigatória 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. Exemplo: um teste logado como operador interno nunca deve compartilhar a mesma sessão de um teste de rota pública anonimo ou de acesso do cliente.
Sub-isolamento para concorrência: Caso múltiplos fluxos de teste concorrentes do mesmo papel rodem simultaneamente, utilizar sufixo discriminador determinístico: --session "${MODULO}_${CONTEXTO}_${SLUG_OU_PID}".

🧭 Contextos Canônicos de Sessão

Contexto	Finalidade e Escopo	Exemplo de Sessão	Fonte de Credenciais
`interno`	Operador interno, suporte, técnico, atendente, administrador	`--session <modulo>_interno`	`modulo-acesso.interno` (ou `modulo-acesso` simples)
`cliente`	Solicitante corporativo, empresa cliente, 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, login, landing page	`--session <modulo>_anonimo`	Nenhuma (perfil limpo sem cookies/tokens)
`<especifico>`	Papel especializado de domínio (ex: `fiscal`, `auditor`)	`--session <modulo>_<papel>`	`modulo-acesso.<papel>`

⚠️ 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 Contexto

Abra a aplicação frontend mantendo a janela visível e isolada pelo módulo e contexto desejado:

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

agent-browser --session "${MODULO}_${CONTEXTO}" open --headed http://localhost:8080

2. Obter Snapshot Interativo

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

agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i

Saída de exemplo:

- heading "Atendimento ao Cliente" [ref=e1]
- textbox "E-mail ou Usuário" [ref=e2]
- textbox "Senha" [ref=e3]
- button "Entrar" [ref=e4]

3. Interagir com Determinismo

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

# Preenchimento de credenciais ou campos de formulário
agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "operador@empresa.com"
agent-browser --session "${MODULO}_${CONTEXTO}" fill @e3 "senha123"

# Acionamento de botões e links
agent-browser --session "${MODULO}_${CONTEXTO}" 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 "${MODULO}_${CONTEXTO}" wait 1500

# Capturar novo snapshot para verificar se o painel ou mensagem apareceu
agent-browser --session "${MODULO}_${CONTEXTO}" 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 "${MODULO}_${CONTEXTO}" console

# Verificar requisições de rede falhadas
agent-browser --session "${MODULO}_${CONTEXTO}" network

6. Registrar Evidência Visual (Pasta Obrigatória `.evidencias/`)

Capture um screenshot na pasta .evidencias/ para comprovação do resultado do teste (é proibido salvar evidências fora de .evidencias/):

# Garantir a pasta .evidencias/ e capturar screenshot padrão ou anotado
mkdir -p .evidencias
agent-browser --session "${MODULO}_${CONTEXTO}" screenshot .evidencias/resultado-sucesso.png
# agent-browser --session "${MODULO}_${CONTEXTO}" screenshot --annotate .evidencias/resultado-anotado.png

7. Encerrar Navegador daquele Contexto

Finalize a sessão isolada limpando apenas os processos e tokens do contexto testado:

agent-browser --session "${MODULO}_${CONTEXTO}" 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 (em `.evidencias/`)	`agent-browser --session <modulo>_<contexto?> screenshot .evidencias/<arquivo.png>`
Auditoria a11y (WCAG)	`agent-browser --session <modulo>_<contexto?> a11y`
Fechar sessão	`agent-browser --session <modulo>_<contexto?> close`

🔑 Autenticação e Credenciais 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 específico:

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

# Extrair credenciais do contexto específico (compatível com multi-contexto ou formato simples)
USUARIO=$(grep -A3 "${CONTEXTO}:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')
[ -z "$USUARIO" ] && USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')

SENHA=$(grep -A3 "${CONTEXTO}:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
[ -z "$SENHA" ] && SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')

# Preenchimento determinístico no formulário de login na sessão isolada
agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "$USUARIO"
agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "$SENHA"
agent-browser --session "${MODULO}_${CONTEXTO}" click @e3

⚠️ Atenção: Nunca misture o fluxo anonimo na mesma sessão que executou login. Use sempre --session "${MODULO}_anonimo" para testes públicos e deslogados.

Sessões Persistentes e Autenticação

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

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

# Verificar status da sessão isolada
agent-browser --session "${MODULO}_${CONTEXTO}" 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 "${MODULO}_${CONTEXTO}" 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 "${MODULO}_${CONTEXTO}" wait 500 && agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i para interagir com o conteúdo do diálogo.
Reporte de Teste e Evidências em .evidencias/: Salve obrigatoriamente todas as evidências geradas na pasta .evidencias/ e apresente ao operador o roteiro executado, os links das evidências em .evidencias/ e a verificação de logs do console.

10 KiB Raw Blame History