--- name: testar-interface-agent-browser description: > 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 ). scope: 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 `) 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 `** (onde `` é o `modulo-id` canônico de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=`. - 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 `--headed` na abertura: ```bash agent-browser --session "$MODULO" open --headed ``` - Ou exportar no ambiente: ```bash 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 ```bash # 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: ```bash # 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: ```bash agent-browser --session "$MODULO" snapshot -i ``` *Saída de exemplo:* ```text - 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.): ```bash # 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: ```bash # 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: ```bash # 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: ```bash # 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: ```bash agent-browser --session "$MODULO" close ``` --- ## Tabela Rápida de Comandos | Ação | Comando | |---|---| | **Abrir tela (visível)** | `agent-browser --session open --headed ` | | **Snapshot de elementos** | `agent-browser --session snapshot -i` | | **Clicar elemento** | `agent-browser --session click @ref` | | **Preencher campo** | `agent-browser --session fill @ref "valor"` | | **Selecionar dropdown** | `agent-browser --session select @ref "opcao"` | | **Pressionar tecla** | `agent-browser --session press Enter` | | **Obter texto** | `agent-browser --session get text @ref` | | **Aguardar tempo** | `agent-browser --session wait ` | | **Aguardar seletor** | `agent-browser --session wait --selector ""` | | **Inspecionar console** | `agent-browser --session console` | | **Inspecionar rede** | `agent-browser --session network` | | **Screenshot** | `agent-browser --session screenshot ` | | **Auditoria a11y (WCAG)** | `agent-browser --session a11y` | | **Fechar sessão** | `agent-browser --session 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`: ```bash # 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: ```bash # 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: ```bash # 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) 1. **Campos Vuetify (`v-text-field`, `v-select`)**: O `snapshot -i` mapeia diretamente o `textbox` e o `combobox`. Utilize `agent-browser --session "$MODULO" fill @ref` ou `click @ref`. 2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser --session "$MODULO" wait 500 && agent-browser --session "$MODULO" snapshot -i` para interagir com o conteúdo do diálogo. 3. **Reporte de Teste**: Apresente ao operador o roteiro executado, evidências de screenshot e verificação de logs do console.