Framework com Framework1535 palavras

Como usar NestJS com Vitest: Guia Completo

Introdução

Se você trabalha com NestJS há algum tempo, provavelmente já sentiu a dor de esperar uma suíte de testes rodar com Jest. Aquele ciclo de feedback lento que faz você pensar duas vezes antes de escrever mais um teste. A boa notícia: existe uma alternativa madura, rápida e compatível que resolve esse problema. Estou falando do Vitest.

Neste guia, vou mostrar como configurar e usar NestJS com Vitest do zero, com exemplos práticos extraídos de projetos reais. Não é um tutorial superficial. Vamos cobrir desde a configuração inicial até padrões avançados de teste para services, controllers e módulos completos.

Por que usar NestJS com Vitest

O problema de performance do Jest no NestJS

O Jest foi a escolha padrão do ecossistema NestJS desde o início. O próprio CLI do Nest gera projetos configurados com Jest. Porém, à medida que seu projeto cresce para centenas de testes, o tempo de execução se torna um gargalo real.

O Jest utiliza transformação de código via ts-jest ou babel-jest, o que adiciona overhead significativo. Em projetos com 500 ou mais testes, não é raro ver suítes que levam 60 segundos ou mais para rodar.

O que o Vitest traz de diferente

O Vitest é construído sobre o Vite e utiliza esbuild para transformação de TypeScript, o que resulta em execução drasticamente mais rápida. Além disso, o Vitest oferece:

API compatível com Jest (migração simplificada)
Suporte nativo a TypeScript sem configuração adicional
Watch mode inteligente com HMR
Execução paralela eficiente por padrão
Suporte a ESM sem gambiarras

Em projetos reais onde fiz essa migração, observei reduções de 40% a 70% no tempo total da suíte de testes. Em um microserviço com 320 testes, o tempo caiu de 45 segundos para 14 segundos.

Casos de uso onde essa combinação brilha

A dupla NestJS com Vitest se destaca em cenários específicos:

Microserviços com deploy frequente: quando o pipeline de CI roda dezenas de vezes por dia, cada segundo economizado nos testes se multiplica.
Monorepos com múltiplos módulos NestJS: o Vitest lida melhor com workspace configurations e execução seletiva de testes.
Projetos com TDD ativo: o watch mode do Vitest é notavelmente mais responsivo, o que torna o ciclo red/green/refactor mais fluido.
APIs com alta cobertura de testes unitários: quando você tem centenas de testes para services e guards, a diferença de velocidade é perceptível no dia a dia.

Setup do Vitest no NestJS: passo a passo

Instalação das dependências

Primeiro, remova as dependências do Jest e instale o Vitest com seus complementos:

TYPESCRIPT

// Remova as dependências do Jest
// npm uninstall jest ts-jest @types/jest
 
// Instale o Vitest e dependências auxiliares
// npm install -D vitest unplugin-swc @swc/core @vitest/coverage-v8

A escolha do unplugin-swc é intencional. O NestJS depende fortemente de decorators e metadata de reflexão, e o SWC lida com isso de forma confiável, ao contrário do esbuild puro que não suporta emitDecoratorMetadata.

Arquivo de configuração do Vitest

Crie um arquivo vitest.config.ts na raiz do projeto:

TYPESCRIPT

import swc from 'unplugin-swc';
import { defineConfig } from 'vitest/config';
 
export default defineConfig({
  test: {
    globals: true,
    root: './',
    environment: 'node',
    include: ['**/*.spec.ts', '**/*.e2e-spec.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'lcov'],
      exclude: [
        'node_modules/',
        'dist/',
        '**/*.module.ts',
        'main.ts',
      ],
    },
    setupFiles: ['./test/setup.ts'],
  },
  plugins: [
    swc.vite({
      module: { type: 'es6' },
    }),
  ],
});

Arquivo de setup global

Crie o arquivo test/setup.ts para configurações globais:

TYPESCRIPT

import { beforeAll, afterAll } from 'vitest';
 
beforeAll(() => {
  // Configurações globais antes de todos os testes
  process.env.NODE_ENV = 'test';
});
 
afterAll(() => {
  // Limpeza global após todos os testes
});

Ajustes no package.json

Atualize os scripts de teste:

TYPESCRIPT

// No package.json, substitua os scripts:
// "test": "vitest run",
// "test:watch": "vitest",
// "test:cov": "vitest run --coverage",
// "test:e2e": "vitest run --config ./vitest.config.e2e.ts"

Ajuste no tsconfig.json

Adicione os tipos do Vitest para que o TypeScript reconheça as globais:

