7.6 KiB
| 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 (--session <modulo>). | 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 (--session <modulo>)
O daemon do agent-browser utiliza sockets Unix independentes por sessão. Para evitar conflitos de comandos, interferência entre módulos diferentes ou encerramento indevido de processos via agent-browser close:
- Todo comando DEVE ser acompanhado da flag
--session <modulo>(onde<modulo>é omodulo-idcanônico dememorias-ia/modulo.yml), ou garantir no ambienteexport AGENT_BROWSER_SESSION=<modulo>. - Caso múltiplos fluxos de teste concorrentes rodem no mesmo módulo, utilizar sufixo discriminador determinístico:
--session "${MODULO}-subfluxo".
⚠️ 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
--headedna abertura:agent-browser --session "$MODULO" 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
Abra a aplicação frontend mantendo a janela visível e isolada por módulo:
# Obter modulo-id canônico
MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
agent-browser --session "$MODULO" open --headed http://localhost:8080
2. Obter Snapshot Interativo
Gere a árvore de acessibilidade enxuta com referências numéricas:
agent-browser --session "$MODULO" 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 "$MODULO" fill @e2 "12.345.678/0001-90"
agent-browser --session "$MODULO" fill @e3 "Indústria Modelo LTDA"
# Acionamento de botões e links
agent-browser --session "$MODULO" 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" wait 1500
# Capturar novo snapshot para verificar se a lista ou mensagem apareceu
agent-browser --session "$MODULO" 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" console
# Verificar requisições de rede falhadas
agent-browser --session "$MODULO" 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 "$MODULO" screenshot evidencias/resultado-sucesso.png
# agent-browser --session "$MODULO" screenshot --annotate evidencias/resultado-anotado.png
7. Encerrar Navegador
Finalize a sessão isolada limpando apenas os processos do seu módulo:
agent-browser --session "$MODULO" close
Tabela Rápida de Comandos
| Ação | Comando |
|---|---|
| Abrir tela (visível) | agent-browser --session <modulo> open --headed <url> |
| Snapshot de elementos | agent-browser --session <modulo> snapshot -i |
| Clicar elemento | agent-browser --session <modulo> click @ref |
| Preencher campo | agent-browser --session <modulo> fill @ref "valor" |
| Selecionar dropdown | agent-browser --session <modulo> select @ref "opcao" |
| Pressionar tecla | agent-browser --session <modulo> press Enter |
| Obter texto | agent-browser --session <modulo> get text @ref |
| Aguardar tempo | agent-browser --session <modulo> wait <ms> |
| Aguardar seletor | agent-browser --session <modulo> wait --selector "<seletor>" |
| Inspecionar console | agent-browser --session <modulo> console |
| Inspecionar rede | agent-browser --session <modulo> network |
| Screenshot | agent-browser --session <modulo> screenshot <arquivo.png> |
| Auditoria a11y (WCAG) | agent-browser --session <modulo> a11y |
| Fechar sessão | agent-browser --session <modulo> close |
🔑 Autenticação e Credenciais Canônicas (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:
# Extrair identificador e credenciais canônicas de teste de memorias-ia/modulo.yml
MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
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}')
# Preenchimento determinístico no formulário de login na sessão isolada
agent-browser --session "$MODULO" fill @e1 "$USUARIO"
agent-browser --session "$MODULO" fill @e2 "$SENHA"
agent-browser --session "$MODULO" click @e3
⚠️ 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
agent-browser --session "$MODULO" --restore open --headed http://localhost:8080/login
# Verificar status da sessão isolada
agent-browser --session "$MODULO" 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): Osnapshot -imapeia diretamente otextboxe ocombobox. Utilizeagent-browser --session "$MODULO" fill @refouclick @ref. - Modais e Diálogos: Após clicar no botão que abre o modal (
v-dialog), executeagent-browser --session "$MODULO" wait 500 && agent-browser --session "$MODULO" snapshot -ipara 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.