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

context agent

Browse source
This commit is contained in:
Luiz Silva 2026-10-08 15:08:09 -03:00
parent 29e5bc979e
commit f47e12fe81
23 changed files with 347 additions and 226 deletions
Download patch file Download diff file Expand all files Collapse all files

18
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>/, regras de negócio e sessão isolada do agent-browser --session <modulo-id>) # 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>_<contexto?>)
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)
@ -14,10 +14,24 @@ modulo-descricao: Descrição detalhada do módulo para contextualização opera
# Descrição da arquitetura, stack tecnológica e banco de dados # Descrição da arquitetura, stack tecnológica e banco de dados
modulo-tipo: aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres modulo-tipo: aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres
# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA) # Credenciais para autenticação em testes (agent-browser, E2E, QA)
# Formato Simples (aplicação com perfil único de acesso):
modulo-acesso: modulo-acesso:
usuario: usuario@exemplo.com.br usuario: usuario@exemplo.com.br
senha: "123" senha: "123"
# Ou Formato Multi-Contexto (quando a aplicação possui acessos distintos - evita mistura de tokens):
# modulo-acesso:
# interno:
# usuario: operador@empresa.com.br
# senha: "123"
# cliente:
# usuario: cliente@cliente.com.br
# senha: "123"
# externo:
# usuario: cidadao@gov.br
# senha: "123"
# anonimo: null # acesso público/deslogado
# Caminho para a Wiki do projeto (quando omitido ou vazio, o padrão adotado é ../wiki/) # Caminho para a Wiki do projeto (quando omitido ou vazio, o padrão adotado é ../wiki/)
modulo-wiki: ../wiki modulo-wiki: ../wiki

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

@ -90,12 +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` (Sempre em Modo Visível `--headed` e com `--session <modulo-id>`) ### 5.2 Roteiro de Teste Manual / `agent-browser` (Sempre em Modo Visível `--headed` e com `--session <modulo-id>_<contexto?>`)
1. Abrir aplicação: `agent-browser --session <modulo-id> open --headed <url>` 1. Abrir aplicação: `agent-browser --session <modulo-id>_<contexto?> open --headed <url>`
2. Mapear interações: `agent-browser --session <modulo-id> snapshot -i` 2. Mapear interações: `agent-browser --session <modulo-id>_<contexto?> snapshot -i`
3. Executar ações: `agent-browser --session <modulo-id> fill @ref "..." && agent-browser --session <modulo-id> click @ref` 3. Executar ações: `agent-browser --session <modulo-id>_<contexto?> fill @ref "..." && agent-browser --session <modulo-id>_<contexto?> click @ref`
4. Capturar evidência: `agent-browser --session <modulo-id> screenshot evidencias/<slug>.png` 4. Capturar evidência: `agent-browser --session <modulo-id>_<contexto?> screenshot evidencias/<slug>.png`
5. Encerrar: `agent-browser --session <modulo-id> close` 5. Encerrar: `agent-browser --session <modulo-id>_<contexto?> close`
--- ---

4
TOOLS
View file

@ -94,8 +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 --session <modulo> 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>_<contexto?> 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. - **Isolamento Mandatório de Sessão e Contexto:** Toda execução DEVE acompanhar a flag `--session <modulo>_<contexto?>` (onde `<modulo>` é o `modulo-id` extraído de `memorias-ia/modulo.yml` e `<contexto?>` discrimina acessos como `interno`, `externo`, `cliente`, `anonimo`) ou garantir `export AGENT_BROWSER_SESSION=<modulo>_<contexto?>`. Previne fechamento indevido de processos e contaminação cruzada de cookies e tokens JWT entre diferentes perfis de usuário.
- **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`

4
TOOLS.md
View file

@ -94,8 +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 --session <modulo> 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>_<contexto?> 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. - **Isolamento Mandatório de Sessão e Contexto:** Toda execução DEVE acompanhar a flag `--session <modulo>_<contexto?>` (onde `<modulo>` é o `modulo-id` extraído de `memorias-ia/modulo.yml` e `<contexto?>` discrimina acessos como `interno`, `externo`, `cliente`, `anonimo`) ou garantir `export AGENT_BROWSER_SESSION=<modulo>_<contexto?>`. Previne fechamento indevido de processos e contaminação cruzada de cookies e tokens JWT entre diferentes perfis de usuário.
- **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`) 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`) 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 e contexto (`--session <modulo-id>_<contexto?>`)** para acompanhamento do operador e prevenção de mistura de tokens e conflitos de sessão (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`) 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`) 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 e contexto (`--session <modulo-id>_<contexto?>`)** para acompanhamento do operador e prevenção de mistura de tokens e conflitos de sessão (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`) 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`) 9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session <modulo-id>_<contexto?>`)** para que o operador acompanhe cada ação na tela e evitar mistura de tokens/cookies entre acessos interno, cliente, externo e anônimo (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`) e com sessão isolada (`--session <modulo-id>`), com screenshots comprobatórios? - [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) e com sessão isolada por contexto (`--session <modulo-id>_<contexto?>`), 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`) 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`) 9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session <modulo-id>_<contexto?>`)** para que o operador acompanhe cada ação na tela e evitar mistura de tokens/cookies entre acessos interno, cliente, externo e anônimo (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`) e com sessão isolada (`--session <modulo-id>`), com screenshots comprobatórios? - [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) e com sessão isolada por contexto (`--session <modulo-id>_<contexto?>`), 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`) 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`) 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 e contexto (`--session <modulo-id>_<contexto?>`)** para que o operador acompanhe a validação visual e evitar mistura de tokens e estados de interface (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`) 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`) 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 e contexto (`--session <modulo-id>_<contexto?>`)** para que o operador acompanhe a validação visual e evitar mistura de tokens e estados de interface (ver `rules/testes-interface-agent-browser.md`)
## Restrições ## Restrições

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

