context agent

skills/testar-interface-agent-browser/SKILL.md

@@ -3,7 +3,7 @@ name: testar-interface-agent-browser
 description: >
   Executar testes automatizados de interface (E2E), navegação e validação visual
   no frontend utilizando a CLI agent-browser, com janela sempre visível (--headed)
-  e isolamento mandatório de sessão por módulo (--session <modulo>).
+  e isolamento mandatório de sessão e contexto (--session <modulo>_<contexto?>).
 scope: global
 ---
 
@@ -11,16 +11,31 @@ scope: global
 
 ## Objetivo
 
-Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuário, preencher formulários, inspecionar componentes gráficos e validar fluxos no frontend de maneira rápida, determinística e econômica em tokens, garantindo isolamento total entre processos e visualização em tempo real pelo operador humano.
+Executar testes automatizados de ponta a ponta (E2E), simular jornadas de usuário, preencher formulários, inspecionar componentes gráficos e validar fluxos no frontend de maneira rápida, determinística e econômica em tokens, garantindo isolamento total de cookies, tokens e processos, com visualização em tempo real pelo operador humano.
 
 ---
 
-## 🔒 Princípio de Isolamento de Sessão por Módulo (`--session <modulo>`)
+## 🔒 Princípio de Isolamento de Sessão e Contexto (`--session <modulo>_<contexto?>`)
 
-O daemon do `agent-browser` utiliza sockets Unix independentes por sessão. Para evitar conflitos de comandos, interferência entre módulos diferentes ou encerramento indevido de processos via `agent-browser close`:
+O daemon do `agent-browser` aloca sockets Unix dedicados e armazena cookies HTTP, tokens JWT (em cabeçalhos, cookies ou `localStorage`/`sessionStorage`) e estados de autenticação independentes por sessão.
 
-- **Todo comando DEVE ser acompanhado da flag `--session <modulo>`** (onde `<modulo>` é o `modulo-id` canônico de `memorias-ia/modulo.yml`), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>`.
-- Caso múltiplos fluxos de teste concorrentes rodem no mesmo módulo, utilizar sufixo discriminador determinístico: `--session "${MODULO}-subfluxo"`.
+Para evitar contaminação cruzada de credenciais, interferência mútua entre módulos ou encerramento indevido de processos via `agent-browser close`:
+
+- **Todo comando DEVE ser acompanhado da flag `--session <modulo>_<contexto?>`** (onde `<modulo>` é o `modulo-id` canônico de `memorias-ia/modulo.yml` e `<contexto?>` identifica o papel ou perfil de acesso), ou garantir no ambiente `export AGENT_BROWSER_SESSION=<modulo>_<contexto?>`.
+- **Prevenção Obrigatória de Mistura de Tokens:** Caso a aplicação possua mais de um tipo de acesso (`interno`, `externo`, `anonimo`, `cliente`, etc.), o `<contexto>` **DEVE SER OBRIGATORIAMENTE PREENCHIDO**. Exemplo: um teste logado como operador `interno` nunca deve compartilhar a mesma sessão de um teste de rota pública `anonimo` ou de acesso do `cliente`.
+- **Sub-isolamento para concorrência:** Caso múltiplos fluxos de teste concorrentes do mesmo papel rodem simultaneamente, utilizar sufixo discriminador determinístico: `--session "${MODULO}_${CONTEXTO}_${SLUG_OU_PID}"`.
+
+---
+
+## 🧭 Contextos Canônicos de Sessão
+
+| Contexto | Finalidade e Escopo | Exemplo de Sessão | Fonte de Credenciais |
+| :--- | :--- | :--- | :--- |
+| **`interno`** | Operador interno, suporte, técnico, atendente, administrador | `--session <modulo>_interno` | `modulo-acesso.interno` (ou `modulo-acesso` simples) |
+| **`cliente`** | Solicitante corporativo, empresa cliente, contratante | `--session <modulo>_cliente` | `modulo-acesso.cliente` |
+| **`externo`** | Portal público autenticado, cidadão, requerente externo | `--session <modulo>_externo` | `modulo-acesso.externo` |
+| **`anonimo`** | Usuário deslogado, consulta pública, login, landing page | `--session <modulo>_anonimo` | Nenhuma (perfil limpo sem cookies/tokens) |
+| **`<especifico>`** | Papel especializado de domínio (ex: `fiscal`, `auditor`) | `--session <modulo>_<papel>` | `modulo-acesso.<papel>` |
 
 ---
 
@@ -30,7 +45,7 @@ Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na á
 
 - Usar sempre a flag `--headed` na abertura:
   ```bash
