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

feat(testes): padronizar uso de --session <modulo>_<contexto?> no agent-browser para isolamento de tokens

Browse source
This commit is contained in:
Luiz Silva 2026-10-08 14:47:46 -03:00
parent 29e5bc979e
commit 1a8adfc2dc
23 changed files with 320 additions and 206 deletions
Download patch file Download diff file Expand all files Collapse all files

16
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)
@ -15,9 +15,23 @@ modulo-descricao: Descrição detalhada do módulo para contextualização opera
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 padrão para autenticação em testes (agent-browser, E2E, QA)
# Suporta formato direto (contexto padrão/único) ou subdividido por contexto de acesso:
modulo-acesso: modulo-acesso:
# Formato direto (quando contexto único ou padrão):
usuario: usuario@exemplo.com.br usuario: usuario@exemplo.com.br
senha: "123" senha: "123"
# OU agrupado por contextos específicos (descomente e adeque conforme os perfis da aplicação):
# interno:
# usuario: admin@gov.br
# senha: "123"
# externo:
# usuario: cidadao@empresa.com.br
# senha: "123"
# cliente:
# usuario: cliente@empresa.com.br
# senha: "123"
# Nota: o perfil 'anonimo' atua sempre sem login na sessão limpa <modulo>_anonimo
# 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

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

@ -90,12 +90,14 @@ 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>` > 💡 **Nota de Contexto:** Caso a aplicação possua múltiplos acessos (interno, externo, anonimo, cliente), utilize obrigatoriamente o sufixo correspondente (ex: `<modulo-id>_interno`, `<modulo-id>_externo`, `<modulo-id>_anonimo`, `<modulo-id>_cliente`) para prevenir mistura de cookies e tokens de autenticação.
2. Mapear interações: `agent-browser --session <modulo-id> snapshot -i`
3. Executar ações: `agent-browser --session <modulo-id> fill @ref "..." && agent-browser --session <modulo-id> click @ref` 1. Abrir aplicação: `agent-browser --session <modulo-id>_<contexto> open --headed <url>`
4. Capturar evidência: `agent-browser --session <modulo-id> screenshot evidencias/<slug>.png` 2. Mapear interações: `agent-browser --session <modulo-id>_<contexto> snapshot -i`
5. Encerrar: `agent-browser --session <modulo-id> close` 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>_<contexto> screenshot evidencias/<slug>.png`
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>` indica o perfil sob teste: `interno`, `externo`, `anonimo`, `cliente`) ou garantir `export AGENT_BROWSER_SESSION=<modulo>_<contexto>`. Cada sessão aloca daemon, socket Unix exclusivo, cookies e LocalStorage independentes, prevenindo colisões e vazamento de tokens de autenticação entre diferentes acessos.
- **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>` indica o perfil sob teste: `interno`, `externo`, `anonimo`, `cliente`) ou garantir `export AGENT_BROWSER_SESSION=<modulo>_<contexto>`. Cada sessão aloca daemon, socket Unix exclusivo, cookies e LocalStorage independentes, prevenindo colisões e vazamento de tokens de autenticação entre diferentes acessos.
- **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 em testes simultâneos (ver `rules/testes-interface-agent-browser.md`)
## Restrições ## Restrições

2
agents/front/persona
View file

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

2
agents/testes/agent.json
View file

File diff suppressed because one or more lines are too long

4
agents/testes/agent.md
View file

@ -53,7 +53,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
6. Identificar casos extremos e cenários de falha não cobertos 6. Identificar casos extremos e cenários de falha não cobertos
7. Validar schemas Zod contra dados reais de produção 7. Validar schemas Zod contra dados reais de produção
8. Documentar bugs encontrados com passos de reprodução 8. Documentar bugs encontrados com passos de reprodução
9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`) 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 de autenticação entre acessos interno, externo, anônimo ou cliente (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 contextual isolada (`--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 de autenticação entre acessos interno, externo, anônimo ou cliente (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 contextual isolada (`--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 interferência entre perfis de acesso (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 interferência entre perfis de acesso (ver `rules/testes-interface-agent-browser.md`)
## Restrições ## Restrições

16
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`
@ -39,9 +39,15 @@ 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 padrão para autenticação em testes (agent-browser, E2E, QA)
# Suporta formato direto legado ou subdividido por contexto de acesso
modulo-acesso: modulo-acesso:
usuario: <login-ou-email> usuario: <login-ou-email>
senha: <senha-de-teste> senha: <senha-de-teste>
# Ou subdividido por contexto:
# interno: { usuario: "...", senha: "..." }
# externo: { usuario: "...", senha: "..." }
# cliente: { usuario: "...", senha: "..." }
# Nota: o perfil 'anonimo' atua sempre sem credenciais na sessão <modulo>_anonimo
# 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 +57,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 identificador mandatório de 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 de teste para autenticação determinística por agentes (`@testes`, QA, `agent-browser`), suportando formato direto padrão (`usuario`/`senha`) ou subdivisão por contexto (`interno`, `externo`, `cliente`). | `{ usuario: "admin@gov.br", senha: "123" }` |
| **`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 +69,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 de `modulo-acesso` em `memorias-ia/modulo.yml` correspondentes ao contexto que está sendo testado (`interno`, `externo`, `cliente`), ou utilizar as credenciais padrão diretas. No contexto `anonimo`, nenhuma autenticação é realizada;
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?>) para evitar mistura de tokens.
scope: global scope: global
trigger: always_on trigger: always_on
updatedAt: "2026-10-08" updatedAt: "2026-10-08"
@ -13,9 +13,9 @@ 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. Em aplicações que possuem múltiplos níveis de acesso (como áreas administrativas internas, portais de requerentes externos, consultas anônimas públicas e acessos de clientes corporativos), a ausência de isolamento por contexto gera **mistura de tokens JWT, cookies de autenticação e dados de LocalStorage**, provocando falsos positivos ou mascarando falhas de segurança.
Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** 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`** com isolamento estrito por módulo e contexto de acesso (`--session <modulo>_<contexto?>`).
--- ---
@ -27,20 +27,29 @@ 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 perfil 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>` representa o perfil ou nível de acesso que está sendo testado), 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. - **Contextos Padronizados de Acesso:**
- Caso um mesmo módulo necessite de sub-isolamento para testes paralelos, deve-se adotar o sufixo determinístico `<modulo-id>-<slug-ou-pid>`. - `interno`: Acesso restrito a servidores públicos, fiscais, analistas internos ou administradores.
- `externo`: Acesso de requerentes externos, contribuintes ou cidadãos logados.
- `anonimo`: Acesso público e não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). **Obrigatório para assegurar ausência total de tokens ou cookies residuais de sessões anteriores.**
- `cliente`: Acesso de clientes ou empresas contratantes em plataformas multi-tenant ou B2B.
- Aplicações de contexto único sem distinção de perfis podem utilizar apenas `<modulo>` ou `<modulo>_default`.
- **Prevenção de Mistura de Tokens e Cookies:** Cada sessão do `agent-browser` possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>_<contexto>.sock`), mantendo cookie jar, cabeçalhos `Authorization`, LocalStorage e SessionStorage completamente estanques. Separar por `<modulo>_<contexto>` é estritamente obrigatório para que um teste anônimo não herde tokens de um teste interno, ou que credenciais de requerente externo não interfiram em fluxos administrativos.
- **Sub-isolamento Concorrente:** Caso múltiplos testes concorrentes ocorram no mesmo módulo e contexto, adota-se o sufixo determinístico: `<modulo>_<contexto>-<slug_ou_pid>`.
4. **Utilizar o modelo de referências (`@ref`)**: 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 de Teste 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`**. - O agente **DEVE OBRIGATORIAMENTE consultar `modulo-acesso` em `memorias-ia/modulo.yml`**.
- Se configurado com chaves específicas por contexto (`interno`, `externo`, `cliente`), extrair as credenciais do contexto sob teste.
- Se configurado no formato plano direto (`usuario` e `senha`), utilizar como credencial padrão para o contexto principal/interno.
- Para o contexto `anonimo`, o agente **NÃO deve autenticar**, validando a jornada como usuário não-logado na sessão isolada `<modulo>_anonimo`.
- É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste. - É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.
--- ---
@ -63,55 +72,59 @@ 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, Definir Contexto 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}')
# Abrir sempre visível ao operador humano na sessão isolada do módulo # Definir contexto sob teste: interno | externo | anonimo | cliente
agent-browser --session "$MODULO" open --headed http://localhost:8080 CONTEXTO="interno" # ou externo, anonimo, cliente
SESSAO="${MODULO}_${CONTEXTO}"
# Abrir sempre visível ao operador humano na sessão isolada do módulo e contexto
agent-browser --session "$SESSAO" open --headed http://localhost:8080
``` ```
### 2. Inspeção de Elementos Interativos ### 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 "$SESSAO" 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 "$SESSAO" fill @e1 "usuario@exemplo.com"
agent-browser --session "$MODULO" fill @e2 "senhaSegura123" agent-browser --session "$SESSAO" fill @e2 "senhaSegura123"
agent-browser --session "$MODULO" click @e3 agent-browser --session "$SESSAO" 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 "$SESSAO" 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 "$SESSAO" 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 "$SESSAO" 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 "$SESSAO" 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 teste
agent-browser --session "$MODULO" close agent-browser --session "$SESSAO" close
``` ```
--- ---
@ -119,23 +132,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 sessões ou misturar tokens entre perfis.
- **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 testar fluxos anônimos em sessões já autenticadas**, garantindo que testes públicos sempre rodem na sessão `<modulo>_anonimo`.
- **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`). - **Proibido 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 <sessao> close`).
### Permitido e Recomendado ✅ ### Permitido e Recomendado ✅
- Manter sessões persistentes quando necessário via `--session <modulo> --restore`. - Manter sessões persistentes 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**: Previne contaminação entre sessões de administradores internos, cidadãos externos e consultas públicas anônimas.
- **Isolamento de Processos e Concorrência**: Múltiplos agentes rodando testes E2E simultâneos não colidem abas nem encerram daemons de outros contextos.
- **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real. - **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 +163,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`.

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

@ -3,7 +3,8 @@ 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 por módulo e contexto (--session <modulo>_<contexto?>)
para evitar mistura de tokens e cookies entre acessos.
scope: global scope: global
--- ---
@ -15,12 +16,18 @@ Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuár
--- ---
## 🔒 Princípio de Isolamento de Sessão por Módulo (`--session <modulo>`) ## 🔒 Princípio de Isolamento de Sessão por Módulo 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` utiliza sockets Unix independentes por sessão (`/run/user/1000/agent-browser/<sessao>.sock`). Em sistemas que possuem diferentes perfis de acesso, separar o contexto na flag de sessão é **indispensável para prevenir mistura de tokens JWT, cookies de autenticação e dados de LocalStorage**:
- **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>`. - **Todo comando DEVE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico de `memorias-ia/modulo.yml` e `<contexto>` é o perfil sob teste), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto>`.
- Caso múltiplos fluxos de teste concorrentes rodem no mesmo módulo, utilizar sufixo discriminador determinístico: `--session "${MODULO}-subfluxo"`. - **Contextos Padronizados:**
- `interno`: Acesso de analistas, fiscais, operadores internos ou administradores.
- `externo`: Acesso de requerentes externos, cidadãos cadastrados ou contribuintes logados.
- `anonimo`: Acesso público / não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). **Garante sessão limpa sem resíduo de autenticações anteriores.**
- `cliente`: Acesso de clientes ou empresas em plataformas multi-tenant ou B2B.
- Aplicações de contexto único sem múltiplos acessos podem utilizar apenas `<modulo>` ou `<modulo>_default`.
- **Sub-isolamento Concorrente:** Caso múltiplos fluxos concorrentes rodem no mesmo contexto: `--session "${MODULO}_${CONTEXTO}-${slug_ou_pid}"`.
--- ---
@ -30,7 +37,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,19 +63,23 @@ 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 Módulo e 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:
```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}')
agent-browser --session "$MODULO" open --headed http://localhost:8080 # Definir contexto sob teste: interno | externo | anonimo | cliente
CONTEXTO="interno" # ou externo, anonimo, cliente
SESSAO="${MODULO}_${CONTEXTO}"
agent-browser --session "$SESSAO" 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 "$SESSAO" snapshot -i
``` ```
*Saída de exemplo:* *Saída de exemplo:*
```text ```text
@ -82,45 +93,45 @@ agent-browser --session "$MODULO" snapshot -i
Utilize as referências identificadas (`@e1`, `@e2`, etc.): Utilize as referências identificadas (`@e1`, `@e2`, etc.):
```bash ```bash
# Preenchimento de campos de texto # Preenchimento de campos de texto
agent-browser --session "$MODULO" fill @e2 "12.345.678/0001-90" agent-browser --session "$SESSAO" fill @e2 "12.345.678/0001-90"
agent-browser --session "$MODULO" fill @e3 "Indústria Modelo LTDA" agent-browser --session "$SESSAO" fill @e3 "Indústria Modelo LTDA"
# Acionamento de botões e links # Acionamento de botões e links
agent-browser --session "$MODULO" click @e4 agent-browser --session "$SESSAO" 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 "$SESSAO" wait 1500
# Capturar novo snapshot para verificar se a lista ou mensagem apareceu # Capturar novo snapshot para verificar se a lista ou mensagem apareceu
agent-browser --session "$MODULO" snapshot -i agent-browser --session "$SESSAO" 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 "$SESSAO" console
# Verificar requisições de rede falhadas # Verificar requisições de rede falhadas
agent-browser --session "$MODULO" network agent-browser --session "$SESSAO" 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 "$SESSAO" screenshot evidencias/resultado-sucesso.png
# agent-browser --session "$MODULO" screenshot --annotate evidencias/resultado-anotado.png # agent-browser --session "$SESSAO" screenshot --annotate evidencias/resultado-anotado.png
``` ```
### 7. Encerrar Navegador ### 7. Encerrar Navegador
Finalize a sessão isolada limpando apenas os processos do seu módulo: Finalize a sessão isolada limpando apenas os processos do seu contexto e módulo:
```bash ```bash
agent-browser --session "$MODULO" close agent-browser --session "$SESSAO" close
``` ```
--- ---
@ -129,37 +140,55 @@ 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 Canônicas 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 correspondente:
```bash ```bash
# Extrair identificador e credenciais canônicas de teste de memorias-ia/modulo.yml # Identificar módulo e contexto
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" # interno | externo | cliente | anonimo
SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}') SESSAO="${MODULO}_${CONTEXTO}"
# Preenchimento determinístico no formulário de login na sessão isolada if [ "$CONTEXTO" = "anonimo" ]; then
agent-browser --session "$MODULO" fill @e1 "$USUARIO" # Contexto anônimo: navegação pública limpa sem autenticação
agent-browser --session "$MODULO" fill @e2 "$SENHA" echo "Iniciando sessão pública limpa: $SESSAO"
agent-browser --session "$MODULO" click @e3 agent-browser --session "$SESSAO" open --headed http://localhost:8080/consulta-publica
else
# Contexto autenticado: obter credenciais do perfil ou usar fallback direto
USUARIO=$(grep -A6 "modulo-acesso:" memorias-ia/modulo.yml | grep -A2 "${CONTEXTO}:" | grep "usuario:" | awk '{print $2}' || true)
SENHA=$(grep -A6 "modulo-acesso:" memorias-ia/modulo.yml | grep -A2 "${CONTEXTO}:" | grep "senha:" | awk '{print $2}' || true)
if [ -z "$USUARIO" ]; then
USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')
SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
fi
# Preenchimento determinístico no formulário de login na sessão isolada
agent-browser --session "$SESSAO" open --headed http://localhost:8080/login
agent-browser --session "$SESSAO" wait 1000
agent-browser --session "$SESSAO" snapshot -i
agent-browser --session "$SESSAO" fill @e1 "$USUARIO"
agent-browser --session "$SESSAO" fill @e2 "$SENHA"
agent-browser --session "$SESSAO" click @e3
fi
``` ```
> ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste. > ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste.
@ -170,11 +199,11 @@ agent-browser --session "$MODULO" click @e3
Para fluxos que necessitam manter login ativo entre comandos com isolamento: Para fluxos que necessitam manter login ativo entre comandos com isolamento:
```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 "$SESSAO" --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 "$SESSAO" session info --json
``` ```
--- ---
@ -194,6 +223,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 "$SESSAO" 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 "$SESSAO" wait 500 && agent-browser --session "$SESSAO" 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

16
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`
@ -39,9 +39,15 @@ 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 padrão para autenticação em testes (agent-browser, E2E, QA)
# Suporta formato direto legado ou subdividido por contexto de acesso
modulo-acesso: modulo-acesso:
usuario: <login-ou-email> usuario: <login-ou-email>
senha: <senha-de-teste> senha: <senha-de-teste>
# Ou subdividido por contexto:
# interno: { usuario: "...", senha: "..." }
# externo: { usuario: "...", senha: "..." }
# cliente: { usuario: "...", senha: "..." }
# Nota: o perfil 'anonimo' atua sempre sem credenciais na sessão <modulo>_anonimo
# 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 +57,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 identificador mandatório de 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 de teste para autenticação determinística por agentes (`@testes`, QA, `agent-browser`), suportando formato direto padrão (`usuario`/`senha`) ou subdivisão por contexto (`interno`, `externo`, `cliente`). | `{ usuario: "admin@gov.br", senha: "123" }` |
| **`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 +69,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 de `modulo-acesso` em `memorias-ia/modulo.yml` correspondentes ao contexto que está sendo testado (`interno`, `externo`, `cliente`), ou utilizar as credenciais padrão diretas. No contexto `anonimo`, nenhuma autenticação é realizada;
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?>) para evitar mistura de tokens.
scope: global scope: global
trigger: always_on trigger: always_on
updatedAt: "2026-10-08" updatedAt: "2026-10-08"
@ -13,9 +13,9 @@ 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. Em aplicações que possuem múltiplos níveis de acesso (como áreas administrativas internas, portais de requerentes externos, consultas anônimas públicas e acessos de clientes corporativos), a ausência de isolamento por contexto gera **mistura de tokens JWT, cookies de autenticação e dados de LocalStorage**, provocando falsos positivos ou mascarando falhas de segurança.
Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** 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`** com isolamento estrito por módulo e contexto de acesso (`--session <modulo>_<contexto?>`).
--- ---
@ -27,20 +27,29 @@ 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 perfil 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>` representa o perfil ou nível de acesso que está sendo testado), 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. - **Contextos Padronizados de Acesso:**
- Caso um mesmo módulo necessite de sub-isolamento para testes paralelos, deve-se adotar o sufixo determinístico `<modulo-id>-<slug-ou-pid>`. - `interno`: Acesso restrito a servidores públicos, fiscais, analistas internos ou administradores.
- `externo`: Acesso de requerentes externos, contribuintes ou cidadãos logados.
- `anonimo`: Acesso público e não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). **Obrigatório para assegurar ausência total de tokens ou cookies residuais de sessões anteriores.**
- `cliente`: Acesso de clientes ou empresas contratantes em plataformas multi-tenant ou B2B.
- Aplicações de contexto único sem distinção de perfis podem utilizar apenas `<modulo>` ou `<modulo>_default`.
- **Prevenção de Mistura de Tokens e Cookies:** Cada sessão do `agent-browser` possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>_<contexto>.sock`), mantendo cookie jar, cabeçalhos `Authorization`, LocalStorage e SessionStorage completamente estanques. Separar por `<modulo>_<contexto>` é estritamente obrigatório para que um teste anônimo não herde tokens de um teste interno, ou que credenciais de requerente externo não interfiram em fluxos administrativos.
- **Sub-isolamento Concorrente:** Caso múltiplos testes concorrentes ocorram no mesmo módulo e contexto, adota-se o sufixo determinístico: `<modulo>_<contexto>-<slug_ou_pid>`.
4. **Utilizar o modelo de referências (`@ref`)**: 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 de Teste 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`**. - O agente **DEVE OBRIGATORIAMENTE consultar `modulo-acesso` em `memorias-ia/modulo.yml`**.
- Se configurado com chaves específicas por contexto (`interno`, `externo`, `cliente`), extrair as credenciais do contexto sob teste.
- Se configurado no formato plano direto (`usuario` e `senha`), utilizar como credencial padrão para o contexto principal/interno.
- Para o contexto `anonimo`, o agente **NÃO deve autenticar**, validando a jornada como usuário não-logado na sessão isolada `<modulo>_anonimo`.
- É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste. - É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste.
--- ---
@ -63,55 +72,59 @@ 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, Definir Contexto 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}')
# Abrir sempre visível ao operador humano na sessão isolada do módulo # Definir contexto sob teste: interno | externo | anonimo | cliente
agent-browser --session "$MODULO" open --headed http://localhost:8080 CONTEXTO="interno" # ou externo, anonimo, cliente
SESSAO="${MODULO}_${CONTEXTO}"
# Abrir sempre visível ao operador humano na sessão isolada do módulo e contexto
agent-browser --session "$SESSAO" open --headed http://localhost:8080
``` ```
### 2. Inspeção de Elementos Interativos ### 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 "$SESSAO" 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 "$SESSAO" fill @e1 "usuario@exemplo.com"
agent-browser --session "$MODULO" fill @e2 "senhaSegura123" agent-browser --session "$SESSAO" fill @e2 "senhaSegura123"
agent-browser --session "$MODULO" click @e3 agent-browser --session "$SESSAO" 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 "$SESSAO" 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 "$SESSAO" 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 "$SESSAO" 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 "$SESSAO" 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 teste
agent-browser --session "$MODULO" close agent-browser --session "$SESSAO" close
``` ```
--- ---
@ -119,23 +132,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 sessões ou misturar tokens entre perfis.
- **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 testar fluxos anônimos em sessões já autenticadas**, garantindo que testes públicos sempre rodem na sessão `<modulo>_anonimo`.
- **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`). - **Proibido 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 <sessao> close`).
### Permitido e Recomendado ✅ ### Permitido e Recomendado ✅
- Manter sessões persistentes quando necessário via `--session <modulo> --restore`. - Manter sessões persistentes 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**: Previne contaminação entre sessões de administradores internos, cidadãos externos e consultas públicas anônimas.
- **Isolamento de Processos e Concorrência**: Múltiplos agentes rodando testes E2E simultâneos não colidem abas nem encerram daemons de outros contextos.
- **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real. - **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 +163,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`.

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

@ -3,7 +3,8 @@ 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 por módulo e contexto (--session <modulo>_<contexto?>)
para evitar mistura de tokens e cookies entre acessos.
scope: global scope: global
--- ---
@ -15,12 +16,18 @@ Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuár
--- ---
## 🔒 Princípio de Isolamento de Sessão por Módulo (`--session <modulo>`) ## 🔒 Princípio de Isolamento de Sessão por Módulo 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` utiliza sockets Unix independentes por sessão (`/run/user/1000/agent-browser/<sessao>.sock`). Em sistemas que possuem diferentes perfis de acesso, separar o contexto na flag de sessão é **indispensável para prevenir mistura de tokens JWT, cookies de autenticação e dados de LocalStorage**:
- **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>`. - **Todo comando DEVE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico de `memorias-ia/modulo.yml` e `<contexto>` é o perfil sob teste), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto>`.
- Caso múltiplos fluxos de teste concorrentes rodem no mesmo módulo, utilizar sufixo discriminador determinístico: `--session "${MODULO}-subfluxo"`. - **Contextos Padronizados:**
- `interno`: Acesso de analistas, fiscais, operadores internos ou administradores.
- `externo`: Acesso de requerentes externos, cidadãos cadastrados ou contribuintes logados.
- `anonimo`: Acesso público / não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). **Garante sessão limpa sem resíduo de autenticações anteriores.**
- `cliente`: Acesso de clientes ou empresas em plataformas multi-tenant ou B2B.
- Aplicações de contexto único sem múltiplos acessos podem utilizar apenas `<modulo>` ou `<modulo>_default`.
- **Sub-isolamento Concorrente:** Caso múltiplos fluxos concorrentes rodem no mesmo contexto: `--session "${MODULO}_${CONTEXTO}-${slug_ou_pid}"`.
--- ---
@ -30,7 +37,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,19 +63,23 @@ 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 Módulo e 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:
```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}')
agent-browser --session "$MODULO" open --headed http://localhost:8080 # Definir contexto sob teste: interno | externo | anonimo | cliente
CONTEXTO="interno" # ou externo, anonimo, cliente
SESSAO="${MODULO}_${CONTEXTO}"
agent-browser --session "$SESSAO" 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 "$SESSAO" snapshot -i
``` ```
*Saída de exemplo:* *Saída de exemplo:*
```text ```text
@ -82,45 +93,45 @@ agent-browser --session "$MODULO" snapshot -i
Utilize as referências identificadas (`@e1`, `@e2`, etc.): Utilize as referências identificadas (`@e1`, `@e2`, etc.):
```bash ```bash
# Preenchimento de campos de texto # Preenchimento de campos de texto
agent-browser --session "$MODULO" fill @e2 "12.345.678/0001-90" agent-browser --session "$SESSAO" fill @e2 "12.345.678/0001-90"
agent-browser --session "$MODULO" fill @e3 "Indústria Modelo LTDA" agent-browser --session "$SESSAO" fill @e3 "Indústria Modelo LTDA"
# Acionamento de botões e links # Acionamento de botões e links
agent-browser --session "$MODULO" click @e4 agent-browser --session "$SESSAO" 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 "$SESSAO" wait 1500
# Capturar novo snapshot para verificar se a lista ou mensagem apareceu # Capturar novo snapshot para verificar se a lista ou mensagem apareceu
agent-browser --session "$MODULO" snapshot -i agent-browser --session "$SESSAO" 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 "$SESSAO" console
# Verificar requisições de rede falhadas # Verificar requisições de rede falhadas
agent-browser --session "$MODULO" network agent-browser --session "$SESSAO" 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 "$SESSAO" screenshot evidencias/resultado-sucesso.png
# agent-browser --session "$MODULO" screenshot --annotate evidencias/resultado-anotado.png # agent-browser --session "$SESSAO" screenshot --annotate evidencias/resultado-anotado.png
``` ```
### 7. Encerrar Navegador ### 7. Encerrar Navegador
Finalize a sessão isolada limpando apenas os processos do seu módulo: Finalize a sessão isolada limpando apenas os processos do seu contexto e módulo:
```bash ```bash
agent-browser --session "$MODULO" close agent-browser --session "$SESSAO" close
``` ```
--- ---
@ -129,37 +140,55 @@ 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 Canônicas 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 correspondente:
```bash ```bash
# Extrair identificador e credenciais canônicas de teste de memorias-ia/modulo.yml # Identificar módulo e contexto
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" # interno | externo | cliente | anonimo
SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}') SESSAO="${MODULO}_${CONTEXTO}"
# Preenchimento determinístico no formulário de login na sessão isolada if [ "$CONTEXTO" = "anonimo" ]; then
agent-browser --session "$MODULO" fill @e1 "$USUARIO" # Contexto anônimo: navegação pública limpa sem autenticação
agent-browser --session "$MODULO" fill @e2 "$SENHA" echo "Iniciando sessão pública limpa: $SESSAO"
agent-browser --session "$MODULO" click @e3 agent-browser --session "$SESSAO" open --headed http://localhost:8080/consulta-publica
else
# Contexto autenticado: obter credenciais do perfil ou usar fallback direto
USUARIO=$(grep -A6 "modulo-acesso:" memorias-ia/modulo.yml | grep -A2 "${CONTEXTO}:" | grep "usuario:" | awk '{print $2}' || true)
SENHA=$(grep -A6 "modulo-acesso:" memorias-ia/modulo.yml | grep -A2 "${CONTEXTO}:" | grep "senha:" | awk '{print $2}' || true)
if [ -z "$USUARIO" ]; then
USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')
SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
fi
# Preenchimento determinístico no formulário de login na sessão isolada
agent-browser --session "$SESSAO" open --headed http://localhost:8080/login
agent-browser --session "$SESSAO" wait 1000
agent-browser --session "$SESSAO" snapshot -i
agent-browser --session "$SESSAO" fill @e1 "$USUARIO"
agent-browser --session "$SESSAO" fill @e2 "$SENHA"
agent-browser --session "$SESSAO" click @e3
fi
``` ```
> ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste. > ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste.
@ -170,11 +199,11 @@ agent-browser --session "$MODULO" click @e3
Para fluxos que necessitam manter login ativo entre comandos com isolamento: Para fluxos que necessitam manter login ativo entre comandos com isolamento:
```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 "$SESSAO" --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 "$SESSAO" session info --json
``` ```
--- ---
@ -194,6 +223,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 "$SESSAO" 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 "$SESSAO" wait 500 && agent-browser --session "$SESSAO" 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
validar-setup.sh
View file

@ -109,7 +109,7 @@ 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} (ex: ${MODULO_ID}_interno, ${MODULO_ID}_externo, ${MODULO_ID}_anonimo, ${MODULO_ID}_cliente)"
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)