@ -5,7 +5,7 @@ description: Identificação obrigatória do projeto/módulo via memorias-ia/mod
scope: global scope: global
trigger: always_on trigger: always_on
priority: critica priority: critica
updatedAt: "2026-10-06" updatedAt: "2026-10-08"
--- ---
# Regra: Identidade do Projeto via `memorias-ia/modulo.yml` # Regra: Identidade do Projeto via `memorias-ia/modulo.yml`
@ -38,11 +38,25 @@ modulo-caminho: <rota-na-url>
modulo-descricao: <texto-descritivo> modulo-descricao: <texto-descritivo>
modulo-tipo: <texto-tipo-arquitetura> modulo-tipo: <texto-tipo-arquitetura>
# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA) # Credenciais para autenticação em testes (agent-browser, E2E, QA)
# Formato Simples (aplicação com contexto único de acesso):
modulo-acesso: modulo-acesso:
usuario: <login-ou-email> usuario: <login-ou-email>
senha: <senha-de-teste> senha: <senha-de-teste>
# Ou Formato Multi-Contexto (quando a aplicação possui acessos distintos - evita mistura de tokens):
# modulo-acesso:
# interno:
# usuario: <login-operador>
# senha: <senha-operador>
# cliente:
# usuario: <login-cliente>
# senha: <senha-cliente>
# externo:
# usuario: <login-cidadao>
# senha: <senha-cidadao>
# anonimo: null # acesso público/deslogado
# Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/) # Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/)
modulo-wiki: <caminho-da-wiki> modulo-wiki: <caminho-da-wiki>
``` ```
@ -51,11 +65,11 @@ 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, 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-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 prefixo da sessão isolada no `agent-browser` (`--session <modulo-id>_<contexto?>`). | `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` |
| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`). | `{ usuario: "admin@gov.br", senha: "123" }` | | **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) ou organizadas por contexto (`interno`, `externo`, `cliente`, `anonimo`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`), prevenindo mistura de tokens. | `{ usuario: "admin@gov.br", senha: "123" }` ou subchaves de contexto |
| **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` | | **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` |
--- ---
@ -63,10 +77,10 @@ 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/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session <modulo-id>`)**; 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>_<contexto?>`)**;
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 as credenciais do contexto específico (`interno`, `externo`, `cliente`, etc.) ou credenciais diretas de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística sem contaminação de cookies/tokens entre perfis;
5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia; 5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia;
6. **Sincronização do Submódulo (`.agent`)**: Ao iniciar qualquer sessão ou interação no projeto hospedeiro, o agente DEVE assegurar que o submódulo `.agent` esteja atualizado com a branch `master` remota executando `git submodule update --init --recursive --remote`. 6. **Sincronização do Submódulo (`.agent`)**: Ao iniciar qualquer sessão ou interação no projeto hospedeiro, o agente DEVE assegurar que o submódulo `.agent` esteja atualizado com a branch `master` remota executando `git submodule update --init --recursive --remote`.

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

@ -1,7 +1,7 @@
--- ---
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) e com isolamento por sessão (--session <modulo>). description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) e com isolamento por sessão e contexto (--session <modulo>_<contexto?>).
scope: global scope: global
trigger: always_on trigger: always_on
updatedAt: "2026-10-08" updatedAt: "2026-10-08"
@ -13,7 +13,7 @@ updatedAt: "2026-10-08"
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. Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Para viabilizar testes concorrentes e evitar interferências mútuas entre múltiplos módulos ou workspaces, todo comando deve operar em sessão isolada identificada pelo módulo e pelo contexto de acesso.
Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA. 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.
@ -27,24 +27,38 @@ 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 --session <modulo> 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>_<contexto?> open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
3. **Isolamento Mandatório de Sessão (`--session <modulo>`)**: 3. **Isolamento Mandatório de Sessão e Contexto (`--session <modulo>_<contexto?>`)**:
- **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo. - **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo e o contexto de acesso.
- Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>`. - Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml` e `<contexto?>` discrimina o papel ou natureza do acesso), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto?>`.
- 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. - **Prevenção de Mistura de Tokens:** Caso a aplicação possua mais de um tipo de acesso (`interno`, `externo`, `anonimo`, `cliente`, etc.), o `<contexto>` **DEVE SER OBRIGATORIAMENTE PREENCHIDO** para evitar que cookies, tokens JWT e estados de login residuais contaminem outros fluxos de teste.
- Caso um mesmo módulo necessite de sub-isolamento para testes paralelos, deve-se adotar o sufixo determinístico `<modulo-id>-<slug-ou-pid>`. - Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>_<contexto>.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos.
- Caso um mesmo módulo e contexto necessite de sub-isolamento para testes paralelos, adota-se o discriminador determinístico: `<modulo>_<contexto>_<slug-ou-pid>`.
4. **Utilizar o modelo de referências (`@ref`)**: 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`. - Mapear a tela via `agent-browser --session <modulo>_<contexto?> snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
- Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`). - Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
5. **Registrar evidências e fechar sessão**: 5. **Registrar evidências e fechar sessão**:
- Registrar comprovações visuais com `agent-browser --session <modulo> screenshot <arquivo.png>`. - Registrar comprovações visuais com `agent-browser --session <modulo>_<contexto?> screenshot <arquivo.png>`.
- Encerrar graciosamente o navegador com `agent-browser --session <modulo> close` ao término do fluxo. - Encerrar graciosamente o navegador com `agent-browser --session <modulo>_<contexto?> close` ao término do fluxo.
6. **Credenciais Canônicas de Teste (`modulo-acesso`)**: 6. **Credenciais Canônicas por Contexto (`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, o agente **DEVE OBRIGATORIAMENTE extrair as credenciais do contexto específico** em `modulo-acesso` de `memorias-ia/modulo.yml` (ex: `modulo-acesso.interno`, `modulo-acesso.cliente`, etc.).
- Para sessões anônimas (`_anonimo`), nenhum login deve ser realizado, garantindo a validação da experiência do usuário público sem tokens.
- É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste. - É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.
--- ---
## 🔒 Contextos Canônicos de Sessão (`<modulo>_<contexto>`)
| Contexto | Finalidade e Natureza | Exemplo de Sessão | Credenciais em `modulo.yml` |
| :--- | :--- | :--- | :--- |
| **`interno`** | Operador interno, suporte, técnico, atendente, administrador | `--session <modulo>_interno` | `modulo-acesso.interno` (ou `modulo-acesso` simples) |
| **`cliente`** | Cliente final, solicitante corporativo, empresa contratante | `--session <modulo>_cliente` | `modulo-acesso.cliente` |
| **`externo`** | Portal público autenticado, cidadão, requerente externo | `--session <modulo>_externo` | `modulo-acesso.externo` |
| **`anonimo`** | Usuário deslogado, consulta pública por código, login, landing | `--session <modulo>_anonimo` | Nenhuma (perfil limpo sem cookies/tokens) |
| **`<especifico>`** | Papel especializado de domínio (ex: `fiscal`, `auditor`) | `--session <modulo>_<papel>` | `modulo-acesso.<papel>` |
---
## Instalação e Configuração ## Instalação e Configuração
O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium: O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium:
@ -63,55 +77,56 @@ 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 com isolamento de sessão: Todo teste ou navegação de interface executado pela IA deve seguir o fluxo com isolamento de sessão e contexto:
### 1. Obter Identificador do Módulo e Abertura com Janela Visível ### 1. Obter Identificador do Módulo e Abertura com Janela Visível
```bash ```bash
# Obter o modulo-id canônico de memorias-ia/modulo.yml # Obter o modulo-id canônico de memorias-ia/modulo.yml
MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}') MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
CONTEXTO="interno" # ou "cliente", "externo", "anonimo"
# Abrir sempre visível ao operador humano na sessão isolada do módulo # Abrir sempre visível ao operador na sessão isolada por módulo e contexto
agent-browser --session "$MODULO" open --headed http://localhost:8080 agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" snapshot -i agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" fill @e1 "usuario@exemplo.com" agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "usuario@exemplo.com"
agent-browser --session "$MODULO" fill @e2 "senhaSegura123" agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "senhaSegura123"
agent-browser --session "$MODULO" click @e3 agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" wait 1000 agent-browser --session "${MODULO}_${CONTEXTO}" wait 1000
# Obter novo snapshot para verificar estado pós-ação # Obter novo snapshot para verificar estado pós-ação
agent-browser --session "$MODULO" snapshot -i agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i
# Capturar evidência gráfica do teste # Capturar evidência gráfica do teste
agent-browser --session "$MODULO" screenshot evidencias/teste-login-sucesso.png agent-browser --session "${MODULO}_${CONTEXTO}" screenshot evidencias/teste-login-sucesso.png
# Verificar erros no console do navegador # Verificar erros no console do navegador
agent-browser --session "$MODULO" console agent-browser --session "${MODULO}_${CONTEXTO}" console
``` ```
### 5. Finalização ### 5. Finalização
```bash ```bash
# Fechar a sessão isolada do navegador ao concluir o teste # Fechar a sessão isolada do navegador ao concluir o fluxo daquele contexto
agent-browser --session "$MODULO" close agent-browser --session "${MODULO}_${CONTEXTO}" close
``` ```
--- ---
@ -119,23 +134,25 @@ agent-browser --session "$MODULO" 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 executar sem a flag `--session <modulo>_<contexto?>`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada.
- **Proibido misturar acessos com perfis diferentes na mesma sessão genérica sem contexto** (ex: logar como operador interno e depois testar fluxo de cliente ou anônimo na mesma sessão, causando mistura de tokens).
- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`. - **Proibido 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 órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <modulo> close`). - **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <modulo>_<contexto?> close`).
### Permitido e Recomendado ✅ ### Permitido e Recomendado ✅
- Manter sessões persistentes quando necessário via `--session <modulo> --restore`. - Manter sessões persistentes por contexto quando necessário via `--session <modulo>_<contexto> --restore`.
- Utilizar sub-isolamento determinístico (`<modulo-id>-<slug-ou-pid>`) caso múltiplos testes do mesmo módulo ocorram simultaneamente no mesmo host. - Utilizar sub-isolamento determinístico (`<modulo>_<contexto>_<slug-ou-pid>`) caso múltiplos testes do mesmo contexto ocorram simultaneamente no mesmo host.
- Usar `agent-browser --session <modulo> screenshot --annotate` para inspecionar layouts complexos com visão computacional. - Usar `agent-browser --session <modulo>_<contexto> screenshot --annotate` para inspecionar layouts complexos com visão computacional.
- Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`. - 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. - **Isolamento de Tokens e Cookies**: Evita vazamento de credenciais e estados de autenticação entre acessos de operador interno, cliente corporativo, cidadão e visitante anônimo.
- **Isolamento e Concorrência**: Múltiplos agentes ou testes E2E simultâneos não conflitam de abas nem fecham janelas alheias.
- **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real. - **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.
@ -148,4 +165,3 @@ agent-browser --session "$MODULO" close
- Skill associada: `skills/testar-interface-agent-browser/SKILL.md` - Skill associada: `skills/testar-interface-agent-browser/SKILL.md`
- Rule associada: `rules/identidade-modulo.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 --session <modulo> --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>_<contexto?> --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 --session <modulo> --headed 5. [@testes] Roda typecheck, biome e testes E2E com agent-browser --session <modulo>_<contexto?> --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 --session <modulo> --headed`. - **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session <modulo>_<contexto?> --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`.

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

