feat(testes): padronizar uso de --session <modulo>_<contexto?> no agent-browser para isolamento de tokens
This commit is contained in:
parent
29e5bc979e
commit
1a8adfc2dc
23 changed files with 320 additions and 206 deletions
|
|
@ -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 <modulo-wiki>/<modulo-id>/, regras de negócio e sessão isolada do agent-browser --session <modulo-id>)
|
||||
# Identificador único do módulo (utilizado para pacotes, wikis <modulo-wiki>/<modulo-id>/, regras de negócio e sessão isolada do agent-browser --session <modulo-id>_<contexto?>)
|
||||
modulo-id: nome-do-modulo.submodulo
|
||||
|
||||
# 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 <modulo>_anonimo
|
||||
|
||||
# Caminho para a Wiki do projeto (quando omitido ou vazio, o padrão adotado é ../wiki/)
|
||||
modulo-wiki: ../wiki
|
||||
|
|
|
|||
|
|
@ -90,12 +90,14 @@ executor: null
|
|||
- Qualidade/Lint: `biome check --write <arquivos>`
|
||||
- Governança: `sh .agent/verificar-linhas.sh`
|
||||
|
||||
### 5.2 Roteiro de Teste Manual / `agent-browser` (Sempre em Modo Visível `--headed` e com `--session <modulo-id>`)
|
||||
1. Abrir aplicação: `agent-browser --session <modulo-id> open --headed <url>`
|
||||
2. Mapear interações: `agent-browser --session <modulo-id> snapshot -i`
|
||||
3. Executar ações: `agent-browser --session <modulo-id> fill @ref "..." && agent-browser --session <modulo-id> click @ref`
|
||||
4. Capturar evidência: `agent-browser --session <modulo-id> screenshot evidencias/<slug>.png`
|
||||
5. Encerrar: `agent-browser --session <modulo-id> close`
|
||||
### 5.2 Roteiro de Teste Manual / `agent-browser` (Sempre em Modo Visível `--headed` e com `--session <modulo-id>_<contexto?>`)
|
||||
> 💡 **Nota de Contexto:** Caso a aplicação possua múltiplos acessos (interno, externo, anonimo, cliente), utilize obrigatoriamente o sufixo correspondente (ex: `<modulo-id>_interno`, `<modulo-id>_externo`, `<modulo-id>_anonimo`, `<modulo-id>_cliente`) para prevenir mistura de cookies e tokens de autenticação.
|
||||
|
||||
1. Abrir aplicação: `agent-browser --session <modulo-id>_<contexto> open --headed <url>`
|
||||
2. Mapear interações: `agent-browser --session <modulo-id>_<contexto> snapshot -i`
|
||||
3. Executar ações: `agent-browser --session <modulo-id>_<contexto> fill @ref "..." && agent-browser --session <modulo-id>_<contexto> click @ref`
|
||||
4. Capturar evidência: `agent-browser --session <modulo-id>_<contexto> screenshot evidencias/<slug>.png`
|
||||
5. Encerrar: `agent-browser --session <modulo-id>_<contexto> close`
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
4
TOOLS
4
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 <modulo> open --headed <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
|
||||
- **Isolamento Mandatório de Sessão:** Toda execução DEVE acompanhar a flag `--session <modulo>` (onde `<modulo>` é o `modulo-id` extraído de `memorias-ia/modulo.yml`) ou garantir `export AGENT_BROWSER_SESSION=<modulo>`. Cada sessão aloca daemon e socket Unix exclusivos, prevenindo colisões e fechamento indevido de janelas em execuções concorrentes.
|
||||
- **Modo Visível Obrigatório:** Para que o operador acompanhe cada teste em tempo real na tela, execute sempre com a flag `--headed` (ex: `agent-browser --session <modulo>_<contexto> open --headed <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
|
||||
- **Isolamento Mandatório de Sessão e Contexto:** Toda execução DEVE acompanhar a flag `--session <modulo>_<contexto?>` (onde `<modulo>` é o `modulo-id` extraído de `memorias-ia/modulo.yml` e `<contexto>` indica o perfil sob teste: `interno`, `externo`, `anonimo`, `cliente`) ou garantir `export AGENT_BROWSER_SESSION=<modulo>_<contexto>`. Cada sessão aloca daemon, socket Unix exclusivo, cookies e LocalStorage independentes, prevenindo colisões e vazamento de tokens de autenticação entre diferentes acessos.
|
||||
- **Instalação:**
|
||||
- Com Bun (padrão): `bun i -g agent-browser && agent-browser install`
|
||||
- Com NPM: `npm install -g agent-browser && agent-browser install`
|
||||
|
|
|
|||
4
TOOLS.md
4
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 <modulo> open --headed <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
|
||||
- **Isolamento Mandatório de Sessão:** Toda execução DEVE acompanhar a flag `--session <modulo>` (onde `<modulo>` é o `modulo-id` extraído de `memorias-ia/modulo.yml`) ou garantir `export AGENT_BROWSER_SESSION=<modulo>`. Cada sessão aloca daemon e socket Unix exclusivos, prevenindo colisões e fechamento indevido de janelas em execuções concorrentes.
|
||||
- **Modo Visível Obrigatório:** Para que o operador acompanhe cada teste em tempo real na tela, execute sempre com a flag `--headed` (ex: `agent-browser --session <modulo>_<contexto> open --headed <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
|
||||
- **Isolamento Mandatório de Sessão e Contexto:** Toda execução DEVE acompanhar a flag `--session <modulo>_<contexto?>` (onde `<modulo>` é o `modulo-id` extraído de `memorias-ia/modulo.yml` e `<contexto>` indica o perfil sob teste: `interno`, `externo`, `anonimo`, `cliente`) ou garantir `export AGENT_BROWSER_SESSION=<modulo>_<contexto>`. Cada sessão aloca daemon, socket Unix exclusivo, cookies e LocalStorage independentes, prevenindo colisões e vazamento de tokens de autenticação entre diferentes acessos.
|
||||
- **Instalação:**
|
||||
- Com Bun (padrão): `bun i -g agent-browser && agent-browser install`
|
||||
- Com NPM: `npm install -g agent-browser && agent-browser install`
|
||||
|
|
|
|||
|
|
@ -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 <modulo-id>`)** para acompanhamento do operador e prevenção de conflitos em testes simultâneos (ver `rules/testes-interface-agent-browser.md`)
|
||||
11. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session <modulo-id>_<contexto?>`)** para acompanhamento do operador e prevenção de mistura de tokens e conflitos em testes simultâneos (ver `rules/testes-interface-agent-browser.md`)
|
||||
|
||||
## Restrições
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <modulo-id>`)** para acompanhamento do operador e prevenção de conflitos em testes simultâneos (ver `rules/testes-interface-agent-browser.md`)
|
||||
11. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session <modulo-id>_<contexto?>`)** para acompanhamento do operador e prevenção de mistura de tokens e conflitos em testes simultâneos (ver `rules/testes-interface-agent-browser.md`)
|
||||
|
||||
## Restrições
|
||||
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -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 <modulo-id>`)** para que o operador acompanhe cada ação na tela e evitar colisões em testes concorrentes (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`)
|
||||
9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session <modulo-id>_<contexto?>`)** para que o operador acompanhe cada ação na tela e evitar mistura de tokens de autenticação entre acessos interno, externo, anônimo ou cliente (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`)
|
||||
10. **Gerar Planos Técnicos via `/plano`** — durante homologações, reviews ou testes, formalizar bugs, melhorias e gaps em planos estruturados em `PLANOS/pendente/` para posterior implementação pelo time de desenvolvimento (ver `global/workflows/plano.md`).
|
||||
|
||||
## 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 <modulo-id>`), com screenshots comprobatórios?
|
||||
- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) e com sessão contextual isolada (`--session <modulo-id>_<contexto?>`), com screenshots comprobatórios?
|
||||
|
||||
## Memória Persistente & Identidade do Projeto
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <modulo-id>`)** para que o operador acompanhe cada ação na tela e evitar colisões em testes concorrentes (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`)
|
||||
9. Realizar testes automatizados de interface (E2E) com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session <modulo-id>_<contexto?>`)** para que o operador acompanhe cada ação na tela e evitar mistura de tokens de autenticação entre acessos interno, externo, anônimo ou cliente (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`)
|
||||
10. **Gerar Planos Técnicos via `/plano`** — durante homologações, reviews ou testes, formalizar bugs, melhorias e gaps em planos estruturados em `PLANOS/pendente/` para posterior implementação pelo time de desenvolvimento (ver `global/workflows/plano.md`).
|
||||
|
||||
## 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 <modulo-id>`), com screenshots comprobatórios?
|
||||
- [ ] Teste de interface E2E via `agent-browser` executado em modo visível (`--headed`) e com sessão contextual isolada (`--session <modulo-id>_<contexto?>`), com screenshots comprobatórios?
|
||||
|
||||
## Memória Persistente & Identidade do Projeto
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <modulo-id>`)** para que o operador acompanhe a validação visual e evitar interferência entre sessões (ver `rules/testes-interface-agent-browser.md`)
|
||||
9. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session <modulo-id>_<contexto?>`)** para que o operador acompanhe a validação visual e evitar mistura de tokens e interferência entre perfis de acesso (ver `rules/testes-interface-agent-browser.md`)
|
||||
|
||||
## Restrições
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <modulo-id>`)** para que o operador acompanhe a validação visual e evitar interferência entre sessões (ver `rules/testes-interface-agent-browser.md`)
|
||||
9. Auditar a usabilidade e inspeção de telas em tempo de execução com `agent-browser`, **sempre em modo visível (`--headed`) e com isolamento por sessão e contexto (`--session <modulo-id>_<contexto?>`)** para que o operador acompanhe a validação visual e evitar mistura de tokens e interferência entre perfis de acesso (ver `rules/testes-interface-agent-browser.md`)
|
||||
|
||||
## Restrições
|
||||
|
||||
|
|
|
|||
|
|
@ -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: <texto-descritivo>
|
|||
modulo-tipo: <texto-tipo-arquitetura>
|
||||
|
||||
# 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: <login-ou-email>
|
||||
senha: <senha-de-teste>
|
||||
# Ou subdividido por contexto:
|
||||
# interno: { usuario: "...", senha: "..." }
|
||||
# externo: { usuario: "...", senha: "..." }
|
||||
# cliente: { usuario: "...", senha: "..." }
|
||||
# Nota: o perfil 'anonimo' atua sempre sem credenciais na sessão <modulo>_anonimo
|
||||
|
||||
# Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/)
|
||||
modulo-wiki: <caminho-da-wiki>
|
||||
|
|
@ -51,11 +57,11 @@ modulo-wiki: <caminho-da-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 <modulo-id>`). | `e-licencie.sigma` |
|
||||
| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e identificador mandatório de sessão isolada no `agent-browser` (`--session <modulo-id>_<contexto?>`). | `e-licencie.sigma` |
|
||||
| **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/sigma/` |
|
||||
| **`modulo-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: <caminho-da-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 (`<modulo-wiki>/<modulo-id>/`), Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<modulo-wiki>/dev/<modulo-id>/adrs/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session <modulo-id>`)**;
|
||||
1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`), Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<modulo-wiki>/dev/<modulo-id>/adrs/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session <modulo-id>_<contexto?>`)**;
|
||||
2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `<modulo-caminho>llm.md`), links de navegação ou proxies;
|
||||
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`.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <modulo>).
|
||||
description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) e com isolamento por sessão e contexto (--session <modulo>_<contexto?>) para evitar mistura de tokens.
|
||||
scope: global
|
||||
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 <modulo>_<contexto?>`).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -27,20 +27,29 @@ Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar
|
|||
2. **Executar SEMPRE em Modo Visível (`--headed`)**:
|
||||
- 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 <modulo> open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
|
||||
3. **Isolamento Mandatório de Sessão (`--session <modulo>`)**:
|
||||
- **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo.
|
||||
- Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>`.
|
||||
- Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos em testes simultâneos multi-módulos.
|
||||
- Caso um mesmo módulo necessite de sub-isolamento para testes paralelos, deve-se adotar o sufixo determinístico `<modulo-id>-<slug-ou-pid>`.
|
||||
- Usar a flag `--headed` nos comandos de abertura (`agent-browser --session <modulo>_<contexto> open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
|
||||
3. **Isolamento Mandatório de Sessão e Contexto (`--session <modulo>_<contexto?>`)**:
|
||||
- **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo e o perfil de acesso.
|
||||
- Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml` e `<contexto>` representa o perfil ou nível de acesso que está sendo testado), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto>`.
|
||||
- **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 `<modulo>` ou `<modulo>_default`.
|
||||
- **Prevenção de Mistura de Tokens e Cookies:** Cada sessão do `agent-browser` possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>_<contexto>.sock`), mantendo cookie jar, cabeçalhos `Authorization`, LocalStorage e SessionStorage completamente estanques. Separar por `<modulo>_<contexto>` é estritamente obrigatório para que um teste anônimo não herde tokens de um teste interno, ou que credenciais de requerente externo não interfiram em fluxos administrativos.
|
||||
- **Sub-isolamento Concorrente:** Caso múltiplos testes concorrentes ocorram no mesmo módulo e contexto, adota-se o sufixo determinístico: `<modulo>_<contexto>-<slug_ou_pid>`.
|
||||
4. **Utilizar o modelo de referências (`@ref`)**:
|
||||
- Mapear a tela via `agent-browser --session <modulo> snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
|
||||
- Mapear a tela via `agent-browser --session <modulo>_<contexto> snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
|
||||
- Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
|
||||
5. **Registrar evidências e fechar sessão**:
|
||||
- Registrar comprovações visuais com `agent-browser --session <modulo> screenshot <arquivo.png>`.
|
||||
- Encerrar graciosamente o navegador com `agent-browser --session <modulo> 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 <modulo>_<contexto> screenshot <arquivo.png>`.
|
||||
- Encerrar graciosamente o navegador com `agent-browser --session <modulo>_<contexto> 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 `<modulo>_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 <modulo>`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada.
|
||||
- **Proibido executar sem a flag `--session <modulo>_<contexto?>`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir sessões ou misturar tokens entre perfis.
|
||||
- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`.
|
||||
- **Proibido testar fluxos anônimos em sessões já autenticadas**, garantindo que testes públicos sempre rodem na sessão `<modulo>_anonimo`.
|
||||
- **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`).
|
||||
- **Proibido navegar para URLs desconhecidas** ou inventadas pela IA fora do escopo aprovado do teste.
|
||||
- **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <modulo> close`).
|
||||
- **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <sessao> close`).
|
||||
|
||||
### Permitido e Recomendado ✅
|
||||
- Manter sessões persistentes quando necessário via `--session <modulo> --restore`.
|
||||
- Utilizar sub-isolamento determinístico (`<modulo-id>-<slug-ou-pid>`) caso múltiplos testes do mesmo módulo ocorram simultaneamente no mesmo host.
|
||||
- Usar `agent-browser --session <modulo> screenshot --annotate` para inspecionar layouts complexos com visão computacional.
|
||||
- Manter sessões persistentes quando necessário via `--session <modulo>_<contexto> --restore`.
|
||||
- Utilizar sub-isolamento determinístico (`<modulo>_<contexto>-<slug_ou_pid>`) caso múltiplos testes do mesmo contexto ocorram simultaneamente no mesmo host.
|
||||
- Usar `agent-browser --session <modulo>_<contexto> screenshot --annotate` para inspecionar layouts complexos com visão computacional.
|
||||
- Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`.
|
||||
|
||||
---
|
||||
|
||||
## 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`
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <modulo> --headed`. |
|
||||
| **`@testes`** *(QA & Automation)* | Checagens e Validação E2E | Tipagem (`bun run typecheck` / `tsc --noEmit`), linter (`biome check --write`), governança (`sh .agent/verificar-linhas.sh`) e testes de interface visual via `agent-browser --session <modulo>_<contexto?> --headed`. |
|
||||
| **`@documentacao`** *(Memory & Docs)* | `memorias-ia/`, `wiki/` | Registro de sessão no Pilar 6 (`memorias-ia/sessao-*.md`), indexação no `historico-acoes.md`, atualização de regras técnicas na Wiki de Dev (`wiki/dev/<modulo>/`). |
|
||||
|
||||
---
|
||||
|
|
@ -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 <modulo> --headed
|
||||
5. [@testes] Roda typecheck, biome e testes E2E com agent-browser --session <modulo>_<contexto?> --headed
|
||||
↓ (Loop /goal de auto-correção se houver falhas)
|
||||
6. [@documentacao] Atualiza memórias-ia/, historico-acoes.md e arquiva o plano
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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 <modulo> --headed`.
|
||||
- **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session <modulo>_<contexto?> --headed`.
|
||||
- **6. Histórico de Execução:** Cabeçalho reservado para preenchimento na conclusão pelo executor.
|
||||
- Salve o arquivo em `./PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.md` usando `write_to_file`.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <modulo>).
|
||||
e isolamento mandatório de sessão por módulo e contexto (--session <modulo>_<contexto?>)
|
||||
para evitar mistura de tokens e cookies entre acessos.
|
||||
scope: global
|
||||
---
|
||||
|
||||
|
|
@ -15,12 +16,18 @@ Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuár
|
|||
|
||||
---
|
||||
|
||||
## 🔒 Princípio de Isolamento de Sessão por Módulo (`--session <modulo>`)
|
||||
## 🔒 Princípio de Isolamento de Sessão por Módulo e Contexto (`--session <modulo>_<contexto?>`)
|
||||
|
||||
O daemon do `agent-browser` utiliza sockets Unix independentes por sessão. Para evitar conflitos de comandos, interferência entre módulos diferentes ou encerramento indevido de processos via `agent-browser close`:
|
||||
O daemon do `agent-browser` utiliza sockets Unix independentes por sessão (`/run/user/1000/agent-browser/<sessao>.sock`). Em sistemas que possuem diferentes perfis de acesso, separar o contexto na flag de sessão é **indispensável para prevenir mistura de tokens JWT, cookies de autenticação e dados de LocalStorage**:
|
||||
|
||||
- **Todo comando DEVE ser acompanhado da flag `--session <modulo>`** (onde `<modulo>` é o `modulo-id` canônico de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>`.
|
||||
- Caso múltiplos fluxos de teste concorrentes rodem no mesmo módulo, utilizar sufixo discriminador determinístico: `--session "${MODULO}-subfluxo"`.
|
||||
- **Todo comando DEVE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico de `memorias-ia/modulo.yml` e `<contexto>` é o perfil sob teste), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto>`.
|
||||
- **Contextos Padronizados:**
|
||||
- `interno`: Acesso de analistas, fiscais, operadores internos ou administradores.
|
||||
- `externo`: Acesso de requerentes externos, cidadãos cadastrados ou contribuintes logados.
|
||||
- `anonimo`: Acesso público / não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). **Garante sessão limpa sem resíduo de autenticações anteriores.**
|
||||
- `cliente`: Acesso de clientes ou empresas em plataformas multi-tenant ou B2B.
|
||||
- Aplicações de contexto único sem múltiplos acessos podem utilizar apenas `<modulo>` ou `<modulo>_default`.
|
||||
- **Sub-isolamento Concorrente:** Caso múltiplos fluxos concorrentes rodem no mesmo contexto: `--session "${MODULO}_${CONTEXTO}-${slug_ou_pid}"`.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -30,7 +37,7 @@ Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na á
|
|||
|
||||
- Usar sempre a flag `--headed` na abertura:
|
||||
```bash
|
||||
agent-browser --session "$MODULO" open --headed <url>
|
||||
agent-browser --session "${MODULO}_${CONTEXTO}" open --headed <url>
|
||||
```
|
||||
- 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 <modulo> open --headed <url>` |
|
||||
| **Snapshot de elementos** | `agent-browser --session <modulo> snapshot -i` |
|
||||
| **Clicar elemento** | `agent-browser --session <modulo> click @ref` |
|
||||
| **Preencher campo** | `agent-browser --session <modulo> fill @ref "valor"` |
|
||||
| **Selecionar dropdown** | `agent-browser --session <modulo> select @ref "opcao"` |
|
||||
| **Pressionar tecla** | `agent-browser --session <modulo> press Enter` |
|
||||
| **Obter texto** | `agent-browser --session <modulo> get text @ref` |
|
||||
| **Aguardar tempo** | `agent-browser --session <modulo> wait <ms>` |
|
||||
| **Aguardar seletor** | `agent-browser --session <modulo> wait --selector "<seletor>"` |
|
||||
| **Inspecionar console** | `agent-browser --session <modulo> console` |
|
||||
| **Inspecionar rede** | `agent-browser --session <modulo> network` |
|
||||
| **Screenshot** | `agent-browser --session <modulo> screenshot <arquivo.png>` |
|
||||
| **Auditoria a11y (WCAG)** | `agent-browser --session <modulo> a11y` |
|
||||
| **Fechar sessão** | `agent-browser --session <modulo> close` |
|
||||
| **Abrir tela (visível)** | `agent-browser --session <modulo>_<contexto> open --headed <url>` |
|
||||
| **Snapshot de elementos** | `agent-browser --session <modulo>_<contexto> snapshot -i` |
|
||||
| **Clicar elemento** | `agent-browser --session <modulo>_<contexto> click @ref` |
|
||||
| **Preencher campo** | `agent-browser --session <modulo>_<contexto> fill @ref "valor"` |
|
||||
| **Selecionar dropdown** | `agent-browser --session <modulo>_<contexto> select @ref "opcao"` |
|
||||
| **Pressionar tecla** | `agent-browser --session <modulo>_<contexto> press Enter` |
|
||||
| **Obter texto** | `agent-browser --session <modulo>_<contexto> get text @ref` |
|
||||
| **Aguardar tempo** | `agent-browser --session <modulo>_<contexto> wait <ms>` |
|
||||
| **Aguardar seletor** | `agent-browser --session <modulo>_<contexto> wait --selector "<seletor>"` |
|
||||
| **Inspecionar console** | `agent-browser --session <modulo>_<contexto> console` |
|
||||
| **Inspecionar rede** | `agent-browser --session <modulo>_<contexto> network` |
|
||||
| **Screenshot** | `agent-browser --session <modulo>_<contexto> screenshot <arquivo.png>` |
|
||||
| **Auditoria a11y (WCAG)** | `agent-browser --session <modulo>_<contexto> a11y` |
|
||||
| **Fechar sessão** | `agent-browser --session <modulo>_<contexto> close` |
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Autenticação e Credenciais Canônicas (`modulo-acesso`)
|
||||
## 🔑 Autenticação e Credenciais Canônicas por Contexto (`modulo-acesso`)
|
||||
|
||||
Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso`:
|
||||
Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso` para o contexto correspondente:
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
|
|
|||
|
|
@ -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 <modulo> --headed`.
|
||||
- **`@testes`**: Roda `typecheck`, `biome check` e validação visual via `agent-browser --session <modulo>_<contexto?> --headed`.
|
||||
- **`@documentacao`**: Documenta a memória da sessão (Pilar 6) e regras de negócio.
|
||||
|
||||
### 3. Modos de Invocação
|
||||
|
|
|
|||
|
|
@ -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: <texto-descritivo>
|
|||
modulo-tipo: <texto-tipo-arquitetura>
|
||||
|
||||
# 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: <login-ou-email>
|
||||
senha: <senha-de-teste>
|
||||
# Ou subdividido por contexto:
|
||||
# interno: { usuario: "...", senha: "..." }
|
||||
# externo: { usuario: "...", senha: "..." }
|
||||
# cliente: { usuario: "...", senha: "..." }
|
||||
# Nota: o perfil 'anonimo' atua sempre sem credenciais na sessão <modulo>_anonimo
|
||||
|
||||
# Caminho para o repositório da Wiki do projeto (quando omitido ou vazio, o padrão é ../wiki/)
|
||||
modulo-wiki: <caminho-da-wiki>
|
||||
|
|
@ -51,11 +57,11 @@ modulo-wiki: <caminho-da-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 <modulo-id>`). | `e-licencie.sigma` |
|
||||
| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki, referências de regras de negócio e identificador mandatório de sessão isolada no `agent-browser` (`--session <modulo-id>_<contexto?>`). | `e-licencie.sigma` |
|
||||
| **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/sigma/` |
|
||||
| **`modulo-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: <caminho-da-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 (`<modulo-wiki>/<modulo-id>/`), Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<modulo-wiki>/dev/<modulo-id>/adrs/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session <modulo-id>`)**;
|
||||
1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`), Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<modulo-wiki>/dev/<modulo-id>/adrs/`), relatórios e **definir o identificador de sessão isolada no `agent-browser` (`agent-browser --session <modulo-id>_<contexto?>`)**;
|
||||
2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `<modulo-caminho>llm.md`), links de navegação ou proxies;
|
||||
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`.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <modulo>).
|
||||
description: Testes automatizados de interface (E2E) e acesso visual ao frontend devem usar agent-browser, sempre visível (--headed) e com isolamento por sessão e contexto (--session <modulo>_<contexto?>) para evitar mistura de tokens.
|
||||
scope: global
|
||||
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 <modulo>_<contexto?>`).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -27,20 +27,29 @@ Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar
|
|||
2. **Executar SEMPRE em Modo Visível (`--headed`)**:
|
||||
- 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 <modulo> open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
|
||||
3. **Isolamento Mandatório de Sessão (`--session <modulo>`)**:
|
||||
- **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo.
|
||||
- Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>`.
|
||||
- Cada sessão possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>.sock`), prevenindo colisões de abas, perda de contexto e encerramento indevido de processos em testes simultâneos multi-módulos.
|
||||
- Caso um mesmo módulo necessite de sub-isolamento para testes paralelos, deve-se adotar o sufixo determinístico `<modulo-id>-<slug-ou-pid>`.
|
||||
- Usar a flag `--headed` nos comandos de abertura (`agent-browser --session <modulo>_<contexto> open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
|
||||
3. **Isolamento Mandatório de Sessão e Contexto (`--session <modulo>_<contexto?>`)**:
|
||||
- **Nunca utilizar a sessão padrão compartilhada** sem identificar o módulo e o perfil de acesso.
|
||||
- Todo comando `agent-browser` **DEVE OBRIGATORIAMENTE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico extraído de `memorias-ia/modulo.yml` e `<contexto>` representa o perfil ou nível de acesso que está sendo testado), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto>`.
|
||||
- **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 `<modulo>` ou `<modulo>_default`.
|
||||
- **Prevenção de Mistura de Tokens e Cookies:** Cada sessão do `agent-browser` possui daemon e socket Unix dedicados (ex: `/run/user/1000/agent-browser/<modulo>_<contexto>.sock`), mantendo cookie jar, cabeçalhos `Authorization`, LocalStorage e SessionStorage completamente estanques. Separar por `<modulo>_<contexto>` é estritamente obrigatório para que um teste anônimo não herde tokens de um teste interno, ou que credenciais de requerente externo não interfiram em fluxos administrativos.
|
||||
- **Sub-isolamento Concorrente:** Caso múltiplos testes concorrentes ocorram no mesmo módulo e contexto, adota-se o sufixo determinístico: `<modulo>_<contexto>-<slug_ou_pid>`.
|
||||
4. **Utilizar o modelo de referências (`@ref`)**:
|
||||
- Mapear a tela via `agent-browser --session <modulo> snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
|
||||
- Mapear a tela via `agent-browser --session <modulo>_<contexto> snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
|
||||
- Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
|
||||
5. **Registrar evidências e fechar sessão**:
|
||||
- Registrar comprovações visuais com `agent-browser --session <modulo> screenshot <arquivo.png>`.
|
||||
- Encerrar graciosamente o navegador com `agent-browser --session <modulo> 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 <modulo>_<contexto> screenshot <arquivo.png>`.
|
||||
- Encerrar graciosamente o navegador com `agent-browser --session <modulo>_<contexto> 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 `<modulo>_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 <modulo>`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir a sessão default compartilhada.
|
||||
- **Proibido executar sem a flag `--session <modulo>_<contexto?>`** (ou sem `AGENT_BROWSER_SESSION`), evitando poluir sessões ou misturar tokens entre perfis.
|
||||
- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`.
|
||||
- **Proibido testar fluxos anônimos em sessões já autenticadas**, garantindo que testes públicos sempre rodem na sessão `<modulo>_anonimo`.
|
||||
- **Proibido despejar o HTML/DOM completo** no contexto da IA (consome milhares de tokens desnecessários; use sempre `snapshot -i`).
|
||||
- **Proibido navegar para URLs desconhecidas** ou inventadas pela IA fora do escopo aprovado do teste.
|
||||
- **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <modulo> close`).
|
||||
- **Proibido deixar processos ou janelas órfãs** após a conclusão do trabalho (sempre executar `agent-browser --session <sessao> close`).
|
||||
|
||||
### Permitido e Recomendado ✅
|
||||
- Manter sessões persistentes quando necessário via `--session <modulo> --restore`.
|
||||
- Utilizar sub-isolamento determinístico (`<modulo-id>-<slug-ou-pid>`) caso múltiplos testes do mesmo módulo ocorram simultaneamente no mesmo host.
|
||||
- Usar `agent-browser --session <modulo> screenshot --annotate` para inspecionar layouts complexos com visão computacional.
|
||||
- Manter sessões persistentes quando necessário via `--session <modulo>_<contexto> --restore`.
|
||||
- Utilizar sub-isolamento determinístico (`<modulo>_<contexto>-<slug_ou_pid>`) caso múltiplos testes do mesmo contexto ocorram simultaneamente no mesmo host.
|
||||
- Usar `agent-browser --session <modulo>_<contexto> screenshot --annotate` para inspecionar layouts complexos com visão computacional.
|
||||
- Consultar guias embutidos do próprio binário via `agent-browser skills get core --full` ou `agent-browser skills get dogfood`.
|
||||
|
||||
---
|
||||
|
||||
## 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`
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <modulo> --headed`. |
|
||||
| **`@testes`** *(QA & Automation)* | Checagens e Validação E2E | Tipagem (`bun run typecheck` / `tsc --noEmit`), linter (`biome check --write`), governança (`sh .agent/verificar-linhas.sh`) e testes de interface visual via `agent-browser --session <modulo>_<contexto?> --headed`. |
|
||||
| **`@documentacao`** *(Memory & Docs)* | `memorias-ia/`, `wiki/` | Registro de sessão no Pilar 6 (`memorias-ia/sessao-*.md`), indexação no `historico-acoes.md`, atualização de regras técnicas na Wiki de Dev (`wiki/dev/<modulo>/`). |
|
||||
|
||||
---
|
||||
|
|
@ -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 <modulo> --headed
|
||||
5. [@testes] Roda typecheck, biome e testes E2E com agent-browser --session <modulo>_<contexto?> --headed
|
||||
↓ (Loop /goal de auto-correção se houver falhas)
|
||||
6. [@documentacao] Atualiza memórias-ia/, historico-acoes.md e arquiva o plano
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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 <modulo> --headed`.
|
||||
- **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser --session <modulo>_<contexto?> --headed`.
|
||||
- **6. Histórico de Execução:** Cabeçalho reservado para preenchimento na conclusão pelo executor.
|
||||
- Salve o arquivo em `./PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.md` usando `write_to_file`.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <modulo>).
|
||||
e isolamento mandatório de sessão por módulo e contexto (--session <modulo>_<contexto?>)
|
||||
para evitar mistura de tokens e cookies entre acessos.
|
||||
scope: global
|
||||
---
|
||||
|
||||
|
|
@ -15,12 +16,18 @@ Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuár
|
|||
|
||||
---
|
||||
|
||||
## 🔒 Princípio de Isolamento de Sessão por Módulo (`--session <modulo>`)
|
||||
## 🔒 Princípio de Isolamento de Sessão por Módulo e Contexto (`--session <modulo>_<contexto?>`)
|
||||
|
||||
O daemon do `agent-browser` utiliza sockets Unix independentes por sessão. Para evitar conflitos de comandos, interferência entre módulos diferentes ou encerramento indevido de processos via `agent-browser close`:
|
||||
O daemon do `agent-browser` utiliza sockets Unix independentes por sessão (`/run/user/1000/agent-browser/<sessao>.sock`). Em sistemas que possuem diferentes perfis de acesso, separar o contexto na flag de sessão é **indispensável para prevenir mistura de tokens JWT, cookies de autenticação e dados de LocalStorage**:
|
||||
|
||||
- **Todo comando DEVE ser acompanhado da flag `--session <modulo>`** (onde `<modulo>` é o `modulo-id` canônico de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>`.
|
||||
- Caso múltiplos fluxos de teste concorrentes rodem no mesmo módulo, utilizar sufixo discriminador determinístico: `--session "${MODULO}-subfluxo"`.
|
||||
- **Todo comando DEVE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico de `memorias-ia/modulo.yml` e `<contexto>` é o perfil sob teste), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto>`.
|
||||
- **Contextos Padronizados:**
|
||||
- `interno`: Acesso de analistas, fiscais, operadores internos ou administradores.
|
||||
- `externo`: Acesso de requerentes externos, cidadãos cadastrados ou contribuintes logados.
|
||||
- `anonimo`: Acesso público / não autenticado (portal de transparência, certidões públicas, formulários abertos, landing pages). **Garante sessão limpa sem resíduo de autenticações anteriores.**
|
||||
- `cliente`: Acesso de clientes ou empresas em plataformas multi-tenant ou B2B.
|
||||
- Aplicações de contexto único sem múltiplos acessos podem utilizar apenas `<modulo>` ou `<modulo>_default`.
|
||||
- **Sub-isolamento Concorrente:** Caso múltiplos fluxos concorrentes rodem no mesmo contexto: `--session "${MODULO}_${CONTEXTO}-${slug_ou_pid}"`.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -30,7 +37,7 @@ Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na á
|
|||
|
||||
- Usar sempre a flag `--headed` na abertura:
|
||||
```bash
|
||||
agent-browser --session "$MODULO" open --headed <url>
|
||||
agent-browser --session "${MODULO}_${CONTEXTO}" open --headed <url>
|
||||
```
|
||||
- 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 <modulo> open --headed <url>` |
|
||||
| **Snapshot de elementos** | `agent-browser --session <modulo> snapshot -i` |
|
||||
| **Clicar elemento** | `agent-browser --session <modulo> click @ref` |
|
||||
| **Preencher campo** | `agent-browser --session <modulo> fill @ref "valor"` |
|
||||
| **Selecionar dropdown** | `agent-browser --session <modulo> select @ref "opcao"` |
|
||||
| **Pressionar tecla** | `agent-browser --session <modulo> press Enter` |
|
||||
| **Obter texto** | `agent-browser --session <modulo> get text @ref` |
|
||||
| **Aguardar tempo** | `agent-browser --session <modulo> wait <ms>` |
|
||||
| **Aguardar seletor** | `agent-browser --session <modulo> wait --selector "<seletor>"` |
|
||||
| **Inspecionar console** | `agent-browser --session <modulo> console` |
|
||||
| **Inspecionar rede** | `agent-browser --session <modulo> network` |
|
||||
| **Screenshot** | `agent-browser --session <modulo> screenshot <arquivo.png>` |
|
||||
| **Auditoria a11y (WCAG)** | `agent-browser --session <modulo> a11y` |
|
||||
| **Fechar sessão** | `agent-browser --session <modulo> close` |
|
||||
| **Abrir tela (visível)** | `agent-browser --session <modulo>_<contexto> open --headed <url>` |
|
||||
| **Snapshot de elementos** | `agent-browser --session <modulo>_<contexto> snapshot -i` |
|
||||
| **Clicar elemento** | `agent-browser --session <modulo>_<contexto> click @ref` |
|
||||
| **Preencher campo** | `agent-browser --session <modulo>_<contexto> fill @ref "valor"` |
|
||||
| **Selecionar dropdown** | `agent-browser --session <modulo>_<contexto> select @ref "opcao"` |
|
||||
| **Pressionar tecla** | `agent-browser --session <modulo>_<contexto> press Enter` |
|
||||
| **Obter texto** | `agent-browser --session <modulo>_<contexto> get text @ref` |
|
||||
| **Aguardar tempo** | `agent-browser --session <modulo>_<contexto> wait <ms>` |
|
||||
| **Aguardar seletor** | `agent-browser --session <modulo>_<contexto> wait --selector "<seletor>"` |
|
||||
| **Inspecionar console** | `agent-browser --session <modulo>_<contexto> console` |
|
||||
| **Inspecionar rede** | `agent-browser --session <modulo>_<contexto> network` |
|
||||
| **Screenshot** | `agent-browser --session <modulo>_<contexto> screenshot <arquivo.png>` |
|
||||
| **Auditoria a11y (WCAG)** | `agent-browser --session <modulo>_<contexto> a11y` |
|
||||
| **Fechar sessão** | `agent-browser --session <modulo>_<contexto> close` |
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Autenticação e Credenciais Canônicas (`modulo-acesso`)
|
||||
## 🔑 Autenticação e Credenciais Canônicas por Contexto (`modulo-acesso`)
|
||||
|
||||
Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso`:
|
||||
Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso` para o contexto correspondente:
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
|
|
|||
|
|
@ -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}_<contexto>${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)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue