--- 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 e contexto (--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 de cookies, tokens e processos, com visualização em tempo real pelo operador humano. --- ## 🔒 Princípio de Isolamento de Sessão e Contexto (`--session _`) 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 _`** (onde `` é o `modulo-id` canônico de `memorias-ia/modulo.yml` e `` identifica o papel ou perfil de acesso), ou garantir no ambiente `export AGENT_BROWSER_SESSION=_`. - **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 `` **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 _interno` | `modulo-acesso.interno` (ou `modulo-acesso` simples) | | **`cliente`** | Solicitante corporativo, empresa cliente, contratante | `--session _cliente` | `modulo-acesso.cliente` | | **`externo`** | Portal público autenticado, cidadão, requerente externo | `--session _externo` | `modulo-acesso.externo` | | **`anonimo`** | Usuário deslogado, consulta pública, login, landing page | `--session _anonimo` | Nenhuma (perfil limpo sem cookies/tokens) | | **``** | Papel especializado de domínio (ex: `fiscal`, `auditor`) | `--session _` | `modulo-acesso.` | --- ## ⚠️ 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}_${CONTEXTO}" 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 por Contexto Abra a aplicação frontend mantendo a janela visível e isolada pelo módulo e contexto desejado: ```bash # 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: ```bash agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i ``` *Saída de exemplo:* ```text - 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.): ```bash # 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: ```bash # 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: ```bash # 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 Capture um screenshot para comprovação do resultado do teste: ```bash # Screenshot padrão ou anotado com identificadores visuais 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: ```bash agent-browser --session "${MODULO}_${CONTEXTO}" 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 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: ```bash 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: ```bash # 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: ```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}_${CONTEXTO}" 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}_${CONTEXTO}" wait 500 && agent-browser --session "${MODULO}_${CONTEXTO}" 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.