Documentação / Guia de Testes Locais — Pilot Status

Guia de Testes Locais — Pilot Status

Entrar

Guia de Testes Locais — Pilot Status

Objetivo: garantir que tudo seja testado localmente antes de subir para produção.

Repositórios envolvidos:

  • pilot-status-nextjs-typescript-frontend-backend — monorepo principal (app + worker)
  • evolution-api — provedor Evo V2 (Node.js)
  • evolution-api-go — provedor Evo Go (Go)

1. Arquitetura de Infraestrutura Local

1.1 Serviços Docker

O ambiente local é composto por 7 serviços definidos nos docker-compose files:

| Serviço | Imagem | Porta | Função | |---------|--------|-------|--------| | postgres | postgres:15-alpine | 5432 | Banco de dados principal | | redis | redis:7-alpine | 6379 | Cache + filas BullMQ | | rabbitmq | rabbitmq:3-management-alpine | 5672 / 15672 | Mensageria AMQP (webhooks Evolution) | | evolution-api-v2 | build local | 8080 | Provedor Evo V2 — conecta instâncias WhatsApp | | evolution-go | build local | 4000 | Provedor Evo Go — conecta instâncias WhatsApp | | web-fullstack-dev | Next.js dev server | 3000 | App principal (API + SPA) | | worker-dev | BullMQ worker | — | Background jobs (envio de mensagens, healthchecks) |

1.2 Docker Compose Files

| File | Uso | |------|-----| | docker/docker-compose.dev.yml | Ambiente de desenvolvimento — hot reload, sem Evolution providers | | docker/docker-compose.yml | Dev com Evolution — inclui evolution-api-v2 e evolution-go | | docker/docker-compose.integration.yml | Testes de integração — DB/Redis/RabbitMQ separados em portas test (55432, 16379, 5673) | | docker/docker-compose.prod.yml | Simulação de produção local — imagens buildadas com Dockerfile.prod / apps/worker/Dockerfile |

1.3 Monorepo Workspaces

apps/fullstack    → Next.js 15 (API routes + SPA frontend)
apps/worker       → BullMQ background worker (ESM)
packages/database → Prisma schema + migrations
packages/shared   → Utilitários compartilhados (OTel, AI, types)
packages/whatsapp-provider → Abstração de provedor WhatsApp (v2 + Go)
packages/plan-constants → Constantes de planos

2. O Que Pode Ser Automatizado vs Manual

2.1 Automatizado (100% sem intervenção humana)

| Camada | Teste | Como | |--------|-------|------| | Unitários | *.test.ts | npm run push:checks — roda todos os workspaces | | Integração DB | *.integration.test.ts | docker compose -f docker/docker-compose.integration.yml up -d + npm run test:backend:integration | | Build | TypeScript compilation | npm --workspace <ws> run build | | Lint | ESLint | Incluído no push:checks | | E2E Playwright (UI) | Navegação, onboarding | npx playwright test — sem QR code | | API Routes | Health, auth, templates, messages | Integração com DB real, mocks de WhatsApp | | Dispatch de webhook | 13 eventos via /api/internal/webhook | Script interativo — payloads simulados | | Login OTP | Fluxo de login via WhatsApp | Playwright — e2e/onboarding.spec.ts |

2.2 Manual (requer intervenção humana)

| Ação | Por quê | Frequência | |------|---------|-----------| | Scan QR Code — Evo V2 | Conectar instância WhatsApp no provedor v2 | Toda vez que o volume evolution_api_instances é limpo | | Scan QR Code — Evo Go | Conectar instância WhatsApp no provedor Go | Toda vez que a sessão expira | | Login Google/GitHub | OAuth requer autorização no navegador | Uma vez por sessão | | Conectar instância "Pilot Status" | A instância do próprio sistema precisa estar conectada | Sempre que o QR code expira | | Validar envio real de mensagem | Confirmar que a mensagem chega no WhatsApp do usuário | Antes de cada deploy de produção | | Testar fallback entre provedores | Trocar EVOLUTION_PRIMARY_PROVIDER entre v2 e go | Antes de deploy que toca na lógica de dual provider | | Testar leitura de mensagem | Ler mensagem no celular para gerar evento "read" | Quando testando eventos de status | | Enviar mensagem para instância | Gerar webhook inbound (message.received) | Quando testando recebimento |

2.3 Estratégia: Minimizar o Manual

Para evitar ter que escanear QR code a cada sessão:

  1. Persistir o volume evolution_api_instances — as sessões Baileys ficam salvas. Se o volume não é deletado, a sessão WhatsApp persiste entre restarts do container.
  2. CONNECT_ON_STARTUP: "false" no Evo Go — evita reconexão automática que pode invalidar sessões.
  3. Testar com mock — a maioria dos testes de integração mocka o WhatsApp provider. Só os testes E2E de envio real precisam de instância conectada.
  4. Script interativo — bash scripts/interactive-provider-test.sh guia todos os passos com confirmação manual a cada seção.

3. Fluxo Completo de Testes Locais

3.1 Passo 1 — Infraestrutura de Testes

