.agent/rules/testes-interface-agent-browser.md

---
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) e com isolamento por sessão e contexto (--session <modulo>_<contexto?>) para evitar mistura de tokens.
scope: global
trigger: always_on
updatedAt: "2026-10-08"
---

# 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. Em aplicações que possuem múltiplos níveis de acesso (como áreas administrativas internas, portais de requerentes externos, consultas anônimas públicas e acessos de clientes corporativos), a ausência de isolamento por contexto gera **mistura de tokens JWT, cookies de autenticação e dados de LocalStorage**, provocando falsos positivos ou mascarando falhas de segurança.

Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** com isolamento estrito por módulo e contexto de acesso (`--session <modulo>_<contexto?>`).

---

## 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 perfil 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>` representa o perfil ou nível de acesso que está sendo testado), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto>`.
   - **Contextos Padronizados de Acesso:**
     - `interno`: Acesso restrito a servidores públicos, fiscais, analistas internos ou administradores.
     - `externo`: Acesso de requerentes externos, contribuintes ou cidadãos logados.
     - `anonimo`: Acesso público e não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). **Obrigatório para assegurar ausência total de tokens ou cookies residuais de sessões anteriores.**
     - `cliente`: Acesso de clientes ou empresas contratantes em plataformas multi-tenant ou B2B.
     - Aplicações de contexto único sem distinção de perfis podem utilizar apenas `<modulo>` ou `<modulo>_default`.
   - **Prevenção de Mistura de Tokens e Cookies:** Cada sessão do `agent-browser` possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>_<contexto>.sock`), mantendo cookie jar, cabeçalhos `Authorization`, LocalStorage e SessionStorage completamente estanques. Separar por `<modulo>_<contexto>` é estritamente obrigatório para que um teste anônimo não herde tokens de um teste interno, ou que credenciais de requerente externo não interfiram em fluxos administrativos.
   - **Sub-isolamento Concorrente:** Caso múltiplos testes concorrentes ocorram no mesmo módulo e contexto, adota-se o sufixo 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 e fechar sessão**:
   - Registrar comprovações visuais com `agent-browser --session <modulo>_<contexto> screenshot <arquivo.png>`.
   - Encerrar graciosamente o navegador com `agent-browser --session <modulo>_<contexto> close` ao término do fluxo.
6. **Credenciais Canônicas de Teste por Contexto (`modulo-acesso`)**:
   - O agente **DEVE OBRIGATORIAMENTE consultar `modulo-acesso` em `memorias-ia/modulo.yml`**.
   - Se configurado com chaves específicas por contexto (`interno`, `externo`, `cliente`), extrair as credenciais do contexto sob teste.
   - Se configurado no formato plano direto (`usuario` e `senha`), utilizar como credencial padrão para o contexto principal/interno.
   - Para o contexto `anonimo`, o agente **NÃO deve autenticar**, validando a jornada como usuário não-logado na sessão isolada `<modulo>_anonimo`.
   - É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.

---

## 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, Definir Contexto 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}')

# Definir contexto sob teste: interno | externo | anonimo | cliente
CONTEXTO="interno" # ou externo, anonimo, cliente
SESSAO="${MODULO}_${CONTEXTO}"

# Abrir sempre visível ao operador humano na sessão isolada do módulo e contexto
agent-browser --session "$SESSAO" 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 "$SESSAO" snapshot -i
```

### 3. Interações por Referência Direta

```bash
# Interagir diretamente com os elementos identificados no snapshot
agent-browser --session "$SESSAO" fill @e1 "usuario@exemplo.com"
agent-browser --session "$SESSAO" fill @e2 "senhaSegura123"
agent-browser --session "$SESSAO" click @e3
```

### 4. Validação e Evidência

```bash
# Aguardar estabilização se houver transição assíncrona
agent-browser --session "$SESSAO" wait 1000

# Obter novo snapshot para verificar estado pós-ação
agent-browser --session "$SESSAO" snapshot -i

# Capturar evidência gráfica do teste
agent-browser --session "$SESSAO" screenshot evidencias/teste-login-sucesso.png

# Verificar erros no console do navegador
agent-browser --session "$SESSAO" console
```

### 5. Finalização

```bash
# Fechar a sessão isolada do navegador ao concluir o teste
agent-browser --session "$SESSAO" close
```

---

## Boas Práticas e Proibições

### Proibido ❌
- **Proibido executar sem a flag `--session <modulo>_<contexto?>`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir sessões ou misturar tokens entre perfis.
- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`.
- **Proibido testar fluxos anônimos em sessões já autenticadas**, garantindo que testes públicos sempre rodem na sessão `<modulo>_anonimo`.
- **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 <sessao> close`).

### Permitido e Recomendado ✅
- Manter sessões persistentes 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` 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**: Previne contaminação entre sessões de administradores internos, cidadãos externos e consultas públicas anônimas.
- **Isolamento de Processos e Concorrência**: Múltiplos agentes rodando testes E2E simultâneos não colidem abas nem encerram daemons de outros contextos.
- **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`