publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(testes): padronizar uso obrigatorio de --session <modulo> no agent-browser

Browse source
This commit is contained in:
Luiz Silva 2026-10-08 10:05:29 -03:00
parent 253930b75b
commit b1c4c5c42e
23 changed files with 248 additions and 163 deletions
Download patch file Download diff file Expand all files Collapse all files

2
DOCUMENTACAO/templates/modulo.yml.template
View file

@ -2,7 +2,7 @@
# Este arquivo é obrigatório na raiz de todos os projetos que utilizam .agent.
# Ele define a identidade oficial e as configurações de rota do módulo.
# Identificador único do módulo (utilizado para pacotes, wikis <modulo-wiki>/<modulo-id>/ e regras de negócio)
# Identificador único do módulo (utilizado para pacotes, wikis <modulo-wiki>/<modulo-id>/, regras de negócio e sessão isolada do agent-browser --session <modulo-id>)
modulo-id: nome-do-modulo.submodulo
# Rota/prefixo utilizado na URL e navegação do módulo (com barras inicial e final)

10
DOCUMENTACAO/templates/plano.md.template
View file

@ -90,10 +90,12 @@ executor: null
- Qualidade/Lint: `biome check --write <arquivos>`
- Governança: `sh .agent/verificar-linhas.sh`
### 5.2 Roteiro de Teste Manual / `agent-browser`
1. Acessar a tela X
2. Executar a ação Y
3. Validar se o resultado Z ocorre
### 5.2 Roteiro de Teste Manual / `agent-browser` (Sempre em Modo Visível `--headed` e com `--session <modulo-id>`)
1. Abrir aplicação: `agent-browser --session <modulo-id> open --headed <url>`
2. Mapear interações: `agent-browser --session <modulo-id> snapshot -i`
3. Executar ações: `agent-browser --session <modulo-id> fill @ref "..." && agent-browser --session <modulo-id> click @ref`
4. Capturar evidência: `agent-browser --session <modulo-id> screenshot evidencias/<slug>.png`
5. Encerrar: `agent-browser --session <modulo-id> close`
---

3
TOOLS
View file

@ -94,7 +94,8 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot
### 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 <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
- **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 --session <modulo> open --headed <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
- **Isolamento Mandatório de Sessão:** Toda execução DEVE acompanhar a flag `--session <modulo>` (onde `<modulo>` é o `modulo-id` extraído de `memorias-ia/modulo.yml`) ou garantir `export AGENT_BROWSER_SESSION=<modulo>`. Cada sessão aloca daemon e socket Unix exclusivos, prevenindo colisões e fechamento indevido de janelas em execuções concorrentes.
- **Instalação:**
- Com Bun (padrão): `bun i -g agent-browser && agent-browser install`
- Com NPM: `npm install -g agent-browser && agent-browser install`

3
TOOLS.md
View file

@ -94,7 +94,8 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot
### 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 <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
- **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 --session <modulo> open --headed <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
- **Isolamento Mandatório de Sessão:** Toda execução DEVE acompanhar a flag `--session <modulo>` (onde `<modulo>` é o `modulo-id` extraído de `memorias-ia/modulo.yml`) ou garantir `export AGENT_BROWSER_SESSION=<modulo>`. Cada sessão aloca daemon e socket Unix exclusivos, prevenindo colisões e fechamento indevido de janelas em execuções concorrentes.
- **Instalação:**
- Com Bun (padrão): `bun i -g agent-browser && agent-browser install`
- Com NPM: `npm install -g agent-browser && agent-browser install`

2
agents/front/agent.md
View file

@ -54,7 +54,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
8. Implementar fluxos de navegação e estados de interface
9. Criar e manter arquivo `{componente}.ajuda.md` co-localizado (para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`) sempre que houver ajuda contextual (ver `skills/adicionar-ajuda`)
10. Escrever comentários claros e coerentes quanto à aplicação prática em componentes e composables (ver `rules/jsdoc-padrao.md`)
11. 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`)
11. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session <modulo-id>`)** para acompanhamento do operador e prevenção de conflitos em testes simultâneos (ver `rules/testes-interface-agent-browser.md`)
## Restrições

2
agents/front/persona
View file

@ -47,7 +47,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
8. Implementar fluxos de navegação e estados de interface
9. Criar e manter arquivo `{componente}.ajuda.md` co-localizado (para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`) sempre que houver ajuda contextual (ver `skills/adicionar-ajuda`)
10. Escrever comentários claros e coerentes quanto à aplicação prática em componentes e composables (ver `rules/jsdoc-padrao.md`)
11. 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`)
11. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session <modulo-id>`)** para acompanhamento do operador e prevenção de conflitos em testes simultâneos (ver `rules/testes-interface-agent-browser.md`)
## Restrições

