Documentação / Testes end-to-end (E2E)

Testes end-to-end (E2E)

Entrar

Testes end-to-end (E2E)

Este documento descreve a recomendação de abordagem e os principais fluxos para testes end-to-end (E2E) no Pilot Status.

Objetivo

Use E2E para validar, do ponto de vista do usuário, que a aplicação funciona “de ponta a ponta” com UI + API + banco + filas, cobrindo as integrações internas mais críticas.

E2E não substitui testes unitários e de integração; ele cobre menos cenários, porém com mais confiança no comportamento real do sistema.

Ferramenta recomendada

Recomendação: Playwright.

Motivos:

  • Multi-browser (Chromium/Firefox/WebKit) e modo headless/CI.
  • Artefatos de debug (trace, vídeo, screenshot) e testes mais estáveis em comparação a alternativas.
  • Boa integração com TypeScript e com a arquitetura atual do repo.

Observação: atualmente não existe uma suíte E2E configurada no repositório; este doc é o guia para a configuração e para o escopo recomendado.

Como rodar (estratégia recomendada)

Executar com stack real

Rodar E2E com:

  • Aplicação (UI + API/BFF)
  • Postgres e Redis
  • Worker (se o fluxo depende de filas/reconciliação)

A recomendação é usar Docker Compose para infraestrutura e rodar a aplicação como nos ambientes reais (ou em modo “prod local”, quando isso simplificar URLs e comportamento).

Para banco isolado de teste (apenas Postgres), existe um compose específico: docker-compose.integration.yml.

Gestão de dados (determinismo)

Regras práticas:

  • Comece cada suite com banco limpo e estado conhecido (migrate + seed).
  • Evite depender de dados “de dev” ou resíduos de execuções anteriores.
  • Prefira IDs previsíveis/derivados do seed para navegar na UI.

Se a suíte usar o banco de testes, mantenha a URL separada via variáveis de ambiente de teste (ver doc de integração: testes-integracao.md).

Autenticação (evitar flakiness de OTP)

Como o login via WhatsApp (OTP) depende de um canal externo, a prática recomendada é:

  • Ter um “atalho de teste” habilitado somente em ambiente de E2E (ex.: endpoint interno que cria sessão para um usuário seed).
  • Alternativamente, gerar uma sessão/token via backend e injetar cookie/headers no browser do Playwright.

O objetivo é testar que “usuário autenticado navega e executa fluxos”, sem tornar a suíte dependente do envio/recebimento real de OTP.

Escopo recomendado de fluxos E2E

A lista abaixo é o conjunto de fluxos com melhor custo/benefício para E2E neste projeto. Sugestão: começar pelos P0 (críticos) e só então expandir.

P0 (críticos)

  • Autenticação e sessão: entrar (via atalho de teste), sessão persiste, logout, rota protegida redireciona para login.
  • Onboarding mínimo: criar/selecionar projeto e chegar ao dashboard principal sem erros.
  • API keys: criar API key, listar/revogar e validar efeito imediato no UI.
  • Env TEST vs LIVE: trocar ambiente no painel e confirmar que endpoints/dados mudam conforme esperado.
  • Envio de mensagem (fluxo básico): enviar mensagem no modo TEST e ver status/linha do tempo aparecer no painel.
  • Agendamento: criar mensagem com entrega futura, aparecer como “agendada” e transicionar para enviada/failed depois (depende de worker; contexto: agendamento-mensagens.md).
  • Webhooks (entrega e logs): cadastrar endpoint, disparar evento, registrar WebhookLog; simular falha e validar retry/registro (contexto: webhooks.md).

P1 (alto valor)

  • Templates: criar/editar, publicar/usar em envio, bloquear envio com template inválido, refletir status no painel.
  • Analytics do dashboard: abrir página, carregar métricas principais e validar que filtros/intervalos atualizam gráficos sem quebrar.
  • Limites/uso do plano: exceder limite (quando aplicável) e validar mensagem/estado de bloqueio na UI.
  • Produção por projeto: solicitar aprovação, simular aprovação e validar liberação do ambiente LIVE por projeto.

P2 (pontuais)

  • Conexão WhatsApp real (QR/instância): rodar só em pipeline/manual, pois tende a ser instável e dependente de provedor.
  • Cobrança (Stripe): cobrir em integração com mocks; em E2E, focar no “resultado no sistema” (estado/entitlements) e não no checkout real.

O que evitar em E2E

  • Testar o comportamento de terceiros (Stripe, Evolution, WhatsApp, e-mail) diretamente.
  • Muitos cenários negativos de validação de formulário (melhor em unit/component tests).
  • Dependência de tempo real sem controle (ex.: sleeps longos); prefira polling com timeouts curtos e sinais observáveis.

Convenção sugerida (quando for implementar)

  • Uma suíte E2E por aplicação-alvo:
    • Se o “app canônico” for o fullstack: apps/fullstack/e2e/.
    • Se o fluxo envolver o SPA separado: apps/web/frontend/e2e/ (mantendo o backend sob apps/web/backend).
  • Defina um baseURL por ambiente (local/CI) e injete via variável (ex.: E2E_BASE_URL).
  • Separar “helpers” de seed/login em utilitários compartilhados da suíte.