@ -3,7 +3,7 @@ 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>). e isolamento mandatório de sessão e contexto (--session <modulo>_<contexto?>).
scope: global scope: global
--- ---
@ -11,16 +11,31 @@ 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 isolamento total entre processos e visualização em tempo real pelo operador humano. 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 de cookies, tokens e processos, com visualização em tempo real pelo operador humano.
--- ---
## 🔒 Princípio de Isolamento de Sessão por Módulo (`--session <modulo>`) ## 🔒 Princípio de Isolamento de Sessão e Contexto (`--session <modulo>_<contexto?>`)
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`: O daemon do `agent-browser` aloca sockets Unix dedicados e armazena cookies HTTP, tokens JWT (em cabeçalhos, cookies ou `localStorage`/`sessionStorage`) e estados de autenticação independentes por sessão.
- **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>`. Para evitar contaminação cruzada de credenciais, interferência mútua entre módulos ou encerramento indevido de processos via `agent-browser close`:
- Caso múltiplos fluxos de teste concorrentes rodem no mesmo módulo, utilizar sufixo discriminador determinístico: `--session "${MODULO}-subfluxo"`.
- **Todo comando DEVE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico de `memorias-ia/modulo.yml` e `<contexto?>` identifica o papel ou perfil de acesso), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto?>`.
- **Prevenção Obrigatória de Mistura de Tokens:** Caso a aplicação possua mais de um tipo de acesso (`interno`, `externo`, `anonimo`, `cliente`, etc.), o `<contexto>` **DEVE SER OBRIGATORIAMENTE PREENCHIDO**. Exemplo: um teste logado como operador `interno` nunca deve compartilhar a mesma sessão de um teste de rota pública `anonimo` ou de acesso do `cliente`.
- **Sub-isolamento para concorrência:** Caso múltiplos fluxos de teste concorrentes do mesmo papel rodem simultaneamente, utilizar sufixo discriminador determinístico: `--session "${MODULO}_${CONTEXTO}_${SLUG_OU_PID}"`.
---
## 🧭 Contextos Canônicos de Sessão
| Contexto | Finalidade e Escopo | Exemplo de Sessão | Fonte de Credenciais |
| :--- | :--- | :--- | :--- |
| **`interno`** | Operador interno, suporte, técnico, atendente, administrador | `--session <modulo>_interno` | `modulo-acesso.interno` (ou `modulo-acesso` simples) |
| **`cliente`** | Solicitante corporativo, empresa cliente, contratante | `--session <modulo>_cliente` | `modulo-acesso.cliente` |
| **`externo`** | Portal público autenticado, cidadão, requerente externo | `--session <modulo>_externo` | `modulo-acesso.externo` |
| **`anonimo`** | Usuário deslogado, consulta pública, login, landing page | `--session <modulo>_anonimo` | Nenhuma (perfil limpo sem cookies/tokens) |
| **`<especifico>`** | Papel especializado de domínio (ex: `fiscal`, `auditor`) | `--session <modulo>_<papel>` | `modulo-acesso.<papel>` |
--- ---
@ -30,7 +45,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 --session "$MODULO" open --headed <url> agent-browser --session "${MODULO}_${CONTEXTO}" open --headed <url>
``` ```
- Ou exportar no ambiente: - Ou exportar no ambiente:
```bash ```bash
@ -56,71 +71,72 @@ Documentação oficial: **https://agent-browser.dev/**
## Fluxo Operacional Passo a Passo ## Fluxo Operacional Passo a Passo
### 1. Iniciar Sessão Visível e Isolada ### 1. Iniciar Sessão Visível e Isolada por Contexto
Abra a aplicação frontend mantendo a janela visível e isolada por módulo: Abra a aplicação frontend mantendo a janela visível e isolada pelo módulo e contexto desejado:
```bash ```bash
# Obter modulo-id canônico # Obter modulo-id canônico de memorias-ia/modulo.yml
MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}') MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
CONTEXTO="interno" # ou "cliente", "externo", "anonimo"
agent-browser --session "$MODULO" open --headed http://localhost:8080 agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" snapshot -i agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i
``` ```
*Saída de exemplo:* *Saída de exemplo:*
```text ```text
- heading "Qualificação de Fornecedores" [ref=e1] - heading "Atendimento ao Cliente" [ref=e1]
- textbox "CNPJ" [ref=e2] - textbox "E-mail ou Usuário" [ref=e2]
- textbox "Razão Social" [ref=e3] - textbox "Senha" [ref=e3]
- button "Pesquisar" [ref=e4] - button "Entrar" [ref=e4]
``` ```
### 3. Interagir com Determinismo ### 3. Interagir com Determinismo
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 credenciais ou campos de formulário
agent-browser --session "$MODULO" fill @e2 "12.345.678/0001-90" agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "operador@empresa.com"
agent-browser --session "$MODULO" fill @e3 "Indústria Modelo LTDA" agent-browser --session "${MODULO}_${CONTEXTO}" fill @e3 "senha123"
# Acionamento de botões e links # Acionamento de botões e links
agent-browser --session "$MODULO" click @e4 agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" wait 1500 agent-browser --session "${MODULO}_${CONTEXTO}" wait 1500
# Capturar novo snapshot para verificar se a lista ou mensagem apareceu # Capturar novo snapshot para verificar se o painel ou mensagem apareceu
agent-browser --session "$MODULO" snapshot -i agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" console agent-browser --session "${MODULO}_${CONTEXTO}" console
# Verificar requisições de rede falhadas # Verificar requisições de rede falhadas
agent-browser --session "$MODULO" network agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" screenshot evidencias/resultado-sucesso.png agent-browser --session "${MODULO}_${CONTEXTO}" screenshot evidencias/resultado-sucesso.png
# agent-browser --session "$MODULO" screenshot --annotate evidencias/resultado-anotado.png # agent-browser --session "${MODULO}_${CONTEXTO}" screenshot --annotate evidencias/resultado-anotado.png
``` ```
### 7. Encerrar Navegador ### 7. Encerrar Navegador daquele Contexto
Finalize a sessão isolada limpando apenas os processos do seu módulo: Finalize a sessão isolada limpando apenas os processos e tokens do contexto testado:
```bash ```bash
agent-browser --session "$MODULO" close agent-browser --session "${MODULO}_${CONTEXTO}" close
``` ```
--- ---
@ -129,52 +145,57 @@ agent-browser --session "$MODULO" close
| Ação | Comando | | Ação | Comando |
|---|---| |---|---|
| **Abrir tela (visível)** | `agent-browser --session <modulo> open --headed <url>` | | **Abrir tela (visível)** | `agent-browser --session <modulo>_<contexto?> open --headed <url>` |
| **Snapshot de elementos** | `agent-browser --session <modulo> snapshot -i` | | **Snapshot de elementos** | `agent-browser --session <modulo>_<contexto?> snapshot -i` |
| **Clicar elemento** | `agent-browser --session <modulo> click @ref` | | **Clicar elemento** | `agent-browser --session <modulo>_<contexto?> click @ref` |
| **Preencher campo** | `agent-browser --session <modulo> fill @ref "valor"` | | **Preencher campo** | `agent-browser --session <modulo>_<contexto?> fill @ref "valor"` |
| **Selecionar dropdown** | `agent-browser --session <modulo> select @ref "opcao"` | | **Selecionar dropdown** | `agent-browser --session <modulo>_<contexto?> select @ref "opcao"` |
| **Pressionar tecla** | `agent-browser --session <modulo> press Enter` | | **Pressionar tecla** | `agent-browser --session <modulo>_<contexto?> press Enter` |
| **Obter texto** | `agent-browser --session <modulo> get text @ref` | | **Obter texto** | `agent-browser --session <modulo>_<contexto?> get text @ref` |
| **Aguardar tempo** | `agent-browser --session <modulo> wait <ms>` | | **Aguardar tempo** | `agent-browser --session <modulo>_<contexto?> wait <ms>` |
| **Aguardar seletor** | `agent-browser --session <modulo> wait --selector "<seletor>"` | | **Aguardar seletor** | `agent-browser --session <modulo>_<contexto?> wait --selector "<seletor>"` |
| **Inspecionar console** | `agent-browser --session <modulo> console` | | **Inspecionar console** | `agent-browser --session <modulo>_<contexto?> console` |
| **Inspecionar rede** | `agent-browser --session <modulo> network` | | **Inspecionar rede** | `agent-browser --session <modulo>_<contexto?> network` |
| **Screenshot** | `agent-browser --session <modulo> screenshot <arquivo.png>` | | **Screenshot** | `agent-browser --session <modulo>_<contexto?> screenshot <arquivo.png>` |
| **Auditoria a11y (WCAG)** | `agent-browser --session <modulo> a11y` | | **Auditoria a11y (WCAG)** | `agent-browser --session <modulo>_<contexto?> a11y` |
| **Fechar sessão** | `agent-browser --session <modulo> close` | | **Fechar sessão** | `agent-browser --session <modulo>_<contexto?> close` |
--- ---
## 🔑 Autenticação e Credenciais Canônicas (`modulo-acesso`) ## 🔑 Autenticação e Credenciais por Contexto (`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`: 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` para o contexto específico:
```bash ```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}') 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}') CONTEXTO="interno" # ou "cliente", "externo"
SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
# Extrair credenciais do contexto específico (compatível com multi-contexto ou formato simples)
USUARIO=$(grep -A3 "${CONTEXTO}:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')
[ -z "$USUARIO" ] && USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')
SENHA=$(grep -A3 "${CONTEXTO}:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
[ -z "$SENHA" ] && 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 # Preenchimento determinístico no formulário de login na sessão isolada
agent-browser --session "$MODULO" fill @e1 "$USUARIO" agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "$USUARIO"
agent-browser --session "$MODULO" fill @e2 "$SENHA" agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "$SENHA"
agent-browser --session "$MODULO" click @e3 agent-browser --session "${MODULO}_${CONTEXTO}" click @e3
``` ```
> ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste. > ⚠️ **Atenção:** Nunca misture o fluxo `anonimo` na mesma sessão que executou login. Use sempre `--session "${MODULO}_anonimo"` para testes públicos e deslogados.
--- ---
## Sessões Persistentes e Autenticação ## Sessões Persistentes e Autenticação
Para fluxos que necessitam manter login ativo entre comandos com isolamento: Para fluxos que necessitam manter login ativo entre comandos com isolamento por contexto:
```bash ```bash
# Iniciar sessão nomeada com auto-restore no escopo do módulo # Iniciar sessão nomeada com auto-restore no escopo do módulo e contexto
agent-browser --session "$MODULO" --restore open --headed http://localhost:8080/login agent-browser --session "${MODULO}_${CONTEXTO}" --restore open --headed http://localhost:8080/login
# Verificar status da sessão isolada # Verificar status da sessão isolada
agent-browser --session "$MODULO" session info --json agent-browser --session "${MODULO}_${CONTEXTO}" session info --json
``` ```
--- ---
@ -194,6 +215,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 --session "$MODULO" fill @ref` ou `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}_${CONTEXTO}" 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. 2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser --session "${MODULO}_${CONTEXTO}" wait 500 && agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session <modulo> --headed`. - **`@testes`**: Roda `typecheck`, `biome check` e validação visual via `agent-browser --session <modulo>_<contexto?> --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

26
rules/identidade-modulo.md
View file

@ -5,7 +5,7 @@ description: Identificação obrigatória do projeto/módulo via memorias-ia/mod
scope: global scope: global
trigger: always_on trigger: always_on
priority: critica priority: critica
updatedAt: "2026-10-06" updatedAt: "2026-10-08"
--- ---
# Regra: Identidade do Projeto via `memorias-ia/modulo.yml` # Regra: Identidade do Projeto via `memorias-ia/modulo.yml`
@ -38,11 +38,25 @@ modulo-caminho: <rota-na-url>
modulo-descricao: <texto-descritivo> modulo-descricao: <texto-descritivo>
modulo-tipo: <texto-tipo-arquitetura> modulo-tipo: <texto-tipo-arquitetura>
# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA) # Credenciais para autenticação em testes (agent-browser, E2E, QA)
# Formato Simples (aplicação com contexto único de acesso):
modulo-acesso: modulo-acesso:
usuario: <login-ou-email> usuario: <login-ou-email>
senha: <senha-de-teste> senha: <senha-de-teste>
# Ou Formato Multi-Contexto (quando a aplicação possui acessos distintos - evita mistura de tokens):
# modulo-acesso:
# interno:
# usuario: <login-operador>
# senha: <senha-operador>
# cliente:
# usuario: <login-cliente>
# senha: <senha-cliente>
# externo:
# usuario: <login-cidadao>
# senha: <senha-cidadao>
# anonimo: null # acesso público/deslogado
# Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/) # Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/)
modulo-wiki: <caminho-da-wiki> modulo-wiki: <caminho-da-wiki>
``` ```
@ -51,11 +65,11 @@ 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, 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-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 prefixo da sessão isolada no `agent-browser` (`--session <modulo-id>_<contexto?>`). | `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` |
| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`). | `{ usuario: "admin@gov.br", senha: "123" }` | | **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) ou organizadas por contexto (`interno`, `externo`, `cliente`, `anonimo`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`), prevenindo mistura de tokens. | `{ usuario: "admin@gov.br", senha: "123" }` ou subchaves de contexto |
| **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` | | **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` |
--- ---
@ -63,10 +77,10 @@ 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/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session <modulo-id>`)**; 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>_<contexto?>`)**;
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 as credenciais do contexto específico (`interno`, `externo`, `cliente`, etc.) ou credenciais diretas de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística sem contaminação de cookies/tokens entre perfis;
5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia; 5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia;
6. **Sincronização do Submódulo (`.agent`)**: Ao iniciar qualquer sessão ou interação no projeto hospedeiro, o agente DEVE assegurar que o submódulo `.agent` esteja atualizado com a branch `master` remota executando `git submodule update --init --recursive --remote`. 6. **Sincronização do Submódulo (`.agent`)**: Ao iniciar qualquer sessão ou interação no projeto hospedeiro, o agente DEVE assegurar que o submódulo `.agent` esteja atualizado com a branch `master` remota executando `git submodule update --init --recursive --remote`.

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

