agente-testes 0.4.11

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

Agente Testes

CLI que transforma pedidos em linguagem natural em testes Playwright executáveis, com relatório e evidências — powered by 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 CLI (3 passos)

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

# 2. (opcional) prepara workspace local
agente-testes init

# 3. Com o app rodando (npm run dev), peça o teste
agente-testes run "Validar login com e-mail inválido na rota /login"

Saída esperada: status ✅/❌, caminhos do relatório, spec e artefatos em .agente-testes/.

Comandos

Comando	Descrição
agente-testes run "<pedido>"	Fluxo completo com IA: análise → Playwright → execução → relatório
agente-testes exec <spec>	Executa spec versionado sem IA (ideal para CI)
agente-testes init	Cria .agente-testes/ e entradas no .gitignore do projeto
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

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
fixtures/demo-app/   App HTTP de demonstração (:3000)
scripts/             smoke, demo, hooks de commit
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

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