Repository navigation
Plano de Testes
⬅ Voltar para Documentação de Arquitetura
A testabilidade é um conceito transversal crítico no QuaLeiDer, garantindo que o sistema seja mantível, confiável e evolua com segurança.
1. Dependency Injection (DI)
- 100% dos serviços utilizam DI via NestJS
- Permite substituição de dependências por mocks/stubs em testes
- Exemplo:
MailServicepode ser substituído porMockMailServiceem testes

2. Ports & Adapters (Hexagonal Architecture)
- Interfaces claramente definidas entre camadas
- Camada de Application independente de infraestrutura
- Exemplo: Interface
IUserRepositoryimplementada porPrismaUserRepositoryem produção eInMemoryUserRepositoryem testes

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:
InvitesControllerrecebe requisições HTTP - Outbound:
PrismaService(PostgreSQL),MailService(Nodemailer)
- Inbound:
Benefícios:
- Testabilidade: Services testados com mocks (ex:
MockMailServicesubstituiMailServiceem 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

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
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
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: 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 personalizadoBenefí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
1. Mocks de Serviços Externos
-
MailService: Mock para evitar envio de emails reais em testes -
PrismaService: Mock para testes unitários de 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

3. Database em Testes E2E
- Database real (PostgreSQL) isolado para testes
- Setup/Teardown automático entre testes
- Transações rollback para garantir isolamento

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é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% | ✅ |
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
- AAA Pattern (Arrange-Act-Assert): Estrutura clara em todos os testes
- Test Isolation: Cada teste independente (sem ordem de execução)
- Single Responsibility: Um teste valida um comportamento
- Meaningful Names: Nomes descritivos em português
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.
Ferramenta: Husky v9.1.7
Localização: backend/.husky/
Configuração: Git hooks path configurado automaticamente via npm run prepare
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
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
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-verifyComo o projeto possui estrutura monorepo (qualeider/ contém backend/ e frontend/), os hooks são configurados para:
- Executar a partir do diretório correto (
cd backend) - Rodar comandos npm do projeto backend
- Configuração do Git:
core.hooksPath = backend/.husky
- Feedback Imediato: Desenvolvedores descobrem falhas em segundos, não minutos
- Economia de CI/CD: Menos execuções no GitHub Actions (falhas detectadas localmente)
- Qualidade Consistente: Impossível commitar código quebrado acidentalmente
- Cultura de Qualidade: Reforça importância de testes na equipe
- Produtividade: Evita ciclos de "commit → push → CI falha → fix → repeat"
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.