-  agent-browser --session "$MODULO" open --headed <url>
+  agent-browser --session "${MODULO}_${CONTEXTO}" open --headed <url>
   ```
 - Ou exportar no ambiente:
   ```bash
@@ -56,71 +71,72 @@ Documentação oficial: **https://agent-browser.dev/**
 
 ## Fluxo Operacional Passo a Passo
 
-### 1. Iniciar Sessão Visível e Isolada
-Abra a aplicação frontend mantendo a janela visível e isolada por módulo:
+### 1. Iniciar Sessão Visível e Isolada por Contexto
+Abra a aplicação frontend mantendo a janela visível e isolada pelo módulo e contexto desejado:
 ```bash
-# Obter modulo-id canônico
+# Obter modulo-id canônico de memorias-ia/modulo.yml
 MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
+CONTEXTO="interno" # ou "cliente", "externo", "anonimo"
 
-agent-browser --session "$MODULO" open --headed http://localhost:8080
+agent-browser --session "${MODULO}_${CONTEXTO}" open --headed http://localhost:8080
 ```
 
 ### 2. Obter Snapshot Interativo
 Gere a árvore de acessibilidade enxuta com referências numéricas:
 ```bash
-agent-browser --session "$MODULO" snapshot -i
+agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i
 ```
 *Saída de exemplo:*
 ```text
-- heading "Qualificação de Fornecedores" [ref=e1]
-- textbox "CNPJ" [ref=e2]
-- textbox "Razão Social" [ref=e3]
-- button "Pesquisar" [ref=e4]
+- heading "Atendimento ao Cliente" [ref=e1]
+- textbox "E-mail ou Usuário" [ref=e2]
+- textbox "Senha" [ref=e3]
+- button "Entrar" [ref=e4]
 ```
 
 ### 3. Interagir com Determinismo
 Utilize as referências identificadas (`@e1`, `@e2`, etc.):
 ```bash
-# Preenchimento de campos de texto
-agent-browser --session "$MODULO" fill @e2 "12.345.678/0001-90"
-agent-browser --session "$MODULO" fill @e3 "Indústria Modelo LTDA"
+# Preenchimento de credenciais ou campos de formulário
+agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "operador@empresa.com"
+agent-browser --session "${MODULO}_${CONTEXTO}" fill @e3 "senha123"
 
 # Acionamento de botões e links
-agent-browser --session "$MODULO" click @e4
+agent-browser --session "${MODULO}_${CONTEXTO}" click @e4
 ```
 
 ### 4. Aguardar Transição e Validar Estado
 Se a ação disparar chamada assíncrona ou animação, aguarde a estabilização:
 ```bash
 # Aguardar 1 a 2 segundos
-agent-browser --session "$MODULO" wait 1500
+agent-browser --session "${MODULO}_${CONTEXTO}" wait 1500
 
-# Capturar novo snapshot para verificar se a lista ou mensagem apareceu
-agent-browser --session "$MODULO" snapshot -i
+# Capturar novo snapshot para verificar se o painel ou mensagem apareceu
+agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i
 ```
 
 ### 5. Verificar Logs de Erro no Console e Rede
 Assegure que nenhum erro de script ou requisição 500 ocorreu silenciosamente:
 ```bash
 # Inspecionar mensagens do console do browser
-agent-browser --session "$MODULO" console
+agent-browser --session "${MODULO}_${CONTEXTO}" console
 
 # Verificar requisições de rede falhadas
-agent-browser --session "$MODULO" network
+agent-browser --session "${MODULO}_${CONTEXTO}" network
 ```
 
 ### 6. Registrar Evidência Visual
 Capture um screenshot para comprovação do resultado do teste:
 ```bash
 # Screenshot padrão ou anotado com identificadores visuais
-agent-browser --session "$MODULO" screenshot evidencias/resultado-sucesso.png
-# agent-browser --session "$MODULO" screenshot --annotate evidencias/resultado-anotado.png
+agent-browser --session "${MODULO}_${CONTEXTO}" screenshot evidencias/resultado-sucesso.png
+# agent-browser --session "${MODULO}_${CONTEXTO}" screenshot --annotate evidencias/resultado-anotado.png
 ```
 