# Subir DB, Redis e RabbitMQ dedicados para testes
docker compose -f docker/docker-compose.integration.yml up -d

# Verificar saúde dos serviços
docker compose -f docker/docker-compose.integration.yml ps

Isso sobe:

  • postgres-test na porta 55432 (DB pilot_status_test)
  • redis-test na porta 16379
  • rabbitmq-test na porta 5673

3.2 Passo 2 — Testes Unitários (sem Docker)

# Roda todos os unit tests de todos os workspaces
npm run test:backend:unit
# Equivale a:
# npm --workspace @pilot-status/fullstack run test:backend:unit
# npm --workspace @pilot-status/worker run test:backend:unit

O que é testado:

  • Lógica de domínio (sem DB)
  • Funções utilitárias
  • Configuração do WhatsApp provider
  • Proxy fetch logic
  • Erros e validações

3.3 Passo 3 — Testes de Integração (com Docker)

# Garantir que a infra de teste está rodando
docker compose -f docker/docker-compose.integration.yml up -d

# Rodar todos os testes de integração
npm run test:backend:integration

O que é testado:

  • API routes com DB real (Postgres 55432)
  • Cache com Redis real (porta 16379)
  • Auth via NextAuth com session mocking
  • Templates, mensagens, checkout, webhooks Stripe/Pdev
  • Dual ingestion
  • Health checks

Arquitetura dos testes de integração:

  • globalSetup.ts — faz prisma migrate reset --force --skip-seed (destrutivo)
  • setup.ts — mocka auth, cache, queue, pushover, WhatsApp
  • db.ts — resetDb(), seedTenant(), seedUser(), seedProject()
  • Cada teste faz resetDb() antes de rodar para isolamento

3.4 Passo 4 — Ambiente Dev Completo (com Evolution)

# Subir tudo: DB + Redis + RabbitMQ + Evolution V2 + Go + App + Worker
npm run dev:docker:compose

Isso usa docker/docker-compose.dev.yml que sobe:

  • Postgres (5432), Redis (6379), RabbitMQ (5672)
  • Evolution API V2 (8080) — build local a partir de evolution-api
  • Evolution Go (4000) — build local a partir de evolution-api-go
  • Web Fullstack Dev (3000) — hot reload via volumes montados
  • Worker Dev — hot reload

Após subir, conectar as instâncias manualmente:

# Verificar se o Evo V2 está rodando
curl http://localhost:8080/api/health

# Verificar se o Evo Go está rodando
curl http://localhost:4000/health

# Obter QR code da instância V2 — escanear com WhatsApp no celular
curl -X POST http://localhost:8080/api/instance/connect/PilotStatusAsh \
  -H "x-api-key: +5511967435133"

# Para Evo Go, o QR code aparece nos logs ao iniciar a instância
docker logs ps-evolution-go-dev | grep -i qrcode

3.5 Passo 5 — Testes E2E Playwright

# Configurar a URL base
export PLAYWRIGHT_TEST_BASE_URL=http://localhost:3000

# Rodar todos os testes E2E
npx playwright test

# Rodar headed (com navegador visível) — já é o padrão
npx playwright test --headed

# Rodar um teste específico
npx playwright test onboarding.spec.ts

Testes E2E atuais:

  • homepage.spec.ts — navegação externa (ismaelnascimento.com)
  • onboarding.spec.ts — fluxo de login com WhatsApp OTP + onboarding page

O que o Playwright testa:

  • Login com WhatsApp (envio de código OTP)
  • Navegação de onboarding
  • Screenshots automáticos em caso de falha

3.6 Passo 6 — Teste de Envio Real de Mensagem

# Com a instância conectada, testar envio via API interna
curl -X POST http://localhost:3000/api/internal/messages/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <INTERNAL_WEBHOOK_SECRET>" \
  -d '{
    "phone": "5585936180633",
    "message": "Teste de envio local",
    "provider": "v2"
  }'

# Testar com provedor Go
curl -X POST http://localhost:3000/api/internal/messages/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <INTERNAL_WEBHOOK_SECRET>" \
  -d '{
    "phone": "5585936180633",
    "message": "Teste de envio via Go",
    "provider": "go"
  }'

3.7 Passo 7 — Simulação de Produção Local

# Build e subir como produção (imagens otimizadas)
npm run prod:docker

Isso usa docker/docker-compose.prod.yml que:

  • Build com Dockerfile.prod (Next.js standalone output)
  • Build com apps/worker/Dockerfile (worker otimizado)
  • EVOLUTION_PRIMARY_PROVIDER: go (diferente do dev que é v2)
  • OTel habilitado para observabilidade
  • Sem hot reload — simula o ambiente real

Verificar saúde:

curl http://localhost:3000/api/health
docker compose --env-file .env.development --env-file docker/.env.prod -f docker/docker-compose.prod.yml ps

4. Testes dos Provedores Evolution

4.1 Evolution API V2 (Node.js)

cd /home/oismaelash/workspace/Pilot-Status-Workspace/evolution-api

# Build local
npm run build

