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

context agent

Browse source
This commit is contained in:
Luiz Silva 2026-10-08 15:08:09 -03:00
parent 29e5bc979e
commit f47e12fe81
23 changed files with 347 additions and 226 deletions
Download patch file Download diff file Expand all files Collapse all files

4
skills/plano.executar/SKILL.md
View file

@ -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
```

2
skills/plano/SKILL.md
View file

@ -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`.

139
skills/testar-interface-agent-browser/SKILL.md
View file

@ -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.