Skip to content

Plano de Testes

jota edited this page Aug 25, 2026 · 1 revision

Plano de Testes

⬅ Voltar para Documentação de Arquitetura


Estratégia de Testabilidade

A testabilidade é um conceito transversal crítico no QuaLeiDer, garantindo que o sistema seja mantível, confiável e evolua com segurança.

Princípios de Design para Testabilidade

1. Dependency Injection (DI)

  • 100% dos serviços utilizam DI via NestJS
  • Permite substituição de dependências por mocks/stubs em testes
  • Exemplo: MailService pode ser substituído por MockMailService em testes

Dependency Injection

2. Ports & Adapters (Hexagonal Architecture)

  • Interfaces claramente definidas entre camadas
  • Camada de Application independente de infraestrutura
  • Exemplo: Interface IUserRepository implementada por PrismaUserRepository em produção e InMemoryUserRepository em testes

Ports & Adapters Pattern

O padrão Ports & Adapters isola a lógica de negócio (núcleo) das preocupações de infraestrutura através de interfaces bem definidas:

  • Ports (Interfaces): Contratos que definem "o quê" o sistema precisa

    • Repository Port: Interface para acesso a dados
    • HTTP Port: Endpoints de entrada (Controllers)
    • Email Port: Interface para envio de emails
  • Adapters (Implementações): Traduzem entre o mundo externo e o núcleo

    • Inbound: InvitesController recebe requisições HTTP
    • Outbound: PrismaService (PostgreSQL), MailService (Nodemailer)

Benefícios:

  • Testabilidade: Services testados com mocks (ex: MockMailService substitui MailService em testes)
  • Independência: Trocar Nodemailer por SendGrid afeta apenas 1 arquivo
  • Manutenibilidade: Lógica de negócio isolada de frameworks

3. Separation of Concerns

  • DTOs separam validação de entrada da lógica de negócio
  • Services contêm apenas lógica de negócio (sem detalhes de HTTP ou Database)
  • Controllers são finos, delegando toda lógica para Services

Separation of Concerns

O princípio de Separation of Concerns divide responsabilidades em camadas distintas:

  • Presentation (Controllers): Apenas recebe requisições HTTP e delega para Services
  • Application (Services): Contém toda lógica de negócio, sem conhecimento de HTTP ou Database
  • Domain (Entities): Regras de negócio puras, validações de domínio
  • Infrastructure (Prisma, Mail): Detalhes técnicos de implementação

Benefícios:

  • Cada camada pode ser testada isoladamente
  • Mudanças em uma camada não afetam outras
  • Código mais legível e organizado

Estrutura de Testes

tests/
├── unit/                          # Testes unitários (459 testes)
│   ├── application/
│   │   ├── dtos/                 # Validação de DTOs (100% cobertura)
│   │   └── services/             # Lógica de negócio (100%+ cobertura)
│   ├── domain/
│   │   ├── entities/             # Regras de domínio (100% cobertura)
│   │   └── enums/
│   └── presentation/
│       └── controllers/          # Endpoints HTTP (100% cobertura)
├── e2e/                           # Testes end-to-end (97 testes)
│   ├── auth/                     # Login, Reset de Senha
│   ├── users/                    # CRUD de Usuários
│   ├── animals/                  # CRUD de Animais
│   ├── daily-collections/        # CRUD de Coletas
│   ├── invites/                  # Sistema de Convites
│   ├── associations/             # CRUD de Associações
│   ├── factories/                # Test Factories para dados de teste
│   └── helpers/                  # Helpers para autenticação e setup
├── mocks/                         # Mocks reutilizáveis
└── factories/                     # Factories para geração de dados

Test Factories Pattern

O padrão Test Factories abstrai a complexidade da criação de dados de teste, atuando como uma "linha de montagem" configurável

  • Criação centralizada e consistente de objetos complexos

  • Flexibilidade através de sobreposições (overrides)

Factory Pattern

  • Factory: Responsável por instanciar o objeto e gerenciar regras de criação

  • Default Values: Dados pré-definidos que garantem que o objeto gerado seja sempre válido para o banco de dados

  • Overrides: Mecanismo que permite ao teste injetar apenas os dados específicos que importam para aquele cenário (ex: { hat: true } ou { age: 17 }), sobrescrevendo os padrões.

  • Specialized Methods: Atalhos para configurações frequentes de negócio, como buildAdmin() ou buildProducer().

// Exemplo: AnimalFactory
AnimalFactory.buildVaca(); // Vaca com dados padrão
AnimalFactory.buildCabra(); // Cabra
AnimalFactory.build({ age: 5 }); // Animal personalizado

Benefícios:

  • O código de teste foca no comportamento, não na configuração de dados
  • Se uma entidade ganha um novo campo obrigatório, você atualiza apenas a Factory, sem quebrar centenas de testes
  • Todos os testes partem de uma base de dados válida e controlada

Estratégias de Mock & Isolamento

1. Mocks de Serviços Externos

  • MailService: Mock para evitar envio de emails reais em testes
  • PrismaService: Mock para testes unitários de services

Mock External Services

2. Test Doubles

  • Stubs: Retornam dados pré-definidos (ex: findById() retorna usuário fixo)
  • Spies: Verificam se métodos foram chamados com argumentos corretos
  • Mocks: Simulam comportamento completo de dependências

