From f47e12fe81b007d2e1ea558851e12cca2e6b8cca Mon Sep 17 00:00:00 2001 From: Luiz Silva Date: Thu, 8 Oct 2026 15:08:09 -0300 Subject: [PATCH] context agent --- DOCUMENTACAO/templates/modulo.yml.template | 18 ++- DOCUMENTACAO/templates/plano.md.template | 12 +- TOOLS | 4 +- TOOLS.md | 4 +- agents/front/agent.md | 2 +- agents/front/persona | 2 +- agents/testes/agent.json | 2 +- agents/testes/agent.md | 4 +- agents/testes/persona | 4 +- agents/ux/agent.md | 2 +- agents/ux/persona | 2 +- global/rules/identidade-modulo.md | 26 +++- .../rules/testes-interface-agent-browser.md | 82 ++++++----- global/skills/plano.executar/SKILL.md | 4 +- global/skills/plano/SKILL.md | 2 +- .../testar-interface-agent-browser/SKILL.md | 139 ++++++++++-------- global/workflows/plano.md | 2 +- rules/identidade-modulo.md | 26 +++- rules/testes-interface-agent-browser.md | 82 ++++++----- skills/plano.executar/SKILL.md | 4 +- skills/plano/SKILL.md | 2 +- .../testar-interface-agent-browser/SKILL.md | 139 ++++++++++-------- validar-setup.sh | 9 +- 23 files changed, 347 insertions(+), 226 deletions(-) diff --git a/DOCUMENTACAO/templates/modulo.yml.template b/DOCUMENTACAO/templates/modulo.yml.template index a5894c5..733dfcb 100644 --- a/DOCUMENTACAO/templates/modulo.yml.template +++ b/DOCUMENTACAO/templates/modulo.yml.template @@ -2,7 +2,7 @@ # Este arquivo é obrigatório na raiz de todos os projetos que utilizam .agent. # Ele define a identidade oficial e as configurações de rota do módulo. -# Identificador único do módulo (utilizado para pacotes, wikis //, regras de negócio e sessão isolada do agent-browser --session ) +# Identificador único do módulo (utilizado para pacotes, wikis //, regras de negócio e sessão isolada do agent-browser --session _) modulo-id: nome-do-modulo.submodulo # Rota/prefixo utilizado na URL e navegação do módulo (com barras inicial e final) @@ -14,10 +14,24 @@ modulo-descricao: Descrição detalhada do módulo para contextualização opera # Descrição da arquitetura, stack tecnológica e banco de dados modulo-tipo: aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres -# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA) +# Credenciais para autenticação em testes (agent-browser, E2E, QA) +# Formato Simples (aplicação com perfil único de acesso): modulo-acesso: usuario: usuario@exemplo.com.br senha: "123" +# Ou Formato Multi-Contexto (quando a aplicação possui acessos distintos - evita mistura de tokens): +# modulo-acesso: +# interno: +# usuario: operador@empresa.com.br +# senha: "123" +# cliente: +# usuario: cliente@cliente.com.br +# senha: "123" +# externo: +# usuario: cidadao@gov.br +# senha: "123" +# anonimo: null # acesso público/deslogado + # Caminho para a Wiki do projeto (quando omitido ou vazio, o padrão adotado é ../wiki/) modulo-wiki: ../wiki diff --git a/DOCUMENTACAO/templates/plano.md.template b/DOCUMENTACAO/templates/plano.md.template index 0994ec1..b41e04d 100644 --- a/DOCUMENTACAO/templates/plano.md.template +++ b/DOCUMENTACAO/templates/plano.md.template @@ -90,12 +90,12 @@ executor: null - Qualidade/Lint: `biome check --write ` - Governança: `sh .agent/verificar-linhas.sh` -### 5.2 Roteiro de Teste Manual / `agent-browser` (Sempre em Modo Visível `--headed` e com `--session `) -1. Abrir aplicação: `agent-browser --session open --headed ` -2. Mapear interações: `agent-browser --session snapshot -i` -3. Executar ações: `agent-browser --session fill @ref "..." && agent-browser --session click @ref` -4. Capturar evidência: `agent-browser --session screenshot evidencias/.png` -5. Encerrar: `agent-browser --session close` +### 5.2 Roteiro de Teste Manual / `agent-browser` (Sempre em Modo Visível `--headed` e com `--session _`) +1. Abrir aplicação: `agent-browser --session _ open --headed ` +2. Mapear interações: `agent-browser --session _ snapshot -i` +3. Executar ações: `agent-browser --session _ fill @ref "..." && agent-browser --session _ click @ref` +4. Capturar evidência: `agent-browser --session _ screenshot evidencias/.png` +5. Encerrar: `agent-browser --session _ close` --- diff --git a/TOOLS b/TOOLS index 4b32cf3..eaea253 100644 --- a/TOOLS +++ b/TOOLS @@ -94,8 +94,8 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot ### agent-browser - **Descrição:** CLI de automação de navegadores baseada em Rust, projetada especificamente para Agentes de IA. - **Por que ajuda as IAs:** Utiliza representação compacta da árvore de acessibilidade com referências determinísticas (`@e1`, `@e2`), consumindo 200–400 tokens (até 90% menos tokens que a leitura do DOM completo). Permite executar testes E2E, interagir com telas, validar fluxos e registrar evidências visuais. -- **Modo Visível Obrigatório:** Para que o operador acompanhe cada teste em tempo real na tela, execute sempre com a flag `--headed` (ex: `agent-browser --session open --headed `) ou defina `export AGENT_BROWSER_HEADED=true`. -- **Isolamento Mandatório de Sessão:** Toda execução DEVE acompanhar a flag `--session ` (onde `` é o `modulo-id` extraído de `memorias-ia/modulo.yml`) ou garantir `export AGENT_BROWSER_SESSION=`. Cada sessão aloca daemon e socket Unix exclusivos, prevenindo colisões e fechamento indevido de janelas em execuções concorrentes. +- **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 _ open --headed `) ou defina `export AGENT_BROWSER_HEADED=true`. +- **Isolamento Mandatório de Sessão e Contexto:** Toda execução DEVE acompanhar a flag `--session _` (onde `` é o `modulo-id` extraído de `memorias-ia/modulo.yml` e `` discrimina acessos como `interno`, `externo`, `cliente`, `anonimo`) ou garantir `export AGENT_BROWSER_SESSION=_`. Previne fechamento indevido de processos e contaminação cruzada de cookies e tokens JWT entre diferentes perfis de usuário. - **Instalação:** - Com Bun (padrão): `bun i -g agent-browser && agent-browser install` - Com NPM: `npm install -g agent-browser && agent-browser install` diff --git a/TOOLS.md b/TOOLS.md index 4b32cf3..eaea253 100644 --- a/TOOLS.md +++ b/TOOLS.md @@ -94,8 +94,8 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot ### agent-browser - **Descrição:** CLI de automação de navegadores baseada em Rust, projetada especificamente para Agentes de IA. - **Por que ajuda as IAs:** Utiliza representação compacta da árvore de acessibilidade com referências determinísticas (`@e1`, `@e2`), consumindo 200–400 tokens (até 90% menos tokens que a leitura do DOM completo). Permite executar testes E2E, interagir com telas, validar fluxos e registrar evidências visuais. -- **Modo Visível Obrigatório:** Para que o operador acompanhe cada teste em tempo real na tela, execute sempre com a flag `--headed` (ex: `agent-browser --session open --headed `) ou defina `export AGENT_BROWSER_HEADED=true`. -- **Isolamento Mandatório de Sessão:** Toda execução DEVE acompanhar a flag `--session ` (onde `` é o `modulo-id` extraído de `memorias-ia/modulo.yml`) ou garantir `export AGENT_BROWSER_SESSION=`. Cada sessão aloca daemon e socket Unix exclusivos, prevenindo colisões e fechamento indevido de janelas em execuções concorrentes. +- **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 _ open --headed `) ou defina `export AGENT_BROWSER_HEADED=true`. +- **Isolamento Mandatório de Sessão e Contexto:** Toda execução DEVE acompanhar a flag `--session _` (onde `` é o `modulo-id` extraído de `memorias-ia/modulo.yml` e `` discrimina acessos como `interno`, `externo`, `cliente`, `anonimo`) ou garantir `export AGENT_BROWSER_SESSION=_`. Previne fechamento indevido de processos e contaminação cruzada de cookies e tokens JWT entre diferentes perfis de usuário. - **Instalação:** - Com Bun (padrão): `bun i -g agent-browser && agent-browser install` - Com NPM: `npm install -g agent-browser && agent-browser install` diff --git a/agents/front/agent.md b/agents/front/agent.md index 78a6268..c7409a7 100644 --- a/agents/front/agent.md +++ b/agents/front/agent.md @@ -54,7 +54,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 8. Implementar fluxos de navegação e estados de interface 9. Criar e manter arquivo `{componente}.ajuda.md` co-localizado (para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`) sempre que houver ajuda contextual (ver `skills/adicionar-ajuda`) 10. Escrever comentários claros e coerentes quanto à aplicação prática em componentes e composables (ver `rules/jsdoc-padrao.md`) -11. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session `)** 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 _`)** para acompanhamento do operador e prevenção de mistura de tokens e conflitos de sessão (ver `rules/testes-interface-agent-browser.md`) ## Restrições diff --git a/agents/front/persona b/agents/front/persona index d579dbc..c447b5d 100644 --- a/agents/front/persona +++ b/agents/front/persona @@ -47,7 +47,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 8. Implementar fluxos de navegação e estados de interface 9. Criar e manter arquivo `{componente}.ajuda.md` co-localizado (para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`) sempre que houver ajuda contextual (ver `skills/adicionar-ajuda`) 10. Escrever comentários claros e coerentes quanto à aplicação prática em componentes e composables (ver `rules/jsdoc-padrao.md`) -11. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session `)** 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 _`)** para acompanhamento do operador e prevenção de mistura de tokens e conflitos de sessão (ver `rules/testes-interface-agent-browser.md`) ## Restrições diff --git a/agents/testes/agent.json b/agents/testes/agent.json index 24e9001..50164dc 100644 --- a/agents/testes/agent.json +++ b/agents/testes/agent.json @@ -8,7 +8,7 @@ "systemPromptSections": [ { "title": "Identidade e Escopo", - "content": "---\nname: testes\ndisplay_name: \"Agente de Testes\"\ndescription: >\n Responsável pela elaboração de rotinas, cenários e critérios de testes,\n tanto para execução por humanos quanto por IAs, garantindo qualidade e\n confiabilidade do software.\nscope: [back, front, comuns]\ninherits: [global]\ntools:\n - view_file\n - list_dir\n - grep_search\n - write_to_file\n - replace_file_content\n - multi_replace_file_content\n - run_command\n - send_message\n---\n\n# Agente de Testes (@testes)\n\n## Identidade\n\nVocê é o agente responsável por garantir a qualidade e confiabilidade do ecossistema Azteca. Você pensa em casos extremos, cenários de falha e comportamentos inesperados. Seu trabalho é tornar bugs impossíveis de esconder.\n\n## Idioma\n\nToda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.\n\n## Escopo de Atuação\n\n- Todos os pacotes: `*-back`, `*-front`, `*-comuns`\n- Testes unitários, de integração e de aceitação\n- Roteiros de teste manual para QA humano\n- Critérios de aceite para features\n\n## Responsabilidades\n\n1. **Diagnosticar antes de testar** — executar a skill `diagnosticar-cobertura-testes` para mapear gaps antes de criar testes (ver `global/rules/diagnostico-antes-correcao`)\n2. Criar e manter testes unitários para lógica de negócio crítica\n3. Criar testes de integração para rotas de API\n4. Elaborar roteiros de teste manual (cenários passo a passo)\n5. Definir critérios de aceite para cada feature\n6. Identificar casos extremos e cenários de falha não cobertos\n7. Validar schemas Zod contra dados reais de produção\n8. Documentar bugs encontrados com passos de reprodução\n9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session `)** 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`)\n10. **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`).\n\n## Restrições\n\n- NUNCA criar testes sem antes diagnosticar a cobertura existente (ver `global/rules/diagnostico-antes-correcao`)\n- NÃO modifica código de produção — apenas cria/modifica arquivos de teste\n- NÃO aprova uma feature sem cobertura dos cenários críticos\n- Testes devem ser independentes e repetíveis\n- Nunca mockar comportamentos sem documentar o que está sendo substituído\n\n## Colaborações\n\n- **Recebe entregáveis de:** `@back`, `@front`\n- **Recebe especificações de:** `@arquiteto`\n- **Reporta problemas para:** `@back`, `@front` (gerando planos técnicos de ação em `PLANOS/pendente/`)\n- **Informa qualidade para:** `@deploy` (antes do deploy)\n\n## Tom e Estilo\n\n- Cético construtivo — assume que o código pode falhar\n- Cenários escritos em linguagem do domínio (Gherkin-style quando aplicável)\n- Documenta o \"o que\" e o \"por que\" de cada cenário\n\n## Contexto de Referência\n\nEste repositório é consumido como **git submodule** em `.agent/` dentro de cada projeto filho. Os artefatos seguem a hierarquia:\n\n```\nprojeto/\n├── .agent/ ← git submodule (este repo — read-only, nunca editar)\n│ ├── global/ ← rules, workflows e skills herdados\n│ └── agents/ ← personas e artefatos de cada agente\n├── .agent-local/ ← extensões do projeto (rules, workflows, skills)\n│ ├── rules/\n│ ├── workflows/\n│ ├── skills/\n│ └── agents/\n└── .gemini/agents/ ← symlinks para .agent/agents/ (Antigravity)\n```\n\n### Onde encontrar artefatos\n\n| Tipo | Caminho |\n|------|---------|\n| Rules globais (herdadas) | `.agent/global/rules/` |\n| Workflows globais (herdados) | `.agent/global/workflows/` |\n| Skills globais (herdadas) | `.agent/global/skills/` |\n| Personas dos agentes | `.agent/agents/*/persona` |\n| Rules locais do projeto | `.agent-local/rules/` |\n| Workflows locais do projeto | `.agent-local/workflows/` |\n| Skills locais do projeto | `.agent-local/skills/` |\n\n### Precedência\n\n```\n.agent-local/ > .agent/ (base)\n```\n\nArtefatos em `.agent-local/` sempre têm prioridade sobre os herdados de `.agent/`.\n\n\n## Checklist de cobertura mínima\n\n- [ ] Happy path (fluxo principal) coberto?\n- [ ] Entradas inválidas testadas?\n- [ ] Casos extremos (null, vazio, limite) testados?\n- [ ] Erros de rede/banco simulados?\n- [ ] Performance em volume realista de dados?\n- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) e com sessão isolada (`--session `), com screenshots comprobatórios?\n\n## Memória Persistente & Identidade do Projeto\n\nO arquivo `/memorias-ia/modulo.yml` é de **existência obrigatória em todos os projetos** e define a identidade do módulo (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`).\n- Toda vez que precisar do ID do módulo (`modulo-id`), da rota/prefixo de URL (`modulo-caminho`), ou de informações de tipo/descrição (`modulo-tipo` / `modulo-descricao`), consulte obrigatoriamente `memorias-ia/modulo.yml`.\n- Toda memória das ações, registros de sessões e decisões tomadas pela IA deve ser armazenada em `/memorias-ia/` na raiz do projeto pai.\n\n### Regras de Operação\n- Gravar registros de ações, sessões e decisões da IA em `/memorias-ia/`.\n- Toda memória deve ser um arquivo Markdown com frontmatter (`type`, `name`, `description`, `session_date`, `updatedAt`).\n" + "content": "---\nname: testes\ndisplay_name: \"Agente de Testes\"\ndescription: >\n Responsável pela elaboração de rotinas, cenários e critérios de testes,\n tanto para execução por humanos quanto por IAs, garantindo qualidade e\n confiabilidade do software.\nscope: [back, front, comuns]\ninherits: [global]\ntools:\n - view_file\n - list_dir\n - grep_search\n - write_to_file\n - replace_file_content\n - multi_replace_file_content\n - run_command\n - send_message\n---\n\n# Agente de Testes (@testes)\n\n## Identidade\n\nVocê é o agente responsável por garantir a qualidade e confiabilidade do ecossistema Azteca. Você pensa em casos extremos, cenários de falha e comportamentos inesperados. Seu trabalho é tornar bugs impossíveis de esconder.\n\n## Idioma\n\nToda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.\n\n## Escopo de Atuação\n\n- Todos os pacotes: `*-back`, `*-front`, `*-comuns`\n- Testes unitários, de integração e de aceitação\n- Roteiros de teste manual para QA humano\n- Critérios de aceite para features\n\n## Responsabilidades\n\n1. **Diagnosticar antes de testar** — executar a skill `diagnosticar-cobertura-testes` para mapear gaps antes de criar testes (ver `global/rules/diagnostico-antes-correcao`)\n2. Criar e manter testes unitários para lógica de negócio crítica\n3. Criar testes de integração para rotas de API\n4. Elaborar roteiros de teste manual (cenários passo a passo)\n5. Definir critérios de aceite para cada feature\n6. Identificar casos extremos e cenários de falha não cobertos\n7. Validar schemas Zod contra dados reais de produção\n8. Documentar bugs encontrados com passos de reprodução\n9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session _`)** para que o operador acompanhe cada ação na tela e evitar mistura de tokens/cookies entre acessos interno, cliente, externo e anônimo (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`)\n10. **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`).\n\n## Restrições\n\n- NUNCA criar testes sem antes diagnosticar a cobertura existente (ver `global/rules/diagnostico-antes-correcao`)\n- NÃO modifica código de produção — apenas cria/modifica arquivos de teste\n- NÃO aprova uma feature sem cobertura dos cenários críticos\n- Testes devem ser independentes e repetíveis\n- Nunca mockar comportamentos sem documentar o que está sendo substituído\n\n## Colaborações\n\n- **Recebe entregáveis de:** `@back`, `@front`\n- **Recebe especificações de:** `@arquiteto`\n- **Reporta problemas para:** `@back`, `@front` (gerando planos técnicos de ação em `PLANOS/pendente/`)\n- **Informa qualidade para:** `@deploy` (antes do deploy)\n\n## Tom e Estilo\n\n- Cético construtivo — assume que o código pode falhar\n- Cenários escritos em linguagem do domínio (Gherkin-style quando aplicável)\n- Documenta o \"o que\" e o \"por que\" de cada cenário\n\n## Contexto de Referência\n\nEste repositório é consumido como **git submodule** em `.agent/` dentro de cada projeto filho. Os artefatos seguem a hierarquia:\n\n```\nprojeto/\n├── .agent/ ← git submodule (este repo — read-only, nunca editar)\n│ ├── global/ ← rules, workflows e skills herdados\n│ └── agents/ ← personas e artefatos de cada agente\n├── .agent-local/ ← extensões do projeto (rules, workflows, skills)\n│ ├── rules/\n│ ├── workflows/\n│ ├── skills/\n│ └── agents/\n└── .gemini/agents/ ← symlinks para .agent/agents/ (Antigravity)\n```\n\n### Onde encontrar artefatos\n\n| Tipo | Caminho |\n|------|---------|\n| Rules globais (herdadas) | `.agent/global/rules/` |\n| Workflows globais (herdados) | `.agent/global/workflows/` |\n| Skills globais (herdadas) | `.agent/global/skills/` |\n| Personas dos agentes | `.agent/agents/*/persona` |\n| Rules locais do projeto | `.agent-local/rules/` |\n| Workflows locais do projeto | `.agent-local/workflows/` |\n| Skills locais do projeto | `.agent-local/skills/` |\n\n### Precedência\n\n```\n.agent-local/ > .agent/ (base)\n```\n\nArtefatos em `.agent-local/` sempre têm prioridade sobre os herdados de `.agent/`.\n\n\n## Checklist de cobertura mínima\n\n- [ ] Happy path (fluxo principal) coberto?\n- [ ] Entradas inválidas testadas?\n- [ ] Casos extremos (null, vazio, limite) testados?\n- [ ] Erros de rede/banco simulados?\n- [ ] Performance em volume realista de dados?\n- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) e com sessão isolada por contexto (`--session _`), com screenshots comprobatórios?\n\n## Memória Persistente & Identidade do Projeto\n\nO arquivo `/memorias-ia/modulo.yml` é de **existência obrigatória em todos os projetos** e define a identidade do módulo (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`).\n- Toda vez que precisar do ID do módulo (`modulo-id`), da rota/prefixo de URL (`modulo-caminho`), ou de informações de tipo/descrição (`modulo-tipo` / `modulo-descricao`), consulte obrigatoriamente `memorias-ia/modulo.yml`.\n- Toda memória das ações, registros de sessões e decisões tomadas pela IA deve ser armazenada em `/memorias-ia/` na raiz do projeto pai.\n\n### Regras de Operação\n- Gravar registros de ações, sessões e decisões da IA em `/memorias-ia/`.\n- Toda memória deve ser um arquivo Markdown com frontmatter (`type`, `name`, `description`, `session_date`, `updatedAt`).\n" } ], "toolNames": [ diff --git a/agents/testes/agent.md b/agents/testes/agent.md index 4802d4c..13c9758 100644 --- a/agents/testes/agent.md +++ b/agents/testes/agent.md @@ -53,7 +53,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 6. Identificar casos extremos e cenários de falha não cobertos 7. Validar schemas Zod contra dados reais de produção 8. Documentar bugs encontrados com passos de reprodução -9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session `)** 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 _`)** para que o operador acompanhe cada ação na tela e evitar mistura de tokens/cookies entre acessos interno, cliente, externo e anônimo (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`) 10. **Gerar Planos Técnicos via `/plano`** — durante homologações, reviews ou testes, formalizar bugs, melhorias e gaps em planos estruturados em `PLANOS/pendente/` para posterior implementação pelo time de desenvolvimento (ver `global/workflows/plano.md`). ## Restrições @@ -122,7 +122,7 @@ Artefatos em `.agent-local/` sempre têm prioridade sobre os herdados de `.agent - [ ] Casos extremos (null, vazio, limite) testados? - [ ] Erros de rede/banco simulados? - [ ] Performance em volume realista de dados? -- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) e com sessão isolada (`--session `), com screenshots comprobatórios? +- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) e com sessão isolada por contexto (`--session _`), com screenshots comprobatórios? ## Memória Persistente & Identidade do Projeto diff --git a/agents/testes/persona b/agents/testes/persona index 42de989..bff370e 100644 --- a/agents/testes/persona +++ b/agents/testes/persona @@ -45,7 +45,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 6. Identificar casos extremos e cenários de falha não cobertos 7. Validar schemas Zod contra dados reais de produção 8. Documentar bugs encontrados com passos de reprodução -9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session `)** 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 _`)** para que o operador acompanhe cada ação na tela e evitar mistura de tokens/cookies entre acessos interno, cliente, externo e anônimo (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`) 10. **Gerar Planos Técnicos via `/plano`** — durante homologações, reviews ou testes, formalizar bugs, melhorias e gaps em planos estruturados em `PLANOS/pendente/` para posterior implementação pelo time de desenvolvimento (ver `global/workflows/plano.md`). ## Restrições @@ -114,7 +114,7 @@ Artefatos em `.agent-local/` sempre têm prioridade sobre os herdados de `.agent - [ ] Casos extremos (null, vazio, limite) testados? - [ ] Erros de rede/banco simulados? - [ ] Performance em volume realista de dados? -- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) e com sessão isolada (`--session `), com screenshots comprobatórios? +- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) e com sessão isolada por contexto (`--session _`), com screenshots comprobatórios? ## Memória Persistente & Identidade do Projeto diff --git a/agents/ux/agent.md b/agents/ux/agent.md index c3f16bb..1d8111e 100644 --- a/agents/ux/agent.md +++ b/agents/ux/agent.md @@ -51,7 +51,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 6. Organizar a hierarquia de informação das telas 7. Revisar labels, placeholders e textos de ajuda 8. Identificar inconsistências de UX entre módulos -9. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session `)** 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 _`)** para que o operador acompanhe a validação visual e evitar mistura de tokens e estados de interface (ver `rules/testes-interface-agent-browser.md`) ## Restrições diff --git a/agents/ux/persona b/agents/ux/persona index b871d48..129ac54 100644 --- a/agents/ux/persona +++ b/agents/ux/persona @@ -45,7 +45,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas 6. Organizar a hierarquia de informação das telas 7. Revisar labels, placeholders e textos de ajuda 8. Identificar inconsistências de UX entre módulos -9. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão (`--session `)** 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 _`)** para que o operador acompanhe a validação visual e evitar mistura de tokens e estados de interface (ver `rules/testes-interface-agent-browser.md`) ## Restrições diff --git a/global/rules/identidade-modulo.md b/global/rules/identidade-modulo.md index 05ba1a4..41dac09 100644 --- a/global/rules/identidade-modulo.md +++ b/global/rules/identidade-modulo.md @@ -5,7 +5,7 @@ description: Identificação obrigatória do projeto/módulo via memorias-ia/mod scope: global trigger: always_on priority: critica -updatedAt: "2026-10-06" +updatedAt: "2026-10-08" --- # Regra: Identidade do Projeto via `memorias-ia/modulo.yml` @@ -38,11 +38,25 @@ modulo-caminho: modulo-descricao: modulo-tipo: -# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA) +# Credenciais para autenticação em testes (agent-browser, E2E, QA) +# Formato Simples (aplicação com contexto único de acesso): modulo-acesso: usuario: senha: +# Ou Formato Multi-Contexto (quando a aplicação possui acessos distintos - evita mistura de tokens): +# modulo-acesso: +# interno: +# usuario: +# senha: +# cliente: +# usuario: +# senha: +# externo: +# usuario: +# senha: +# anonimo: null # acesso público/deslogado + # Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/) modulo-wiki: ``` @@ -51,11 +65,11 @@ modulo-wiki: | Campo | Tipo | Descrição | Exemplo | | :--- | :--- | :--- | :--- | -| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e identificador mandatório de sessão isolada no `agent-browser` (`--session `). | `e-licencie.sigma` | +| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e prefixo da sessão isolada no `agent-browser` (`--session _`). | `e-licencie.sigma` | | **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/sigma/` | | **`modulo-descricao`** | `string` | Descrição textual do propósito funcional e escopo de negócio do módulo. | `Módulo para gestão de monitoramentos ambientais` | | **`modulo-tipo`** | `string` | Descrição textual da arquitetura e tecnologias empregadas no módulo. | `aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres` | -| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`). | `{ usuario: "admin@gov.br", senha: "123" }` | +| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) ou organizadas por contexto (`interno`, `externo`, `cliente`, `anonimo`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`), prevenindo mistura de tokens. | `{ usuario: "admin@gov.br", senha: "123" }` ou subchaves de contexto | | **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` | --- @@ -63,10 +77,10 @@ modulo-wiki: ## Regra Universal de Consulta Sempre que qualquer agente, persona, workflow ou skill necessitar de: -1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`//`), Wiki de Desenvolvimento (`/dev//`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`/dev//adrs/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session `)**; +1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`//`), Wiki de Desenvolvimento (`/dev//`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`/dev//adrs/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session _`)**; 2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `llm.md`), links de navegação ou proxies; 3. **Propósito ou Stack (`modulo-descricao` e `modulo-tipo`)**: para contextualizar novos agentes, gerar propostas comerciais, marketing, reels, análises de arquitetura ou testes; -4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística em rotinas de teste e validação de interface; +4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair as credenciais do contexto específico (`interno`, `externo`, `cliente`, etc.) ou credenciais diretas de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística sem contaminação de cookies/tokens entre perfis; 5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia; 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`. diff --git a/global/rules/testes-interface-agent-browser.md b/global/rules/testes-interface-agent-browser.md index c929846..9688e5b 100644 --- a/global/rules/testes-interface-agent-browser.md +++ b/global/rules/testes-interface-agent-browser.md @@ -1,7 +1,7 @@ --- type: rule name: testes-interface-agent-browser -description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) e com isolamento por sessão (--session ). +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 _). scope: global trigger: always_on updatedAt: "2026-10-08" @@ -13,7 +13,7 @@ updatedAt: "2026-10-08" Quando uma IA precisa testar o frontend, validar jornadas de usuário, inspecionar componentes gráficos ou simular interações na tela, é crucial utilizar uma ferramenta rápida, determinística e econômica em tokens. Além disso, o operador humano deve sempre ter visibilidade do que a IA está executando em tempo real na interface gráfica. -Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Para viabilizar testes concorrentes e evitar interferências mútuas entre múltiplos módulos ou workspaces, todo comando deve operar em sessão isolada identificada pelo módulo. +Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Para viabilizar testes concorrentes e evitar interferências mútuas entre múltiplos módulos ou workspaces, todo comando deve operar em sessão isolada identificada pelo módulo e pelo contexto de acesso. Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA. @@ -27,24 +27,38 @@ Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar 2. **Executar SEMPRE em Modo Visível (`--headed`)**: - A janela do navegador **deve sempre aparecer na área de trabalho do operador**. - É **terminantemente proibido** rodar testes ocultos (headless silencioso), a menos que o operador humano solicite expressamente essa exceção. - - Usar a flag `--headed` nos comandos de abertura (`agent-browser --session open --headed `) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`. -3. **Isolamento Mandatório de Sessão (`--session `)**: - - **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo. - - Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session `** (onde `` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=`. - - Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos em testes simultâneos multi-módulos. - - Caso um mesmo módulo necessite de sub-isolamento para testes paralelos, deve-se adotar o sufixo determinístico `-`. + - Usar a flag `--headed` nos comandos de abertura (`agent-browser --session _ open --headed `) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`. +3. **Isolamento Mandatório de Sessão e Contexto (`--session _`)**: + - **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo e o contexto de acesso. + - Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session _`** (onde `` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml` e `` discrimina o papel ou natureza do acesso), ou garantir no ambiente `export AGENT_BROWSER_SESSION=_`. + - **Prevenção de Mistura de Tokens:** Caso a aplicação possua mais de um tipo de acesso (`interno`, `externo`, `anonimo`, `cliente`, etc.), o `` **DEVE SER OBRIGATORIAMENTE PREENCHIDO** para evitar que cookies, tokens JWT e estados de login residuais contaminem outros fluxos de teste. + - Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/_.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos. + - Caso um mesmo módulo e contexto necessite de sub-isolamento para testes paralelos, adota-se o discriminador determinístico: `__`. 4. **Utilizar o modelo de referências (`@ref`)**: - - Mapear a tela via `agent-browser --session snapshot -i`, obtendo referências compactas como `@e1`, `@e2`. + - Mapear a tela via `agent-browser --session _ snapshot -i`, obtendo referências compactas como `@e1`, `@e2`. - Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`). 5. **Registrar evidências e fechar sessão**: - - Registrar comprovações visuais com `agent-browser --session screenshot `. - - Encerrar graciosamente o navegador com `agent-browser --session close` ao término do fluxo. -6. **Credenciais Canônicas de Teste (`modulo-acesso`)**: - - Sempre que o teste exigir autenticação (login, sessão administrativa), o agente **DEVE OBRIGATORIAMENTE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml`**. + - Registrar comprovações visuais com `agent-browser --session _ screenshot `. + - Encerrar graciosamente o navegador com `agent-browser --session _ close` ao término do fluxo. +6. **Credenciais Canônicas por Contexto (`modulo-acesso`)**: + - Sempre que o teste exigir autenticação, o agente **DEVE OBRIGATORIAMENTE extrair as credenciais do contexto específico** em `modulo-acesso` de `memorias-ia/modulo.yml` (ex: `modulo-acesso.interno`, `modulo-acesso.cliente`, etc.). + - Para sessões anônimas (`_anonimo`), nenhum login deve ser realizado, garantindo a validação da experiência do usuário público sem tokens. - É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste. --- +## 🔒 Contextos Canônicos de Sessão (`_`) + +| Contexto | Finalidade e Natureza | Exemplo de Sessão | Credenciais em `modulo.yml` | +| :--- | :--- | :--- | :--- | +| **`interno`** | Operador interno, suporte, técnico, atendente, administrador | `--session _interno` | `modulo-acesso.interno` (ou `modulo-acesso` simples) | +| **`cliente`** | Cliente final, solicitante corporativo, empresa contratante | `--session _cliente` | `modulo-acesso.cliente` | +| **`externo`** | Portal público autenticado, cidadão, requerente externo | `--session _externo` | `modulo-acesso.externo` | +| **`anonimo`** | Usuário deslogado, consulta pública por código, login, landing | `--session _anonimo` | Nenhuma (perfil limpo sem cookies/tokens) | +| **``** | Papel especializado de domínio (ex: `fiscal`, `auditor`) | `--session _` | `modulo-acesso.` | + +--- + ## Instalação e Configuração O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium: @@ -63,55 +77,56 @@ Documentação de referência: **https://agent-browser.dev/** ## Protocolo Operacional Padrão -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 ```bash # Obter o modulo-id canônico de memorias-ia/modulo.yml MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}') +CONTEXTO="interno" # ou "cliente", "externo", "anonimo" -# Abrir sempre visível ao operador humano na sessão isolada do módulo -agent-browser --session "$MODULO" open --headed http://localhost:8080 +# Abrir sempre visível ao operador na sessão isolada por módulo e contexto +agent-browser --session "${MODULO}_${CONTEXTO}" open --headed http://localhost:8080 ``` ### 2. Inspeção de Elementos Interativos ```bash # Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2) -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i ``` ### 3. Interações por Referência Direta ```bash # Interagir diretamente com os elementos identificados no snapshot -agent-browser --session "$MODULO" fill @e1 "usuario@exemplo.com" -agent-browser --session "$MODULO" fill @e2 "senhaSegura123" -agent-browser --session "$MODULO" click @e3 +agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "usuario@exemplo.com" +agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "senhaSegura123" +agent-browser --session "${MODULO}_${CONTEXTO}" click @e3 ``` ### 4. Validação e Evidência ```bash # Aguardar estabilização se houver transição assíncrona -agent-browser --session "$MODULO" wait 1000 +agent-browser --session "${MODULO}_${CONTEXTO}" wait 1000 # Obter novo snapshot para verificar estado pós-ação -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i # Capturar evidência gráfica do teste -agent-browser --session "$MODULO" screenshot evidencias/teste-login-sucesso.png +agent-browser --session "${MODULO}_${CONTEXTO}" screenshot evidencias/teste-login-sucesso.png # Verificar erros no console do navegador -agent-browser --session "$MODULO" console +agent-browser --session "${MODULO}_${CONTEXTO}" console ``` ### 5. Finalização ```bash -# Fechar a sessão isolada do navegador ao concluir o teste -agent-browser --session "$MODULO" close +# Fechar a sessão isolada do navegador ao concluir o fluxo daquele contexto +agent-browser --session "${MODULO}_${CONTEXTO}" close ``` --- @@ -119,23 +134,25 @@ agent-browser --session "$MODULO" close ## Boas Práticas e Proibições ### Proibido ❌ -- **Proibido executar sem a flag `--session `** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada. +- **Proibido executar sem a flag `--session _`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada. +- **Proibido misturar acessos com perfis diferentes na mesma sessão genérica sem contexto** (ex: logar como operador interno e depois testar fluxo de cliente ou anônimo na mesma sessão, causando mistura de tokens). - **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`. - **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`). - **Proibido navegar para URLs desconhecidas** ou inventadas pela IA fora do escopo aprovado do teste. -- **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session close`). +- **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session _ close`). ### Permitido e Recomendado ✅ -- Manter sessões persistentes quando necessário via `--session --restore`. -- Utilizar sub-isolamento determinístico (`-`) caso múltiplos testes do mesmo módulo ocorram simultaneamente no mesmo host. -- Usar `agent-browser --session screenshot --annotate` para inspecionar layouts complexos com visão computacional. +- Manter sessões persistentes por contexto quando necessário via `--session _ --restore`. +- Utilizar sub-isolamento determinístico (`__`) caso múltiplos testes do mesmo contexto ocorram simultaneamente no mesmo host. +- Usar `agent-browser --session _ screenshot --annotate` para inspecionar layouts complexos com visão computacional. - Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`. --- ## Impacto -- **Isolamento e Concorrência**: Múltiplos agentes ou módulos rodando testes E2E simultâneos não conflitam de abas nem fecham janelas alheias. +- **Isolamento de Tokens e Cookies**: Evita vazamento de credenciais e estados de autenticação entre acessos de operador interno, cliente corporativo, cidadão e visitante anônimo. +- **Isolamento e Concorrência**: Múltiplos agentes ou testes E2E simultâneos não conflitam de abas nem fecham janelas alheias. - **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real. - **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. @@ -148,4 +165,3 @@ agent-browser --session "$MODULO" close - Skill associada: `skills/testar-interface-agent-browser/SKILL.md` - Rule associada: `rules/identidade-modulo.md` - Ferramentas CLI: `.agent/TOOLS` - diff --git a/global/skills/plano.executar/SKILL.md b/global/skills/plano.executar/SKILL.md index d2313c2..c61f101 100644 --- a/global/skills/plano.executar/SKILL.md +++ b/global/skills/plano.executar/SKILL.md @@ -56,7 +56,7 @@ O Orquestrador Líder decompõe a especificação técnica do plano e distribui | **`@front`** *(Frontend Specialist)* | `*-front`, `*-comuns` | Componentes Vue 3, composables, views, formulários reativos, binding de eventos, consumo de APIs e CSS co-localizado. | | **`@ux`** *(UX Specialist)* | `*-front` (Interface & Heurísticas) | Aplicação das Heurísticas de Nielsen: visibilidade do estado (spinners, loading, feedback imediato), clareza cognitiva, prevenção de erros e mensagens amigáveis ao usuário. | | **`@refatorar`** *(Clean Code Specialist)* | Todo o código alterado | Governança estrita das 12 regras de Código Limpo: garantia do **limite de 250 linhas por arquivo**, eliminação de code smells, modularidade e Dispatch Tables. | -| **`@testes`** *(QA & Automation)* | Checagens e Validação E2E | Tipagem (`bun run typecheck` / `tsc --noEmit`), linter (`biome check --write`), governança (`sh .agent/verificar-linhas.sh`) e testes de interface visual via `agent-browser --session --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 _ --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//`). | --- @@ -80,7 +80,7 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof ↓ 4. [@refatorar] Extrai módulos se exceder 250 linhas e aplica Código Limpo ↓ -5. [@testes] Roda typecheck, biome e testes E2E com agent-browser --session --headed +5. [@testes] Roda typecheck, biome e testes E2E com agent-browser --session _ --headed ↓ (Loop /goal de auto-correção se houver falhas) 6. [@documentacao] Atualiza memórias-ia/, historico-acoes.md e arquiva o plano ``` diff --git a/global/skills/plano/SKILL.md b/global/skills/plano/SKILL.md index 922a45e..144ff3a 100644 --- a/global/skills/plano/SKILL.md +++ b/global/skills/plano/SKILL.md @@ -74,7 +74,7 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer - **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps e arquivos mapeados com links `[arquivo](file://...)`. - **3. Critérios de Aceite & Validação (DoD):** Checklist com caixas `- [ ]` contendo condições verificáveis de sucesso. - **4. Especificação Técnica & Passos de Implementação:** Roteiro prático para o desenvolvedor (schemas, backend, frontend, código sugerido). - - **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session --headed`. + - **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session _ --headed`. - **6. Histórico de Execução:** Cabeçalho reservado para preenchimento na conclusão pelo executor. - Salve o arquivo em `./PLANOS/pendente/AAAA-MM-DD-HH-mm-.md` usando `write_to_file`. diff --git a/global/skills/testar-interface-agent-browser/SKILL.md b/global/skills/testar-interface-agent-browser/SKILL.md index 4ce13bb..8de4388 100644 --- a/global/skills/testar-interface-agent-browser/SKILL.md +++ b/global/skills/testar-interface-agent-browser/SKILL.md @@ -3,7 +3,7 @@ name: testar-interface-agent-browser description: > Executar testes automatizados de interface (E2E), navegação e validação visual no frontend utilizando a CLI agent-browser, com janela sempre visível (--headed) - e isolamento mandatório de sessão por módulo (--session ). + e isolamento mandatório de sessão e contexto (--session _). scope: global --- @@ -11,16 +11,31 @@ scope: global ## Objetivo -Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuário, preencher formulários, inspecionar componentes gráficos e validar fluxos no frontend de maneira rápida, determinística e econômica em tokens, garantindo isolamento total entre processos e visualização em tempo real pelo operador humano. +Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuário, preencher formulários, inspecionar componentes gráficos e validar fluxos no frontend de maneira rápida, determinística e econômica em tokens, garantindo isolamento total de cookies, tokens e processos, com visualização em tempo real pelo operador humano. --- -## 🔒 Princípio de Isolamento de Sessão por Módulo (`--session `) +## 🔒 Princípio de Isolamento de Sessão e Contexto (`--session _`) -O daemon do `agent-browser` utiliza sockets Unix independentes por sessão. Para evitar conflitos de comandos, interferência entre módulos diferentes ou encerramento indevido de processos via `agent-browser close`: +O daemon do `agent-browser` aloca sockets Unix dedicados e armazena cookies HTTP, tokens JWT (em cabeçalhos, cookies ou `localStorage`/`sessionStorage`) e estados de autenticação independentes por sessão. -- **Todo comando DEVE ser acompanhado da flag `--session `** (onde `` é o `modulo-id` canônico de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=`. -- Caso múltiplos fluxos de teste concorrentes rodem no mesmo módulo, utilizar sufixo discriminador determinístico: `--session "${MODULO}-subfluxo"`. +Para evitar contaminação cruzada de credenciais, interferência mútua entre módulos ou encerramento indevido de processos via `agent-browser close`: + +- **Todo comando DEVE ser acompanhado da flag `--session _`** (onde `` é o `modulo-id` canônico de `memorias-ia/modulo.yml` e `` identifica o papel ou perfil de acesso), ou garantir no ambiente `export AGENT_BROWSER_SESSION=_`. +- **Prevenção Obrigatória de Mistura de Tokens:** Caso a aplicação possua mais de um tipo de acesso (`interno`, `externo`, `anonimo`, `cliente`, etc.), o `` **DEVE SER OBRIGATORIAMENTE PREENCHIDO**. Exemplo: um teste logado como operador `interno` nunca deve compartilhar a mesma sessão de um teste de rota pública `anonimo` ou de acesso do `cliente`. +- **Sub-isolamento para concorrência:** Caso múltiplos fluxos de teste concorrentes do mesmo papel rodem simultaneamente, utilizar sufixo discriminador determinístico: `--session "${MODULO}_${CONTEXTO}_${SLUG_OU_PID}"`. + +--- + +## 🧭 Contextos Canônicos de Sessão + +| Contexto | Finalidade e Escopo | Exemplo de Sessão | Fonte de Credenciais | +| :--- | :--- | :--- | :--- | +| **`interno`** | Operador interno, suporte, técnico, atendente, administrador | `--session _interno` | `modulo-acesso.interno` (ou `modulo-acesso` simples) | +| **`cliente`** | Solicitante corporativo, empresa cliente, contratante | `--session _cliente` | `modulo-acesso.cliente` | +| **`externo`** | Portal público autenticado, cidadão, requerente externo | `--session _externo` | `modulo-acesso.externo` | +| **`anonimo`** | Usuário deslogado, consulta pública, login, landing page | `--session _anonimo` | Nenhuma (perfil limpo sem cookies/tokens) | +| **``** | Papel especializado de domínio (ex: `fiscal`, `auditor`) | `--session _` | `modulo-acesso.` | --- @@ -30,7 +45,7 @@ Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na á - Usar sempre a flag `--headed` na abertura: ```bash - agent-browser --session "$MODULO" open --headed + agent-browser --session "${MODULO}_${CONTEXTO}" open --headed ``` - Ou exportar no ambiente: ```bash @@ -56,71 +71,72 @@ Documentação oficial: **https://agent-browser.dev/** ## Fluxo Operacional Passo a Passo -### 1. Iniciar Sessão Visível e Isolada -Abra a aplicação frontend mantendo a janela visível e isolada por módulo: +### 1. Iniciar Sessão Visível e Isolada por Contexto +Abra a aplicação frontend mantendo a janela visível e isolada pelo módulo e contexto desejado: ```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}') +CONTEXTO="interno" # ou "cliente", "externo", "anonimo" -agent-browser --session "$MODULO" open --headed http://localhost:8080 +agent-browser --session "${MODULO}_${CONTEXTO}" open --headed http://localhost:8080 ``` ### 2. Obter Snapshot Interativo Gere a árvore de acessibilidade enxuta com referências numéricas: ```bash -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i ``` *Saída de exemplo:* ```text -- heading "Qualificação de Fornecedores" [ref=e1] -- textbox "CNPJ" [ref=e2] -- textbox "Razão Social" [ref=e3] -- button "Pesquisar" [ref=e4] +- heading "Atendimento ao Cliente" [ref=e1] +- textbox "E-mail ou Usuário" [ref=e2] +- textbox "Senha" [ref=e3] +- button "Entrar" [ref=e4] ``` ### 3. Interagir com Determinismo Utilize as referências identificadas (`@e1`, `@e2`, etc.): ```bash -# Preenchimento de campos de texto -agent-browser --session "$MODULO" fill @e2 "12.345.678/0001-90" -agent-browser --session "$MODULO" fill @e3 "Indústria Modelo LTDA" +# Preenchimento de credenciais ou campos de formulário +agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "operador@empresa.com" +agent-browser --session "${MODULO}_${CONTEXTO}" fill @e3 "senha123" # Acionamento de botões e links -agent-browser --session "$MODULO" click @e4 +agent-browser --session "${MODULO}_${CONTEXTO}" click @e4 ``` ### 4. Aguardar Transição e Validar Estado Se a ação disparar chamada assíncrona ou animação, aguarde a estabilização: ```bash # Aguardar 1 a 2 segundos -agent-browser --session "$MODULO" wait 1500 +agent-browser --session "${MODULO}_${CONTEXTO}" wait 1500 -# Capturar novo snapshot para verificar se a lista ou mensagem apareceu -agent-browser --session "$MODULO" snapshot -i +# Capturar novo snapshot para verificar se o painel ou mensagem apareceu +agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i ``` ### 5. Verificar Logs de Erro no Console e Rede Assegure que nenhum erro de script ou requisição 500 ocorreu silenciosamente: ```bash # Inspecionar mensagens do console do browser -agent-browser --session "$MODULO" console +agent-browser --session "${MODULO}_${CONTEXTO}" console # Verificar requisições de rede falhadas -agent-browser --session "$MODULO" network +agent-browser --session "${MODULO}_${CONTEXTO}" network ``` ### 6. Registrar Evidência Visual Capture um screenshot para comprovação do resultado do teste: ```bash # Screenshot padrão ou anotado com identificadores visuais -agent-browser --session "$MODULO" screenshot evidencias/resultado-sucesso.png -# agent-browser --session "$MODULO" screenshot --annotate evidencias/resultado-anotado.png +agent-browser --session "${MODULO}_${CONTEXTO}" screenshot evidencias/resultado-sucesso.png +# agent-browser --session "${MODULO}_${CONTEXTO}" screenshot --annotate evidencias/resultado-anotado.png ``` -### 7. Encerrar Navegador -Finalize a sessão isolada limpando apenas os processos do seu módulo: +### 7. Encerrar Navegador daquele Contexto +Finalize a sessão isolada limpando apenas os processos e tokens do contexto testado: ```bash -agent-browser --session "$MODULO" close +agent-browser --session "${MODULO}_${CONTEXTO}" close ``` --- @@ -129,52 +145,57 @@ agent-browser --session "$MODULO" close | Ação | Comando | |---|---| -| **Abrir tela (visível)** | `agent-browser --session open --headed ` | -| **Snapshot de elementos** | `agent-browser --session snapshot -i` | -| **Clicar elemento** | `agent-browser --session click @ref` | -| **Preencher campo** | `agent-browser --session fill @ref "valor"` | -| **Selecionar dropdown** | `agent-browser --session select @ref "opcao"` | -| **Pressionar tecla** | `agent-browser --session press Enter` | -| **Obter texto** | `agent-browser --session get text @ref` | -| **Aguardar tempo** | `agent-browser --session wait ` | -| **Aguardar seletor** | `agent-browser --session wait --selector ""` | -| **Inspecionar console** | `agent-browser --session console` | -| **Inspecionar rede** | `agent-browser --session network` | -| **Screenshot** | `agent-browser --session screenshot ` | -| **Auditoria a11y (WCAG)** | `agent-browser --session a11y` | -| **Fechar sessão** | `agent-browser --session close` | +| **Abrir tela (visível)** | `agent-browser --session _ open --headed ` | +| **Snapshot de elementos** | `agent-browser --session _ snapshot -i` | +| **Clicar elemento** | `agent-browser --session _ click @ref` | +| **Preencher campo** | `agent-browser --session _ fill @ref "valor"` | +| **Selecionar dropdown** | `agent-browser --session _ select @ref "opcao"` | +| **Pressionar tecla** | `agent-browser --session _ press Enter` | +| **Obter texto** | `agent-browser --session _ get text @ref` | +| **Aguardar tempo** | `agent-browser --session _ wait ` | +| **Aguardar seletor** | `agent-browser --session _ wait --selector ""` | +| **Inspecionar console** | `agent-browser --session _ console` | +| **Inspecionar rede** | `agent-browser --session _ network` | +| **Screenshot** | `agent-browser --session _ screenshot ` | +| **Auditoria a11y (WCAG)** | `agent-browser --session _ a11y` | +| **Fechar sessão** | `agent-browser --session _ close` | --- -## 🔑 Autenticação e Credenciais Canônicas (`modulo-acesso`) +## 🔑 Autenticação e Credenciais por Contexto (`modulo-acesso`) -Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso`: +Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso` para o contexto específico: ```bash -# Extrair identificador e credenciais canônicas de teste de memorias-ia/modulo.yml MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}') -USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}') -SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}') +CONTEXTO="interno" # ou "cliente", "externo" + +# Extrair credenciais do contexto específico (compatível com multi-contexto ou formato simples) +USUARIO=$(grep -A3 "${CONTEXTO}:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}') +[ -z "$USUARIO" ] && USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}') + +SENHA=$(grep -A3 "${CONTEXTO}:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}') +[ -z "$SENHA" ] && SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}') # Preenchimento determinístico no formulário de login na sessão isolada -agent-browser --session "$MODULO" fill @e1 "$USUARIO" -agent-browser --session "$MODULO" fill @e2 "$SENHA" -agent-browser --session "$MODULO" click @e3 +agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "$USUARIO" +agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "$SENHA" +agent-browser --session "${MODULO}_${CONTEXTO}" click @e3 ``` -> ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste. +> ⚠️ **Atenção:** Nunca misture o fluxo `anonimo` na mesma sessão que executou login. Use sempre `--session "${MODULO}_anonimo"` para testes públicos e deslogados. --- ## Sessões Persistentes e Autenticação -Para fluxos que necessitam manter login ativo entre comandos com isolamento: +Para fluxos que necessitam manter login ativo entre comandos com isolamento por contexto: ```bash -# Iniciar sessão nomeada com auto-restore no escopo do módulo -agent-browser --session "$MODULO" --restore open --headed http://localhost:8080/login +# Iniciar sessão nomeada com auto-restore no escopo do módulo e contexto +agent-browser --session "${MODULO}_${CONTEXTO}" --restore open --headed http://localhost:8080/login # Verificar status da sessão isolada -agent-browser --session "$MODULO" session info --json +agent-browser --session "${MODULO}_${CONTEXTO}" session info --json ``` --- @@ -194,6 +215,6 @@ agent-browser skills get dogfood ## Boas Práticas no Ecossistema Azteca (Vue 3 / Vuetify) -1. **Campos Vuetify (`v-text-field`, `v-select`)**: O `snapshot -i` mapeia diretamente o `textbox` e o `combobox`. Utilize `agent-browser --session "$MODULO" fill @ref` ou `click @ref`. -2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser --session "$MODULO" wait 500 && agent-browser --session "$MODULO" snapshot -i` para interagir com o conteúdo do diálogo. +1. **Campos Vuetify (`v-text-field`, `v-select`)**: O `snapshot -i` mapeia diretamente o `textbox` e o `combobox`. Utilize `agent-browser --session "${MODULO}_${CONTEXTO}" fill @ref` ou `click @ref`. +2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser --session "${MODULO}_${CONTEXTO}" wait 500 && agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i` para interagir com o conteúdo do diálogo. 3. **Reporte de Teste**: Apresente ao operador o roteiro executado, evidências de screenshot e verificação de logs do console. diff --git a/global/workflows/plano.md b/global/workflows/plano.md index fa803b5..a2faa1f 100644 --- a/global/workflows/plano.md +++ b/global/workflows/plano.md @@ -99,7 +99,7 @@ O Orquestrador divide as tarefas entre os especialistas: - **`@front`**: Implementa telas Vue 3, composables e formulários consumindo `*-comuns`. - **`@ux`**: Aplica as Heurísticas de Nielsen (visibilidade de loading/erro, feedback imediato). - **`@refatorar`**: Governança de Código Limpo (limite estrito de 250 linhas, Dispatch Tables). -- **`@testes`**: Roda `typecheck`, `biome check` e validação visual via `agent-browser --session --headed`. +- **`@testes`**: Roda `typecheck`, `biome check` e validação visual via `agent-browser --session _ --headed`. - **`@documentacao`**: Documenta a memória da sessão (Pilar 6) e regras de negócio. ### 3. Modos de Invocação diff --git a/rules/identidade-modulo.md b/rules/identidade-modulo.md index 05ba1a4..41dac09 100644 --- a/rules/identidade-modulo.md +++ b/rules/identidade-modulo.md @@ -5,7 +5,7 @@ description: Identificação obrigatória do projeto/módulo via memorias-ia/mod scope: global trigger: always_on priority: critica -updatedAt: "2026-10-06" +updatedAt: "2026-10-08" --- # Regra: Identidade do Projeto via `memorias-ia/modulo.yml` @@ -38,11 +38,25 @@ modulo-caminho: modulo-descricao: modulo-tipo: -# Credenciais padrão para autenticação em testes (agent-browser, E2E, QA) +# Credenciais para autenticação em testes (agent-browser, E2E, QA) +# Formato Simples (aplicação com contexto único de acesso): modulo-acesso: usuario: senha: +# Ou Formato Multi-Contexto (quando a aplicação possui acessos distintos - evita mistura de tokens): +# modulo-acesso: +# interno: +# usuario: +# senha: +# cliente: +# usuario: +# senha: +# externo: +# usuario: +# senha: +# anonimo: null # acesso público/deslogado + # Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/) modulo-wiki: ``` @@ -51,11 +65,11 @@ modulo-wiki: | Campo | Tipo | Descrição | Exemplo | | :--- | :--- | :--- | :--- | -| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e identificador mandatório de sessão isolada no `agent-browser` (`--session `). | `e-licencie.sigma` | +| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e prefixo da sessão isolada no `agent-browser` (`--session _`). | `e-licencie.sigma` | | **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/sigma/` | | **`modulo-descricao`** | `string` | Descrição textual do propósito funcional e escopo de negócio do módulo. | `Módulo para gestão de monitoramentos ambientais` | | **`modulo-tipo`** | `string` | Descrição textual da arquitetura e tecnologias empregadas no módulo. | `aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres` | -| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`). | `{ usuario: "admin@gov.br", senha: "123" }` | +| **`modulo-acesso`** | `object` | Credenciais padrão (`usuario` e `senha`) ou organizadas por contexto (`interno`, `externo`, `cliente`, `anonimo`) para autenticação determinística por agentes de teste (`@testes`, QA, `agent-browser`), prevenindo mistura de tokens. | `{ usuario: "admin@gov.br", senha: "123" }` ou subchaves de contexto | | **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` | --- @@ -63,10 +77,10 @@ modulo-wiki: ## Regra Universal de Consulta Sempre que qualquer agente, persona, workflow ou skill necessitar de: -1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`//`), Wiki de Desenvolvimento (`/dev//`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`/dev//adrs/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session `)**; +1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`//`), Wiki de Desenvolvimento (`/dev//`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`/dev//adrs/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session _`)**; 2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `llm.md`), links de navegação ou proxies; 3. **Propósito ou Stack (`modulo-descricao` e `modulo-tipo`)**: para contextualizar novos agentes, gerar propostas comerciais, marketing, reels, análises de arquitetura ou testes; -4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística em rotinas de teste e validação de interface; +4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair as credenciais do contexto específico (`interno`, `externo`, `cliente`, etc.) ou credenciais diretas de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística sem contaminação de cookies/tokens entre perfis; 5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia; 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`. diff --git a/rules/testes-interface-agent-browser.md b/rules/testes-interface-agent-browser.md index c929846..9688e5b 100644 --- a/rules/testes-interface-agent-browser.md +++ b/rules/testes-interface-agent-browser.md @@ -1,7 +1,7 @@ --- type: rule name: testes-interface-agent-browser -description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) e com isolamento por sessão (--session ). +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 _). scope: global trigger: always_on updatedAt: "2026-10-08" @@ -13,7 +13,7 @@ updatedAt: "2026-10-08" Quando uma IA precisa testar o frontend, validar jornadas de usuário, inspecionar componentes gráficos ou simular interações na tela, é crucial utilizar uma ferramenta rápida, determinística e econômica em tokens. Além disso, o operador humano deve sempre ter visibilidade do que a IA está executando em tempo real na interface gráfica. -Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Para viabilizar testes concorrentes e evitar interferências mútuas entre múltiplos módulos ou workspaces, todo comando deve operar em sessão isolada identificada pelo módulo. +Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Para viabilizar testes concorrentes e evitar interferências mútuas entre múltiplos módulos ou workspaces, todo comando deve operar em sessão isolada identificada pelo módulo e pelo contexto de acesso. Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA. @@ -27,24 +27,38 @@ Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar 2. **Executar SEMPRE em Modo Visível (`--headed`)**: - A janela do navegador **deve sempre aparecer na área de trabalho do operador**. - É **terminantemente proibido** rodar testes ocultos (headless silencioso), a menos que o operador humano solicite expressamente essa exceção. - - Usar a flag `--headed` nos comandos de abertura (`agent-browser --session open --headed `) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`. -3. **Isolamento Mandatório de Sessão (`--session `)**: - - **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo. - - Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session `** (onde `` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=`. - - Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos em testes simultâneos multi-módulos. - - Caso um mesmo módulo necessite de sub-isolamento para testes paralelos, deve-se adotar o sufixo determinístico `-`. + - Usar a flag `--headed` nos comandos de abertura (`agent-browser --session _ open --headed `) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`. +3. **Isolamento Mandatório de Sessão e Contexto (`--session _`)**: + - **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo e o contexto de acesso. + - Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session _`** (onde `` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml` e `` discrimina o papel ou natureza do acesso), ou garantir no ambiente `export AGENT_BROWSER_SESSION=_`. + - **Prevenção de Mistura de Tokens:** Caso a aplicação possua mais de um tipo de acesso (`interno`, `externo`, `anonimo`, `cliente`, etc.), o `` **DEVE SER OBRIGATORIAMENTE PREENCHIDO** para evitar que cookies, tokens JWT e estados de login residuais contaminem outros fluxos de teste. + - Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/_.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos. + - Caso um mesmo módulo e contexto necessite de sub-isolamento para testes paralelos, adota-se o discriminador determinístico: `__`. 4. **Utilizar o modelo de referências (`@ref`)**: - - Mapear a tela via `agent-browser --session snapshot -i`, obtendo referências compactas como `@e1`, `@e2`. + - Mapear a tela via `agent-browser --session _ snapshot -i`, obtendo referências compactas como `@e1`, `@e2`. - Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`). 5. **Registrar evidências e fechar sessão**: - - Registrar comprovações visuais com `agent-browser --session screenshot `. - - Encerrar graciosamente o navegador com `agent-browser --session close` ao término do fluxo. -6. **Credenciais Canônicas de Teste (`modulo-acesso`)**: - - Sempre que o teste exigir autenticação (login, sessão administrativa), o agente **DEVE OBRIGATORIAMENTE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml`**. + - Registrar comprovações visuais com `agent-browser --session _ screenshot `. + - Encerrar graciosamente o navegador com `agent-browser --session _ close` ao término do fluxo. +6. **Credenciais Canônicas por Contexto (`modulo-acesso`)**: + - Sempre que o teste exigir autenticação, o agente **DEVE OBRIGATORIAMENTE extrair as credenciais do contexto específico** em `modulo-acesso` de `memorias-ia/modulo.yml` (ex: `modulo-acesso.interno`, `modulo-acesso.cliente`, etc.). + - Para sessões anônimas (`_anonimo`), nenhum login deve ser realizado, garantindo a validação da experiência do usuário público sem tokens. - É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste. --- +## 🔒 Contextos Canônicos de Sessão (`_`) + +| Contexto | Finalidade e Natureza | Exemplo de Sessão | Credenciais em `modulo.yml` | +| :--- | :--- | :--- | :--- | +| **`interno`** | Operador interno, suporte, técnico, atendente, administrador | `--session _interno` | `modulo-acesso.interno` (ou `modulo-acesso` simples) | +| **`cliente`** | Cliente final, solicitante corporativo, empresa contratante | `--session _cliente` | `modulo-acesso.cliente` | +| **`externo`** | Portal público autenticado, cidadão, requerente externo | `--session _externo` | `modulo-acesso.externo` | +| **`anonimo`** | Usuário deslogado, consulta pública por código, login, landing | `--session _anonimo` | Nenhuma (perfil limpo sem cookies/tokens) | +| **``** | Papel especializado de domínio (ex: `fiscal`, `auditor`) | `--session _` | `modulo-acesso.` | + +--- + ## Instalação e Configuração O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium: @@ -63,55 +77,56 @@ Documentação de referência: **https://agent-browser.dev/** ## Protocolo Operacional Padrão -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 ```bash # Obter o modulo-id canônico de memorias-ia/modulo.yml MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}') +CONTEXTO="interno" # ou "cliente", "externo", "anonimo" -# Abrir sempre visível ao operador humano na sessão isolada do módulo -agent-browser --session "$MODULO" open --headed http://localhost:8080 +# Abrir sempre visível ao operador na sessão isolada por módulo e contexto +agent-browser --session "${MODULO}_${CONTEXTO}" open --headed http://localhost:8080 ``` ### 2. Inspeção de Elementos Interativos ```bash # Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2) -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i ``` ### 3. Interações por Referência Direta ```bash # Interagir diretamente com os elementos identificados no snapshot -agent-browser --session "$MODULO" fill @e1 "usuario@exemplo.com" -agent-browser --session "$MODULO" fill @e2 "senhaSegura123" -agent-browser --session "$MODULO" click @e3 +agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "usuario@exemplo.com" +agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "senhaSegura123" +agent-browser --session "${MODULO}_${CONTEXTO}" click @e3 ``` ### 4. Validação e Evidência ```bash # Aguardar estabilização se houver transição assíncrona -agent-browser --session "$MODULO" wait 1000 +agent-browser --session "${MODULO}_${CONTEXTO}" wait 1000 # Obter novo snapshot para verificar estado pós-ação -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i # Capturar evidência gráfica do teste -agent-browser --session "$MODULO" screenshot evidencias/teste-login-sucesso.png +agent-browser --session "${MODULO}_${CONTEXTO}" screenshot evidencias/teste-login-sucesso.png # Verificar erros no console do navegador -agent-browser --session "$MODULO" console +agent-browser --session "${MODULO}_${CONTEXTO}" console ``` ### 5. Finalização ```bash -# Fechar a sessão isolada do navegador ao concluir o teste -agent-browser --session "$MODULO" close +# Fechar a sessão isolada do navegador ao concluir o fluxo daquele contexto +agent-browser --session "${MODULO}_${CONTEXTO}" close ``` --- @@ -119,23 +134,25 @@ agent-browser --session "$MODULO" close ## Boas Práticas e Proibições ### Proibido ❌ -- **Proibido executar sem a flag `--session `** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada. +- **Proibido executar sem a flag `--session _`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada. +- **Proibido misturar acessos com perfis diferentes na mesma sessão genérica sem contexto** (ex: logar como operador interno e depois testar fluxo de cliente ou anônimo na mesma sessão, causando mistura de tokens). - **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`. - **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`). - **Proibido navegar para URLs desconhecidas** ou inventadas pela IA fora do escopo aprovado do teste. -- **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session close`). +- **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session _ close`). ### Permitido e Recomendado ✅ -- Manter sessões persistentes quando necessário via `--session --restore`. -- Utilizar sub-isolamento determinístico (`-`) caso múltiplos testes do mesmo módulo ocorram simultaneamente no mesmo host. -- Usar `agent-browser --session screenshot --annotate` para inspecionar layouts complexos com visão computacional. +- Manter sessões persistentes por contexto quando necessário via `--session _ --restore`. +- Utilizar sub-isolamento determinístico (`__`) caso múltiplos testes do mesmo contexto ocorram simultaneamente no mesmo host. +- Usar `agent-browser --session _ screenshot --annotate` para inspecionar layouts complexos com visão computacional. - Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`. --- ## Impacto -- **Isolamento e Concorrência**: Múltiplos agentes ou módulos rodando testes E2E simultâneos não conflitam de abas nem fecham janelas alheias. +- **Isolamento de Tokens e Cookies**: Evita vazamento de credenciais e estados de autenticação entre acessos de operador interno, cliente corporativo, cidadão e visitante anônimo. +- **Isolamento e Concorrência**: Múltiplos agentes ou testes E2E simultâneos não conflitam de abas nem fecham janelas alheias. - **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real. - **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. @@ -148,4 +165,3 @@ agent-browser --session "$MODULO" close - Skill associada: `skills/testar-interface-agent-browser/SKILL.md` - Rule associada: `rules/identidade-modulo.md` - Ferramentas CLI: `.agent/TOOLS` - diff --git a/skills/plano.executar/SKILL.md b/skills/plano.executar/SKILL.md index d2313c2..c61f101 100644 --- a/skills/plano.executar/SKILL.md +++ b/skills/plano.executar/SKILL.md @@ -56,7 +56,7 @@ O Orquestrador Líder decompõe a especificação técnica do plano e distribui | **`@front`** *(Frontend Specialist)* | `*-front`, `*-comuns` | Componentes Vue 3, composables, views, formulários reativos, binding de eventos, consumo de APIs e CSS co-localizado. | | **`@ux`** *(UX Specialist)* | `*-front` (Interface & Heurísticas) | Aplicação das Heurísticas de Nielsen: visibilidade do estado (spinners, loading, feedback imediato), clareza cognitiva, prevenção de erros e mensagens amigáveis ao usuário. | | **`@refatorar`** *(Clean Code Specialist)* | Todo o código alterado | Governança estrita das 12 regras de Código Limpo: garantia do **limite de 250 linhas por arquivo**, eliminação de code smells, modularidade e Dispatch Tables. | -| **`@testes`** *(QA & Automation)* | Checagens e Validação E2E | Tipagem (`bun run typecheck` / `tsc --noEmit`), linter (`biome check --write`), governança (`sh .agent/verificar-linhas.sh`) e testes de interface visual via `agent-browser --session --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 _ --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//`). | --- @@ -80,7 +80,7 @@ Em implementações integradas, o Orquestrador segue a ordem canônica de handof ↓ 4. [@refatorar] Extrai módulos se exceder 250 linhas e aplica Código Limpo ↓ -5. [@testes] Roda typecheck, biome e testes E2E com agent-browser --session --headed +5. [@testes] Roda typecheck, biome e testes E2E com agent-browser --session _ --headed ↓ (Loop /goal de auto-correção se houver falhas) 6. [@documentacao] Atualiza memórias-ia/, historico-acoes.md e arquiva o plano ``` diff --git a/skills/plano/SKILL.md b/skills/plano/SKILL.md index 922a45e..144ff3a 100644 --- a/skills/plano/SKILL.md +++ b/skills/plano/SKILL.md @@ -74,7 +74,7 @@ Quando invocado com uma instrução (ex.: `/plano corrigir validação do númer - **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps e arquivos mapeados com links `[arquivo](file://...)`. - **3. Critérios de Aceite & Validação (DoD):** Checklist com caixas `- [ ]` contendo condições verificáveis de sucesso. - **4. Especificação Técnica & Passos de Implementação:** Roteiro prático para o desenvolvedor (schemas, backend, frontend, código sugerido). - - **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session --headed`. + - **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session _ --headed`. - **6. Histórico de Execução:** Cabeçalho reservado para preenchimento na conclusão pelo executor. - Salve o arquivo em `./PLANOS/pendente/AAAA-MM-DD-HH-mm-.md` usando `write_to_file`. diff --git a/skills/testar-interface-agent-browser/SKILL.md b/skills/testar-interface-agent-browser/SKILL.md index 4ce13bb..8de4388 100644 --- a/skills/testar-interface-agent-browser/SKILL.md +++ b/skills/testar-interface-agent-browser/SKILL.md @@ -3,7 +3,7 @@ name: testar-interface-agent-browser description: > Executar testes automatizados de interface (E2E), navegação e validação visual no frontend utilizando a CLI agent-browser, com janela sempre visível (--headed) - e isolamento mandatório de sessão por módulo (--session ). + e isolamento mandatório de sessão e contexto (--session _). scope: global --- @@ -11,16 +11,31 @@ scope: global ## Objetivo -Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuário, preencher formulários, inspecionar componentes gráficos e validar fluxos no frontend de maneira rápida, determinística e econômica em tokens, garantindo isolamento total entre processos e visualização em tempo real pelo operador humano. +Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuário, preencher formulários, inspecionar componentes gráficos e validar fluxos no frontend de maneira rápida, determinística e econômica em tokens, garantindo isolamento total de cookies, tokens e processos, com visualização em tempo real pelo operador humano. --- -## 🔒 Princípio de Isolamento de Sessão por Módulo (`--session `) +## 🔒 Princípio de Isolamento de Sessão e Contexto (`--session _`) -O daemon do `agent-browser` utiliza sockets Unix independentes por sessão. Para evitar conflitos de comandos, interferência entre módulos diferentes ou encerramento indevido de processos via `agent-browser close`: +O daemon do `agent-browser` aloca sockets Unix dedicados e armazena cookies HTTP, tokens JWT (em cabeçalhos, cookies ou `localStorage`/`sessionStorage`) e estados de autenticação independentes por sessão. -- **Todo comando DEVE ser acompanhado da flag `--session `** (onde `` é o `modulo-id` canônico de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=`. -- Caso múltiplos fluxos de teste concorrentes rodem no mesmo módulo, utilizar sufixo discriminador determinístico: `--session "${MODULO}-subfluxo"`. +Para evitar contaminação cruzada de credenciais, interferência mútua entre módulos ou encerramento indevido de processos via `agent-browser close`: + +- **Todo comando DEVE ser acompanhado da flag `--session _`** (onde `` é o `modulo-id` canônico de `memorias-ia/modulo.yml` e `` identifica o papel ou perfil de acesso), ou garantir no ambiente `export AGENT_BROWSER_SESSION=_`. +- **Prevenção Obrigatória de Mistura de Tokens:** Caso a aplicação possua mais de um tipo de acesso (`interno`, `externo`, `anonimo`, `cliente`, etc.), o `` **DEVE SER OBRIGATORIAMENTE PREENCHIDO**. Exemplo: um teste logado como operador `interno` nunca deve compartilhar a mesma sessão de um teste de rota pública `anonimo` ou de acesso do `cliente`. +- **Sub-isolamento para concorrência:** Caso múltiplos fluxos de teste concorrentes do mesmo papel rodem simultaneamente, utilizar sufixo discriminador determinístico: `--session "${MODULO}_${CONTEXTO}_${SLUG_OU_PID}"`. + +--- + +## 🧭 Contextos Canônicos de Sessão + +| Contexto | Finalidade e Escopo | Exemplo de Sessão | Fonte de Credenciais | +| :--- | :--- | :--- | :--- | +| **`interno`** | Operador interno, suporte, técnico, atendente, administrador | `--session _interno` | `modulo-acesso.interno` (ou `modulo-acesso` simples) | +| **`cliente`** | Solicitante corporativo, empresa cliente, contratante | `--session _cliente` | `modulo-acesso.cliente` | +| **`externo`** | Portal público autenticado, cidadão, requerente externo | `--session _externo` | `modulo-acesso.externo` | +| **`anonimo`** | Usuário deslogado, consulta pública, login, landing page | `--session _anonimo` | Nenhuma (perfil limpo sem cookies/tokens) | +| **``** | Papel especializado de domínio (ex: `fiscal`, `auditor`) | `--session _` | `modulo-acesso.` | --- @@ -30,7 +45,7 @@ Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na á - Usar sempre a flag `--headed` na abertura: ```bash - agent-browser --session "$MODULO" open --headed + agent-browser --session "${MODULO}_${CONTEXTO}" open --headed ``` - Ou exportar no ambiente: ```bash @@ -56,71 +71,72 @@ Documentação oficial: **https://agent-browser.dev/** ## Fluxo Operacional Passo a Passo -### 1. Iniciar Sessão Visível e Isolada -Abra a aplicação frontend mantendo a janela visível e isolada por módulo: +### 1. Iniciar Sessão Visível e Isolada por Contexto +Abra a aplicação frontend mantendo a janela visível e isolada pelo módulo e contexto desejado: ```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}') +CONTEXTO="interno" # ou "cliente", "externo", "anonimo" -agent-browser --session "$MODULO" open --headed http://localhost:8080 +agent-browser --session "${MODULO}_${CONTEXTO}" open --headed http://localhost:8080 ``` ### 2. Obter Snapshot Interativo Gere a árvore de acessibilidade enxuta com referências numéricas: ```bash -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i ``` *Saída de exemplo:* ```text -- heading "Qualificação de Fornecedores" [ref=e1] -- textbox "CNPJ" [ref=e2] -- textbox "Razão Social" [ref=e3] -- button "Pesquisar" [ref=e4] +- heading "Atendimento ao Cliente" [ref=e1] +- textbox "E-mail ou Usuário" [ref=e2] +- textbox "Senha" [ref=e3] +- button "Entrar" [ref=e4] ``` ### 3. Interagir com Determinismo Utilize as referências identificadas (`@e1`, `@e2`, etc.): ```bash -# Preenchimento de campos de texto -agent-browser --session "$MODULO" fill @e2 "12.345.678/0001-90" -agent-browser --session "$MODULO" fill @e3 "Indústria Modelo LTDA" +# Preenchimento de credenciais ou campos de formulário +agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "operador@empresa.com" +agent-browser --session "${MODULO}_${CONTEXTO}" fill @e3 "senha123" # Acionamento de botões e links -agent-browser --session "$MODULO" click @e4 +agent-browser --session "${MODULO}_${CONTEXTO}" click @e4 ``` ### 4. Aguardar Transição e Validar Estado Se a ação disparar chamada assíncrona ou animação, aguarde a estabilização: ```bash # Aguardar 1 a 2 segundos -agent-browser --session "$MODULO" wait 1500 +agent-browser --session "${MODULO}_${CONTEXTO}" wait 1500 -# Capturar novo snapshot para verificar se a lista ou mensagem apareceu -agent-browser --session "$MODULO" snapshot -i +# Capturar novo snapshot para verificar se o painel ou mensagem apareceu +agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i ``` ### 5. Verificar Logs de Erro no Console e Rede Assegure que nenhum erro de script ou requisição 500 ocorreu silenciosamente: ```bash # Inspecionar mensagens do console do browser -agent-browser --session "$MODULO" console +agent-browser --session "${MODULO}_${CONTEXTO}" console # Verificar requisições de rede falhadas -agent-browser --session "$MODULO" network +agent-browser --session "${MODULO}_${CONTEXTO}" network ``` ### 6. Registrar Evidência Visual Capture um screenshot para comprovação do resultado do teste: ```bash # Screenshot padrão ou anotado com identificadores visuais -agent-browser --session "$MODULO" screenshot evidencias/resultado-sucesso.png -# agent-browser --session "$MODULO" screenshot --annotate evidencias/resultado-anotado.png +agent-browser --session "${MODULO}_${CONTEXTO}" screenshot evidencias/resultado-sucesso.png +# agent-browser --session "${MODULO}_${CONTEXTO}" screenshot --annotate evidencias/resultado-anotado.png ``` -### 7. Encerrar Navegador -Finalize a sessão isolada limpando apenas os processos do seu módulo: +### 7. Encerrar Navegador daquele Contexto +Finalize a sessão isolada limpando apenas os processos e tokens do contexto testado: ```bash -agent-browser --session "$MODULO" close +agent-browser --session "${MODULO}_${CONTEXTO}" close ``` --- @@ -129,52 +145,57 @@ agent-browser --session "$MODULO" close | Ação | Comando | |---|---| -| **Abrir tela (visível)** | `agent-browser --session open --headed ` | -| **Snapshot de elementos** | `agent-browser --session snapshot -i` | -| **Clicar elemento** | `agent-browser --session click @ref` | -| **Preencher campo** | `agent-browser --session fill @ref "valor"` | -| **Selecionar dropdown** | `agent-browser --session select @ref "opcao"` | -| **Pressionar tecla** | `agent-browser --session press Enter` | -| **Obter texto** | `agent-browser --session get text @ref` | -| **Aguardar tempo** | `agent-browser --session wait ` | -| **Aguardar seletor** | `agent-browser --session wait --selector ""` | -| **Inspecionar console** | `agent-browser --session console` | -| **Inspecionar rede** | `agent-browser --session network` | -| **Screenshot** | `agent-browser --session screenshot ` | -| **Auditoria a11y (WCAG)** | `agent-browser --session a11y` | -| **Fechar sessão** | `agent-browser --session close` | +| **Abrir tela (visível)** | `agent-browser --session _ open --headed ` | +| **Snapshot de elementos** | `agent-browser --session _ snapshot -i` | +| **Clicar elemento** | `agent-browser --session _ click @ref` | +| **Preencher campo** | `agent-browser --session _ fill @ref "valor"` | +| **Selecionar dropdown** | `agent-browser --session _ select @ref "opcao"` | +| **Pressionar tecla** | `agent-browser --session _ press Enter` | +| **Obter texto** | `agent-browser --session _ get text @ref` | +| **Aguardar tempo** | `agent-browser --session _ wait ` | +| **Aguardar seletor** | `agent-browser --session _ wait --selector ""` | +| **Inspecionar console** | `agent-browser --session _ console` | +| **Inspecionar rede** | `agent-browser --session _ network` | +| **Screenshot** | `agent-browser --session _ screenshot ` | +| **Auditoria a11y (WCAG)** | `agent-browser --session _ a11y` | +| **Fechar sessão** | `agent-browser --session _ close` | --- -## 🔑 Autenticação e Credenciais Canônicas (`modulo-acesso`) +## 🔑 Autenticação e Credenciais por Contexto (`modulo-acesso`) -Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso`: +Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso` para o contexto específico: ```bash -# Extrair identificador e credenciais canônicas de teste de memorias-ia/modulo.yml MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}') -USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}') -SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}') +CONTEXTO="interno" # ou "cliente", "externo" + +# Extrair credenciais do contexto específico (compatível com multi-contexto ou formato simples) +USUARIO=$(grep -A3 "${CONTEXTO}:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}') +[ -z "$USUARIO" ] && USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}') + +SENHA=$(grep -A3 "${CONTEXTO}:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}') +[ -z "$SENHA" ] && SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}') # Preenchimento determinístico no formulário de login na sessão isolada -agent-browser --session "$MODULO" fill @e1 "$USUARIO" -agent-browser --session "$MODULO" fill @e2 "$SENHA" -agent-browser --session "$MODULO" click @e3 +agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "$USUARIO" +agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "$SENHA" +agent-browser --session "${MODULO}_${CONTEXTO}" click @e3 ``` -> ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste. +> ⚠️ **Atenção:** Nunca misture o fluxo `anonimo` na mesma sessão que executou login. Use sempre `--session "${MODULO}_anonimo"` para testes públicos e deslogados. --- ## Sessões Persistentes e Autenticação -Para fluxos que necessitam manter login ativo entre comandos com isolamento: +Para fluxos que necessitam manter login ativo entre comandos com isolamento por contexto: ```bash -# Iniciar sessão nomeada com auto-restore no escopo do módulo -agent-browser --session "$MODULO" --restore open --headed http://localhost:8080/login +# Iniciar sessão nomeada com auto-restore no escopo do módulo e contexto +agent-browser --session "${MODULO}_${CONTEXTO}" --restore open --headed http://localhost:8080/login # Verificar status da sessão isolada -agent-browser --session "$MODULO" session info --json +agent-browser --session "${MODULO}_${CONTEXTO}" session info --json ``` --- @@ -194,6 +215,6 @@ agent-browser skills get dogfood ## Boas Práticas no Ecossistema Azteca (Vue 3 / Vuetify) -1. **Campos Vuetify (`v-text-field`, `v-select`)**: O `snapshot -i` mapeia diretamente o `textbox` e o `combobox`. Utilize `agent-browser --session "$MODULO" fill @ref` ou `click @ref`. -2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser --session "$MODULO" wait 500 && agent-browser --session "$MODULO" snapshot -i` para interagir com o conteúdo do diálogo. +1. **Campos Vuetify (`v-text-field`, `v-select`)**: O `snapshot -i` mapeia diretamente o `textbox` e o `combobox`. Utilize `agent-browser --session "${MODULO}_${CONTEXTO}" fill @ref` ou `click @ref`. +2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser --session "${MODULO}_${CONTEXTO}" wait 500 && agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i` para interagir com o conteúdo do diálogo. 3. **Reporte de Teste**: Apresente ao operador o roteiro executado, evidências de screenshot e verificação de logs do console. diff --git a/validar-setup.sh b/validar-setup.sh index 4ba31de..57f81d6 100644 --- a/validar-setup.sh +++ b/validar-setup.sh @@ -95,7 +95,11 @@ if [ -f "$MODULO_YML" ]; then # Validar modulo-acesso (credenciais de teste para automação e QA) if grep -q "modulo-acesso:" "$MODULO_YML"; then - echo -e " ${VERDE}✓${RESET} modulo-acesso: credenciais de teste configuradas." + if grep -E -q "^\s+(interno|cliente|externo|anonimo):" "$MODULO_YML"; then + echo -e " ${VERDE}✓${RESET} modulo-acesso: credenciais multi-contexto configuradas (isolamento de tokens)." + else + echo -e " ${VERDE}✓${RESET} modulo-acesso: credenciais de teste configuradas." + fi else echo -e " ${AMARELO}⚠${RESET} modulo-acesso: credenciais de teste não configuradas em modulo.yml." fi @@ -109,7 +113,8 @@ if [ -f "$MODULO_YML" ]; then # Exibir convenção de sessão isolada para agent-browser if [ -n "$MODULO_ID" ]; then - echo -e " ${AZUL}ℹ${RESET} Sessão agent-browser: agent-browser --session ${NEGRITO}$MODULO_ID${RESET}" + echo -e " ${AZUL}ℹ${RESET} Sessão agent-browser: agent-browser --session ${NEGRITO}${MODULO_ID}_${RESET}" + echo -e " Exemplos: ${MODULO_ID}_interno | ${MODULO_ID}_cliente | ${MODULO_ID}_externo | ${MODULO_ID}_anonimo" fi # Validar memorias-ia/historico-acoes.md (Pilar 6 - Índice de Ações)