171 lines
10 KiB
Markdown
171 lines
10 KiB
Markdown
---
|
|
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), com isolamento por sessão e contexto (--session <modulo>_<contexto?>) e salvando evidências obrigatoriamente na pasta .evidencias/.
|
|
scope: global
|
|
trigger: always_on
|
|
updatedAt: "2026-10-30"
|
|
---
|
|
|
|
# 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.
|
|
|
|
Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Para viabilizar testes concorrentes e evitar interferências mútuas entre múltiplos módulos ou workspaces, todo comando deve operar em sessão isolada identificada pelo módulo e pelo contexto de acesso.
|
|
|
|
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 --session <modulo>_<contexto?> open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
|
|
3. **Isolamento Mandatório de Sessão e Contexto (`--session <modulo>_<contexto?>`)**:
|
|
- **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo e o contexto de acesso.
|
|
- Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml` e `<contexto?>` discrimina o papel ou natureza do acesso), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto?>`.
|
|
- **Prevenção de Mistura de Tokens:** Caso a aplicação possua mais de um tipo de acesso (`interno`, `externo`, `anonimo`, `cliente`, etc.), o `<contexto>` **DEVE SER OBRIGATORIAMENTE PREENCHIDO** para evitar que cookies, tokens JWT e estados de login residuais contaminem outros fluxos de teste.
|
|
- Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>_<contexto>.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos.
|
|
- Caso um mesmo módulo e contexto necessite de sub-isolamento para testes paralelos, adota-se o discriminador determinístico: `<modulo>_<contexto>_<slug-ou-pid>`.
|
|
4. **Utilizar o modelo de referências (`@ref`)**:
|
|
- Mapear a tela via `agent-browser --session <modulo>_<contexto?> snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
|
|
- Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
|
|
5. **Registrar evidências obrigatoriamente na pasta `.evidencias/` e fechar sessão**:
|
|
- Todas as evidências geradas pelos testes automatizados (screenshots, capturas anotadas, PDFs, vídeos, traces, relatórios ou dumps de console/rede) **DEVEM OBRIGATORIAMENTE ser salvas na pasta `.evidencias/`** na raiz do projeto (`mkdir -p .evidencias`).
|
|
- Registrar comprovações visuais com `agent-browser --session <modulo>_<contexto?> screenshot .evidencias/<arquivo.png>`.
|
|
- Garantir que `.evidencias/` conste no `.gitignore` do projeto para evitar o versionamento acidental de binários de teste.
|
|
- Encerrar graciosamente o navegador com `agent-browser --session <modulo>_<contexto?> close` ao término do fluxo.
|
|
6. **Credenciais Canônicas por Contexto (`modulo-acesso`)**:
|
|
- Sempre que o teste exigir autenticação, o agente **DEVE OBRIGATORIAMENTE extrair as credenciais do contexto específico** em `modulo-acesso` de `memorias-ia/modulo.yml` (ex: `modulo-acesso.interno`, `modulo-acesso.cliente`, etc.).
|
|
- Para sessões anônimas (`_anonimo`), nenhum login deve ser realizado, garantindo a validação da experiência do usuário público sem tokens.
|
|
- É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.
|
|
|
|
---
|
|
|
|
## 🔒 Contextos Canônicos de Sessão (`<modulo>_<contexto>`)
|
|
|
|
| Contexto | Finalidade e Natureza | Exemplo de Sessão | Credenciais em `modulo.yml` |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **`interno`** | Operador interno, suporte, técnico, atendente, administrador | `--session <modulo>_interno` | `modulo-acesso.interno` (ou `modulo-acesso` simples) |
|
|
| **`cliente`** | Cliente final, solicitante corporativo, empresa contratante | `--session <modulo>_cliente` | `modulo-acesso.cliente` |
|
|
| **`externo`** | Portal público autenticado, cidadão, requerente externo | `--session <modulo>_externo` | `modulo-acesso.externo` |
|
|
| **`anonimo`** | Usuário deslogado, consulta pública por código, login, landing | `--session <modulo>_anonimo` | Nenhuma (perfil limpo sem cookies/tokens) |
|
|
| **`<especifico>`** | Papel especializado de domínio (ex: `fiscal`, `auditor`) | `--session <modulo>_<papel>` | `modulo-acesso.<papel>` |
|
|
|
|
---
|
|
|
|
## 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 com isolamento de sessão e contexto:
|
|
|
|
### 1. Obter Identificador do Módulo e Abertura com Janela Visível
|
|
|
|
```bash
|
|
# Obter o 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"
|
|
|
|
# Abrir sempre visível ao operador na sessão isolada por módulo e contexto
|
|
agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "${MODULO}_${CONTEXTO}" snapshot -i
|
|
```
|
|
|
|
### 3. Interações por Referência Direta
|
|
|
|
```bash
|
|
# Interagir diretamente com os elementos identificados no snapshot
|
|
agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "usuario@exemplo.com"
|
|
agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "senhaSegura123"
|
|
agent-browser --session "${MODULO}_${CONTEXTO}" click @e3
|
|
```
|
|
|
|
### 4. Validação e Evidência
|
|
|
|
```bash
|
|
# Aguardar estabilização se houver transição assíncrona
|
|
agent-browser --session "${MODULO}_${CONTEXTO}" wait 1000
|
|
|
|
# Obter novo snapshot para verificar estado pós-ação
|
|
agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i
|
|
|
|
# Garantir pasta .evidencias e capturar evidência gráfica do teste
|
|
mkdir -p .evidencias
|
|
agent-browser --session "${MODULO}_${CONTEXTO}" screenshot .evidencias/teste-login-sucesso.png
|
|
|
|
# Verificar erros no console do navegador
|
|
agent-browser --session "${MODULO}_${CONTEXTO}" console
|
|
```
|
|
|
|
### 5. Finalização
|
|
|
|
```bash
|
|
# Fechar a sessão isolada do navegador ao concluir o fluxo daquele contexto
|
|
agent-browser --session "${MODULO}_${CONTEXTO}" close
|
|
```
|
|
|
|
---
|
|
|
|
## Boas Práticas e Proibições
|
|
|
|
### Proibido ❌
|
|
- **Proibido executar sem a flag `--session <modulo>_<contexto?>`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada.
|
|
- **Proibido misturar acessos com perfis diferentes na mesma sessão genérica sem contexto** (ex: logar como operador interno e depois testar fluxo de cliente ou anônimo na mesma sessão, causando mistura de tokens).
|
|
- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`.
|
|
- **Proibido salvar evidências de testes automatizados fora da pasta `.evidencias/`** (como soltas na raiz do projeto, em `/tmp/` ou em `evidencias/` sem ponto inicial).
|
|
- **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 órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <modulo>_<contexto?> close`).
|
|
|
|
### Permitido e Recomendado ✅
|
|
- Manter sessões persistentes por contexto quando necessário via `--session <modulo>_<contexto> --restore`.
|
|
- Utilizar sub-isolamento determinístico (`<modulo>_<contexto>_<slug-ou-pid>`) caso múltiplos testes do mesmo contexto ocorram simultaneamente no mesmo host.
|
|
- Usar `agent-browser --session <modulo>_<contexto> screenshot --annotate .evidencias/<slug>-anotado.png` 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
|
|
|
|
- **Isolamento de Tokens e Cookies**: Evita vazamento de credenciais e estados de autenticação entre acessos de operador interno, cliente corporativo, cidadão e visitante anônimo.
|
|
- **Isolamento e Concorrência**: Múltiplos agentes ou testes E2E simultâneos não conflitam de abas nem fecham janelas alheias.
|
|
- **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`
|
|
- Rule associada: `rules/identidade-modulo.md`
|
|
- Ferramentas CLI: `.agent/TOOLS`
|