agente-testes 0.6.0

CLI de testes E2E com IA: linguagem natural vira Playwright executável.

Agente Testes

CLI para gravar fluxos E2E (Playwright codegen) e executar specs em segundos — com opção de exploração via linguagem natural e CrewAI.

Repositório: https://github.com/BrunooooPaiva/agente-testes

Instalação global (recomendado)

Pré-requisitos: Python 3.10–3.13, Node.js 18+ (npm/npx no PATH), chave OpenAI.

Opção A — PyPI (recomendado)

pip install --pre agente-testes
agente-testes setup

Com uv:

uv tool install --pre agente-testes
agente-testes setup

Opção B — uv tool a partir do repositório

cd agente_testes
uv tool install --prerelease=allow .
agente-testes setup

Opção C — repositório Git

pip install "agente-testes @ git+https://github.com/BrunooooPaiva/agente-testes.git"
agente-testes setup

O comando setup cria ~/.agente-testes/.env, instala @playwright/test e o Chromium no runtime global.

Edite a API key:

notepad $env:USERPROFILE\.agente-testes\.env

Fluxo principal (painel ou CLI)

# 1. Entre no projeto que quer testar
cd C:\projetos\meu-app

# 2. Prepara workspace (tests/e2e/ + .agente-testes/)
agente-testes init

# 3. Com o app rodando (npm run dev), abra o painel web
agente-testes ui --url http://localhost:3000
# → http://127.0.0.1:9323 (gravar, executar, evidências)

# Alternativa CLI:
agente-testes record --url http://localhost:3000
agente-testes exec tests/e2e/recorded-YYYYMMDD-HHMMSS.spec.js --url http://localhost:3000
agente-testes list

Rotas autenticadas: agente-testes auth-setup e depois record --auth ou exec com AGENTE_TESTES_STORAGE_STATE. Specs que gravam login devem rodar com --clear-storage ou sem a variável de sessão.

Exploração com IA (opcional)

agente-testes run "Validar login com e-mail inválido na rota /login"

Use run para descobrir cenários; use record + exec para repetir com custo zero de API.

Comandos

Comando	Descrição
agente-testes ui	Painel web local (127.0.0.1:9323) — gravar, executar, evidências
agente-testes record	Grava fluxo com Playwright codegen → tests/e2e/*.spec.js
agente-testes exec <spec>	Executa spec sem IA (replay em segundos)
agente-testes list	Lista specs em tests/e2e/ com último status
agente-testes auth-setup	Login determinístico → auth-state.json
agente-testes run "<pedido>"	Exploração com IA (CrewAI) — mais lento, usa API
agente-testes init	Cria tests/e2e/, .agente-testes/ e .gitignore
agente-testes doctor	Valida Python, API key, npx, Playwright, URL e portas locais
agente-testes setup	Instala runtime Playwright (uso global)
agente-testes --verbose run ...	Logs completos do CrewAI

Flags do exec: --video on|retain-on-failure|off, --screenshot on|only-on-failure|off, --trace on|retain-on-failure|off, --clear-storage.

Exemplo determinístico (CT-02 versionado):

agente-testes exec tests/e2e/demo-login-invalid.spec.js --repo fixtures/demo-app

Flags úteis do run: --repo, --url, --skip-url-check.

Desenvolvimento local

cd agente_testes
uv sync
npm install
npx playwright install chromium
copy .env.example .env
# Edite OPENAI_API_KEY em .env

uv run agente-testes doctor
uv run python scripts/start_demo.py   # http://localhost:3000/login

Demo E2E:

cd fixtures\demo-app
uv run agente-testes init
uv run agente-testes run "Validar login com e-mail inválido na rota /login"

Smoke (sem LLM):

uv run python scripts/smoke_tools.py

Configuração

Onde	Variável	Uso
~/.agente-testes/.env	OPENAI_API_KEY	Obrigatória (instalação global)
Projeto alvo .env	AGENTE_TESTES_APP_URL	URL do app sob teste
CLI	--url	Sobrescreve URL na execução

Artefatos ficam em <projeto>/.agente-testes/ (output/, artifacts/, temp_specs/).

Estrutura

src/agente_testes/       CLI, crew, tools, self-healing
src/agente_testes/ui/    Painel web (server, API, static/)
fixtures/demo-app/       App HTTP de demonstração (:3000)
scripts/                 smoke, demo, hooks de commit
docs/ESCOPO_PROJETO.md   Escopo e roadmap por fase
docs/FASE-8.md           Painel web v0.6.0
docs/COMMITS.md          Padrão de commits do projeto

Segurança

• Nunca commite .env; use .env.example / ~/.agente-testes/.env
• Tools bloqueiam leitura de secrets no repositório alvo
• Subprocess Playwright usa env mínimo (sem OPENAI_API_KEY)

Validação em app externo (CT-05, só local)

Apps reais na sua máquina podem ser usados para teste manual (agente-testes run com --repo implícito via cwd). Isso não faz parte do CI nem dos specs versionados deste pacote. Guia: docs/CT-05.md.

Padrões Next.js + toast Sonner: fixture fixtures/nextjs-sonner-fixture/.

Fase 5 — qualidade

• Pré-leitura de login antes da IA (login_preflight)
• Healing proativo ao salvar specs
• Testes: uv run --group dev pytest tests/ -q

Detalhes: docs/FASE-5.md

Fase 8 — painel web (v0.6.0)

• agente-testes ui — gravar, executar specs, auth-setup, relatório e evidências
• agente-testes list — catálogo com último status
• exec com --video, --screenshot, --trace, --clear-storage
• Navegador fecha automaticamente após record (Windows)

Detalhes: docs/FASE-8.md · Escopo: docs/ESCOPO_PROJETO.md

CI (GitHub Actions)

• Automático em PR/push: smoke + pytest + exec (sem custo de API) — ver docs/CI.md
• Manual com IA: workflow E2E com IA + secret OPENAI_API_KEY — ver docs/CI.md#secret-obrigatório

Licença

MIT