From 1a8adfc2dc7b2a7c8c0cd5811e9f5207475dd97a Mon Sep 17 00:00:00 2001 From: Luiz Silva Date: Thu, 8 Oct 2026 14:47:46 -0300 Subject: [PATCH] feat(testes): padronizar uso de --session _ no agent-browser para isolamento de tokens --- DOCUMENTACAO/templates/modulo.yml.template | 16 ++- DOCUMENTACAO/templates/plano.md.template | 14 +- 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 | 16 ++- .../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 | 129 +++++++++++------- global/workflows/plano.md | 2 +- rules/identidade-modulo.md | 16 ++- rules/testes-interface-agent-browser.md | 82 ++++++----- skills/plano.executar/SKILL.md | 4 +- skills/plano/SKILL.md | 2 +- .../testar-interface-agent-browser/SKILL.md | 129 +++++++++++------- validar-setup.sh | 2 +- 23 files changed, 320 insertions(+), 206 deletions(-) diff --git a/DOCUMENTACAO/templates/modulo.yml.template b/DOCUMENTACAO/templates/modulo.yml.template index a5894c5..6d84c6d 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) @@ -15,9 +15,23 @@ modulo-descricao: Descrição detalhada do módulo para contextualização opera modulo-tipo: aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres # Credenciais padrão para autenticação em testes (agent-browser, E2E, QA) +# Suporta formato direto (contexto padrão/único) ou subdividido por contexto de acesso: modulo-acesso: + # Formato direto (quando contexto único ou padrão): usuario: usuario@exemplo.com.br senha: "123" + # OU agrupado por contextos específicos (descomente e adeque conforme os perfis da aplicação): + # interno: + # usuario: admin@gov.br + # senha: "123" + # externo: + # usuario: cidadao@empresa.com.br + # senha: "123" + # cliente: + # usuario: cliente@empresa.com.br + # senha: "123" + # Nota: o perfil 'anonimo' atua sempre sem login na sessão limpa _anonimo + # 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..7066f28 100644 --- a/DOCUMENTACAO/templates/plano.md.template +++ b/DOCUMENTACAO/templates/plano.md.template @@ -90,12 +90,14 @@ 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 _`) +> 💡 **Nota de Contexto:** Caso a aplicação possua múltiplos acessos (interno, externo, anonimo, cliente), utilize obrigatoriamente o sufixo correspondente (ex: `_interno`, `_externo`, `_anonimo`, `_cliente`) para prevenir mistura de cookies e tokens de autenticação. + +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..a68eea8 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 `` indica o perfil sob teste: `interno`, `externo`, `anonimo`, `cliente`) ou garantir `export AGENT_BROWSER_SESSION=_`. Cada sessão aloca daemon, socket Unix exclusivo, cookies e LocalStorage independentes, prevenindo colisões e vazamento de tokens de autenticação entre diferentes acessos. - **Instalação:** - 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..a68eea8 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 `` indica o perfil sob teste: `interno`, `externo`, `anonimo`, `cliente`) ou garantir `export AGENT_BROWSER_SESSION=_`. Cada sessão aloca daemon, socket Unix exclusivo, cookies e LocalStorage independentes, prevenindo colisões e vazamento de tokens de autenticação entre diferentes acessos. - **Instalação:** - 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..55879b0 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 em testes simultâneos (ver `rules/testes-interface-agent-browser.md`) ## Restrições diff --git a/agents/front/persona b/agents/front/persona index d579dbc..cff2416 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 em testes simultâneos (ver `rules/testes-interface-agent-browser.md`) ## Restrições diff --git a/agents/testes/agent.json b/agents/testes/agent.json index 24e9001..64ca2a7 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 de autenticação entre acessos interno, externo, anônimo ou cliente (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 contextual 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" } ], "toolNames": [ diff --git a/agents/testes/agent.md b/agents/testes/agent.md index 4802d4c..6aa8584 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 de autenticação entre acessos interno, externo, anônimo ou cliente (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`) 10. **Gerar Planos Técnicos via `/plano`** — durante homologações, reviews ou testes, formalizar bugs, melhorias e gaps em planos estruturados em `PLANOS/pendente/` para posterior implementação pelo time de desenvolvimento (ver `global/workflows/plano.md`). ## 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 contextual isolada (`--session _`), com screenshots comprobatórios? ## Memória Persistente & Identidade do Projeto diff --git a/agents/testes/persona b/agents/testes/persona index 42de989..a2c0bfb 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 de autenticação entre acessos interno, externo, anônimo ou cliente (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`) 10. **Gerar Planos Técnicos via `/plano`** — durante homologações, reviews ou testes, formalizar bugs, melhorias e gaps em planos estruturados em `PLANOS/pendente/` para posterior implementação pelo time de desenvolvimento (ver `global/workflows/plano.md`). ## 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 contextual isolada (`--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..55417b2 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 interferência entre perfis de acesso (ver `rules/testes-interface-agent-browser.md`) ## Restrições diff --git a/agents/ux/persona b/agents/ux/persona index b871d48..afcee0f 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 interferência entre perfis de acesso (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..0812394 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` @@ -39,9 +39,15 @@ modulo-descricao: modulo-tipo: # Credenciais padrão para autenticação em testes (agent-browser, E2E, QA) +# Suporta formato direto legado ou subdividido por contexto de acesso modulo-acesso: usuario: senha: + # Ou subdividido por contexto: + # interno: { usuario: "...", senha: "..." } + # externo: { usuario: "...", senha: "..." } + # cliente: { usuario: "...", senha: "..." } + # Nota: o perfil 'anonimo' atua sempre sem credenciais na sessão _anonimo # Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/) modulo-wiki: @@ -51,11 +57,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 identificador mandatório de 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 de teste para autenticação determinística por agentes (`@testes`, QA, `agent-browser`), suportando formato direto padrão (`usuario`/`senha`) ou subdivisão por contexto (`interno`, `externo`, `cliente`). | `{ usuario: "admin@gov.br", senha: "123" }` | | **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` | --- @@ -63,10 +69,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 de `modulo-acesso` em `memorias-ia/modulo.yml` correspondentes ao contexto que está sendo testado (`interno`, `externo`, `cliente`), ou utilizar as credenciais padrão diretas. No contexto `anonimo`, nenhuma autenticação é realizada; 5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia; 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..61deace 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 _) para evitar mistura de tokens. scope: global trigger: always_on updatedAt: "2026-10-08" @@ -13,9 +13,9 @@ updatedAt: "2026-10-08" Quando uma IA precisa testar o frontend, validar jornadas de usuário, inspecionar componentes gráficos ou simular interações na tela, é crucial utilizar uma ferramenta rápida, determinística e econômica em tokens. Além disso, o operador humano deve sempre ter visibilidade do que a IA está executando em tempo real na interface gráfica. -Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Para viabilizar testes concorrentes e evitar interferências mútuas entre múltiplos módulos ou workspaces, todo comando deve operar em sessão isolada identificada pelo módulo. +Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Em aplicações que possuem múltiplos níveis de acesso (como áreas administrativas internas, portais de requerentes externos, consultas anônimas públicas e acessos de clientes corporativos), a ausência de isolamento por contexto gera **mistura de tokens JWT, cookies de autenticação e dados de LocalStorage**, provocando falsos positivos ou mascarando falhas de segurança. -Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA. +Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** com isolamento estrito por módulo e contexto de acesso (`--session _`). --- @@ -27,20 +27,29 @@ 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 perfil 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 `` representa o perfil ou nível de acesso que está sendo testado), ou garantir no ambiente `export AGENT_BROWSER_SESSION=_`. + - **Contextos Padronizados de Acesso:** + - `interno`: Acesso restrito a servidores públicos, fiscais, analistas internos ou administradores. + - `externo`: Acesso de requerentes externos, contribuintes ou cidadãos logados. + - `anonimo`: Acesso público e não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). **Obrigatório para assegurar ausência total de tokens ou cookies residuais de sessões anteriores.** + - `cliente`: Acesso de clientes ou empresas contratantes em plataformas multi-tenant ou B2B. + - Aplicações de contexto único sem distinção de perfis podem utilizar apenas `` ou `_default`. + - **Prevenção de Mistura de Tokens e Cookies:** Cada sessão do `agent-browser` possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/_.sock`), mantendo cookie jar, cabeçalhos `Authorization`, LocalStorage e SessionStorage completamente estanques. Separar por `_` é estritamente obrigatório para que um teste anônimo não herde tokens de um teste interno, ou que credenciais de requerente externo não interfiram em fluxos administrativos. + - **Sub-isolamento Concorrente:** Caso múltiplos testes concorrentes ocorram no mesmo módulo e contexto, adota-se o sufixo determinístico: `_-`. 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 de Teste por Contexto (`modulo-acesso`)**: + - O agente **DEVE OBRIGATORIAMENTE consultar `modulo-acesso` em `memorias-ia/modulo.yml`**. + - Se configurado com chaves específicas por contexto (`interno`, `externo`, `cliente`), extrair as credenciais do contexto sob teste. + - Se configurado no formato plano direto (`usuario` e `senha`), utilizar como credencial padrão para o contexto principal/interno. + - Para o contexto `anonimo`, o agente **NÃO deve autenticar**, validando a jornada como usuário não-logado na sessão isolada `_anonimo`. - É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste. --- @@ -63,55 +72,59 @@ Documentação de referência: **https://agent-browser.dev/** ## Protocolo Operacional Padrão -Todo teste ou navegação de interface executado pela IA deve seguir o fluxo com isolamento de sessão: +Todo teste ou navegação de interface executado pela IA deve seguir o fluxo com isolamento de sessão e contexto: -### 1. Obter Identificador do Módulo e Abertura com Janela Visível +### 1. Obter Identificador do Módulo, Definir Contexto e Abertura com Janela Visível ```bash # Obter o modulo-id canônico de memorias-ia/modulo.yml MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}') -# Abrir sempre visível ao operador humano na sessão isolada do módulo -agent-browser --session "$MODULO" open --headed http://localhost:8080 +# Definir contexto sob teste: interno | externo | anonimo | cliente +CONTEXTO="interno" # ou externo, anonimo, cliente +SESSAO="${MODULO}_${CONTEXTO}" + +# Abrir sempre visível ao operador humano na sessão isolada do módulo e contexto +agent-browser --session "$SESSAO" open --headed http://localhost:8080 ``` ### 2. Inspeção de Elementos Interativos ```bash # Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2) -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "$SESSAO" snapshot -i ``` ### 3. Interações por Referência Direta ```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 "$SESSAO" fill @e1 "usuario@exemplo.com" +agent-browser --session "$SESSAO" fill @e2 "senhaSegura123" +agent-browser --session "$SESSAO" 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 "$SESSAO" wait 1000 # Obter novo snapshot para verificar estado pós-ação -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "$SESSAO" snapshot -i # Capturar evidência gráfica do teste -agent-browser --session "$MODULO" screenshot evidencias/teste-login-sucesso.png +agent-browser --session "$SESSAO" screenshot evidencias/teste-login-sucesso.png # Verificar erros no console do navegador -agent-browser --session "$MODULO" console +agent-browser --session "$SESSAO" console ``` ### 5. Finalização ```bash # Fechar a sessão isolada do navegador ao concluir o teste -agent-browser --session "$MODULO" close +agent-browser --session "$SESSAO" close ``` --- @@ -119,23 +132,25 @@ agent-browser --session "$MODULO" close ## Boas Práticas e Proibições ### 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 sessões ou misturar tokens entre perfis. - **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`. +- **Proibido testar fluxos anônimos em sessões já autenticadas**, garantindo que testes públicos sempre rodem na sessão `_anonimo`. - **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 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**: Previne contaminação entre sessões de administradores internos, cidadãos externos e consultas públicas anônimas. +- **Isolamento de Processos e Concorrência**: Múltiplos agentes rodando testes E2E simultâneos não colidem abas nem encerram daemons de outros contextos. - **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real. - **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 +163,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..51b7aad 100644 --- a/global/skills/testar-interface-agent-browser/SKILL.md +++ b/global/skills/testar-interface-agent-browser/SKILL.md @@ -3,7 +3,8 @@ name: testar-interface-agent-browser description: > Executar testes automatizados de interface (E2E), navegação e validação visual no frontend utilizando a CLI agent-browser, com janela sempre visível (--headed) - e isolamento mandatório de sessão por módulo (--session ). + e isolamento mandatório de sessão por módulo e contexto (--session _) + para evitar mistura de tokens e cookies entre acessos. scope: global --- @@ -15,12 +16,18 @@ Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuár --- -## 🔒 Princípio de Isolamento de Sessão por Módulo (`--session `) +## 🔒 Princípio de Isolamento de Sessão por Módulo 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` utiliza sockets Unix independentes por sessão (`/run/user/1000/agent-browser/.sock`). Em sistemas que possuem diferentes perfis de acesso, separar o contexto na flag de sessão é **indispensável para prevenir mistura de tokens JWT, cookies de autenticação e dados de LocalStorage**: -- **Todo comando DEVE ser acompanhado da flag `--session `** (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"`. +- **Todo comando DEVE ser acompanhado da flag `--session _`** (onde `` é o `modulo-id` canônico de `memorias-ia/modulo.yml` e `` é o perfil sob teste), ou garantir no ambiente `export AGENT_BROWSER_SESSION=_`. +- **Contextos Padronizados:** + - `interno`: Acesso de analistas, fiscais, operadores internos ou administradores. + - `externo`: Acesso de requerentes externos, cidadãos cadastrados ou contribuintes logados. + - `anonimo`: Acesso público / não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). **Garante sessão limpa sem resíduo de autenticações anteriores.** + - `cliente`: Acesso de clientes ou empresas em plataformas multi-tenant ou B2B. + - Aplicações de contexto único sem múltiplos acessos podem utilizar apenas `` ou `_default`. +- **Sub-isolamento Concorrente:** Caso múltiplos fluxos concorrentes rodem no mesmo contexto: `--session "${MODULO}_${CONTEXTO}-${slug_ou_pid}"`. --- @@ -30,7 +37,7 @@ Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na á - Usar sempre a flag `--headed` na abertura: ```bash - agent-browser --session "$MODULO" open --headed + agent-browser --session "${MODULO}_${CONTEXTO}" open --headed ``` - Ou exportar no ambiente: ```bash @@ -56,19 +63,23 @@ 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 Módulo e Contexto +Abra a aplicação frontend mantendo a janela visível e isolada: ```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}') -agent-browser --session "$MODULO" open --headed http://localhost:8080 +# Definir contexto sob teste: interno | externo | anonimo | cliente +CONTEXTO="interno" # ou externo, anonimo, cliente +SESSAO="${MODULO}_${CONTEXTO}" + +agent-browser --session "$SESSAO" open --headed http://localhost:8080 ``` ### 2. Obter Snapshot Interativo Gere a árvore de acessibilidade enxuta com referências numéricas: ```bash -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "$SESSAO" snapshot -i ``` *Saída de exemplo:* ```text @@ -82,45 +93,45 @@ agent-browser --session "$MODULO" snapshot -i 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" +agent-browser --session "$SESSAO" fill @e2 "12.345.678/0001-90" +agent-browser --session "$SESSAO" fill @e3 "Indústria Modelo LTDA" # Acionamento de botões e links -agent-browser --session "$MODULO" click @e4 +agent-browser --session "$SESSAO" click @e4 ``` ### 4. Aguardar Transição e Validar Estado 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 "$SESSAO" wait 1500 # Capturar novo snapshot para verificar se a lista ou mensagem apareceu -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "$SESSAO" snapshot -i ``` ### 5. Verificar Logs de Erro no Console e Rede 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 "$SESSAO" console # Verificar requisições de rede falhadas -agent-browser --session "$MODULO" network +agent-browser --session "$SESSAO" 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 "$SESSAO" screenshot evidencias/resultado-sucesso.png +# agent-browser --session "$SESSAO" screenshot --annotate evidencias/resultado-anotado.png ``` ### 7. Encerrar Navegador -Finalize a sessão isolada limpando apenas os processos do seu módulo: +Finalize a sessão isolada limpando apenas os processos do seu contexto e módulo: ```bash -agent-browser --session "$MODULO" close +agent-browser --session "$SESSAO" close ``` --- @@ -129,37 +140,55 @@ 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 Canônicas por Contexto (`modulo-acesso`) -Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso`: +Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso` para o contexto correspondente: ```bash -# Extrair identificador e credenciais canônicas de teste de memorias-ia/modulo.yml +# Identificar módulo e contexto MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}') -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" # interno | externo | cliente | anonimo +SESSAO="${MODULO}_${CONTEXTO}" -# 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 +if [ "$CONTEXTO" = "anonimo" ]; then + # Contexto anônimo: navegação pública limpa sem autenticação + echo "Iniciando sessão pública limpa: $SESSAO" + agent-browser --session "$SESSAO" open --headed http://localhost:8080/consulta-publica +else + # Contexto autenticado: obter credenciais do perfil ou usar fallback direto + USUARIO=$(grep -A6 "modulo-acesso:" memorias-ia/modulo.yml | grep -A2 "${CONTEXTO}:" | grep "usuario:" | awk '{print $2}' || true) + SENHA=$(grep -A6 "modulo-acesso:" memorias-ia/modulo.yml | grep -A2 "${CONTEXTO}:" | grep "senha:" | awk '{print $2}' || true) + + if [ -z "$USUARIO" ]; then + USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}') + SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}') + fi + + # Preenchimento determinístico no formulário de login na sessão isolada + agent-browser --session "$SESSAO" open --headed http://localhost:8080/login + agent-browser --session "$SESSAO" wait 1000 + agent-browser --session "$SESSAO" snapshot -i + agent-browser --session "$SESSAO" fill @e1 "$USUARIO" + agent-browser --session "$SESSAO" fill @e2 "$SENHA" + agent-browser --session "$SESSAO" click @e3 +fi ``` > ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste. @@ -170,11 +199,11 @@ agent-browser --session "$MODULO" click @e3 Para fluxos que necessitam manter login ativo entre comandos com isolamento: ```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 "$SESSAO" --restore open --headed http://localhost:8080/login # Verificar status da sessão isolada -agent-browser --session "$MODULO" session info --json +agent-browser --session "$SESSAO" session info --json ``` --- @@ -194,6 +223,6 @@ agent-browser skills get dogfood ## Boas Práticas no Ecossistema Azteca (Vue 3 / Vuetify) -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 "$SESSAO" fill @ref` ou `click @ref`. +2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser --session "$SESSAO" wait 500 && agent-browser --session "$SESSAO" snapshot -i` para interagir com o conteúdo do diálogo. 3. **Reporte de Teste**: Apresente ao operador o roteiro executado, evidências de screenshot e verificação de logs do console. 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..0812394 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` @@ -39,9 +39,15 @@ modulo-descricao: modulo-tipo: # Credenciais padrão para autenticação em testes (agent-browser, E2E, QA) +# Suporta formato direto legado ou subdividido por contexto de acesso modulo-acesso: usuario: senha: + # Ou subdividido por contexto: + # interno: { usuario: "...", senha: "..." } + # externo: { usuario: "...", senha: "..." } + # cliente: { usuario: "...", senha: "..." } + # Nota: o perfil 'anonimo' atua sempre sem credenciais na sessão _anonimo # Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/) modulo-wiki: @@ -51,11 +57,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 identificador mandatório de 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 de teste para autenticação determinística por agentes (`@testes`, QA, `agent-browser`), suportando formato direto padrão (`usuario`/`senha`) ou subdivisão por contexto (`interno`, `externo`, `cliente`). | `{ usuario: "admin@gov.br", senha: "123" }` | | **`modulo-wiki`** | `string` | Caminho relativo ou absoluto da Wiki do projeto (VitePress). **Fallback obrigatório:** se omitido ou vazio, assume-se `../wiki/`. | `./QUIPO-WIKI` ou `../wiki` | --- @@ -63,10 +69,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 de `modulo-acesso` em `memorias-ia/modulo.yml` correspondentes ao contexto que está sendo testado (`interno`, `externo`, `cliente`), ou utilizar as credenciais padrão diretas. No contexto `anonimo`, nenhuma autenticação é realizada; 5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia; 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..61deace 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 _) para evitar mistura de tokens. scope: global trigger: always_on updatedAt: "2026-10-08" @@ -13,9 +13,9 @@ updatedAt: "2026-10-08" Quando uma IA precisa testar o frontend, validar jornadas de usuário, inspecionar componentes gráficos ou simular interações na tela, é crucial utilizar uma ferramenta rápida, determinística e econômica em tokens. Além disso, o operador humano deve sempre ter visibilidade do que a IA está executando em tempo real na interface gráfica. -Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Para viabilizar testes concorrentes e evitar interferências mútuas entre múltiplos módulos ou workspaces, todo comando deve operar em sessão isolada identificada pelo módulo. +Por padrão, invocações sem identificação de sessão utilizam a sessão `"default"`, compartilhando o mesmo daemon e socket Unix. Em aplicações que possuem múltiplos níveis de acesso (como áreas administrativas internas, portais de requerentes externos, consultas anônimas públicas e acessos de clientes corporativos), a ausência de isolamento por contexto gera **mistura de tokens JWT, cookies de autenticação e dados de LocalStorage**, provocando falsos positivos ou mascarando falhas de segurança. -Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** para qualquer teste de interface ou automação de navegador conduzida por agentes de IA. +Esta regra padroniza o uso da ferramenta CLI **`agent-browser`** com isolamento estrito por módulo e contexto de acesso (`--session _`). --- @@ -27,20 +27,29 @@ 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 perfil 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 `` representa o perfil ou nível de acesso que está sendo testado), ou garantir no ambiente `export AGENT_BROWSER_SESSION=_`. + - **Contextos Padronizados de Acesso:** + - `interno`: Acesso restrito a servidores públicos, fiscais, analistas internos ou administradores. + - `externo`: Acesso de requerentes externos, contribuintes ou cidadãos logados. + - `anonimo`: Acesso público e não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). **Obrigatório para assegurar ausência total de tokens ou cookies residuais de sessões anteriores.** + - `cliente`: Acesso de clientes ou empresas contratantes em plataformas multi-tenant ou B2B. + - Aplicações de contexto único sem distinção de perfis podem utilizar apenas `` ou `_default`. + - **Prevenção de Mistura de Tokens e Cookies:** Cada sessão do `agent-browser` possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/_.sock`), mantendo cookie jar, cabeçalhos `Authorization`, LocalStorage e SessionStorage completamente estanques. Separar por `_` é estritamente obrigatório para que um teste anônimo não herde tokens de um teste interno, ou que credenciais de requerente externo não interfiram em fluxos administrativos. + - **Sub-isolamento Concorrente:** Caso múltiplos testes concorrentes ocorram no mesmo módulo e contexto, adota-se o sufixo determinístico: `_-`. 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 de Teste por Contexto (`modulo-acesso`)**: + - O agente **DEVE OBRIGATORIAMENTE consultar `modulo-acesso` em `memorias-ia/modulo.yml`**. + - Se configurado com chaves específicas por contexto (`interno`, `externo`, `cliente`), extrair as credenciais do contexto sob teste. + - Se configurado no formato plano direto (`usuario` e `senha`), utilizar como credencial padrão para o contexto principal/interno. + - Para o contexto `anonimo`, o agente **NÃO deve autenticar**, validando a jornada como usuário não-logado na sessão isolada `_anonimo`. - É terminantemente proibido inventar credenciais aleatórias ou chutar credenciais inexistentes que falhem no teste. --- @@ -63,55 +72,59 @@ Documentação de referência: **https://agent-browser.dev/** ## Protocolo Operacional Padrão -Todo teste ou navegação de interface executado pela IA deve seguir o fluxo com isolamento de sessão: +Todo teste ou navegação de interface executado pela IA deve seguir o fluxo com isolamento de sessão e contexto: -### 1. Obter Identificador do Módulo e Abertura com Janela Visível +### 1. Obter Identificador do Módulo, Definir Contexto e Abertura com Janela Visível ```bash # Obter o modulo-id canônico de memorias-ia/modulo.yml MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}') -# Abrir sempre visível ao operador humano na sessão isolada do módulo -agent-browser --session "$MODULO" open --headed http://localhost:8080 +# Definir contexto sob teste: interno | externo | anonimo | cliente +CONTEXTO="interno" # ou externo, anonimo, cliente +SESSAO="${MODULO}_${CONTEXTO}" + +# Abrir sempre visível ao operador humano na sessão isolada do módulo e contexto +agent-browser --session "$SESSAO" open --headed http://localhost:8080 ``` ### 2. Inspeção de Elementos Interativos ```bash # Gera árvore de acessibilidade compacta com refs determinísticas (@e1, @e2) -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "$SESSAO" snapshot -i ``` ### 3. Interações por Referência Direta ```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 "$SESSAO" fill @e1 "usuario@exemplo.com" +agent-browser --session "$SESSAO" fill @e2 "senhaSegura123" +agent-browser --session "$SESSAO" 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 "$SESSAO" wait 1000 # Obter novo snapshot para verificar estado pós-ação -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "$SESSAO" snapshot -i # Capturar evidência gráfica do teste -agent-browser --session "$MODULO" screenshot evidencias/teste-login-sucesso.png +agent-browser --session "$SESSAO" screenshot evidencias/teste-login-sucesso.png # Verificar erros no console do navegador -agent-browser --session "$MODULO" console +agent-browser --session "$SESSAO" console ``` ### 5. Finalização ```bash # Fechar a sessão isolada do navegador ao concluir o teste -agent-browser --session "$MODULO" close +agent-browser --session "$SESSAO" close ``` --- @@ -119,23 +132,25 @@ agent-browser --session "$MODULO" close ## Boas Práticas e Proibições ### 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 sessões ou misturar tokens entre perfis. - **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`. +- **Proibido testar fluxos anônimos em sessões já autenticadas**, garantindo que testes públicos sempre rodem na sessão `_anonimo`. - **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 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**: Previne contaminação entre sessões de administradores internos, cidadãos externos e consultas públicas anônimas. +- **Isolamento de Processos e Concorrência**: Múltiplos agentes rodando testes E2E simultâneos não colidem abas nem encerram daemons de outros contextos. - **Transparência para o operador**: O operador humano acompanha exatamente o que a IA está clicando e testando na interface em tempo real. - **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 +163,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..51b7aad 100644 --- a/skills/testar-interface-agent-browser/SKILL.md +++ b/skills/testar-interface-agent-browser/SKILL.md @@ -3,7 +3,8 @@ name: testar-interface-agent-browser description: > Executar testes automatizados de interface (E2E), navegação e validação visual no frontend utilizando a CLI agent-browser, com janela sempre visível (--headed) - e isolamento mandatório de sessão por módulo (--session ). + e isolamento mandatório de sessão por módulo e contexto (--session _) + para evitar mistura de tokens e cookies entre acessos. scope: global --- @@ -15,12 +16,18 @@ Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuár --- -## 🔒 Princípio de Isolamento de Sessão por Módulo (`--session `) +## 🔒 Princípio de Isolamento de Sessão por Módulo 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` utiliza sockets Unix independentes por sessão (`/run/user/1000/agent-browser/.sock`). Em sistemas que possuem diferentes perfis de acesso, separar o contexto na flag de sessão é **indispensável para prevenir mistura de tokens JWT, cookies de autenticação e dados de LocalStorage**: -- **Todo comando DEVE ser acompanhado da flag `--session `** (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"`. +- **Todo comando DEVE ser acompanhado da flag `--session _`** (onde `` é o `modulo-id` canônico de `memorias-ia/modulo.yml` e `` é o perfil sob teste), ou garantir no ambiente `export AGENT_BROWSER_SESSION=_`. +- **Contextos Padronizados:** + - `interno`: Acesso de analistas, fiscais, operadores internos ou administradores. + - `externo`: Acesso de requerentes externos, cidadãos cadastrados ou contribuintes logados. + - `anonimo`: Acesso público / não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). **Garante sessão limpa sem resíduo de autenticações anteriores.** + - `cliente`: Acesso de clientes ou empresas em plataformas multi-tenant ou B2B. + - Aplicações de contexto único sem múltiplos acessos podem utilizar apenas `` ou `_default`. +- **Sub-isolamento Concorrente:** Caso múltiplos fluxos concorrentes rodem no mesmo contexto: `--session "${MODULO}_${CONTEXTO}-${slug_ou_pid}"`. --- @@ -30,7 +37,7 @@ Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na á - Usar sempre a flag `--headed` na abertura: ```bash - agent-browser --session "$MODULO" open --headed + agent-browser --session "${MODULO}_${CONTEXTO}" open --headed ``` - Ou exportar no ambiente: ```bash @@ -56,19 +63,23 @@ 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 Módulo e Contexto +Abra a aplicação frontend mantendo a janela visível e isolada: ```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}') -agent-browser --session "$MODULO" open --headed http://localhost:8080 +# Definir contexto sob teste: interno | externo | anonimo | cliente +CONTEXTO="interno" # ou externo, anonimo, cliente +SESSAO="${MODULO}_${CONTEXTO}" + +agent-browser --session "$SESSAO" open --headed http://localhost:8080 ``` ### 2. Obter Snapshot Interativo Gere a árvore de acessibilidade enxuta com referências numéricas: ```bash -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "$SESSAO" snapshot -i ``` *Saída de exemplo:* ```text @@ -82,45 +93,45 @@ agent-browser --session "$MODULO" snapshot -i 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" +agent-browser --session "$SESSAO" fill @e2 "12.345.678/0001-90" +agent-browser --session "$SESSAO" fill @e3 "Indústria Modelo LTDA" # Acionamento de botões e links -agent-browser --session "$MODULO" click @e4 +agent-browser --session "$SESSAO" click @e4 ``` ### 4. Aguardar Transição e Validar Estado 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 "$SESSAO" wait 1500 # Capturar novo snapshot para verificar se a lista ou mensagem apareceu -agent-browser --session "$MODULO" snapshot -i +agent-browser --session "$SESSAO" snapshot -i ``` ### 5. Verificar Logs de Erro no Console e Rede 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 "$SESSAO" console # Verificar requisições de rede falhadas -agent-browser --session "$MODULO" network +agent-browser --session "$SESSAO" 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 "$SESSAO" screenshot evidencias/resultado-sucesso.png +# agent-browser --session "$SESSAO" screenshot --annotate evidencias/resultado-anotado.png ``` ### 7. Encerrar Navegador -Finalize a sessão isolada limpando apenas os processos do seu módulo: +Finalize a sessão isolada limpando apenas os processos do seu contexto e módulo: ```bash -agent-browser --session "$MODULO" close +agent-browser --session "$SESSAO" close ``` --- @@ -129,37 +140,55 @@ 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 Canônicas por Contexto (`modulo-acesso`) -Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso`: +Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso` para o contexto correspondente: ```bash -# Extrair identificador e credenciais canônicas de teste de memorias-ia/modulo.yml +# Identificar módulo e contexto MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}') -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" # interno | externo | cliente | anonimo +SESSAO="${MODULO}_${CONTEXTO}" -# 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 +if [ "$CONTEXTO" = "anonimo" ]; then + # Contexto anônimo: navegação pública limpa sem autenticação + echo "Iniciando sessão pública limpa: $SESSAO" + agent-browser --session "$SESSAO" open --headed http://localhost:8080/consulta-publica +else + # Contexto autenticado: obter credenciais do perfil ou usar fallback direto + USUARIO=$(grep -A6 "modulo-acesso:" memorias-ia/modulo.yml | grep -A2 "${CONTEXTO}:" | grep "usuario:" | awk '{print $2}' || true) + SENHA=$(grep -A6 "modulo-acesso:" memorias-ia/modulo.yml | grep -A2 "${CONTEXTO}:" | grep "senha:" | awk '{print $2}' || true) + + if [ -z "$USUARIO" ]; then + USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}') + SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}') + fi + + # Preenchimento determinístico no formulário de login na sessão isolada + agent-browser --session "$SESSAO" open --headed http://localhost:8080/login + agent-browser --session "$SESSAO" wait 1000 + agent-browser --session "$SESSAO" snapshot -i + agent-browser --session "$SESSAO" fill @e1 "$USUARIO" + agent-browser --session "$SESSAO" fill @e2 "$SENHA" + agent-browser --session "$SESSAO" click @e3 +fi ``` > ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste. @@ -170,11 +199,11 @@ agent-browser --session "$MODULO" click @e3 Para fluxos que necessitam manter login ativo entre comandos com isolamento: ```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 "$SESSAO" --restore open --headed http://localhost:8080/login # Verificar status da sessão isolada -agent-browser --session "$MODULO" session info --json +agent-browser --session "$SESSAO" session info --json ``` --- @@ -194,6 +223,6 @@ agent-browser skills get dogfood ## Boas Práticas no Ecossistema Azteca (Vue 3 / Vuetify) -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 "$SESSAO" fill @ref` ou `click @ref`. +2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser --session "$SESSAO" wait 500 && agent-browser --session "$SESSAO" snapshot -i` para interagir com o conteúdo do diálogo. 3. **Reporte de Teste**: Apresente ao operador o roteiro executado, evidências de screenshot e verificação de logs do console. diff --git a/validar-setup.sh b/validar-setup.sh index 4ba31de..c5697c2 100644 --- a/validar-setup.sh +++ b/validar-setup.sh @@ -109,7 +109,7 @@ 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} (ex: ${MODULO_ID}_interno, ${MODULO_ID}_externo, ${MODULO_ID}_anonimo, ${MODULO_ID}_cliente)" fi # Validar memorias-ia/historico-acoes.md (Pilar 6 - Índice de Ações)