# Testes (se disponíveis)
npm test

Testar conexão local:

# Health check
curl http://localhost:8080/api/health

# Listar instâncias
curl http://localhost:8080/api/instance/getInstances \
  -H "x-api-key: +5511967435133"

# Status da instância
curl http://localhost:8080/api/instance/status/PilotStatusAsh \
  -H "x-api-key: +5511967435133"

4.2 Evolution Go (Go)

cd /home/oismaelash/workspace/Pilot-Status-Workspace/evolution-api-go

# Testes Go
go test ./...

# Build
make build

Testar conexão local:

# Health check
curl http://localhost:4000/health

# Criar/verificar instância
curl http://localhost:4000/instance \
  -H "Authorization: Bearer +5511967435133"

4.3 Testar Fallback entre Provedores

# No .env.development, alternar:
# EVOLUTION_PRIMARY_PROVIDER=v2   → usa Evo V2 como primário
# EVOLUTION_PRIMARY_PROVIDER=go    → usa Evo Go como primário

# Testar que o sistema funciona com ambos
# 1. Conectar instância no V2 → testar envio
# 2. Conectar instância no Go → testar envio
# 3. Desconectar V2 → verificar se Go assume
# 4. Desconectar Go → verificar se V2 assume

5. Pre-Push Checks (Gate de Qualidade)

# Roda tudo antes de push
npm run push:check

Ordem de execução:

  1. whatsapp-provider build
  2. whatsapp-provider tests
  3. plan-constants tests
  4. shared build
  5. shared tests
  6. fullstack build
  7. fullstack unit tests
  8. fullstack integration tests
  9. fullstack integration cache tests
  10. worker build
  11. worker unit tests
  12. worker integration tests

6. Checklist Pré-Produção

Antes de fazer deploy para produção, execute este checklist:

6.1 Automatizado

  • [ ] npm run push:check — todos os checks passaram
  • [ ] npm run test:backend:all — unit + integration sem falhas
  • [ ] npx playwright test — E2E passaram
  • [ ] npm run prod:docker — build de produção funciona
  • [ ] curl http://localhost:3000/api/health — health OK em modo prod

6.2 Manual

  • [ ] Instância WhatsApp conectada (QR code escaneado)
  • [ ] Mensagem de teste enviada via V2 — chegou no WhatsApp
  • [ ] Mensagem de teste enviada via Go — chegou no WhatsApp
  • [ ] Fallback entre provedores testado
  • [ ] Worker processando jobs (verificar logs)
  • [ ] RabbitMQ recebendo eventos (http://localhost:15672)

6.3 Verificação Final

# Verificar logs do worker
docker logs ps-worker-dev --tail 50

# Verificar logs do app
docker logs ps-web-backend-dev --tail 50

# Verificar RabbitMQ queues
curl http://localhost:15672/api/queues -u pilot:pilot

# Verificar instâncias Evolution
curl http://localhost:8080/api/instance/getInstances -H "x-api-key: +5511967435133"
curl http://localhost:4000/instance -H "Authorization: Bearer +5511967435133"

7. Resumo: O Que Testar e Como

| Componente | Tipo | Método | Infra Necessária | |-----------|------|--------|-----------------| | Domain logic | Unit | Vitest | Nenhuma | | API routes | Unit | Vitest | Nenhuma | | DB queries | Integration | Vitest + Postgres | docker/docker-compose.integration.yml | | Cache | Integration | Vitest + Redis | docker/docker-compose.integration.yml | | Worker jobs | Integration | Vitest + BullMQ | docker/docker-compose.integration.yml | | RabbitMQ consumer | Integration | Vitest + RabbitMQ | docker/docker-compose.integration.yml | | UI navigation | E2E | Playwright | App rodando em :3000 | | Login flow | E2E | Playwright | App rodando em :3000 | | WhatsApp connect | Manual | QR Code scan | Evolution + celular | | Message send | Manual | curl / UI | Instância conectada | | Provider fallback | Manual | Trocar env var | Ambos os provedores | | Production build | Build | prod:docker | Docker |

8. Comandos Rápidos de Referência

# === Setup Inicial ===
npm install
npm run dev:docker:compose          # sobe tudo com hot reload

# === Testes ===
npm run push:check                   # gate de qualidade completo
npm run test:backend:unit            # unit apenas
npm run test:backend:integration     # integration apenas
npx playwright test                  # E2E

# === Infra ===
docker compose -f docker/docker-compose.integration.yml up -d    # infra de teste
docker compose -f docker/docker-compose.integration.yml down      # derrubar infra de teste

# === DB ===
npm run db:reset                   # reset DB dev
npm run db:reset:prod              # reset DB prod

# === Produção Local ===
npm run prod:docker                # subir como produção
npm run prod:docker:down           # derrubar produção

# === Logs ===
docker logs ps-web-backend-dev -f  # app logs
docker logs ps-worker-dev -f       # worker logs
docker logs ps-evolution-api-v2-dev -f  # Evo V2 logs
docker logs ps-evolution-go-dev -f    # Evo Go logs