@ -1,7 +1,7 @@
--- ---
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) e com isolamento por sessão (--session <modulo>). description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) e com isolamento por sessão e contexto (--session <modulo>_<contexto?>).
scope: global scope: global
trigger: always_on trigger: always_on
updatedAt: "2026-10-08" updatedAt: "2026-10-08"
@ -13,7 +13,7 @@ updatedAt: "2026-10-08"
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. Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Para viabilizar testes concorrentes e evitar interferências mútuas entre múltiplos módulos ou workspaces, todo comando deve operar em sessão isolada identificada pelo módulo e pelo contexto de acesso.
Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA. 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.
@ -27,24 +27,38 @@ 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 --session <modulo> 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>_<contexto?> open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
3. **Isolamento Mandatório de Sessão (`--session <modulo>`)**: 3. **Isolamento Mandatório de Sessão e Contexto (`--session <modulo>_<contexto?>`)**:
- **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo. - **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo e o contexto de acesso.
- Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>`. - Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml` e `<contexto?>` discrimina o papel ou natureza do acesso), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto?>`.
- 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. - **Prevenção de Mistura de Tokens:** Caso a aplicação possua mais de um tipo de acesso (`interno`, `externo`, `anonimo`, `cliente`, etc.), o `<contexto>` **DEVE SER OBRIGATORIAMENTE PREENCHIDO** para evitar que cookies, tokens JWT e estados de login residuais contaminem outros fluxos de teste.
- Caso um mesmo módulo necessite de sub-isolamento para testes paralelos, deve-se adotar o sufixo determinístico `<modulo-id>-<slug-ou-pid>`. - Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>_<contexto>.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos.
- Caso um mesmo módulo e contexto necessite de sub-isolamento para testes paralelos, adota-se o discriminador determinístico: `<modulo>_<contexto>_<slug-ou-pid>`.
4. **Utilizar o modelo de referências (`@ref`)**: 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`. - Mapear a tela via `agent-browser --session <modulo>_<contexto?> snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
- Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`). - Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
5. **Registrar evidências e fechar sessão**: 5. **Registrar evidências e fechar sessão**:
- Registrar comprovações visuais com `agent-browser --session <modulo> screenshot <arquivo.png>`. - Registrar comprovações visuais com `agent-browser --session <modulo>_<contexto?> screenshot <arquivo.png>`.
- Encerrar graciosamente o navegador com `agent-browser --session <modulo> close` ao término do fluxo. - Encerrar graciosamente o navegador com `agent-browser --session <modulo>_<contexto?> close` ao término do fluxo.
6. **Credenciais Canônicas de Teste (`modulo-acesso`)**: 6. **Credenciais Canônicas por Contexto (`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, o agente **DEVE OBRIGATORIAMENTE extrair as credenciais do contexto específico** em `modulo-acesso` de `memorias-ia/modulo.yml` (ex: `modulo-acesso.interno`, `modulo-acesso.cliente`, etc.).
- Para sessões anônimas (`_anonimo`), nenhum login deve ser realizado, garantindo a validação da experiência do usuário público sem tokens.
- É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste. - É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.
--- ---
## 🔒 Contextos Canônicos de Sessão (`<modulo>_<contexto>`)
| Contexto | Finalidade e Natureza | Exemplo de Sessão | Credenciais em `modulo.yml` |
| :--- | :--- | :--- | :--- |
| **`interno`** | Operador interno, suporte, técnico, atendente, administrador | `--session <modulo>_interno` | `modulo-acesso.interno` (ou `modulo-acesso` simples) |
| **`cliente`** | Cliente final, solicitante corporativo, empresa contratante | `--session <modulo>_cliente` | `modulo-acesso.cliente` |
| **`externo`** | Portal público autenticado, cidadão, requerente externo | `--session <modulo>_externo` | `modulo-acesso.externo` |
| **`anonimo`** | Usuário deslogado, consulta pública por código, login, landing | `--session <modulo>_anonimo` | Nenhuma (perfil limpo sem cookies/tokens) |
| **`<especifico>`** | Papel especializado de domínio (ex: `fiscal`, `auditor`) | `--session <modulo>_<papel>` | `modulo-acesso.<papel>` |
---
## Instalação e Configuração ## Instalação e Configuração
O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium: O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium:
@ -63,55 +77,56 @@ 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 com isolamento de sessão: Todo teste ou navegação de interface executado pela IA deve seguir o fluxo com isolamento de sessão e contexto:
### 1. Obter Identificador do Módulo e Abertura com Janela Visível ### 1. Obter Identificador do Módulo e Abertura com Janela Visível
```bash ```bash
# Obter o modulo-id canônico de memorias-ia/modulo.yml # Obter o modulo-id canônico de memorias-ia/modulo.yml
MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}') MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
CONTEXTO="interno" # ou "cliente", "externo", "anonimo"
# Abrir sempre visível ao operador humano na sessão isolada do módulo # Abrir sempre visível ao operador na sessão isolada por módulo e contexto
agent-browser --session "$MODULO" open --headed http://localhost:8080 agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" snapshot -i agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" fill @e1 "usuario@exemplo.com" agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "usuario@exemplo.com"
agent-browser --session "$MODULO" fill @e2 "senhaSegura123" agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "senhaSegura123"
agent-browser --session "$MODULO" click @e3 agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" wait 1000 agent-browser --session "${MODULO}_${CONTEXTO}" wait 1000
# Obter novo snapshot para verificar estado pós-ação # Obter novo snapshot para verificar estado pós-ação
agent-browser --session "$MODULO" snapshot -i agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i
# Capturar evidência gráfica do teste # Capturar evidência gráfica do teste
agent-browser --session "$MODULO" screenshot evidencias/teste-login-sucesso.png agent-browser --session "${MODULO}_${CONTEXTO}" screenshot evidencias/teste-login-sucesso.png
# Verificar erros no console do navegador # Verificar erros no console do navegador
agent-browser --session "$MODULO" console agent-browser --session "${MODULO}_${CONTEXTO}" console
``` ```
### 5. Finalização ### 5. Finalização
```bash ```bash
# Fechar a sessão isolada do navegador ao concluir o teste # Fechar a sessão isolada do navegador ao concluir o fluxo daquele contexto
agent-browser --session "$MODULO" close agent-browser --session "${MODULO}_${CONTEXTO}" close
``` ```
--- ---
@ -119,23 +134,25 @@ agent-browser --session "$MODULO" 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 executar sem a flag `--session <modulo>_<contexto?>`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada.
- **Proibido misturar acessos com perfis diferentes na mesma sessão genérica sem contexto** (ex: logar como operador interno e depois testar fluxo de cliente ou anônimo na mesma sessão, causando mistura de tokens).
- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`. - **Proibido 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 órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <modulo> close`). - **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <modulo>_<contexto?> close`).
### Permitido e Recomendado ✅ ### Permitido e Recomendado ✅
- Manter sessões persistentes quando necessário via `--session <modulo> --restore`. - Manter sessões persistentes por contexto quando necessário via `--session <modulo>_<contexto> --restore`.
- Utilizar sub-isolamento determinístico (`<modulo-id>-<slug-ou-pid>`) caso múltiplos testes do mesmo módulo ocorram simultaneamente no mesmo host. - Utilizar sub-isolamento determinístico (`<modulo>_<contexto>_<slug-ou-pid>`) caso múltiplos testes do mesmo contexto ocorram simultaneamente no mesmo host.
- Usar `agent-browser --session <modulo> screenshot --annotate` para inspecionar layouts complexos com visão computacional. - Usar `agent-browser --session <modulo>_<contexto> screenshot --annotate` para inspecionar layouts complexos com visão computacional.
- Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`. - 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. - **Isolamento de Tokens e Cookies**: Evita vazamento de credenciais e estados de autenticação entre acessos de operador interno, cliente corporativo, cidadão e visitante anônimo.
- **Isolamento e Concorrência**: Múltiplos agentes ou testes E2E simultâneos não conflitam de abas nem fecham janelas alheias.
- **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real. - **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.
@ -148,4 +165,3 @@ agent-browser --session "$MODULO" close
- Skill associada: `skills/testar-interface-agent-browser/SKILL.md` - Skill associada: `skills/testar-interface-agent-browser/SKILL.md`
- Rule associada: `rules/identidade-modulo.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 --session <modulo> --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>_<contexto?> --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 --session <modulo> --headed 5. [@testes] Roda typecheck, biome e testes E2E com agent-browser --session <modulo>_<contexto?> --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 --session <modulo> --headed`. - **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session <modulo>_<contexto?> --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`.

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

