Compare commits
No commits in common. "a947483a7693b4ed28dd2a8d9f10c7042c7dc7ef" and "ee747d80701895ff0f150bf4537a33765d49ab30" have entirely different histories.
a947483a76
...
ee747d8070
13 changed files with 11 additions and 731 deletions
23
TOOLS
23
TOOLS
|
|
@ -89,22 +89,9 @@ Este documento lista ferramentas de linha de comando (CLI) e utilitários que ot
|
|||
|
||||
---
|
||||
|
||||
## 6. Automação e Testes de Interface (Browser)
|
||||
## 6. Instalação Rápida (Copia e Cola)
|
||||
|
||||
### 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 open --headed <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
|
||||
- **Instalação:**
|
||||
- Com Bun (padrão): `bun i -g agent-browser && agent-browser install`
|
||||
- Com NPM: `npm install -g agent-browser && agent-browser install`
|
||||
- **Documentação:** https://agent-browser.dev/
|
||||
|
||||
---
|
||||
|
||||
## 7. Instalação Rápida (Copia e Cola)
|
||||
|
||||
Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer `npm`, `bun` e `snap` já configurados).
|
||||
Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer `npm` e `snap` já configurados).
|
||||
|
||||
### Linux (Debian / Ubuntu)
|
||||
|
||||
|
|
@ -116,10 +103,7 @@ sudo apt-get install -y ripgrep fd-find jq shellcheck bat tree eza httpie gh
|
|||
# 2. Instalar ferramentas em Node
|
||||
npm install -g @ast-grep/cli @biomejs/biome
|
||||
|
||||
# 3. Instalar automação de navegador para IA (visível com --headed)
|
||||
bun i -g agent-browser && agent-browser install
|
||||
|
||||
# 4. Instalar yq via snap
|
||||
# 3. Instalar yq via snap
|
||||
sudo snap install yq
|
||||
```
|
||||
|
||||
|
|
@ -129,5 +113,4 @@ sudo snap install yq
|
|||
# Instalar utilitários essenciais
|
||||
brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh
|
||||
npm install -g @biomejs/biome
|
||||
bun i -g agent-browser && agent-browser install
|
||||
```
|
||||
|
|
|
|||
|
|
@ -47,7 +47,6 @@ 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`)** para acompanhamento do operador (ver `rules/testes-interface-agent-browser.md`)
|
||||
|
||||
## Restrições
|
||||
|
||||
|
|
|
|||
|
|
@ -45,7 +45,6 @@ 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`)** para que o operador acompanhe cada ação na tela (ver `rules/testes-interface-agent-browser.md` e skill `testar-interface-agent-browser`)
|
||||
|
||||
## Restrições
|
||||
|
||||
|
|
@ -113,7 +112,6 @@ 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`) com screenshots comprobatórios?
|
||||
|
||||
## Memória Persistente & Identidade do Projeto
|
||||
|
||||
|
|
|
|||
|
|
@ -45,7 +45,6 @@ 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`)** para que o operador acompanhe a validação visual (ver `rules/testes-interface-agent-browser.md`)
|
||||
|
||||
## Restrições
|
||||
|
||||
|
|
|
|||
|
|
@ -1,133 +0,0 @@
|
|||
---
|
||||
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) ao operador.
|
||||
scope: global
|
||||
trigger: always_on
|
||||
updatedAt: "2026-09-16"
|
||||
---
|
||||
|
||||
# Regra: Testes Automatizados de Interface e Navegação com agent-browser
|
||||
|
||||
## Contexto
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Regra
|
||||
|
||||
Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar realizar testes automatizados de interface (E2E), navegar no frontend ou inspecionar telas ativas, **DEVE OBRIGATORIAMENTE**:
|
||||
|
||||
1. **Utilizar o `agent-browser`** como ferramenta oficial de automação de navegador.
|
||||
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 open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
|
||||
3. **Utilizar o modelo de referências (`@ref`)**:
|
||||
- Mapear a tela via `agent-browser snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
|
||||
- Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
|
||||
4. **Registrar evidências e fechar sessão**:
|
||||
- Registrar comprovações visuais com `agent-browser screenshot <arquivo.png>`.
|
||||
- Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo.
|
||||
|
||||
---
|
||||
|
||||
## Instalação e Configuração
|
||||
|
||||
O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium:
|
||||
|
||||
```bash
|
||||
# Instalação global via bun (recomendado)
|
||||
bun i -g agent-browser
|
||||
|
||||
# Download do motor do navegador (primeira execução)
|
||||
agent-browser install
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
### 1. Abertura com Janela Visível
|
||||
|
||||
```bash
|
||||
# Abrir sempre visível ao operador humano
|
||||
agent-browser 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 snapshot -i
|
||||
```
|
||||
|
||||
### 3. Interações por Referência Direta
|
||||
|
||||
```bash
|
||||
# Interagir diretamente com os elementos identificados no snapshot
|
||||
agent-browser fill @e1 "usuario@exemplo.com"
|
||||
agent-browser fill @e2 "senhaSegura123"
|
||||
agent-browser click @e3
|
||||
```
|
||||
|
||||
### 4. Validação e Evidência
|
||||
|
||||
```bash
|
||||
# Aguardar estabilização se houver transição assíncrona
|
||||
agent-browser wait 1000
|
||||
|
||||
# Obter novo snapshot para verificar estado pós-ação
|
||||
agent-browser snapshot -i
|
||||
|
||||
# Capturar evidência gráfica do teste
|
||||
agent-browser screenshot evidencias/teste-login-sucesso.png
|
||||
|
||||
# Verificar erros no console do navegador
|
||||
agent-browser console
|
||||
```
|
||||
|
||||
### 5. Finalização
|
||||
|
||||
```bash
|
||||
# Fechar a sessão do navegador ao concluir o teste
|
||||
agent-browser close
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Boas Práticas e Proibições
|
||||
|
||||
### Proibido ❌
|
||||
- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`.
|
||||
- **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 orfãs** após a conclusão do trabalho (sempre executar `agent-browser close`).
|
||||
|
||||
### Permitido e Recomendado ✅
|
||||
- Manter sessões persistentes quando necessário via `--session <nome>` e `--restore`.
|
||||
- Usar `agent-browser 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
|
||||
|
||||
- **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.
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Documentação Oficial: https://agent-browser.dev/
|
||||
- Skill associada: `skills/testar-interface-agent-browser/SKILL.md`
|
||||
- Ferramentas CLI: `.agent/TOOLS`
|
||||
|
|
@ -139,7 +139,7 @@ export const zProdutoCriar = z.object({
|
|||
nome: z.string().trim().min(1),
|
||||
preco: z.coerce.number().positive(),
|
||||
ativo: z.boolean().default(true),
|
||||
codigo: z.string().toUpperCase().nullish(),
|
||||
codigo: z.string().toUpperCase().optional(),
|
||||
tags: z.array(z.string()).default([]),
|
||||
})
|
||||
|
||||
|
|
@ -149,35 +149,7 @@ produto.nome = produto.nome.trim()
|
|||
produto.codigo = produto.codigo?.toUpperCase()
|
||||
```
|
||||
|
||||
### 8. Colunas e Registros que Podem ser Nulos Devem Usar `.nullish()`
|
||||
|
||||
Em schemas de tabelas, entidades e contratos de dados que mapeiam colunas do banco de dados ou campos de formulário/API que podem ser nulos ou omitidos, **DEVE-SE obrigatoriamente usar `.nullish()`** (nunca `.optional()` ou `.nullable()` isolados).
|
||||
|
||||
**Por que `.nullish()` é obrigatório?**
|
||||
- **Bancos relacionais (PostgreSQL/Knex)**: colunas nulas retornam `null`.
|
||||
- **Formulários e payloads parciais**: frequentemente omitem o campo (`undefined`) ou enviam `null` ao limpar.
|
||||
- `.optional()` aceita apenas `undefined` — **falha** com `Expected string, received null` ao receber dados do banco ou payload com `null`.
|
||||
- `.nullable()` aceita apenas `null` — **falha** com `Required` ao omitir o campo em atualizações parciais (`undefined`).
|
||||
- `.nullish()` aceita ambos (`T | null | undefined`), garantindo interoperabilidade total entre banco, API e frontend sem erros de runtime.
|
||||
|
||||
```typescript
|
||||
// ✅ CORRETO — coluna/registro opcional ou nulo com .nullish()
|
||||
export const zPontosBase = z.object({
|
||||
id: z.string().max(64).nullish(),
|
||||
nome: z.string().min(1),
|
||||
descricao: z.string().max(5000).nullish(),
|
||||
codigo_empreendimento: zUUID.nullish(),
|
||||
coordenadas: zCoordenadas.nullish(),
|
||||
})
|
||||
|
||||
// ❌ ERRADO — quebra ao ler do banco quando a coluna for NULL
|
||||
descricao: z.string().optional()
|
||||
|
||||
// ❌ ERRADO — quebra se o campo for omitido no payload (undefined)
|
||||
descricao: z.string().nullable()
|
||||
```
|
||||
|
||||
### 9. Composição e Enums Zod
|
||||
### 8. Composição e Enums Zod
|
||||
|
||||
```typescript
|
||||
// ✅ Composição de schemas via extend/partial
|
||||
|
|
|
|||
|
|
@ -72,26 +72,6 @@ export const zUsuarioCriar = z.object({
|
|||
| `z{Modulo}Config` | Configuração |
|
||||
| `z{Modulo}Ambiente` | Variáveis de ambiente |
|
||||
|
||||
### 2.4. Colunas e Campos que Podem ser Nulos: Usar `.nullish()`
|
||||
|
||||
Toda coluna do banco de dados relacional ou campo de entidade/registro que puder ser nulo ou omitido **DEVE** utilizar `.nullish()` (nunca `.optional()` ou `.nullable()` isolados):
|
||||
|
||||
```typescript
|
||||
// ✅ CORRETO — aceita null (do banco PostgreSQL) e undefined (payload omitido)
|
||||
export const zPontoCriar = z.object({
|
||||
nome: z.string().min(1),
|
||||
descricao: z.string().max(5000).nullish(),
|
||||
codigo_empreendimento: zUUID.nullish(),
|
||||
coordenadas: zCoordenadas.nullish(),
|
||||
})
|
||||
|
||||
// ❌ ERRADO — quebra com null retornado pelo Knex/PostgreSQL
|
||||
descricao: z.string().optional(),
|
||||
|
||||
// ❌ ERRADO — quebra quando a chave é omitida no payload (undefined)
|
||||
descricao: z.string().nullable(),
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 3 — Derivar o Tipo com `z.infer<>`
|
||||
|
|
@ -195,7 +175,6 @@ Zero erros = concluído.
|
|||
- [ ] A validação usa `safeParse` (exceto em boot/middleware)?
|
||||
- [ ] A nomenclatura segue o padrão `z{Entidade}{Acao}`?
|
||||
- [ ] Transformações (trim, coerce, default) estão no schema, não no handler?
|
||||
- [ ] Colunas e campos que podem ser nulos/opcionais utilizam `.nullish()` (em vez de `.optional()` ou `.nullable()` isolados)?
|
||||
- [ ] Schemas derivados usam composição (.partial, .extend, .pick), não duplicação?
|
||||
- [ ] `tsc --noEmit` passa sem erros?
|
||||
|
||||
|
|
|
|||
|
|
@ -1,166 +0,0 @@
|
|||
---
|
||||
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).
|
||||
scope: global
|
||||
---
|
||||
|
||||
# Skill: Testar Interface com agent-browser
|
||||
|
||||
## 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 que o operador humano sempre acompanhe a execução na tela.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Princípio Fundamental: Navegador Sempre Visível ao Operador
|
||||
|
||||
Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na área de trabalho do operador:
|
||||
|
||||
- Usar sempre a flag `--headed` na abertura:
|
||||
```bash
|
||||
agent-browser open --headed <url>
|
||||
```
|
||||
- Ou exportar no ambiente:
|
||||
```bash
|
||||
export AGENT_BROWSER_HEADED=true
|
||||
```
|
||||
- **Nunca executar em modo headless silencioso**, a menos que o operador humano solicite expressamente essa exceção.
|
||||
|
||||
---
|
||||
|
||||
## Pré-requisitos e Instalação
|
||||
|
||||
```bash
|
||||
# Verificar se o agent-browser já está instalado
|
||||
which agent-browser || bun i -g agent-browser
|
||||
|
||||
# Baixar o binário do Chromium gerenciado pelo daemon (na primeira vez)
|
||||
agent-browser install
|
||||
```
|
||||
|
||||
Documentação oficial: **https://agent-browser.dev/**
|
||||
|
||||
---
|
||||
|
||||
## Fluxo Operacional Passo a Passo
|
||||
|
||||
### 1. Iniciar Sessão Visível
|
||||
Abra a aplicação frontend mantendo a janela visível ao operador:
|
||||
```bash
|
||||
agent-browser open --headed http://localhost:8080
|
||||
```
|
||||
|
||||
### 2. Obter Snapshot Interativo
|
||||
Gere a árvore de acessibilidade enxuta com referências numéricas:
|
||||
```bash
|
||||
agent-browser 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]
|
||||
```
|
||||
|
||||
### 3. Interagir com Determinismo
|
||||
Utilize as referências identificadas (`@e1`, `@e2`, etc.):
|
||||
```bash
|
||||
# Preenchimento de campos de texto
|
||||
agent-browser fill @e2 "12.345.678/0001-90"
|
||||
agent-browser fill @e3 "Indústria Modelo LTDA"
|
||||
|
||||
# Acionamento de botões e links
|
||||
agent-browser 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 wait 1500
|
||||
|
||||
# Capturar novo snapshot para verificar se a lista ou mensagem apareceu
|
||||
agent-browser 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 console
|
||||
|
||||
# Verificar requisições de rede falhadas
|
||||
agent-browser 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 screenshot evidencias/resultado-sucesso.png
|
||||
# agent-browser screenshot --annotate evidencias/resultado-anotado.png
|
||||
```
|
||||
|
||||
### 7. Encerrar Navegador
|
||||
Finalize a sessão limpando os processos do daemon:
|
||||
```bash
|
||||
agent-browser close
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tabela Rápida de Comandos
|
||||
|
||||
| Ação | Comando |
|
||||
|---|---|
|
||||
| **Abrir tela (visível)** | `agent-browser open --headed <url>` |
|
||||
| **Snapshot de elementos** | `agent-browser snapshot -i` |
|
||||
| **Clicar elemento** | `agent-browser click @ref` |
|
||||
| **Preencher campo** | `agent-browser fill @ref "valor"` |
|
||||
| **Selecionar dropdown** | `agent-browser select @ref "opcao"` |
|
||||
| **Pressionar tecla** | `agent-browser press Enter` |
|
||||
| **Obter texto** | `agent-browser get text @ref` |
|
||||
| **Aguardar tempo** | `agent-browser wait <ms>` |
|
||||
| **Aguardar seletor** | `agent-browser wait --selector "<seletor>"` |
|
||||
| **Inspecionar console** | `agent-browser console` |
|
||||
| **Inspecionar rede** | `agent-browser network` |
|
||||
| **Screenshot** | `agent-browser screenshot <arquivo.png>` |
|
||||
| **Auditoria a11y (WCAG)** | `agent-browser a11y` |
|
||||
| **Fechar sessão** | `agent-browser close` |
|
||||
|
||||
---
|
||||
|
||||
## Sessões Persistentes e Autenticação
|
||||
|
||||
Para fluxos que necessitam manter login ativo entre comandos:
|
||||
```bash
|
||||
# Iniciar sessão nomeada com auto-restore
|
||||
agent-browser --session auth-test --restore open --headed http://localhost:8080/login
|
||||
|
||||
# Verificar status da sessão
|
||||
agent-browser session info --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skills Nativas do agent-browser
|
||||
|
||||
O binário `agent-browser` possui guias aprofundados integrados que podem ser consultados a qualquer momento:
|
||||
```bash
|
||||
# Guia completo do core (todas as opções e referências)
|
||||
agent-browser skills get core --full
|
||||
|
||||
# Guia para testes exploratórios e caça a bugs (dogfooding)
|
||||
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 fill @ref` ou `agent-browser click @ref`.
|
||||
2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser wait 500 && agent-browser 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.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"versao": "3.2.0",
|
||||
"atualizadoEm": "2026-09-16",
|
||||
"atualizadoEm": "2026-09-02",
|
||||
"projeto": "e-licencie",
|
||||
"artefatos": {
|
||||
"global": {
|
||||
|
|
@ -28,8 +28,7 @@
|
|||
"global/rules/typescript-sem-any.md",
|
||||
"global/rules/zod-validacao-padrao.md",
|
||||
"global/rules/ddd-documentacao-primeiro.md",
|
||||
"global/rules/identidade-modulo.md",
|
||||
"global/rules/testes-interface-agent-browser.md"
|
||||
"global/rules/identidade-modulo.md"
|
||||
],
|
||||
"workflows": [
|
||||
"global/workflows/aprimora-ia.md",
|
||||
|
|
@ -52,8 +51,7 @@
|
|||
"global/skills/documentar-regras-negocio/SKILL.md",
|
||||
"global/skills/mapear-codigo-fonte/SKILL.md",
|
||||
"global/skills/onboarding-projeto/SKILL.md",
|
||||
"global/skills/orquestrar-agentes/SKILL.md",
|
||||
"global/skills/testar-interface-agent-browser/SKILL.md"
|
||||
"global/skills/orquestrar-agentes/SKILL.md"
|
||||
]
|
||||
},
|
||||
"documentacao": {
|
||||
|
|
@ -185,8 +183,7 @@
|
|||
"persona": "agents/testes/persona",
|
||||
"config": "agents/testes/agent.json",
|
||||
"skills": [
|
||||
"agents/testes/skills/diagnosticar-cobertura-testes/SKILL.md",
|
||||
"skills/testar-interface-agent-browser/SKILL.md"
|
||||
"agents/testes/skills/diagnosticar-cobertura-testes/SKILL.md"
|
||||
]
|
||||
},
|
||||
"ux": {
|
||||
|
|
|
|||
|
|
@ -1,133 +0,0 @@
|
|||
---
|
||||
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) ao operador.
|
||||
scope: global
|
||||
trigger: always_on
|
||||
updatedAt: "2026-09-16"
|
||||
---
|
||||
|
||||
# Regra: Testes Automatizados de Interface e Navegação com agent-browser
|
||||
|
||||
## Contexto
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Regra
|
||||
|
||||
Sempre que qualquer agente de IA (`@testes`, `@front`, `@ux` ou outro) precisar realizar testes automatizados de interface (E2E), navegar no frontend ou inspecionar telas ativas, **DEVE OBRIGATORIAMENTE**:
|
||||
|
||||
1. **Utilizar o `agent-browser`** como ferramenta oficial de automação de navegador.
|
||||
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 open --headed <url>`) ou garantir a variável de ambiente `export AGENT_BROWSER_HEADED=true`.
|
||||
3. **Utilizar o modelo de referências (`@ref`)**:
|
||||
- Mapear a tela via `agent-browser snapshot -i`, obtendo referências compactas como `@e1`, `@e2`.
|
||||
- Executar ações determinísticas referenciando os IDs gerados (`click @e1`, `fill @e2 "texto"`).
|
||||
4. **Registrar evidências e fechar sessão**:
|
||||
- Registrar comprovações visuais com `agent-browser screenshot <arquivo.png>`.
|
||||
- Encerrar graciosamente o navegador com `agent-browser close` ao término do fluxo.
|
||||
|
||||
---
|
||||
|
||||
## Instalação e Configuração
|
||||
|
||||
O `agent-browser` é instalado globalmente via `bun` (ou `npm`) com download de binários do Chromium:
|
||||
|
||||
```bash
|
||||
# Instalação global via bun (recomendado)
|
||||
bun i -g agent-browser
|
||||
|
||||
# Download do motor do navegador (primeira execução)
|
||||
agent-browser install
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
### 1. Abertura com Janela Visível
|
||||
|
||||
```bash
|
||||
# Abrir sempre visível ao operador humano
|
||||
agent-browser 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 snapshot -i
|
||||
```
|
||||
|
||||
### 3. Interações por Referência Direta
|
||||
|
||||
```bash
|
||||
# Interagir diretamente com os elementos identificados no snapshot
|
||||
agent-browser fill @e1 "usuario@exemplo.com"
|
||||
agent-browser fill @e2 "senhaSegura123"
|
||||
agent-browser click @e3
|
||||
```
|
||||
|
||||
### 4. Validação e Evidência
|
||||
|
||||
```bash
|
||||
# Aguardar estabilização se houver transição assíncrona
|
||||
agent-browser wait 1000
|
||||
|
||||
# Obter novo snapshot para verificar estado pós-ação
|
||||
agent-browser snapshot -i
|
||||
|
||||
# Capturar evidência gráfica do teste
|
||||
agent-browser screenshot evidencias/teste-login-sucesso.png
|
||||
|
||||
# Verificar erros no console do navegador
|
||||
agent-browser console
|
||||
```
|
||||
|
||||
### 5. Finalização
|
||||
|
||||
```bash
|
||||
# Fechar a sessão do navegador ao concluir o teste
|
||||
agent-browser close
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Boas Práticas e Proibições
|
||||
|
||||
### Proibido ❌
|
||||
- **Proibido abrir em modo headless silencioso** sem flag `--headed` ou variável `AGENT_BROWSER_HEADED=true`.
|
||||
- **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 orfãs** após a conclusão do trabalho (sempre executar `agent-browser close`).
|
||||
|
||||
### Permitido e Recomendado ✅
|
||||
- Manter sessões persistentes quando necessário via `--session <nome>` e `--restore`.
|
||||
- Usar `agent-browser 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
|
||||
|
||||
- **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.
|
||||
|
||||
---
|
||||
|
||||
## Referências
|
||||
|
||||
- Documentação Oficial: https://agent-browser.dev/
|
||||
- Skill associada: `skills/testar-interface-agent-browser/SKILL.md`
|
||||
- Ferramentas CLI: `.agent/TOOLS`
|
||||
|
|
@ -139,7 +139,7 @@ export const zProdutoCriar = z.object({
|
|||
nome: z.string().trim().min(1),
|
||||
preco: z.coerce.number().positive(),
|
||||
ativo: z.boolean().default(true),
|
||||
codigo: z.string().toUpperCase().nullish(),
|
||||
codigo: z.string().toUpperCase().optional(),
|
||||
tags: z.array(z.string()).default([]),
|
||||
})
|
||||
|
||||
|
|
@ -149,35 +149,7 @@ produto.nome = produto.nome.trim()
|
|||
produto.codigo = produto.codigo?.toUpperCase()
|
||||
```
|
||||
|
||||
### 8. Colunas e Registros que Podem ser Nulos Devem Usar `.nullish()`
|
||||
|
||||
Em schemas de tabelas, entidades e contratos de dados que mapeiam colunas do banco de dados ou campos de formulário/API que podem ser nulos ou omitidos, **DEVE-SE obrigatoriamente usar `.nullish()`** (nunca `.optional()` ou `.nullable()` isolados).
|
||||
|
||||
**Por que `.nullish()` é obrigatório?**
|
||||
- **Bancos relacionais (PostgreSQL/Knex)**: colunas nulas retornam `null`.
|
||||
- **Formulários e payloads parciais**: frequentemente omitem o campo (`undefined`) ou enviam `null` ao limpar.
|
||||
- `.optional()` aceita apenas `undefined` — **falha** com `Expected string, received null` ao receber dados do banco ou payload com `null`.
|
||||
- `.nullable()` aceita apenas `null` — **falha** com `Required` ao omitir o campo em atualizações parciais (`undefined`).
|
||||
- `.nullish()` aceita ambos (`T | null | undefined`), garantindo interoperabilidade total entre banco, API e frontend sem erros de runtime.
|
||||
|
||||
```typescript
|
||||
// ✅ CORRETO — coluna/registro opcional ou nulo com .nullish()
|
||||
export const zPontosBase = z.object({
|
||||
id: z.string().max(64).nullish(),
|
||||
nome: z.string().min(1),
|
||||
descricao: z.string().max(5000).nullish(),
|
||||
codigo_empreendimento: zUUID.nullish(),
|
||||
coordenadas: zCoordenadas.nullish(),
|
||||
})
|
||||
|
||||
// ❌ ERRADO — quebra ao ler do banco quando a coluna for NULL
|
||||
descricao: z.string().optional()
|
||||
|
||||
// ❌ ERRADO — quebra se o campo for omitido no payload (undefined)
|
||||
descricao: z.string().nullable()
|
||||
```
|
||||
|
||||
### 9. Composição e Enums Zod
|
||||
### 8. Composição e Enums Zod
|
||||
|
||||
```typescript
|
||||
// ✅ Composição de schemas via extend/partial
|
||||
|
|
|
|||
|
|
@ -72,26 +72,6 @@ export const zUsuarioCriar = z.object({
|
|||
| `z{Modulo}Config` | Configuração |
|
||||
| `z{Modulo}Ambiente` | Variáveis de ambiente |
|
||||
|
||||
### 2.4. Colunas e Campos que Podem ser Nulos: Usar `.nullish()`
|
||||
|
||||
Toda coluna do banco de dados relacional ou campo de entidade/registro que puder ser nulo ou omitido **DEVE** utilizar `.nullish()` (nunca `.optional()` ou `.nullable()` isolados):
|
||||
|
||||
```typescript
|
||||
// ✅ CORRETO — aceita null (do banco PostgreSQL) e undefined (payload omitido)
|
||||
export const zPontoCriar = z.object({
|
||||
nome: z.string().min(1),
|
||||
descricao: z.string().max(5000).nullish(),
|
||||
codigo_empreendimento: zUUID.nullish(),
|
||||
coordenadas: zCoordenadas.nullish(),
|
||||
})
|
||||
|
||||
// ❌ ERRADO — quebra com null retornado pelo Knex/PostgreSQL
|
||||
descricao: z.string().optional(),
|
||||
|
||||
// ❌ ERRADO — quebra quando a chave é omitida no payload (undefined)
|
||||
descricao: z.string().nullable(),
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PASSO 3 — Derivar o Tipo com `z.infer<>`
|
||||
|
|
@ -195,7 +175,6 @@ Zero erros = concluído.
|
|||
- [ ] A validação usa `safeParse` (exceto em boot/middleware)?
|
||||
- [ ] A nomenclatura segue o padrão `z{Entidade}{Acao}`?
|
||||
- [ ] Transformações (trim, coerce, default) estão no schema, não no handler?
|
||||
- [ ] Colunas e campos que podem ser nulos/opcionais utilizam `.nullish()` (em vez de `.optional()` ou `.nullable()` isolados)?
|
||||
- [ ] Schemas derivados usam composição (.partial, .extend, .pick), não duplicação?
|
||||
- [ ] `tsc --noEmit` passa sem erros?
|
||||
|
||||
|
|
|
|||
|
|
@ -1,166 +0,0 @@
|
|||
---
|
||||
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).
|
||||
scope: global
|
||||
---
|
||||
|
||||
# Skill: Testar Interface com agent-browser
|
||||
|
||||
## 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 que o operador humano sempre acompanhe a execução na tela.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Princípio Fundamental: Navegador Sempre Visível ao Operador
|
||||
|
||||
Todo teste de interface executado pela IA **DEVE ABRIR A JANELA VISÍVEL** na área de trabalho do operador:
|
||||
|
||||
- Usar sempre a flag `--headed` na abertura:
|
||||
```bash
|
||||
agent-browser open --headed <url>
|
||||
```
|
||||
- Ou exportar no ambiente:
|
||||
```bash
|
||||
export AGENT_BROWSER_HEADED=true
|
||||
```
|
||||
- **Nunca executar em modo headless silencioso**, a menos que o operador humano solicite expressamente essa exceção.
|
||||
|
||||
---
|
||||
|
||||
## Pré-requisitos e Instalação
|
||||
|
||||
```bash
|
||||
# Verificar se o agent-browser já está instalado
|
||||
which agent-browser || bun i -g agent-browser
|
||||
|
||||
# Baixar o binário do Chromium gerenciado pelo daemon (na primeira vez)
|
||||
agent-browser install
|
||||
```
|
||||
|
||||
Documentação oficial: **https://agent-browser.dev/**
|
||||
|
||||
---
|
||||
|
||||
## Fluxo Operacional Passo a Passo
|
||||
|
||||
### 1. Iniciar Sessão Visível
|
||||
Abra a aplicação frontend mantendo a janela visível ao operador:
|
||||
```bash
|
||||
agent-browser open --headed http://localhost:8080
|
||||
```
|
||||
|
||||
### 2. Obter Snapshot Interativo
|
||||
Gere a árvore de acessibilidade enxuta com referências numéricas:
|
||||
```bash
|
||||
agent-browser 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]
|
||||
```
|
||||
|
||||
### 3. Interagir com Determinismo
|
||||
Utilize as referências identificadas (`@e1`, `@e2`, etc.):
|
||||
```bash
|
||||
# Preenchimento de campos de texto
|
||||
agent-browser fill @e2 "12.345.678/0001-90"
|
||||
agent-browser fill @e3 "Indústria Modelo LTDA"
|
||||
|
||||
# Acionamento de botões e links
|
||||
agent-browser 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 wait 1500
|
||||
|
||||
# Capturar novo snapshot para verificar se a lista ou mensagem apareceu
|
||||
agent-browser 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 console
|
||||
|
||||
# Verificar requisições de rede falhadas
|
||||
agent-browser 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 screenshot evidencias/resultado-sucesso.png
|
||||
# agent-browser screenshot --annotate evidencias/resultado-anotado.png
|
||||
```
|
||||
|
||||
### 7. Encerrar Navegador
|
||||
Finalize a sessão limpando os processos do daemon:
|
||||
```bash
|
||||
agent-browser close
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tabela Rápida de Comandos
|
||||
|
||||
| Ação | Comando |
|
||||
|---|---|
|
||||
| **Abrir tela (visível)** | `agent-browser open --headed <url>` |
|
||||
| **Snapshot de elementos** | `agent-browser snapshot -i` |
|
||||
| **Clicar elemento** | `agent-browser click @ref` |
|
||||
| **Preencher campo** | `agent-browser fill @ref "valor"` |
|
||||
| **Selecionar dropdown** | `agent-browser select @ref "opcao"` |
|
||||
| **Pressionar tecla** | `agent-browser press Enter` |
|
||||
| **Obter texto** | `agent-browser get text @ref` |
|
||||
| **Aguardar tempo** | `agent-browser wait <ms>` |
|
||||
| **Aguardar seletor** | `agent-browser wait --selector "<seletor>"` |
|
||||
| **Inspecionar console** | `agent-browser console` |
|
||||
| **Inspecionar rede** | `agent-browser network` |
|
||||
| **Screenshot** | `agent-browser screenshot <arquivo.png>` |
|
||||
| **Auditoria a11y (WCAG)** | `agent-browser a11y` |
|
||||
| **Fechar sessão** | `agent-browser close` |
|
||||
|
||||
---
|
||||
|
||||
## Sessões Persistentes e Autenticação
|
||||
|
||||
Para fluxos que necessitam manter login ativo entre comandos:
|
||||
```bash
|
||||
# Iniciar sessão nomeada com auto-restore
|
||||
agent-browser --session auth-test --restore open --headed http://localhost:8080/login
|
||||
|
||||
# Verificar status da sessão
|
||||
agent-browser session info --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skills Nativas do agent-browser
|
||||
|
||||
O binário `agent-browser` possui guias aprofundados integrados que podem ser consultados a qualquer momento:
|
||||
```bash
|
||||
# Guia completo do core (todas as opções e referências)
|
||||
agent-browser skills get core --full
|
||||
|
||||
# Guia para testes exploratórios e caça a bugs (dogfooding)
|
||||
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 fill @ref` ou `agent-browser click @ref`.
|
||||
2. **Modais e Diálogos**: Após clicar no botão que abre o modal (`v-dialog`), execute `agent-browser wait 500 && agent-browser 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue