199 lines
7.6 KiB
Markdown
199 lines
7.6 KiB
Markdown
---
|
|
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 <modulo>).
|
|
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 <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>` é o `modulo-id` canônico de `memorias-ia/modulo.yml`), ou garantir no ambiente `export 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 `--headed` na abertura:
|
|
```bash
|
|
agent-browser --session "$MODULO" open --headed <url>
|
|
```
|
|
- 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 <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`:
|
|
|
|
```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.
|