2
agents/testes/agent.json
View file

File diff suppressed because one or more lines are too long

4
agents/testes/agent.md
View file

@ -53,7 +53,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`)
9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session <modulo-id>`)** para que o operador acompanhe cada ação na tela e evitar colisões em testes concorrentes (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`)
10. **Gerar Planos Técnicos via `/plano`** — durante homologações, reviews ou testes, formalizar bugs, melhorias e gaps em planos estruturados em `PLANOS/pendente/` para posterior implementação pelo time de desenvolvimento (ver `global/workflows/plano.md`).
## Restrições
@ -122,7 +122,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?
- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) e com sessão isolada (`--session <modulo-id>`), com screenshots comprobatórios?
## Memória Persistente & Identidade do Projeto

4
agents/testes/persona
View file

@ -45,7 +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`)
9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session <modulo-id>`)** para que o operador acompanhe cada ação na tela e evitar colisões em testes concorrentes (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`)
10. **Gerar Planos Técnicos via `/plano`** — durante homologações, reviews ou testes, formalizar bugs, melhorias e gaps em planos estruturados em `PLANOS/pendente/` para posterior implementação pelo time de desenvolvimento (ver `global/workflows/plano.md`).
## Restrições
@ -114,7 +114,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?
- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) e com sessão isolada (`--session <modulo-id>`), com screenshots comprobatórios?
## Memória Persistente & Identidade do Projeto

2
agents/ux/agent.md
View file

@ -51,7 +51,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`)
9. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session <modulo-id>`)** para que o operador acompanhe a validação visual e evitar interferência entre sessões (ver `rules/testes-interface-agent-browser.md`)
## Restrições

2
agents/ux/persona
View file

@ -45,7 +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`)
9. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session <modulo-id>`)** para que o operador acompanhe a validação visual e evitar interferência entre sessões (ver `rules/testes-interface-agent-browser.md`)
## Restrições

4
global/rules/identidade-modulo.md
View file

