---
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 <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
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 <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` |

---

## 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.