@ -3,7 +3,7 @@ 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>). e isolamento mandatório de sessão e contexto (--session <modulo>_<contexto?>).
scope: global scope: global
--- ---
@ -11,16 +11,31 @@ 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 isolamento total entre processos e visualização em tempo real pelo operador humano. 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 de cookies, tokens e processos, com visualização em tempo real pelo operador humano.
--- ---
## 🔒 Princípio de Isolamento de Sessão por Módulo (`--session <modulo>`) ## 🔒 Princípio de Isolamento de Sessão e Contexto (`--session <modulo>_<contexto?>`)
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`: O daemon do `agent-browser` aloca sockets Unix dedicados e armazena cookies HTTP, tokens JWT (em cabeçalhos, cookies ou `localStorage`/`sessionStorage`) e estados de autenticação independentes por sessão.
- **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>`. Para evitar contaminação cruzada de credenciais, interferência mútua entre módulos ou encerramento indevido de processos via `agent-browser close`:
- Caso múltiplos fluxos de teste concorrentes rodem no mesmo módulo, utilizar sufixo discriminador determinístico: `--session "${MODULO}-subfluxo"`.
- **Todo comando DEVE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico de `memorias-ia/modulo.yml` e `<contexto?>` identifica o papel ou perfil de acesso), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto?>`.
- **Prevenção Obrigatória de Mistura de Tokens:** Caso a aplicação possua mais de um tipo de acesso (`interno`, `externo`, `anonimo`, `cliente`, etc.), o `<contexto>` **DEVE SER OBRIGATORIAMENTE PREENCHIDO**. Exemplo: um teste logado como operador `interno` nunca deve compartilhar a mesma sessão de um teste de rota pública `anonimo` ou de acesso do `cliente`.
- **Sub-isolamento para concorrência:** Caso múltiplos fluxos de teste concorrentes do mesmo papel rodem simultaneamente, utilizar sufixo discriminador determinístico: `--session "${MODULO}_${CONTEXTO}_${SLUG_OU_PID}"`.
---
## 🧭 Contextos Canônicos de Sessão
| Contexto | Finalidade e Escopo | Exemplo de Sessão | Fonte de Credenciais |
| :--- | :--- | :--- | :--- |
| **`interno`** | Operador interno, suporte, técnico, atendente, administrador | `--session <modulo>_interno` | `modulo-acesso.interno` (ou `modulo-acesso` simples) |
| **`cliente`** | Solicitante corporativo, empresa cliente, contratante | `--session <modulo>_cliente` | `modulo-acesso.cliente` |
| **`externo`** | Portal público autenticado, cidadão, requerente externo | `--session <modulo>_externo` | `modulo-acesso.externo` |
| **`anonimo`** | Usuário deslogado, consulta pública, login, landing page | `--session <modulo>_anonimo` | Nenhuma (perfil limpo sem cookies/tokens) |
| **`<especifico>`** | Papel especializado de domínio (ex: `fiscal`, `auditor`) | `--session <modulo>_<papel>` | `modulo-acesso.<papel>` |
--- ---
@ -30,7 +45,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 --session "$MODULO" open --headed <url> agent-browser --session "${MODULO}_${CONTEXTO}" open --headed <url>
``` ```
- Ou exportar no ambiente: - Ou exportar no ambiente:
```bash ```bash
@ -56,71 +71,72 @@ Documentação oficial: **https://agent-browser.dev/**
## Fluxo Operacional Passo a Passo ## Fluxo Operacional Passo a Passo
### 1. Iniciar Sessão Visível e Isolada ### 1. Iniciar Sessão Visível e Isolada por Contexto
Abra a aplicação frontend mantendo a janela visível e isolada por módulo: Abra a aplicação frontend mantendo a janela visível e isolada pelo módulo e contexto desejado:
```bash ```bash
# Obter modulo-id canônico # Obter modulo-id canônico de memorias-ia/modulo.yml
MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}') MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
CONTEXTO="interno" # ou "cliente", "externo", "anonimo"
agent-browser --session "$MODULO" open --headed http://localhost:8080 agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" snapshot -i agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i
``` ```
*Saída de exemplo:* *Saída de exemplo:*
```text ```text
- heading "Qualificação de Fornecedores" [ref=e1] - heading "Atendimento ao Cliente" [ref=e1]
- textbox "CNPJ" [ref=e2] - textbox "E-mail ou Usuário" [ref=e2]
- textbox "Razão Social" [ref=e3] - textbox "Senha" [ref=e3]
- button "Pesquisar" [ref=e4] - button "Entrar" [ref=e4]
``` ```
### 3. Interagir com Determinismo ### 3. Interagir com Determinismo
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 credenciais ou campos de formulário
agent-browser --session "$MODULO" fill @e2 "12.345.678/0001-90" agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "operador@empresa.com"
agent-browser --session "$MODULO" fill @e3 "Indústria Modelo LTDA" agent-browser --session "${MODULO}_${CONTEXTO}" fill @e3 "senha123"
# Acionamento de botões e links # Acionamento de botões e links
agent-browser --session "$MODULO" click @e4 agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" wait 1500 agent-browser --session "${MODULO}_${CONTEXTO}" wait 1500
# Capturar novo snapshot para verificar se a lista ou mensagem apareceu # Capturar novo snapshot para verificar se o painel ou mensagem apareceu
agent-browser --session "$MODULO" snapshot -i agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" console agent-browser --session "${MODULO}_${CONTEXTO}" console
# Verificar requisições de rede falhadas # Verificar requisições de rede falhadas
agent-browser --session "$MODULO" network agent-browser --session "${MODULO}_${CONTEXTO}" 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 --session "$MODULO" screenshot evidencias/resultado-sucesso.png agent-browser --session "${MODULO}_${CONTEXTO}" screenshot evidencias/resultado-sucesso.png
# agent-browser --session "$MODULO" screenshot --annotate evidencias/resultado-anotado.png # agent-browser --session "${MODULO}_${CONTEXTO}" screenshot --annotate evidencias/resultado-anotado.png
``` ```
### 7. Encerrar Navegador ### 7. Encerrar Navegador daquele Contexto
Finalize a sessão isolada limpando apenas os processos do seu módulo: Finalize a sessão isolada limpando apenas os processos e tokens do contexto testado:
```bash ```bash
agent-browser --session "$MODULO" close agent-browser --session "${MODULO}_${CONTEXTO}" close
``` ```
--- ---
@ -129,52 +145,57 @@ agent-browser --session "$MODULO" close
| Ação | Comando | | Ação | Comando |
|---|---| |---|---|
| **Abrir tela (visível)** | `agent-browser --session <modulo> open --headed <url>` | | **Abrir tela (visível)** | `agent-browser --session <modulo>_<contexto?> open --headed <url>` |
| **Snapshot de elementos** | `agent-browser --session <modulo> snapshot -i` | | **Snapshot de elementos** | `agent-browser --session <modulo>_<contexto?> snapshot -i` |
| **Clicar elemento** | `agent-browser --session <modulo> click @ref` | | **Clicar elemento** | `agent-browser --session <modulo>_<contexto?> click @ref` |
| **Preencher campo** | `agent-browser --session <modulo> fill @ref "valor"` | | **Preencher campo** | `agent-browser --session <modulo>_<contexto?> fill @ref "valor"` |
| **Selecionar dropdown** | `agent-browser --session <modulo> select @ref "opcao"` | | **Selecionar dropdown** | `agent-browser --session <modulo>_<contexto?> select @ref "opcao"` |
| **Pressionar tecla** | `agent-browser --session <modulo> press Enter` | | **Pressionar tecla** | `agent-browser --session <modulo>_<contexto?> press Enter` |
| **Obter texto** | `agent-browser --session <modulo> get text @ref` | | **Obter texto** | `agent-browser --session <modulo>_<contexto?> get text @ref` |
| **Aguardar tempo** | `agent-browser --session <modulo> wait <ms>` | | **Aguardar tempo** | `agent-browser --session <modulo>_<contexto?> wait <ms>` |
| **Aguardar seletor** | `agent-browser --session <modulo> wait --selector "<seletor>"` | | **Aguardar seletor** | `agent-browser --session <modulo>_<contexto?> wait --selector "<seletor>"` |
| **Inspecionar console** | `agent-browser --session <modulo> console` | | **Inspecionar console** | `agent-browser --session <modulo>_<contexto?> console` |
| **Inspecionar rede** | `agent-browser --session <modulo> network` | | **Inspecionar rede** | `agent-browser --session <modulo>_<contexto?> network` |
| **Screenshot** | `agent-browser --session <modulo> screenshot <arquivo.png>` | | **Screenshot** | `agent-browser --session <modulo>_<contexto?> screenshot <arquivo.png>` |
| **Auditoria a11y (WCAG)** | `agent-browser --session <modulo> a11y` | | **Auditoria a11y (WCAG)** | `agent-browser --session <modulo>_<contexto?> a11y` |
| **Fechar sessão** | `agent-browser --session <modulo> close` | | **Fechar sessão** | `agent-browser --session <modulo>_<contexto?> close` |
--- ---
## 🔑 Autenticação e Credenciais Canônicas (`modulo-acesso`) ## 🔑 Autenticação e Credenciais por Contexto (`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`: 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` para o contexto específico:
```bash ```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}') 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}') CONTEXTO="interno" # ou "cliente", "externo"
SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
# Extrair credenciais do contexto específico (compatível com multi-contexto ou formato simples)
USUARIO=$(grep -A3 "${CONTEXTO}:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')
[ -z "$USUARIO" ] && USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')
SENHA=$(grep -A3 "${CONTEXTO}:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
[ -z "$SENHA" ] && 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 # Preenchimento determinístico no formulário de login na sessão isolada
agent-browser --session "$MODULO" fill @e1 "$USUARIO" agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "$USUARIO"
agent-browser --session "$MODULO" fill @e2 "$SENHA" agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "$SENHA"
agent-browser --session "$MODULO" click @e3 agent-browser --session "${MODULO}_${CONTEXTO}" click @e3
``` ```
> ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste. > ⚠️ **Atenção:** Nunca misture o fluxo `anonimo` na mesma sessão que executou login. Use sempre `--session "${MODULO}_anonimo"` para testes públicos e deslogados.
--- ---
## Sessões Persistentes e Autenticação ## Sessões Persistentes e Autenticação
Para fluxos que necessitam manter login ativo entre comandos com isolamento: Para fluxos que necessitam manter login ativo entre comandos com isolamento por contexto:
```bash ```bash
# Iniciar sessão nomeada com auto-restore no escopo do módulo # Iniciar sessão nomeada com auto-restore no escopo do módulo e contexto
agent-browser --session "$MODULO" --restore open --headed http://localhost:8080/login agent-browser --session "${MODULO}_${CONTEXTO}" --restore open --headed http://localhost:8080/login
# Verificar status da sessão isolada # Verificar status da sessão isolada
agent-browser --session "$MODULO" session info --json agent-browser --session "${MODULO}_${CONTEXTO}" session info --json
``` ```
--- ---
@ -194,6 +215,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 --session "$MODULO" fill @ref` ou `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}_${CONTEXTO}" 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. 2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser --session "${MODULO}_${CONTEXTO}" wait 500 && agent-browser --session "${MODULO}_${CONTEXTO}" 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.

9
validar-setup.sh
View file

@ -95,7 +95,11 @@ if [ -f "$MODULO_YML" ]; then
# Validar modulo-acesso (credenciais de teste para automação e QA) # Validar modulo-acesso (credenciais de teste para automação e QA)
if grep -q "modulo-acesso:" "$MODULO_YML"; then if grep -q "modulo-acesso:" "$MODULO_YML"; then
echo -e " ${VERDE}✓${RESET} modulo-acesso: credenciais de teste configuradas." if grep -E -q "^\s+(interno|cliente|externo|anonimo):" "$MODULO_YML"; then
echo -e " ${VERDE}✓${RESET} modulo-acesso: credenciais multi-contexto configuradas (isolamento de tokens)."
else
echo -e " ${VERDE}✓${RESET} modulo-acesso: credenciais de teste configuradas."
fi
else else
echo -e " ${AMARELO}⚠${RESET} modulo-acesso: credenciais de teste não configuradas em modulo.yml." echo -e " ${AMARELO}⚠${RESET} modulo-acesso: credenciais de teste não configuradas em modulo.yml."
fi fi
@ -109,7 +113,8 @@ if [ -f "$MODULO_YML" ]; then
# Exibir convenção de sessão isolada para agent-browser # Exibir convenção de sessão isolada para agent-browser
if [ -n "$MODULO_ID" ]; then if [ -n "$MODULO_ID" ]; then
echo -e " ${AZUL}ℹ${RESET} Sessão agent-browser: agent-browser --session ${NEGRITO}$MODULO_ID${RESET}" echo -e " ${AZUL}ℹ${RESET} Sessão agent-browser: agent-browser --session ${NEGRITO}${MODULO_ID}_<contexto?>${RESET}"
echo -e " Exemplos: ${MODULO_ID}_interno | ${MODULO_ID}_cliente | ${MODULO_ID}_externo | ${MODULO_ID}_anonimo"
fi 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)