@ -51,7 +51,7 @@ modulo-wiki: <caminho-da-wiki>
| Campo | Tipo | Descrição | Exemplo |
| :--- | :--- | :--- | :--- |
| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki e referências de regras de negócio. | `e-licencie.sigma` |
| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e identificador mandatório de sessão isolada no `agent-browser` (`--session <modulo-id>`). | `e-licencie.sigma` |
| **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/sigma/` |
| **`modulo-descricao`** | `string` | Descrição textual do propósito funcional e escopo de negócio do módulo. | `Módulo para gestão de monitoramentos ambientais` |
| **`modulo-tipo`** | `string` | Descrição textual da arquitetura e tecnologias empregadas no módulo. | `aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres` |
@ -63,7 +63,7 @@ modulo-wiki: <caminho-da-wiki>
## Regra Universal de Consulta
Sempre que qualquer agente, persona, workflow ou skill necessitar de:
1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`), Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<modulo-wiki>/dev/<modulo-id>/adrs/`) ou relatórios;
1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`), Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<modulo-wiki>/dev/<modulo-id>/adrs/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session <modulo-id>`)**;
2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `<modulo-caminho>llm.md`), links de navegação ou proxies;
3. **Propósito ou Stack (`modulo-descricao` e `modulo-tipo`)**: para contextualizar novos agentes, gerar propostas comerciais, marketing, reels, análises de arquitetura ou testes;
4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística em rotinas de teste e validação de interface;

67
global/rules/testes-interface-agent-browser.md
View file

@ -1,10 +1,10 @@
---
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.
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 (--session <modulo>).
scope: global
trigger: always_on
updatedAt: "2026-09-16"
updatedAt: "2026-10-08"
---
# Regra: Testes Automatizados de Interface e Navegação com agent-browser
@ -13,6 +13,8 @@ updatedAt: "2026-09-16"
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.
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.
---
@ -25,14 +27,19 @@ Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar
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 <url>`) 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`.
- Usar a flag `--headed` nos comandos de abertura (`agent-browser --session <modulo> open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
3. **Isolamento Mandatório de Sessão (`--session <modulo>`)**:
- **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo.
- Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>`.
- Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos em testes simultâneos multi-módulos.
- Caso um mesmo módulo necessite de sub-isolamento para testes paralelos, deve-se adotar o sufixo determinístico `<modulo-id>-<slug-ou-pid>`.
4. **Utilizar o modelo de referências (`@ref`)**:
- Mapear a tela via `agent-browser --session <modulo> 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 <arquivo.png>`.
- Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo.
5. **Credenciais Canônicas de Teste (`modulo-acesso`)**:
5. **Registrar evidências e fechar sessão**:
- Registrar comprovações visuais com `agent-browser --session <modulo> screenshot <arquivo.png>`.
- Encerrar graciosamente o navegador com `agent-browser --session <modulo> close` ao término do fluxo.
6. **Credenciais Canônicas de Teste (`modulo-acesso`)**:
- Sempre que o teste exigir autenticação (login, sessão administrativa), o agente **DEVE OBRIGATORIAMENTE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml`**.
- É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.
@ -56,52 +63,55 @@ 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:
Todo teste ou navegação de interface executado pela IA deve seguir o fluxo com isolamento de sessão:
### 1. Abertura com Janela Visível
### 1. Obter Identificador do Módulo e Abertura com Janela Visível
```bash
# Abrir sempre visível ao operador humano
agent-browser open --headed http://localhost:8080
# Obter o modulo-id canônico de memorias-ia/modulo.yml
MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
# Abrir sempre visível ao operador humano na sessão isolada do módulo
agent-browser --session "$MODULO" 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
agent-browser --session "$MODULO" 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
agent-browser --session "$MODULO" fill @e1 "usuario@exemplo.com"
agent-browser --session "$MODULO" fill @e2 "senhaSegura123"
agent-browser --session "$MODULO" click @e3
```
### 4. Validação e Evidência
```bash
# Aguardar estabilização se houver transição assíncrona
agent-browser wait 1000
agent-browser --session "$MODULO" wait 1000
# Obter novo snapshot para verificar estado pós-ação
agent-browser snapshot -i
agent-browser --session "$MODULO" snapshot -i
# Capturar evidência gráfica do teste
agent-browser screenshot evidencias/teste-login-sucesso.png
agent-browser --session "$MODULO" screenshot evidencias/teste-login-sucesso.png
# Verificar erros no console do navegador
agent-browser console
agent-browser --session "$MODULO" console
```
### 5. Finalização
```bash
# Fechar a sessão do navegador ao concluir o teste
agent-browser close
# Fechar a sessão isolada do navegador ao concluir o teste
agent-browser --session "$MODULO" close
```
---
@ -109,20 +119,23 @@ agent-browser close
## Boas Práticas e Proibições
### Proibido ❌
- **Proibido executar sem a flag `--session <modulo>`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada.
- **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`).
- **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <modulo> close`).
### Permitido e Recomendado ✅
- Manter sessões persistentes quando necessário via `--session <nome>` e `--restore`.
- Usar `agent-browser screenshot --annotate` para inspecionar layouts complexos com visão computacional.
- Manter sessões persistentes quando necessário via `--session <modulo> --restore`.
- Utilizar sub-isolamento determinístico (`<modulo-id>-<slug-ou-pid>`) caso múltiplos testes do mesmo módulo ocorram simultaneamente no mesmo host.
- Usar `agent-browser --session <modulo> 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 e Concorrência**: Múltiplos agentes ou módulos rodando 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.
@ -133,4 +146,6 @@ agent-browser close
- 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`

4
global/skills/plano.executar/SKILL.md
View file