Test Doubles

3. Database em Testes E2E

  • Database real (PostgreSQL) isolado para testes
  • Setup/Teardown automático entre testes
  • Transações rollback para garantir isolamento

Test Database E2E

Padrões de Nomenclatura

Testes em português seguindo convenção "deve...":

describe('E2E: Animais - Operações CRUD', () => {
  describe('POST /animals (Criar)', () => {
    it('deve criar um novo animal com dados válidos', ...)
    it('deve retornar 404 com userId inexistente', ...)
    it('deve retornar 400 com dados inválidos', ...)
  })
})

Benefícios:

  • Testes funcionam como documentação viva em português
  • Facilitam compreensão por desenvolvedores brasileiros
  • Mensagens de erro claras ao executar testes

Métricas e Metas

Métrica Meta Atual Status
Cobertura Geral > 80% 96.25% ✅
Cobertura DTOs 100% 100% ✅
Cobertura Services > 90% 100% ✅
Cobertura Controllers > 90% 100% ✅
Testes Unitários > 300 457 ✅
Testes E2E > 80 110 ✅
Testes Arquiteturais 100% 100% ✅
Tempo Exec. Unit < 60s 50s ✅
Tempo Exec. E2E < 120s 90s ✅
Taxa de Sucesso 100% 100% ✅

Processo de CI/CD

1. Validação Pré-Commit

  • Linter (ESLint) valida padrões de código
  • Prettier formata código automaticamente

2. Pipeline de Testes

  • Testes unitários executados primeiro (rápido feedback)
  • Testes E2E executados se unitários passarem
  • Cobertura validada (bloqueia merge se < 80%)

3. Proteção de Branches

  • Pull Requests requerem 100% dos testes passando
  • Cobertura não pode diminuir
  • Review de código obrigatório

Boas Práticas Adotadas

  1. AAA Pattern (Arrange-Act-Assert): Estrutura clara em todos os testes
  2. Test Isolation: Cada teste independente (sem ordem de execução)
  3. Single Responsibility: Um teste valida um comportamento
  4. Meaningful Names: Nomes descritivos em português

8.5 Proteção Automatizada com Git Hooks

Objetivo

Prevenir que código não testado ou com falhas chegue ao repositório remoto através de validações automáticas locais executadas antes de commits e pushes.

Implementação

Ferramenta: Husky v9.1.7
Localização: backend/.husky/
Configuração: Git hooks path configurado automaticamente via npm run prepare

Hooks Configurados

Pre-commit:

  • Trigger: Executado antes de finalizar cada commit
  • Comando: npm run test:unit -- --bail --passWithNoTests
  • Validação: Testes unitários (459 testes)
  • Tempo médio: 45 segundos
  • Comportamento: Bloqueia commit se algum teste falhar
  • Objetivo: Feedback imediato sobre falhas antes de salvar alterações

Pre-push:

  • Trigger: Executado antes de enviar commits ao repositório remoto
  • Comandos:
    npm run test:unit      # 459 testes unitários
    npm run test:e2e       # 110 testes E2E
  • Tempo médio: 2 minutos (testes completos)
  • Comportamento: Bloqueia push se qualquer teste falhar
  • Objetivo: Última validação local antes de código chegar ao repositório

Fluxo de Validação

Desenvolvedor faz alteração
         ↓
    git add .
         ↓
   git commit -m "..."
         ↓
   [PRE-COMMIT HOOK]
   → Executa testes unitários
   → ✅ Passa: Commit criado
   → ❌ Falha: Commit bloqueado
         ↓
    git push origin main
         ↓
   [PRE-PUSH HOOK]
   → Executa testes unitários + E2E
   → ✅ Passa: Push realizado
   → ❌ Falha: Push bloqueado
         ↓
   [GITHUB ACTIONS]
   → Validação de cobertura (80%)
   → Build e testes no servidor

Bypass de Hooks (Não Recomendado)

Em situações excepcionais (emergências, hotfixes urgentes), é possível ignorar hooks:

# Ignorar pre-commit
git commit --no-verify

# Ignorar pre-push
git push --no-verify

⚠️ Atenção: Usar apenas quando absolutamente necessário. O código ainda será validado pelo GitHub Actions, mas o feedback será mais tardio.

Integração com Monorepo

Como o projeto possui estrutura monorepo (qualeider/ contém backend/ e frontend/), os hooks são configurados para:

  1. Executar a partir do diretório correto (cd backend)
  2. Rodar comandos npm do projeto backend
  3. Configuração do Git: core.hooksPath = backend/.husky

Benefícios da Abordagem

  1. Feedback Imediato: Desenvolvedores descobrem falhas em segundos, não minutos
  2. Economia de CI/CD: Menos execuções no GitHub Actions (falhas detectadas localmente)
  3. Qualidade Consistente: Impossível commitar código quebrado acidentalmente
  4. Cultura de Qualidade: Reforça importância de testes na equipe
  5. Produtividade: Evita ciclos de "commit → push → CI falha → fix → repeat"

Limitações Conhecidas

O modelo de domínio do QuaLeiDer representa as entidades principais do sistema e seus relacionamentos, refletindo as regras de negócio da gestão de produtores de leite.

Class diagram UML

Clone this wiki locally