TYPESCRIPT

// No tsconfig.json, adicione em compilerOptions:
// "types": ["vitest/globals"]

Exemplo prático: testando um Service no NestJS com Vitest

Vamos criar um cenário realista. Imagine um serviço de gerenciamento de pedidos que depende de um repositório e de um serviço de notificações.

O service a ser testado

TYPESCRIPT

// orders.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { OrderRepository } from './order.repository';
import { NotificationService } from '../notifications/notification.service';
import { CreateOrderDto } from './dto/create-order.dto';
import { Order, OrderStatus } from './entities/order.entity';
 
@Injectable()
export class OrdersService {
  constructor(
    private readonly orderRepository: OrderRepository,
    private readonly notificationService: NotificationService,
  ) {}
 
  async create(dto: CreateOrderDto): Promise<Order> {
    const order = await this.orderRepository.save({
      ...dto,
      status: OrderStatus.PENDING,
      createdAt: new Date(),
    });
 
    await this.notificationService.sendOrderConfirmation(
      order.id,
      dto.customerEmail,
    );
 
    return order;
  }
 
  async cancel(orderId: string): Promise<Order> {
    const order = await this.orderRepository.findById(orderId);
 
    if (!order) {
      throw new NotFoundException(
        `Pedido com ID ${orderId} não encontrado`,
      );
    }
 
    if (order.status === OrderStatus.SHIPPED) {
      throw new Error(
        'Não é possível cancelar um pedido já enviado',
      );
    }
 
    order.status = OrderStatus.CANCELLED;
    const updated = await this.orderRepository.save(order);
 
    await this.notificationService.sendOrderCancellation(
      orderId,
      order.customerEmail,
    );
 
    return updated;
  }
}

O teste completo com Vitest

TYPESCRIPT

// orders.service.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { NotFoundException } from '@nestjs/common';
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { OrdersService } from './orders.service';
import { OrderRepository } from './order.repository';
import { NotificationService } from '../notifications/notification.service';
import { OrderStatus } from './entities/order.entity';
 
describe('OrdersService', () => {
  let service: OrdersService;
  let orderRepository: OrderRepository;
  let notificationService: NotificationService;
 
  const mockOrderRepository = {
    save: vi.fn(),
    findById: vi.fn(),
  };
 
  const mockNotificationService = {
    sendOrderConfirmation: vi.fn(),
    sendOrderCancellation: vi.fn(),
  };
 
  beforeEach(async () => {
    vi.clearAllMocks();
 
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        OrdersService,
        {
          provide: OrderRepository,
          useValue: mockOrderRepository,
        },
        {
          provide: NotificationService,
          useValue: mockNotificationService,
        },
      ],
    }).compile();
 
    service = module.get<OrdersService>(OrdersService);
    orderRepository = module.get<OrderRepository>(OrderRepository);
    notificationService = module.get<NotificationService>(
      NotificationService,
    );
  });
 
  describe('create', () => {
    it('deve criar um pedido com status PENDING', async () => {
      const dto = {
        customerEmail: '[email protected]',
        items: [{ productId: 'prod-1', quantity: 2 }],
      };
 
      const savedOrder = {
        id: 'order-123',
        ...dto,
        status: OrderStatus.PENDING,
        createdAt: new Date(),
      };
 
      mockOrderRepository.save.mockResolvedValue(savedOrder);
      mockNotificationService.sendOrderConfirmation.mockResolvedValue(
        undefined,
      );
 
      const result = await service.create(dto);
 
      expect(result).toEqual(savedOrder);
      expect(mockOrderRepository.save).toHaveBeenCalledWith(
        expect.objectContaining({
          status: OrderStatus.PENDING,
          customerEmail: '[email protected]',
        }),
      );
    });
 
    it('deve enviar notificação de confirmação após criar pedido', async () => {
      const dto = {
        customerEmail: '[email protected]',
        items: [{ productId: 'prod-1', quantity: 1 }],
      };
 
      mockOrderRepository.save.mockResolvedValue({
        id: 'order-456',
        ...dto,
        status: OrderStatus.PENDING,
      });
 
      await service.create(dto);
 
      expect(
        mockNotificationService.sendOrderConfirmation,
      ).toHaveBeenCalledWith('order-456', '[email protected]');
    });
  });
 
  describe('cancel', () => {
    it('deve lançar NotFoundException quando pedido não existe', async () => {
      mockOrderRepository.findById.mockResolvedValue(null);
 
      await expect(
        service.cancel('inexistente'),
      ).rejects.toThrow(NotFoundException);
    });
 
    it('deve lançar erro ao cancelar pedido já enviado', async () => {
      mockOrderRepository.findById.mockResolvedValue({
        id: 'order-789',
        status: OrderStatus.SHIPPED,
        customerEmail: '[email protected]',
      });
 
      await expect(service.cancel('order-789')).rejects.toThrow(
        'Não é possível cancelar um pedido já enviado',
      );
    });
 
    it('deve cancelar pedido pendente com sucesso', async () => {
      const existingOrder = {
        id: 'order-101',
        status: OrderStatus.PENDING,
        customerEmail: '[email protected]',
      };
 
      const cancelledOrder = {
        ...existingOrder,
        status: OrderStatus.CANCELLED,
      };
 
      mockOrderRepository.findById.mockResolvedValue(
        existingOrder,
      );
      mockOrderRepository.save.mockResolvedValue(cancelledOrder);
 
      const result = await service.cancel('order-101');
 
      expect(result.status).toBe(OrderStatus.CANCELLED);
      expect(
        mockNotificationService.sendOrderCancellation,
      ).toHaveBeenCalledWith('order-101', '[email protected]');
    });
  });
});