@ -56,7 +56,7 @@ O Orquestrador Líder decompõe a especificação técnica do plano e distribui
| **`@front`** *(Frontend Specialist)* | `*-front`, `*-comuns` | Componentes Vue 3, composables, views, formulários reativos, binding de eventos, consumo de APIs e CSS co-localizado. |
| **`@ux`** *(UX Specialist)* | `*-front` (Interface & Heurísticas) | Aplicação das Heurísticas de Nielsen: visibilidade do estado (spinners, loading, feedback imediato), clareza cognitiva, prevenção de erros e mensagens amigáveis ao usuário. |
| **`@refatorar`** *(Clean Code Specialist)* | Todo o código alterado | Governança estrita das 12 regras de Código Limpo: garantia do **limite de 250 linhas por arquivo**, eliminação de code smells, modularidade e Dispatch Tables. |
| **`@testes`** *(QA & Automation)* | Checagens e Validação E2E | Tipagem (`bun run typecheck` / `tsc --noEmit`), linter (`biome check --write`), governança (`sh .agent/verificar-linhas.sh`) e testes de interface visual via `agent-browser --headed`. |
| **`@testes`** *(QA & Automation)* | Checagens e Validação E2E | Tipagem (`bun run typecheck` / `tsc --noEmit`), linter (`biome check --write`), governança (`sh .agent/verificar-linhas.sh`) e testes de interface visual via `agent-browser --session <modulo> --headed`. |
| **`@documentacao`** *(Memory & Docs)* | `memorias-ia/`, `wiki/` | Registro de sessão no Pilar 6 (`memorias-ia/sessao-*.md`), indexação no `historico-acoes.md`, atualização de regras técnicas na Wiki de Dev (`wiki/dev/<modulo>/`). |
---
@ -80,7 +80,7 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof
↓
4. [@refatorar] Extrai módulos se exceder 250 linhas e aplica Código Limpo
↓
5. [@testes] Roda typecheck, biome e testes E2E com agent-browser --headed
5. [@testes] Roda typecheck, biome e testes E2E com agent-browser --session <modulo> --headed
↓ (Loop /goal de auto-correção se houver falhas)
6. [@documentacao] Atualiza memórias-ia/, historico-acoes.md e arquiva o plano
```

2
global/skills/plano/SKILL.md
View file

@ -74,7 +74,7 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer
- **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps e arquivos mapeados com links `[arquivo](file://...)`.
- **3. Critérios de Aceite & Validação (DoD):** Checklist com caixas `- [ ]` contendo condições verificáveis de sucesso.
- **4. Especificação Técnica & Passos de Implementação:** Roteiro prático para o desenvolvedor (schemas, backend, frontend, código sugerido).
- **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser`.
- **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session <modulo> --headed`.
- **6. Histórico de Execução:** Cabeçalho reservado para preenchimento na conclusão pelo executor.
- Salve o arquivo em `./PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.md` usando `write_to_file`.

111
global/skills/testar-interface-agent-browser/SKILL.md
View file

@ -2,7 +2,8 @@
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).
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
---
@ -10,7 +11,16 @@ scope: global
## 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.
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"`.
---
@ -20,7 +30,7 @@ Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na á
- Usar sempre a flag `--headed` na abertura:
```bash
agent-browser open --headed <url>
agent-browser --session "$MODULO" open --headed <url>
```
- Ou exportar no ambiente:
```bash
@ -46,16 +56,19 @@ 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:
### 1. Iniciar Sessão Visível e Isolada
Abra a aplicação frontend mantendo a janela visível e isolada por módulo:
```bash
agent-browser open --headed http://localhost:8080
# 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 snapshot -i
agent-browser --session "$MODULO" snapshot -i
```
*Saída de exemplo:*
```text
@ -69,45 +82,45 @@ agent-browser snapshot -i
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"
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 click @e4
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 wait 1500
agent-browser --session "$MODULO" wait 1500
# Capturar novo snapshot para verificar se a lista ou mensagem apareceu
agent-browser snapshot -i
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 console
agent-browser --session "$MODULO" console
# Verificar requisições de rede falhadas
agent-browser network
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 screenshot evidencias/resultado-sucesso.png
# agent-browser screenshot --annotate evidencias/resultado-anotado.png
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 limpando os processos do daemon:
Finalize a sessão isolada limpando apenas os processos do seu módulo:
```bash
agent-browser close
agent-browser --session "$MODULO" close
```
---
@ -116,32 +129,52 @@ agent-browser close
| 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` |
| **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:
Para fluxos que necessitam manter login ativo entre comandos com isolamento:
```bash
# Iniciar sessão nomeada com auto-restore
agent-browser --session auth-test --restore open --headed http://localhost:8080/login
# 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
agent-browser session info --json
# Verificar status da sessão isolada
agent-browser --session "$MODULO" session info --json
```
---
@ -161,6 +194,6 @@ 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.
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.

2
global/workflows/plano.md
View file

@ -99,7 +99,7 @@ O Orquestrador divide as tarefas entre os especialistas:
- **`@front`**: Implementa telas Vue 3, composables e formulários consumindo `*-comuns`.
- **`@ux`**: Aplica as Heurísticas de Nielsen (visibilidade de loading/erro, feedback imediato).
- **`@refatorar`**: Governança de Código Limpo (limite estrito de 250 linhas, Dispatch Tables).
- **`@testes`**: Roda `typecheck`, `biome check` e validação visual via `agent-browser --headed`.
- **`@testes`**: Roda `typecheck`, `biome check` e validação visual via `agent-browser --session <modulo> --headed`.
- **`@documentacao`**: Documenta a memória da sessão (Pilar 6) e regras de negócio.
### 3. Modos de Invocação

4
rules/identidade-modulo.md
View file

@ -51,7 +51,7 @@ modulo-wiki: <caminho-da-wiki>
| Campo | Tipo | Descrição | Exemplo |
| :--- | :--- | :--- | :--- |
| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki e referências de regras de negócio. | `e-licencie.sigma` |
| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e identificador mandatório de sessão isolada no `agent-browser` (`--session <modulo-id>`). | `e-licencie.sigma` |
| **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/sigma/` |
| **`modulo-descricao`** | `string` | Descrição textual do propósito funcional e escopo de negócio do módulo. | `Módulo para gestão de monitoramentos ambientais` |
| **`modulo-tipo`** | `string` | Descrição textual da arquitetura e tecnologias empregadas no módulo. | `aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres` |
@ -63,7 +63,7 @@ modulo-wiki: <caminho-da-wiki>
## Regra Universal de Consulta
Sempre que qualquer agente, persona, workflow ou skill necessitar de:
1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`), Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<modulo-wiki>/dev/<modulo-id>/adrs/`) ou relatórios;
1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`), Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<modulo-wiki>/dev/<modulo-id>/adrs/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session <modulo-id>`)**;
2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `<modulo-caminho>llm.md`), links de navegação ou proxies;
3. **Propósito ou Stack (`modulo-descricao` e `modulo-tipo`)**: para contextualizar novos agentes, gerar propostas comerciais, marketing, reels, análises de arquitetura ou testes;
4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística em rotinas de teste e validação de interface;

