From f7ba75d0c3798993d2165ff59e7cf6da57a26297 Mon Sep 17 00:00:00 2001 From: Luiz Silva Date: Wed, 16 Sep 2026 23:42:27 -0300 Subject: [PATCH] feat: incluir agent-browser com modo visivel (--headed) obrigatorio no .agent --- TOOLS | 23 ++- agents/front/persona | 1 + agents/testes/persona | 2 + agents/ux/persona | 1 + .../rules/testes-interface-agent-browser.md | 133 ++++++++++++++ .../testar-interface-agent-browser/SKILL.md | 166 ++++++++++++++++++ manifesto.json | 11 +- rules/testes-interface-agent-browser.md | 133 ++++++++++++++ .../testar-interface-agent-browser/SKILL.md | 166 ++++++++++++++++++ 9 files changed, 629 insertions(+), 7 deletions(-) create mode 100644 global/rules/testes-interface-agent-browser.md create mode 100644 global/skills/testar-interface-agent-browser/SKILL.md create mode 100644 rules/testes-interface-agent-browser.md create mode 100644 skills/testar-interface-agent-browser/SKILL.md diff --git a/TOOLS b/TOOLS index cf568ac..fd21b8e 100644 --- a/TOOLS +++ b/TOOLS @@ -89,9 +89,22 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot --- -## 6. Instalação Rápida (Copia e Cola) +## 6. Automação e Testes de Interface (Browser) -Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer `npm` e `snap` já configurados). +### agent-browser +- **Descrição:** CLI de automação de navegadores baseada em Rust, projetada especificamente para Agentes de IA. +- **Por que ajuda as IAs:** Utiliza representação compacta da árvore de acessibilidade com referências determinísticas (`@e1`, `@e2`), consumindo 200–400 tokens (até 90% menos tokens que a leitura do DOM completo). Permite executar testes E2E, interagir com telas, validar fluxos e registrar evidências visuais. +- **Modo Visível Obrigatório:** Para que o operador acompanhe cada teste em tempo real na tela, execute sempre com a flag `--headed` (ex: `agent-browser open --headed `) ou defina `export AGENT_BROWSER_HEADED=true`. +- **Instalação:** + - Com Bun (padrão): `bun i -g agent-browser && agent-browser install` + - Com NPM: `npm install -g agent-browser && agent-browser install` +- **Documentação:** https://agent-browser.dev/ + +--- + +## 7. Instalação Rápida (Copia e Cola) + +Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer `npm`, `bun` e `snap` já configurados). ### Linux (Debian / Ubuntu) @@ -103,7 +116,10 @@ sudo apt-get install -y ripgrep fd-find jq shellcheck bat tree eza httpie gh # 2. Instalar ferramentas em Node npm install -g @ast-grep/cli @biomejs/biome -# 3. Instalar yq via snap +# 3. Instalar automação de navegador para IA (visível com --headed) +bun i -g agent-browser && agent-browser install + +# 4. Instalar yq via snap sudo snap install yq ``` @@ -113,4 +129,5 @@ sudo snap install yq # Instalar utilitários essenciais brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh npm install -g @biomejs/biome +bun i -g agent-browser && agent-browser install ``` diff --git a/agents/front/persona b/agents/front/persona index 9adc20c..648fa96 100644 --- a/agents/front/persona +++ b/agents/front/persona @@ -45,6 +45,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 6. Extrair CSS para arquivos co-localizados quando necessário 7. Manter componentes dentro do limite de 250 linhas 8. Implementar fluxos de navegação e estados de interface +9. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`)** para acompanhamento do operador (ver `rules/testes-interface-agent-browser.md`) ## Restrições diff --git a/agents/testes/persona b/agents/testes/persona index 7ea3952..532180f 100644 --- a/agents/testes/persona +++ b/agents/testes/persona @@ -45,6 +45,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 6. Identificar casos extremos e cenários de falha não cobertos 7. Validar schemas Zod contra dados reais de produção 8. Documentar bugs encontrados com passos de reprodução +9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`)** para que o operador acompanhe cada ação na tela (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`) ## Restrições @@ -112,6 +113,7 @@ Artefatos em `.agent-local/` sempre têm prioridade sobre os herdados de `.agent - [ ] Casos extremos (null, vazio, limite) testados? - [ ] Erros de rede/banco simulados? - [ ] Performance em volume realista de dados? +- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) com screenshots comprobatórios? ## Memória Persistente diff --git a/agents/ux/persona b/agents/ux/persona index 9e676a2..4cac589 100644 --- a/agents/ux/persona +++ b/agents/ux/persona @@ -45,6 +45,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 6. Organizar a hierarquia de informação das telas 7. Revisar labels, placeholders e textos de ajuda 8. Identificar inconsistências de UX entre módulos +9. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`)** para que o operador acompanhe a validação visual (ver `rules/testes-interface-agent-browser.md`) ## Restrições diff --git a/global/rules/testes-interface-agent-browser.md b/global/rules/testes-interface-agent-browser.md new file mode 100644 index 0000000..96d477c --- /dev/null +++ b/global/rules/testes-interface-agent-browser.md @@ -0,0 +1,133 @@ +--- +type: rule +name: testes-interface-agent-browser +description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) ao operador. +scope: global +trigger: always_on +updatedAt: "2026-09-16" +--- + +# Regra: Testes Automatizados de Interface e Navegação com agent-browser + +## Contexto + +Quando uma IA precisa testar o frontend, validar jornadas de usuário, inspecionar componentes gráficos ou simular interações na tela, é crucial utilizar uma ferramenta rápida, determinística e econômica em tokens. Além disso, o operador humano deve sempre ter visibilidade do que a IA está executando em tempo real na interface gráfica. + +Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA. + +--- + +## Regra + +Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar realizar testes automatizados de interface (E2E), navegar no frontend ou inspecionar telas ativas, **DEVE OBRIGATORIAMENTE**: + +1. **Utilizar o `agent-browser`** como ferramenta oficial de automação de navegador. +2. **Executar SEMPRE em Modo Visível (`--headed`)**: + - A janela do navegador **deve sempre aparecer na área de trabalho do operador**. + - É **terminantemente proibido** rodar testes ocultos (headless silencioso), a menos que o operador humano solicite expressamente essa exceção. + - Usar a flag `--headed` nos comandos de abertura (`agent-browser open --headed `) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`. +3. **Utilizar o modelo de referências (`@ref`)**: + - Mapear a tela via `agent-browser snapshot -i`, obtendo referências compactas como `@e1`, `@e2`. + - Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`). +4. **Registrar evidências e fechar sessão**: + - Registrar comprovações visuais com `agent-browser screenshot `. + - Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo. + +--- + +## Instalação e Configuração + +O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium: + +```bash +# Instalação global via bun (recomendado) +bun i -g agent-browser + +# Download do motor do navegador (primeira execução) +agent-browser install +``` + +Documentação de referência: **https://agent-browser.dev/** + +--- + +## Protocolo Operacional Padrão + +Todo teste ou navegação de interface executado pela IA deve seguir o fluxo: + +### 1. Abertura com Janela Visível + +```bash +# Abrir sempre visível ao operador humano +agent-browser open --headed http://localhost:8080 +``` + +### 2. Inspeção de Elementos Interativos + +```bash +# Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2) +agent-browser snapshot -i +``` + +### 3. Interações por Referência Direta + +```bash +# Interagir diretamente com os elementos identificados no snapshot +agent-browser fill @e1 "usuario@exemplo.com" +agent-browser fill @e2 "senhaSegura123" +agent-browser click @e3 +``` + +### 4. Validação e Evidência + +```bash +# Aguardar estabilização se houver transição assíncrona +agent-browser wait 1000 + +# Obter novo snapshot para verificar estado pós-ação +agent-browser snapshot -i + +# Capturar evidência gráfica do teste +agent-browser screenshot evidencias/teste-login-sucesso.png + +# Verificar erros no console do navegador +agent-browser console +``` + +### 5. Finalização + +```bash +# Fechar a sessão do navegador ao concluir o teste +agent-browser close +``` + +--- + +## Boas Práticas e Proibições + +### Proibido ❌ +- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`. +- **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`). +- **Proibido navegar para URLs desconhecidas** ou inventadas pela IA fora do escopo aprovado do teste. +- **Proibido deixar processos ou janelas orfãs** após a conclusão do trabalho (sempre executar `agent-browser close`). + +### Permitido e Recomendado ✅ +- Manter sessões persistentes quando necessário via `--session ` e `--restore`. +- Usar `agent-browser screenshot --annotate` para inspecionar layouts complexos com visão computacional. +- Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`. + +--- + +## Impacto + +- **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real. +- **Eficiência de tokens**: A árvore de acessibilidade reduz o consumo de contexto em até 90% comparado a inspeções de DOM HTML bruto. +- **Confiabilidade**: Interações determinísticas por `@ref` eliminam fragilidade de seletores CSS dinâmicos. + +--- + +## Referências + +- Documentação Oficial: https://agent-browser.dev/ +- Skill associada: `skills/testar-interface-agent-browser/SKILL.md` +- Ferramentas CLI: `.agent/TOOLS` diff --git a/global/skills/testar-interface-agent-browser/SKILL.md b/global/skills/testar-interface-agent-browser/SKILL.md new file mode 100644 index 0000000..24851f4 --- /dev/null +++ b/global/skills/testar-interface-agent-browser/SKILL.md @@ -0,0 +1,166 @@ +--- +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). +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 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 `--headed` na abertura: + ```bash + agent-browser 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 +Abra a aplicação frontend mantendo a janela visível ao operador: +```bash +agent-browser open --headed http://localhost:8080 +``` + +### 2. Obter Snapshot Interativo +Gere a árvore de acessibilidade enxuta com referências numéricas: +```bash +agent-browser 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 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: +```bash +# 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: +```bash +# 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: +```bash +# 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: +```bash +agent-browser close +``` + +--- + +## Tabela Rápida de Comandos + +| Ação | Comando | +|---|---| +| **Abrir tela (visível)** | `agent-browser open --headed ` | +| **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 ` | +| **Aguardar seletor** | `agent-browser wait --selector ""` | +| **Inspecionar console** | `agent-browser console` | +| **Inspecionar rede** | `agent-browser network` | +| **Screenshot** | `agent-browser screenshot ` | +| **Auditoria a11y (WCAG)** | `agent-browser a11y` | +| **Fechar sessão** | `agent-browser close` | + +--- + +## Sessões Persistentes e Autenticação + +Para fluxos que necessitam manter login ativo entre comandos: +```bash +# 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: +```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 fill @ref` ou `agent-browser click @ref`. +2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser wait 500 && agent-browser 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. diff --git a/manifesto.json b/manifesto.json index b80f940..ea977e1 100644 --- a/manifesto.json +++ b/manifesto.json @@ -1,6 +1,6 @@ { "versao": "3.1.0", - "atualizadoEm": "2026-08-12", + "atualizadoEm": "2026-09-16", "projeto": "e-licencie", "artefatos": { "global": { @@ -27,7 +27,8 @@ "global/rules/typescript-module-resolution.md", "global/rules/typescript-sem-any.md", "global/rules/zod-validacao-padrao.md", - "global/rules/ddd-documentacao-primeiro.md" + "global/rules/ddd-documentacao-primeiro.md", + "global/rules/testes-interface-agent-browser.md" ], "workflows": [ "global/workflows/aprimora-ia.md", @@ -43,7 +44,8 @@ "global/skills/documentar-dominio-modulo/SKILL.md", "global/skills/documentar-regras-negocio/SKILL.md", "global/skills/mapear-codigo-fonte/SKILL.md", - "global/skills/orquestrar-agentes/SKILL.md" + "global/skills/orquestrar-agentes/SKILL.md", + "global/skills/testar-interface-agent-browser/SKILL.md" ] }, "documentacao": { @@ -161,7 +163,8 @@ "persona": "agents/testes/persona", "config": "agents/testes/agent.json", "skills": [ - "agents/testes/skills/diagnosticar-cobertura-testes/SKILL.md" + "agents/testes/skills/diagnosticar-cobertura-testes/SKILL.md", + "skills/testar-interface-agent-browser/SKILL.md" ] }, "ux": { diff --git a/rules/testes-interface-agent-browser.md b/rules/testes-interface-agent-browser.md new file mode 100644 index 0000000..96d477c --- /dev/null +++ b/rules/testes-interface-agent-browser.md @@ -0,0 +1,133 @@ +--- +type: rule +name: testes-interface-agent-browser +description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) ao operador. +scope: global +trigger: always_on +updatedAt: "2026-09-16" +--- + +# Regra: Testes Automatizados de Interface e Navegação com agent-browser + +## Contexto + +Quando uma IA precisa testar o frontend, validar jornadas de usuário, inspecionar componentes gráficos ou simular interações na tela, é crucial utilizar uma ferramenta rápida, determinística e econômica em tokens. Além disso, o operador humano deve sempre ter visibilidade do que a IA está executando em tempo real na interface gráfica. + +Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA. + +--- + +## Regra + +Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar realizar testes automatizados de interface (E2E), navegar no frontend ou inspecionar telas ativas, **DEVE OBRIGATORIAMENTE**: + +1. **Utilizar o `agent-browser`** como ferramenta oficial de automação de navegador. +2. **Executar SEMPRE em Modo Visível (`--headed`)**: + - A janela do navegador **deve sempre aparecer na área de trabalho do operador**. + - É **terminantemente proibido** rodar testes ocultos (headless silencioso), a menos que o operador humano solicite expressamente essa exceção. + - Usar a flag `--headed` nos comandos de abertura (`agent-browser open --headed `) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`. +3. **Utilizar o modelo de referências (`@ref`)**: + - Mapear a tela via `agent-browser snapshot -i`, obtendo referências compactas como `@e1`, `@e2`. + - Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`). +4. **Registrar evidências e fechar sessão**: + - Registrar comprovações visuais com `agent-browser screenshot `. + - Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo. + +--- + +## Instalação e Configuração + +O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium: + +```bash +# Instalação global via bun (recomendado) +bun i -g agent-browser + +# Download do motor do navegador (primeira execução) +agent-browser install +``` + +Documentação de referência: **https://agent-browser.dev/** + +--- + +## Protocolo Operacional Padrão + +Todo teste ou navegação de interface executado pela IA deve seguir o fluxo: + +### 1. Abertura com Janela Visível + +```bash +# Abrir sempre visível ao operador humano +agent-browser open --headed http://localhost:8080 +``` + +### 2. Inspeção de Elementos Interativos + +```bash +# Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2) +agent-browser snapshot -i +``` + +### 3. Interações por Referência Direta + +```bash +# Interagir diretamente com os elementos identificados no snapshot +agent-browser fill @e1 "usuario@exemplo.com" +agent-browser fill @e2 "senhaSegura123" +agent-browser click @e3 +``` + +### 4. Validação e Evidência + +```bash +# Aguardar estabilização se houver transição assíncrona +agent-browser wait 1000 + +# Obter novo snapshot para verificar estado pós-ação +agent-browser snapshot -i + +# Capturar evidência gráfica do teste +agent-browser screenshot evidencias/teste-login-sucesso.png + +# Verificar erros no console do navegador +agent-browser console +``` + +### 5. Finalização + +```bash +# Fechar a sessão do navegador ao concluir o teste +agent-browser close +``` + +--- + +## Boas Práticas e Proibições + +### Proibido ❌ +- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`. +- **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`). +- **Proibido navegar para URLs desconhecidas** ou inventadas pela IA fora do escopo aprovado do teste. +- **Proibido deixar processos ou janelas orfãs** após a conclusão do trabalho (sempre executar `agent-browser close`). + +### Permitido e Recomendado ✅ +- Manter sessões persistentes quando necessário via `--session ` e `--restore`. +- Usar `agent-browser screenshot --annotate` para inspecionar layouts complexos com visão computacional. +- Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`. + +--- + +## Impacto + +- **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real. +- **Eficiência de tokens**: A árvore de acessibilidade reduz o consumo de contexto em até 90% comparado a inspeções de DOM HTML bruto. +- **Confiabilidade**: Interações determinísticas por `@ref` eliminam fragilidade de seletores CSS dinâmicos. + +--- + +## Referências + +- Documentação Oficial: https://agent-browser.dev/ +- Skill associada: `skills/testar-interface-agent-browser/SKILL.md` +- Ferramentas CLI: `.agent/TOOLS` diff --git a/skills/testar-interface-agent-browser/SKILL.md b/skills/testar-interface-agent-browser/SKILL.md new file mode 100644 index 0000000..24851f4 --- /dev/null +++ b/skills/testar-interface-agent-browser/SKILL.md @@ -0,0 +1,166 @@ +--- +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). +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 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 `--headed` na abertura: + ```bash + agent-browser 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 +Abra a aplicação frontend mantendo a janela visível ao operador: +```bash +agent-browser open --headed http://localhost:8080 +``` + +### 2. Obter Snapshot Interativo +Gere a árvore de acessibilidade enxuta com referências numéricas: +```bash +agent-browser 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 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: +```bash +# 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: +```bash +# 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: +```bash +# 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: +```bash +agent-browser close +``` + +--- + +## Tabela Rápida de Comandos + +| Ação | Comando | +|---|---| +| **Abrir tela (visível)** | `agent-browser open --headed ` | +| **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 ` | +| **Aguardar seletor** | `agent-browser wait --selector ""` | +| **Inspecionar console** | `agent-browser console` | +| **Inspecionar rede** | `agent-browser network` | +| **Screenshot** | `agent-browser screenshot ` | +| **Auditoria a11y (WCAG)** | `agent-browser a11y` | +| **Fechar sessão** | `agent-browser close` | + +--- + +## Sessões Persistentes e Autenticação + +Para fluxos que necessitam manter login ativo entre comandos: +```bash +# 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: +```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 fill @ref` ou `agent-browser click @ref`. +2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser wait 500 && agent-browser 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.