5.9 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). | 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 que o operador humano sempre acompanhe a execução na tela.
⚠️ 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 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
Abra a aplicação frontend mantendo a janela visível ao operador:
agent-browser open --headed http://localhost:8080
2. Obter Snapshot Interativo
Gere a árvore de acessibilidade enxuta com referências numéricas:
agent-browser 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 fill @e2 "12.345.678/0001-90"
agent-browser fill @e3 "Indústria Modelo LTDA"
# Acionamento de botões e links
agent-browser 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 wait 1500
# Capturar novo snapshot para verificar se a lista ou mensagem apareceu
agent-browser 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 console
# Verificar requisições de rede falhadas
agent-browser 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 screenshot evidencias/resultado-sucesso.png
# agent-browser screenshot --annotate evidencias/resultado-anotado.png
7. Encerrar Navegador
Finalize a sessão limpando os processos do daemon:
agent-browser close
Tabela Rápida de Comandos
| Ação | Comando |
|---|---|
| Abrir tela (visível) | agent-browser open --headed <url> |
| Snapshot de elementos | agent-browser snapshot -i |
| Clicar elemento | agent-browser click @ref |
| Preencher campo | agent-browser fill @ref "valor" |
| Selecionar dropdown | agent-browser select @ref "opcao" |
| Pressionar tecla | agent-browser press Enter |
| Obter texto | agent-browser get text @ref |
| Aguardar tempo | agent-browser wait <ms> |
| Aguardar seletor | agent-browser wait --selector "<seletor>" |
| Inspecionar console | agent-browser console |
| Inspecionar rede | agent-browser network |
| Screenshot | agent-browser screenshot <arquivo.png> |
| Auditoria a11y (WCAG) | agent-browser a11y |
| Fechar sessão | agent-browser 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 credenciais canônicas de teste de memorias-ia/modulo.yml
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
agent-browser fill @e1 "$USUARIO"
agent-browser fill @e2 "$SENHA"
agent-browser 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:
# Iniciar sessão nomeada com auto-restore
agent-browser --session auth-test --restore open --headed http://localhost:8080/login
# Verificar status da sessão
agent-browser 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 fill @refouagent-browser click @ref. - Modais e Diálogos: Após clicar no botão que abre o modal (
v-dialog), executeagent-browser wait 500 && agent-browser 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.