67
rules/testes-interface-agent-browser.md
View file

@ -1,10 +1,10 @@
---
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.
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 (--session <modulo>).
scope: global
trigger: always_on
updatedAt: "2026-09-16"
updatedAt: "2026-10-08"
---
# Regra: Testes Automatizados de Interface e Navegação com agent-browser
@ -13,6 +13,8 @@ updatedAt: "2026-09-16"
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.
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.
---
@ -25,14 +27,19 @@ Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar
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 <url>`) 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`.
- Usar a flag `--headed` nos comandos de abertura (`agent-browser --session <modulo> open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
3. **Isolamento Mandatório de Sessão (`--session <modulo>`)**:
- **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo.
- Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>`.
- Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos em testes simultâneos multi-módulos.
- Caso um mesmo módulo necessite de sub-isolamento para testes paralelos, deve-se adotar o sufixo determinístico `<modulo-id>-<slug-ou-pid>`.
4. **Utilizar o modelo de referências (`@ref`)**:
- Mapear a tela via `agent-browser --session <modulo> 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 <arquivo.png>`.
- Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo.
5. **Credenciais Canônicas de Teste (`modulo-acesso`)**:
5. **Registrar evidências e fechar sessão**:
- Registrar comprovações visuais com `agent-browser --session <modulo> screenshot <arquivo.png>`.
- Encerrar graciosamente o navegador com `agent-browser --session <modulo> close` ao término do fluxo.
6. **Credenciais Canônicas de Teste (`modulo-acesso`)**:
- Sempre que o teste exigir autenticação (login, sessão administrativa), o agente **DEVE OBRIGATORIAMENTE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml`**.
- É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.
@ -56,52 +63,55 @@ 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:
Todo teste ou navegação de interface executado pela IA deve seguir o fluxo com isolamento de sessão:
### 1. Abertura com Janela Visível
### 1. Obter Identificador do Módulo e Abertura com Janela Visível
```bash
# Abrir sempre visível ao operador humano
agent-browser open --headed http://localhost:8080
# Obter o modulo-id canônico de memorias-ia/modulo.yml
MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
# Abrir sempre visível ao operador humano na sessão isolada do módulo
agent-browser --session "$MODULO" 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
agent-browser --session "$MODULO" 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
agent-browser --session "$MODULO" fill @e1 "usuario@exemplo.com"
agent-browser --session "$MODULO" fill @e2 "senhaSegura123"
agent-browser --session "$MODULO" click @e3
```
### 4. Validação e Evidência
```bash
# Aguardar estabilização se houver transição assíncrona
agent-browser wait 1000
agent-browser --session "$MODULO" wait 1000
# Obter novo snapshot para verificar estado pós-ação
agent-browser snapshot -i
agent-browser --session "$MODULO" snapshot -i
# Capturar evidência gráfica do teste
agent-browser screenshot evidencias/teste-login-sucesso.png
agent-browser --session "$MODULO" screenshot evidencias/teste-login-sucesso.png
# Verificar erros no console do navegador
agent-browser console
agent-browser --session "$MODULO" console
```
### 5. Finalização
```bash
# Fechar a sessão do navegador ao concluir o teste
agent-browser close
# Fechar a sessão isolada do navegador ao concluir o teste
agent-browser --session "$MODULO" close
```
---
@ -109,20 +119,23 @@ agent-browser close
## Boas Práticas e Proibições
### Proibido ❌
- **Proibido executar sem a flag `--session <modulo>`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada.
- **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`).
- **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <modulo> close`).
### Permitido e Recomendado ✅
- Manter sessões persistentes quando necessário via `--session <nome>` e `--restore`.
- Usar `agent-browser screenshot --annotate` para inspecionar layouts complexos com visão computacional.
- Manter sessões persistentes quando necessário via `--session <modulo> --restore`.
- Utilizar sub-isolamento determinístico (`<modulo-id>-<slug-ou-pid>`) caso múltiplos testes do mesmo módulo ocorram simultaneamente no mesmo host.
- Usar `agent-browser --session <modulo> 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 e Concorrência**: Múltiplos agentes ou módulos rodando 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.
@ -133,4 +146,6 @@ agent-browser close
- 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`

4
skills/plano.executar/SKILL.md
View file

@ -56,7 +56,7 @@ O Orquestrador Líder decompõe a especificação técnica do plano e distribui
| **`@front`** *(Frontend Specialist)* | `*-front`, `*-comuns` | Componentes Vue 3, composables, views, formulários reativos, binding de eventos, consumo de APIs e CSS co-localizado. |
| **`@ux`** *(UX Specialist)* | `*-front` (Interface & Heurísticas) | Aplicação das Heurísticas de Nielsen: visibilidade do estado (spinners, loading, feedback imediato), clareza cognitiva, prevenção de erros e mensagens amigáveis ao usuário. |
| **`@refatorar`** *(Clean Code Specialist)* | Todo o código alterado | Governança estrita das 12 regras de Código Limpo: garantia do **limite de 250 linhas por arquivo**, eliminação de code smells, modularidade e Dispatch Tables. |
| **`@testes`** *(QA & Automation)* | Checagens e Validação E2E | Tipagem (`bun run typecheck` / `tsc --noEmit`), linter (`biome check --write`), governança (`sh .agent/verificar-linhas.sh`) e testes de interface visual via `agent-browser --headed`. |
| **`@testes`** *(QA & Automation)* | Checagens e Validação E2E | Tipagem (`bun run typecheck` / `tsc --noEmit`), linter (`biome check --write`), governança (`sh .agent/verificar-linhas.sh`) e testes de interface visual via `agent-browser --session <modulo> --headed`. |
| **`@documentacao`** *(Memory & Docs)* | `memorias-ia/`, `wiki/` | Registro de sessão no Pilar 6 (`memorias-ia/sessao-*.md`), indexação no `historico-acoes.md`, atualização de regras técnicas na Wiki de Dev (`wiki/dev/<modulo>/`). |
---
@ -80,7 +80,7 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof
↓
4. [@refatorar] Extrai módulos se exceder 250 linhas e aplica Código Limpo
↓
5. [@testes] Roda typecheck, biome e testes E2E com agent-browser --headed
5. [@testes] Roda typecheck, biome e testes E2E com agent-browser --session <modulo> --headed
↓ (Loop /goal de auto-correção se houver falhas)
6. [@documentacao] Atualiza memórias-ia/, historico-acoes.md e arquiva o plano
```