Observe que a estrutura do teste é praticamente idêntica ao que você faria com Jest. A diferença principal está no uso de vi.fn() no lugar de jest.fn() e na importação explícita das funções do Vitest quando não se usa o modo globals.

Exemplo prático: testando um Controller com Guards

TYPESCRIPT

// orders.controller.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { OrdersController } from './orders.controller';
import { OrdersService } from './orders.service';
import { AuthGuard } from '../auth/auth.guard';
import { OrderStatus } from './entities/order.entity';
 
describe('OrdersController', () => {
  let controller: OrdersController;
 
  const mockOrdersService = {
    create: vi.fn(),
    cancel: vi.fn(),
    findAll: vi.fn(),
  };
 
  beforeEach(async () => {
    vi.clearAllMocks();
 
    const module: TestingModule = await Test.createTestingModule({
      controllers: [OrdersController],
      providers: [
        {
          provide: OrdersService,
          useValue: mockOrdersService,
        },
      ],
    })
      .overrideGuard(AuthGuard)
      .useValue({ canActivate: () => true })
      .compile();
 
    controller = module.get<OrdersController>(OrdersController);
  });
 
  describe('findAll', () => {
    it('deve retornar lista de pedidos do usuário', async () => {
      const orders = [
        {
          id: 'order-1',
          status: OrderStatus.PENDING,
          customerEmail: '[email protected]',
        },
        {
          id: 'order-2',
          status: OrderStatus.SHIPPED,
          customerEmail: '[email protected]',
        },
      ];
 
      mockOrdersService.findAll.mockResolvedValue(orders);
 
      const mockRequest = {
        user: { id: 'user-1', email: '[email protected]' },
      };
 
      const result = await controller.findAll(mockRequest);
 
      expect(result).toHaveLength(2);
      expect(mockOrdersService.findAll).toHaveBeenCalledTimes(1);
    });
  });
 
  describe('create', () => {
    it('deve delegar criação ao service e retornar o pedido', async () => {
      const dto = {
        customerEmail: '[email protected]',
        items: [{ productId: 'p1', quantity: 3 }],
      };
 
      const createdOrder = {
        id: 'order-new',
        ...dto,
        status: OrderStatus.PENDING,
      };
 
      mockOrdersService.create.mockResolvedValue(createdOrder);
 
      const result = await controller.create(dto);
 
      expect(result.id).toBe('order-new');
      expect(result.status).toBe(OrderStatus.PENDING);
    });
  });
});

Boas práticas para NestJS com Vitest

Use vi.clearAllMocks() no beforeEach

Sempre limpe os mocks entre os testes. Isso evita vazamento de estado entre casos de teste e é a causa número um de testes que passam isolados mas falham quando executados em conjunto.

Separe configurações de teste e2e

Crie um arquivo vitest.config.e2e.ts separado para testes de integração. Testes e2e geralmente precisam de timeouts maiores e configurações específicas de ambiente:

TYPESCRIPT

// vitest.config.e2e.ts
import swc from 'unplugin-swc';
import { defineConfig } from 'vitest/config';
 
export default defineConfig({
  test

Guias Relacionados

Como usar Angular com Vitest: Guia Completo Como usar NestJS com Prisma: Guia Completo Como usar NestJS com TypeORM: Guia Completo Como usar NestJS com Zod: Guia Completo

Explore mais guias técnicos

Mais de 100 guias práticos de integração entre frameworks, ferramentas e plataformas.

Ver todos os guias