diff --git a/TOOLS b/TOOLS index fd21b8e..cf568ac 100644 --- a/TOOLS +++ b/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 `) 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 ``` diff --git a/agents/front/persona b/agents/front/persona index 73ca4e5..9940a01 100644 --- a/agents/front/persona +++ b/agents/front/persona @@ -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 diff --git a/agents/testes/persona b/agents/testes/persona index c674fe4..edf8f0a 100644 --- a/agents/testes/persona +++ b/agents/testes/persona @@ -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 diff --git a/agents/ux/persona b/agents/ux/persona index 63efb5f..b3c85b9 100644 --- a/agents/ux/persona +++ b/agents/ux/persona @@ -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 diff --git a/global/rules/testes-interface-agent-browser.md b/global/rules/testes-interface-agent-browser.md deleted file mode 100644 index 96d477c..0000000 --- a/global/rules/testes-interface-agent-browser.md +++ /dev/null @@ -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 `) 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 `. - - 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 ` 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` diff --git a/global/rules/zod-validacao-padrao.md b/global/rules/zod-validacao-padrao.md index 8388eaa..36fa24f 100644 --- a/global/rules/zod-validacao-padrao.md +++ b/global/rules/zod-validacao-padrao.md @@ -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 diff --git a/global/skills/criar-schema-zod/SKILL.md b/global/skills/criar-schema-zod/SKILL.md index c9ed425..e517f51 100644 --- a/global/skills/criar-schema-zod/SKILL.md +++ b/global/skills/criar-schema-zod/SKILL.md @@ -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? diff --git a/global/skills/testar-interface-agent-browser/SKILL.md b/global/skills/testar-interface-agent-browser/SKILL.md deleted file mode 100644 index 24851f4..0000000 --- a/global/skills/testar-interface-agent-browser/SKILL.md +++ /dev/null @@ -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 - ``` -- 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 ` | -| **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 ` | -| **Aguardar seletor** | `agent-browser wait --selector ""` | -| **Inspecionar console** | `agent-browser console` | -| **Inspecionar rede** | `agent-browser network` | -| **Screenshot** | `agent-browser screenshot ` | -| **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. diff --git a/manifesto.json b/manifesto.json index fe51e09..bf7d682 100644 --- a/manifesto.json +++ b/manifesto.json @@ -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": { diff --git a/rules/testes-interface-agent-browser.md b/rules/testes-interface-agent-browser.md deleted file mode 100644 index 96d477c..0000000 --- a/rules/testes-interface-agent-browser.md +++ /dev/null @@ -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 `) 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 `. - - 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 ` 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` diff --git a/rules/zod-validacao-padrao.md b/rules/zod-validacao-padrao.md index 8388eaa..36fa24f 100644 --- a/rules/zod-validacao-padrao.md +++ b/rules/zod-validacao-padrao.md @@ -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 diff --git a/skills/criar-schema-zod/SKILL.md b/skills/criar-schema-zod/SKILL.md index c9ed425..e517f51 100644 --- a/skills/criar-schema-zod/SKILL.md +++ b/skills/criar-schema-zod/SKILL.md @@ -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? diff --git a/skills/testar-interface-agent-browser/SKILL.md b/skills/testar-interface-agent-browser/SKILL.md deleted file mode 100644 index 24851f4..0000000 --- a/skills/testar-interface-agent-browser/SKILL.md +++ /dev/null @@ -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 - ``` -- 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 ` | -| **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 ` | -| **Aguardar seletor** | `agent-browser wait --selector ""` | -| **Inspecionar console** | `agent-browser console` | -| **Inspecionar rede** | `agent-browser network` | -| **Screenshot** | `agent-browser screenshot ` | -| **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.