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. # 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. # 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 modulo-id: nome-do-modulo.submodulo
# Rota/prefixo utilizado na URL e navegação do módulo (com barras inicial e final) # 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>` - Qualidade/Lint: `biome check --write <arquivos>`
- Governança: `sh .agent/verificar-linhas.sh` - Governança: `sh .agent/verificar-linhas.sh`
### 5.2 Roteiro de Teste Manual / `agent-browser` ### 5.2 Roteiro de Teste Manual / `agent-browser` (Sempre em Modo Visível `--headed` e com `--session <modulo-id>`)
1. Acessar a tela X 1. Abrir aplicação: `agent-browser --session <modulo-id> open --headed <url>`
2. Executar a ação Y 2. Mapear interações: `agent-browser --session <modulo-id> snapshot -i`
3. Validar se o resultado Z ocorre 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 ### agent-browser
- **Descrição:** CLI de automação de navegadores baseada em Rust, projetada especificamente para Agentes de IA. - **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. - **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:** - **Instalação:**
- Com Bun (padrão): `bun i -g agent-browser && agent-browser install` - Com Bun (padrão): `bun i -g agent-browser && agent-browser install`
- Com NPM: `npm install -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 ### agent-browser
- **Descrição:** CLI de automação de navegadores baseada em Rust, projetada especificamente para Agentes de IA. - **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. - **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:** - **Instalação:**
- Com Bun (padrão): `bun i -g agent-browser && agent-browser install` - Com Bun (padrão): `bun i -g agent-browser && agent-browser install`
- Com NPM: `npm install -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 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`) 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`) 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 ## 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 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`) 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`) 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 ## 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 6. Identificar casos extremos e cenários de falha não cobertos
7. Validar schemas Zod contra dados reais de produção 7. Validar schemas Zod contra dados reais de produção
8. Documentar bugs encontrados com passos de reproduçã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`). 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 ## 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? - [ ] Casos extremos (null, vazio, limite) testados?
- [ ] Erros de rede/banco simulados? - [ ] Erros de rede/banco simulados?
- [ ] Performance em volume realista de dados? - [ ] 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 ## 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 6. Identificar casos extremos e cenários de falha não cobertos
7. Validar schemas Zod contra dados reais de produção 7. Validar schemas Zod contra dados reais de produção
8. Documentar bugs encontrados com passos de reproduçã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`). 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 ## 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? - [ ] Casos extremos (null, vazio, limite) testados?
- [ ] Erros de rede/banco simulados? - [ ] Erros de rede/banco simulados?
- [ ] Performance em volume realista de dados? - [ ] 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 ## 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 6. Organizar a hierarquia de informação das telas
7. Revisar labels, placeholders e textos de ajuda 7. Revisar labels, placeholders e textos de ajuda
8. Identificar inconsistências de UX entre módulos 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 ## 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 6. Organizar a hierarquia de informação das telas
7. Revisar labels, placeholders e textos de ajuda 7. Revisar labels, placeholders e textos de ajuda
8. Identificar inconsistências de UX entre módulos 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 ## Restrições

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

@ -51,7 +51,7 @@ modulo-wiki: <caminho-da-wiki>
| Campo | Tipo | Descrição | Exemplo | | 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-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-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` | | **`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 ## Regra Universal de Consulta
Sempre que qualquer agente, persona, workflow ou skill necessitar de: 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; 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; 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; 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 type: rule
name: testes-interface-agent-browser 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 scope: global
trigger: always_on trigger: always_on
updatedAt: "2026-09-16" updatedAt: "2026-10-08"
--- ---
# Regra: Testes Automatizados de Interface e Navegação com agent-browser # 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. 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. 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`)**: 2. **Executar SEMPRE em Modo Visível (`--headed`)**:
- A janela do navegador **deve sempre aparecer na área de trabalho do operador**. - 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. - É **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`. - 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. **Utilizar o modelo de referências (`@ref`)**: 3. **Isolamento Mandatório de Sessão (`--session <modulo>`)**:
- Mapear a tela via `agent-browser snapshot -i`, obtendo referências compactas como `@e1`, `@e2`. - **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"`). - Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
4. **Registrar evidências e fechar sessão**: 5. **Registrar evidências e fechar sessão**:
- Registrar comprovações visuais com `agent-browser screenshot <arquivo.png>`. - Registrar comprovações visuais com `agent-browser --session <modulo> screenshot <arquivo.png>`.
- Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo. - Encerrar graciosamente o navegador com `agent-browser --session <modulo> close` ao término do fluxo.
5. **Credenciais Canônicas de Teste (`modulo-acesso`)**: 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`**. - 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. - É 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 ## 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 ```bash
# Abrir sempre visível ao operador humano # Obter o modulo-id canônico de memorias-ia/modulo.yml
agent-browser open --headed http://localhost:8080 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 ### 2. Inspeção de Elementos Interativos
```bash ```bash
# Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2) # 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 ### 3. Interações por Referência Direta
```bash ```bash
# Interagir diretamente com os elementos identificados no snapshot # Interagir diretamente com os elementos identificados no snapshot
agent-browser fill @e1 "usuario@exemplo.com" agent-browser --session "$MODULO" fill @e1 "usuario@exemplo.com"
agent-browser fill @e2 "senhaSegura123" agent-browser --session "$MODULO" fill @e2 "senhaSegura123"
agent-browser click @e3 agent-browser --session "$MODULO" click @e3
``` ```
### 4. Validação e Evidência ### 4. Validação e Evidência
```bash ```bash
# Aguardar estabilização se houver transição assíncrona # 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 # 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 # 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 # Verificar erros no console do navegador
agent-browser console agent-browser --session "$MODULO" console
``` ```
### 5. Finalização ### 5. Finalização
```bash ```bash
# Fechar a sessão do navegador ao concluir o teste # Fechar a sessão isolada do navegador ao concluir o teste
agent-browser close agent-browser --session "$MODULO" close
``` ```
--- ---
@ -109,20 +119,23 @@ agent-browser close
## Boas Práticas e Proibições ## Boas Práticas e Proibições
### Proibido ❌ ### 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 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 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 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 ✅ ### Permitido e Recomendado ✅
- Manter sessões persistentes quando necessário via `--session <nome>` e `--restore`. - Manter sessões persistentes quando necessário via `--session <modulo> --restore`.
- Usar `agent-browser screenshot --annotate` para inspecionar layouts complexos com visão computacional. - 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`. - Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`.
--- ---
## Impacto ## 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. - **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. - **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. - **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/ - Documentação Oficial: https://agent-browser.dev/
- Skill associada: `skills/testar-interface-agent-browser/SKILL.md` - Skill associada: `skills/testar-interface-agent-browser/SKILL.md`
- Rule associada: `rules/identidade-modulo.md`
- Ferramentas CLI: `.agent/TOOLS` - 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. | | **`@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. | | **`@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. | | **`@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>/`). | | **`@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 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) ↓ (Loop /goal de auto-correção se houver falhas)
6. [@documentacao] Atualiza memórias-ia/, historico-acoes.md e arquiva o plano 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://...)`. - **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. - **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). - **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. - **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`. - 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 name: testar-interface-agent-browser
description: > description: >
Executar testes automatizados de interface (E2E), navegação e validação visual 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 scope: global
--- ---
@ -10,7 +11,16 @@ scope: global
## Objetivo ## 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: - Usar sempre a flag `--headed` na abertura:
```bash ```bash
agent-browser open --headed <url> agent-browser --session "$MODULO" open --headed <url>
``` ```
- Ou exportar no ambiente: - Ou exportar no ambiente:
```bash ```bash
@ -46,16 +56,19 @@ Documentação oficial: **https://agent-browser.dev/**
## Fluxo Operacional Passo a Passo ## Fluxo Operacional Passo a Passo
### 1. Iniciar Sessão Visível ### 1. Iniciar Sessão Visível e Isolada
Abra a aplicação frontend mantendo a janela visível ao operador: Abra a aplicação frontend mantendo a janela visível e isolada por módulo:
```bash ```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 ### 2. Obter Snapshot Interativo
Gere a árvore de acessibilidade enxuta com referências numéricas: Gere a árvore de acessibilidade enxuta com referências numéricas:
```bash ```bash
agent-browser snapshot -i agent-browser --session "$MODULO" snapshot -i
``` ```
*Saída de exemplo:* *Saída de exemplo:*
```text ```text
@ -69,45 +82,45 @@ agent-browser snapshot -i
Utilize as referências identificadas (`@e1`, `@e2`, etc.): Utilize as referências identificadas (`@e1`, `@e2`, etc.):
```bash ```bash
# Preenchimento de campos de texto # Preenchimento de campos de texto
agent-browser fill @e2 "12.345.678/0001-90" agent-browser --session "$MODULO" fill @e2 "12.345.678/0001-90"
agent-browser fill @e3 "Indústria Modelo LTDA" agent-browser --session "$MODULO" fill @e3 "Indústria Modelo LTDA"
# Acionamento de botões e links # Acionamento de botões e links
agent-browser click @e4 agent-browser --session "$MODULO" click @e4
``` ```
### 4. Aguardar Transição e Validar Estado ### 4. Aguardar Transição e Validar Estado
Se a ação disparar chamada assíncrona ou animação, aguarde a estabilização: Se a ação disparar chamada assíncrona ou animação, aguarde a estabilização:
```bash ```bash
# Aguardar 1 a 2 segundos # 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 # 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 ### 5. Verificar Logs de Erro no Console e Rede
Assegure que nenhum erro de script ou requisição 500 ocorreu silenciosamente: Assegure que nenhum erro de script ou requisição 500 ocorreu silenciosamente:
```bash ```bash
# Inspecionar mensagens do console do browser # Inspecionar mensagens do console do browser
agent-browser console agent-browser --session "$MODULO" console
# Verificar requisições de rede falhadas # Verificar requisições de rede falhadas
agent-browser network agent-browser --session "$MODULO" network
``` ```
### 6. Registrar Evidência Visual ### 6. Registrar Evidência Visual
Capture um screenshot para comprovação do resultado do teste: Capture um screenshot para comprovação do resultado do teste:
```bash ```bash
# Screenshot padrão ou anotado com identificadores visuais # Screenshot padrão ou anotado com identificadores visuais
agent-browser screenshot evidencias/resultado-sucesso.png agent-browser --session "$MODULO" screenshot evidencias/resultado-sucesso.png
# agent-browser screenshot --annotate evidencias/resultado-anotado.png # agent-browser --session "$MODULO" screenshot --annotate evidencias/resultado-anotado.png
``` ```
### 7. Encerrar Navegador ### 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 ```bash
agent-browser close agent-browser --session "$MODULO" close
``` ```
--- ---
@ -116,32 +129,52 @@ agent-browser close
| Ação | Comando | | Ação | Comando |
|---|---| |---|---|
| **Abrir tela (visível)** | `agent-browser open --headed <url>` | | **Abrir tela (visível)** | `agent-browser --session <modulo> open --headed <url>` |
| **Snapshot de elementos** | `agent-browser snapshot -i` | | **Snapshot de elementos** | `agent-browser --session <modulo> snapshot -i` |
| **Clicar elemento** | `agent-browser click @ref` | | **Clicar elemento** | `agent-browser --session <modulo> click @ref` |
| **Preencher campo** | `agent-browser fill @ref "valor"` | | **Preencher campo** | `agent-browser --session <modulo> fill @ref "valor"` |
| **Selecionar dropdown** | `agent-browser select @ref "opcao"` | | **Selecionar dropdown** | `agent-browser --session <modulo> select @ref "opcao"` |
| **Pressionar tecla** | `agent-browser press Enter` | | **Pressionar tecla** | `agent-browser --session <modulo> press Enter` |
| **Obter texto** | `agent-browser get text @ref` | | **Obter texto** | `agent-browser --session <modulo> get text @ref` |
| **Aguardar tempo** | `agent-browser wait <ms>` | | **Aguardar tempo** | `agent-browser --session <modulo> wait <ms>` |
| **Aguardar seletor** | `agent-browser wait --selector "<seletor>"` | | **Aguardar seletor** | `agent-browser --session <modulo> wait --selector "<seletor>"` |
| **Inspecionar console** | `agent-browser console` | | **Inspecionar console** | `agent-browser --session <modulo> console` |
| **Inspecionar rede** | `agent-browser network` | | **Inspecionar rede** | `agent-browser --session <modulo> network` |
| **Screenshot** | `agent-browser screenshot <arquivo.png>` | | **Screenshot** | `agent-browser --session <modulo> screenshot <arquivo.png>` |
| **Auditoria a11y (WCAG)** | `agent-browser a11y` | | **Auditoria a11y (WCAG)** | `agent-browser --session <modulo> a11y` |
| **Fechar sessão** | `agent-browser close` | | **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 ## 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 ```bash
# Iniciar sessão nomeada com auto-restore # Iniciar sessão nomeada com auto-restore no escopo do módulo
agent-browser --session auth-test --restore open --headed http://localhost:8080/login agent-browser --session "$MODULO" --restore open --headed http://localhost:8080/login
# Verificar status da sessão # Verificar status da sessão isolada
agent-browser session info --json 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) ## 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`. 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 wait 500 && agent-browser snapshot -i` para interagir com o conteúdo do diálogo. 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. 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`. - **`@front`**: Implementa telas Vue 3, composables e formulários consumindo `*-comuns`.
- **`@ux`**: Aplica as Heurísticas de Nielsen (visibilidade de loading/erro, feedback imediato). - **`@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). - **`@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. - **`@documentacao`**: Documenta a memória da sessão (Pilar 6) e regras de negócio.
### 3. Modos de Invocação ### 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 | | 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-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-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` | | **`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 ## Regra Universal de Consulta
Sempre que qualquer agente, persona, workflow ou skill necessitar de: 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; 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; 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; 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 type: rule
name: testes-interface-agent-browser 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 scope: global
trigger: always_on trigger: always_on
updatedAt: "2026-09-16" updatedAt: "2026-10-08"
--- ---
# Regra: Testes Automatizados de Interface e Navegação com agent-browser # 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. 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. 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`)**: 2. **Executar SEMPRE em Modo Visível (`--headed`)**:
- A janela do navegador **deve sempre aparecer na área de trabalho do operador**. - 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. - É **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`. - 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. **Utilizar o modelo de referências (`@ref`)**: 3. **Isolamento Mandatório de Sessão (`--session <modulo>`)**:
- Mapear a tela via `agent-browser snapshot -i`, obtendo referências compactas como `@e1`, `@e2`. - **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"`). - Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
4. **Registrar evidências e fechar sessão**: 5. **Registrar evidências e fechar sessão**:
- Registrar comprovações visuais com `agent-browser screenshot <arquivo.png>`. - Registrar comprovações visuais com `agent-browser --session <modulo> screenshot <arquivo.png>`.
- Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo. - Encerrar graciosamente o navegador com `agent-browser --session <modulo> close` ao término do fluxo.
5. **Credenciais Canônicas de Teste (`modulo-acesso`)**: 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`**. - 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. - É 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 ## 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 ```bash
# Abrir sempre visível ao operador humano # Obter o modulo-id canônico de memorias-ia/modulo.yml
agent-browser open --headed http://localhost:8080 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 ### 2. Inspeção de Elementos Interativos
```bash ```bash
# Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2) # 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 ### 3. Interações por Referência Direta
```bash ```bash
# Interagir diretamente com os elementos identificados no snapshot # Interagir diretamente com os elementos identificados no snapshot
agent-browser fill @e1 "usuario@exemplo.com" agent-browser --session "$MODULO" fill @e1 "usuario@exemplo.com"
agent-browser fill @e2 "senhaSegura123" agent-browser --session "$MODULO" fill @e2 "senhaSegura123"
agent-browser click @e3 agent-browser --session "$MODULO" click @e3
``` ```
### 4. Validação e Evidência ### 4. Validação e Evidência
```bash ```bash
# Aguardar estabilização se houver transição assíncrona # 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 # 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 # 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 # Verificar erros no console do navegador
agent-browser console agent-browser --session "$MODULO" console
``` ```
### 5. Finalização ### 5. Finalização
```bash ```bash
# Fechar a sessão do navegador ao concluir o teste # Fechar a sessão isolada do navegador ao concluir o teste
agent-browser close agent-browser --session "$MODULO" close
``` ```
--- ---
@ -109,20 +119,23 @@ agent-browser close
## Boas Práticas e Proibições ## Boas Práticas e Proibições
### Proibido ❌ ### 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 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 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 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 ✅ ### Permitido e Recomendado ✅
- Manter sessões persistentes quando necessário via `--session <nome>` e `--restore`. - Manter sessões persistentes quando necessário via `--session <modulo> --restore`.
- Usar `agent-browser screenshot --annotate` para inspecionar layouts complexos com visão computacional. - 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`. - Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`.
--- ---
## Impacto ## 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. - **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. - **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. - **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/ - Documentação Oficial: https://agent-browser.dev/
- Skill associada: `skills/testar-interface-agent-browser/SKILL.md` - Skill associada: `skills/testar-interface-agent-browser/SKILL.md`
- Rule associada: `rules/identidade-modulo.md`
- Ferramentas CLI: `.agent/TOOLS` - 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. | | **`@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. | | **`@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. | | **`@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>/`). | | **`@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 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) ↓ (Loop /goal de auto-correção se houver falhas)
6. [@documentacao] Atualiza memórias-ia/, historico-acoes.md e arquiva o plano 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://...)`. - **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. - **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). - **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. - **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`. - 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 name: testar-interface-agent-browser
description: > description: >
Executar testes automatizados de interface (E2E), navegação e validação visual 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 scope: global
--- ---
@ -10,7 +11,16 @@ scope: global
## Objetivo ## 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: - Usar sempre a flag `--headed` na abertura:
```bash ```bash
agent-browser open --headed <url> agent-browser --session "$MODULO" open --headed <url>
``` ```
- Ou exportar no ambiente: - Ou exportar no ambiente:
```bash ```bash
@ -46,16 +56,19 @@ Documentação oficial: **https://agent-browser.dev/**
## Fluxo Operacional Passo a Passo ## Fluxo Operacional Passo a Passo
### 1. Iniciar Sessão Visível ### 1. Iniciar Sessão Visível e Isolada
Abra a aplicação frontend mantendo a janela visível ao operador: Abra a aplicação frontend mantendo a janela visível e isolada por módulo:
```bash ```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 ### 2. Obter Snapshot Interativo
Gere a árvore de acessibilidade enxuta com referências numéricas: Gere a árvore de acessibilidade enxuta com referências numéricas:
```bash ```bash
agent-browser snapshot -i agent-browser --session "$MODULO" snapshot -i
``` ```
*Saída de exemplo:* *Saída de exemplo:*
```text ```text
@ -69,45 +82,45 @@ agent-browser snapshot -i
Utilize as referências identificadas (`@e1`, `@e2`, etc.): Utilize as referências identificadas (`@e1`, `@e2`, etc.):
```bash ```bash
# Preenchimento de campos de texto # Preenchimento de campos de texto
agent-browser fill @e2 "12.345.678/0001-90" agent-browser --session "$MODULO" fill @e2 "12.345.678/0001-90"
agent-browser fill @e3 "Indústria Modelo LTDA" agent-browser --session "$MODULO" fill @e3 "Indústria Modelo LTDA"
# Acionamento de botões e links # Acionamento de botões e links
agent-browser click @e4 agent-browser --session "$MODULO" click @e4
``` ```
### 4. Aguardar Transição e Validar Estado ### 4. Aguardar Transição e Validar Estado
Se a ação disparar chamada assíncrona ou animação, aguarde a estabilização: Se a ação disparar chamada assíncrona ou animação, aguarde a estabilização:
```bash ```bash
# Aguardar 1 a 2 segundos # 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 # 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 ### 5. Verificar Logs de Erro no Console e Rede
Assegure que nenhum erro de script ou requisição 500 ocorreu silenciosamente: Assegure que nenhum erro de script ou requisição 500 ocorreu silenciosamente:
```bash ```bash
# Inspecionar mensagens do console do browser # Inspecionar mensagens do console do browser
agent-browser console agent-browser --session "$MODULO" console
# Verificar requisições de rede falhadas # Verificar requisições de rede falhadas
agent-browser network agent-browser --session "$MODULO" network
``` ```
### 6. Registrar Evidência Visual ### 6. Registrar Evidência Visual
Capture um screenshot para comprovação do resultado do teste: Capture um screenshot para comprovação do resultado do teste:
```bash ```bash
# Screenshot padrão ou anotado com identificadores visuais # Screenshot padrão ou anotado com identificadores visuais
agent-browser screenshot evidencias/resultado-sucesso.png agent-browser --session "$MODULO" screenshot evidencias/resultado-sucesso.png
# agent-browser screenshot --annotate evidencias/resultado-anotado.png # agent-browser --session "$MODULO" screenshot --annotate evidencias/resultado-anotado.png
``` ```
### 7. Encerrar Navegador ### 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 ```bash
agent-browser close agent-browser --session "$MODULO" close
``` ```
--- ---
@ -116,20 +129,20 @@ agent-browser close
| Ação | Comando | | Ação | Comando |
|---|---| |---|---|
| **Abrir tela (visível)** | `agent-browser open --headed <url>` | | **Abrir tela (visível)** | `agent-browser --session <modulo> open --headed <url>` |
| **Snapshot de elementos** | `agent-browser snapshot -i` | | **Snapshot de elementos** | `agent-browser --session <modulo> snapshot -i` |
| **Clicar elemento** | `agent-browser click @ref` | | **Clicar elemento** | `agent-browser --session <modulo> click @ref` |
| **Preencher campo** | `agent-browser fill @ref "valor"` | | **Preencher campo** | `agent-browser --session <modulo> fill @ref "valor"` |
| **Selecionar dropdown** | `agent-browser select @ref "opcao"` | | **Selecionar dropdown** | `agent-browser --session <modulo> select @ref "opcao"` |
| **Pressionar tecla** | `agent-browser press Enter` | | **Pressionar tecla** | `agent-browser --session <modulo> press Enter` |
| **Obter texto** | `agent-browser get text @ref` | | **Obter texto** | `agent-browser --session <modulo> get text @ref` |
| **Aguardar tempo** | `agent-browser wait <ms>` | | **Aguardar tempo** | `agent-browser --session <modulo> wait <ms>` |
| **Aguardar seletor** | `agent-browser wait --selector "<seletor>"` | | **Aguardar seletor** | `agent-browser --session <modulo> wait --selector "<seletor>"` |
| **Inspecionar console** | `agent-browser console` | | **Inspecionar console** | `agent-browser --session <modulo> console` |
| **Inspecionar rede** | `agent-browser network` | | **Inspecionar rede** | `agent-browser --session <modulo> network` |
| **Screenshot** | `agent-browser screenshot <arquivo.png>` | | **Screenshot** | `agent-browser --session <modulo> screenshot <arquivo.png>` |
| **Auditoria a11y (WCAG)** | `agent-browser a11y` | | **Auditoria a11y (WCAG)** | `agent-browser --session <modulo> a11y` |
| **Fechar sessão** | `agent-browser close` | | **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`: 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 ```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}') 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}') SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
# Preenchimento determinístico no formulário de login # Preenchimento determinístico no formulário de login na sessão isolada
agent-browser fill @e1 "$USUARIO" agent-browser --session "$MODULO" fill @e1 "$USUARIO"
agent-browser fill @e2 "$SENHA" agent-browser --session "$MODULO" fill @e2 "$SENHA"
agent-browser click @e3 agent-browser --session "$MODULO" click @e3
``` ```
> ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste. > ⚠️ **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 ## 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 ```bash
# Iniciar sessão nomeada com auto-restore # Iniciar sessão nomeada com auto-restore no escopo do módulo
agent-browser --session auth-test --restore open --headed http://localhost:8080/login agent-browser --session "$MODULO" --restore open --headed http://localhost:8080/login
# Verificar status da sessão # Verificar status da sessão isolada
agent-browser session info --json agent-browser --session "$MODULO" session info --json
``` ```
--- ---
## Skills Nativas do agent-browser ## Skills Nativas do agent-browser
@ -181,6 +194,6 @@ agent-browser skills get dogfood
## Boas Práticas no Ecossistema Azteca (Vue 3 / Vuetify) ## 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`. 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 wait 500 && agent-browser snapshot -i` para interagir com o conteúdo do diálogo. 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. 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 fi
echo -e " ${VERDE}✓${RESET} modulo-wiki resolvido: ${NEGRITO}$MODULO_WIKI${RESET}" 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) # Validar memorias-ia/historico-acoes.md (Pilar 6 - Índice de Ações)
HISTORICO_MD="$ROOT_DIR/memorias-ia/historico-acoes.md" HISTORICO_MD="$ROOT_DIR/memorias-ia/historico-acoes.md"
if [ -f "$HISTORICO_MD" ]; then if [ -f "$HISTORICO_MD" ]; then