Vitest

Vitest oferece execuções de testes TypeScript rápidas, modo de observação, mocking e cobertura para backends Node que superam o node:test básico.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

npm install -D vitest @vitest/coverage-v8

// vitest.config.ts
import { defineConfig } from "vitest/config";
 
export default defineConfig({
  test: {
    environment: "node",
    include: ["test/**/*.test.ts", "src/**/*.test.ts"],
    coverage: { provider: "v8", reporter: ["text", "lcov"] },
  },
});

{ "scripts": { "test": "vitest run", "test:watch": "vitest" } }

Quando usar isso:

• Uso intensivo de vi.mock() para APIs e bancos de dados externos.
• Modo de observação durante TDD em serviços TypeScript.
• Limiares de cobertura em CI.

Exemplo de Trabalho

// src/users/client.ts
export async function fetchUser(id: string): Promise<{ id: string; name: string }> {
  const res = await fetch(`https://api.example.com/users/${id}`);
  if (!res.ok) throw new Error("erro upstream");
  return res.json() as Promise<{ id: string; name: string }>;
}

// test/users/client.test.ts
import { afterEach, describe, expect, it, vi } from "vitest";
 
import { fetchUser } from "../../src/users/client.js";
 
afterEach(() => vi.restoreAllMocks());
 
describe("fetchUser", () => {
  it("retorna o json do usuário", async () => {
    vi.stubGlobal(
      "fetch",
      vi.fn().mockResolvedValue({
        ok: true,
        json: async () => ({ id: "1", name: "Ada" }),
      }),
    );
 
    await expect(fetchUser("1")).resolves.toEqual({ id: "1", name: "Ada" });
  });
});

# CI
- run: npm run test -- --coverage

O que isso demonstra:

• vi.stubGlobal substitui fetch sem refatoração de injeção de dependência.
• vitest run para passagem única para CI; vitest observa localmente.
• A cobertura V8 se integra com Codecov/Sonar.

Mergulho Profundo

Como Funciona

• Vitest usa o pipeline de transformação do Vite para transpilação rápida de TS (esbuild/swc).
• Compatível com a API semelhante ao Jest (describe, it, expect, vi).
• environment: "node" evita jsdom, a menos que esteja testando o DOM.
• Threads de pool executam arquivos de teste em paralelo.

Dicas de Configuração

Notas TypeScript

• vitest/config tipa defineConfig.
• Aliases de caminho do tsconfig podem ser conectados via plugin vite-tsconfig-paths, se necessário.

Armadilhas

• Misturar Vitest e node:test - Dois runners confundem os contribuidores. Correção: escolha um por repositório ou por pacote em um monorepo.
• Mocking de módulos ESM - Problemas de hoisting com vi.mock. Correção: use a fábrica vi.mock e importações dinâmicas após o mock.
• Testes de integração no pool padrão - Condições de corrida de banco de dados. Correção: vitest.integration.config.ts separado com fileParallelism: false.
• Cobertura em código apenas de ramificação - Falsa confiança. Correção: combine cobertura com testes de mutação ou asserções de comportamento com moderação.
• Instabilidade de Snapshot - Ruído de PR grande. Correção: prefira toEqual explícito em campos estáveis.

Alternativas

FAQs

vi.mock("../src/db.js", () => ({ query: vi.fn() }));

coverage: { thresholds: { lines: 80, functions: 80 } }

Relacionado

• node:test & node:assert - alternativa de dependência zero
• Supertest & Integração HTTP - testes HTTP
• Melhores Práticas de Teste - comportamento sobre implementação

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.