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

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

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

129
global/skills/testar-interface-agent-browser/SKILL.md
View 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.