-### 7. Encerrar Navegador
-Finalize a sessão isolada limpando apenas os processos do seu módulo:
+### 7. Encerrar Navegador daquele Contexto
+Finalize a sessão isolada limpando apenas os processos e tokens do contexto testado:
 ```bash
-agent-browser --session "$MODULO" close
+agent-browser --session "${MODULO}_${CONTEXTO}" close
 ```
 
 ---
@@ -129,52 +145,57 @@ agent-browser --session "$MODULO" close
 
 | Ação | Comando |
 |---|---|
-| **Abrir tela (visível)** | `agent-browser --session <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 por Contexto (`modulo-acesso`)
 
-Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso`:
+Sempre que a aplicação exigir login, o agente DEVE consultar `memorias-ia/modulo.yml` para obter as credenciais canônicas configuradas em `modulo-acesso` para o contexto específico:
 
 ```bash
-# Extrair identificador e credenciais canônicas de teste de memorias-ia/modulo.yml
 MODULO=$(grep -E "^modulo-id:" memorias-ia/modulo.yml | awk '{print $2}')
-USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')
-SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
+CONTEXTO="interno" # ou "cliente", "externo"
+
+# Extrair credenciais do contexto específico (compatível com multi-contexto ou formato simples)
+USUARIO=$(grep -A3 "${CONTEXTO}:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')
+[ -z "$USUARIO" ] && USUARIO=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "usuario:" | awk '{print $2}')
+
+SENHA=$(grep -A3 "${CONTEXTO}:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
+[ -z "$SENHA" ] && SENHA=$(grep -A2 "modulo-acesso:" memorias-ia/modulo.yml | grep "senha:" | awk '{print $2}')
 
 # Preenchimento determinístico no formulário de login na sessão isolada
-agent-browser --session "$MODULO" fill @e1 "$USUARIO"
-agent-browser --session "$MODULO" fill @e2 "$SENHA"
-agent-browser --session "$MODULO" click @e3
+agent-browser --session "${MODULO}_${CONTEXTO}" fill @e1 "$USUARIO"
+agent-browser --session "${MODULO}_${CONTEXTO}" fill @e2 "$SENHA"
+agent-browser --session "${MODULO}_${CONTEXTO}" click @e3
 ```
 
-> ⚠️ **Atenção:** Nunca utilize credenciais aleatórias ou inventadas que possam falhar no teste.
+> ⚠️ **Atenção:** Nunca misture o fluxo `anonimo` na mesma sessão que executou login. Use sempre `--session "${MODULO}_anonimo"` para testes públicos e deslogados.
 
 ---
 
 ## Sessões Persistentes e Autenticação
 
-Para fluxos que necessitam manter login ativo entre comandos com isolamento:
+Para fluxos que necessitam manter login ativo entre comandos com isolamento por contexto:
 ```bash
-# Iniciar sessão nomeada com auto-restore no escopo do módulo
-agent-browser --session "$MODULO" --restore open --headed http://localhost:8080/login
+# Iniciar sessão nomeada com auto-restore no escopo do módulo e contexto
+agent-browser --session "${MODULO}_${CONTEXTO}" --restore open --headed http://localhost:8080/login
 
 # Verificar status da sessão isolada
-agent-browser --session "$MODULO" session info --json
+agent-browser --session "${MODULO}_${CONTEXTO}" session info --json
 ```
 
 ---
@@ -194,6 +215,6 @@ agent-browser skills get dogfood
 
 ## Boas Práticas no Ecossistema Azteca (Vue 3 / Vuetify)
 
-1. **Campos Vuetify (`v-text-field`, `v-select`)**: O `snapshot -i` mapeia diretamente o `textbox` e o `combobox`. Utilize `agent-browser --session "$MODULO" fill @ref` ou `click @ref`.
-2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser --session "$MODULO" wait 500 && agent-browser --session "$MODULO" snapshot -i` para interagir com o conteúdo do diálogo.
+1. **Campos Vuetify (`v-text-field`, `v-select`)**: O `snapshot -i` mapeia diretamente o `textbox` e o `combobox`. Utilize `agent-browser --session "${MODULO}_${CONTEXTO}" fill @ref` ou `click @ref`.
+2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser --session "${MODULO}_${CONTEXTO}" wait 500 && agent-browser --session "${MODULO}_${CONTEXTO}" snapshot -i` para interagir com o conteúdo do diálogo.
 3. **Reporte de Teste**: Apresente ao operador o roteiro executado, evidências de screenshot e verificação de logs do console.