2
skills/plano/SKILL.md
View file

@ -74,7 +74,7 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer
- **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps e arquivos mapeados com links `[arquivo](file://...)`.
- **3. Critérios de Aceite & Validação (DoD):** Checklist com caixas `- [ ]` contendo condições verificáveis de sucesso.
- **4. Especificação Técnica & Passos de Implementação:** Roteiro prático para o desenvolvedor (schemas, backend, frontend, código sugerido).
- **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser`.
- **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session <modulo> --headed`.
- **6. Histórico de Execução:** Cabeçalho reservado para preenchimento na conclusão pelo executor.
- Salve o arquivo em `./PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.md` usando `write_to_file`.

103
skills/testar-interface-agent-browser/SKILL.md
View file

@ -2,7 +2,8 @@
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).
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
---
@ -10,7 +11,16 @@ scope: global
## 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.
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"`.
---
@ -20,7 +30,7 @@ Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na á
- Usar sempre a flag `--headed` na abertura:
```bash
agent-browser open --headed <url>
agent-browser --session "$MODULO" open --headed <url>
```
- Ou exportar no ambiente:
```bash
@ -46,16 +56,19 @@ 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:
### 1. Iniciar Sessão Visível e Isolada
Abra a aplicação frontend mantendo a janela visível e isolada por módulo:
```bash
agent-browser open --headed http://localhost:8080
# 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 snapshot -i
agent-browser --session "$MODULO" snapshot -i
```
*Saída de exemplo:*
```text
@ -69,45 +82,45 @@ agent-browser snapshot -i
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"
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 click @e4
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 wait 1500
agent-browser --session "$MODULO" wait 1500
# Capturar novo snapshot para verificar se a lista ou mensagem apareceu
agent-browser snapshot -i
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 console
agent-browser --session "$MODULO" console
# Verificar requisições de rede falhadas
agent-browser network
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 screenshot evidencias/resultado-sucesso.png
# agent-browser screenshot --annotate evidencias/resultado-anotado.png
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 limpando os processos do daemon:
Finalize a sessão isolada limpando apenas os processos do seu módulo:
```bash
agent-browser close
agent-browser --session "$MODULO" close
```
---
@ -116,20 +129,20 @@ agent-browser close
| 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` |
| **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` |
---
@ -138,14 +151,15 @@ agent-browser close
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 credenciais canônicas de teste de memorias-ia/modulo.yml
# 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
agent-browser fill @e1 "$USUARIO"
agent-browser fill @e2 "$SENHA"
agent-browser click @e3
# 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.
@ -154,16 +168,15 @@ agent-browser click @e3
## Sessões Persistentes e Autenticação
Para fluxos que necessitam manter login ativo entre comandos:
Para fluxos que necessitam manter login ativo entre comandos com isolamento:
```bash
# Iniciar sessão nomeada com auto-restore
agent-browser --session auth-test --restore open --headed http://localhost:8080/login
# 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
agent-browser session info --json
# Verificar status da sessão isolada
agent-browser --session "$MODULO" session info --json
```
---
## Skills Nativas do agent-browser
@ -181,6 +194,6 @@ 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.
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.

5
validar-setup.sh
View file

@ -85,6 +85,11 @@ if [ -f "$MODULO_YML" ]; then
fi
echo -e " ${VERDE}✓${RESET} modulo-wiki resolvido: ${NEGRITO}$MODULO_WIKI${RESET}"
# Exibir convenção de sessão isolada para agent-browser
if [ -n "$MODULO_ID" ]; then
echo -e " ${AZUL}ℹ${RESET} Sessão agent-browser: agent-browser --session ${NEGRITO}$MODULO_ID${RESET}"
fi
# Validar memorias-ia/historico-acoes.md (Pilar 6 - Índice de Ações)
HISTORICO_MD="$ROOT_DIR/memorias-ia/historico-acoes.md"
if [ -f "$HISTORICO_MD" ]; then