Vitest

Vitest proporciona ejecuciones rápidas de pruebas de TypeScript, modo de observación, mocking y cobertura para backends de Node que superan las capacidades de node:test puro.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

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" } }

Cuándo usarlo:

• Uso intensivo de vi.mock() para APIs externas y bases de datos.
• Modo de observación durante TDD en servicios TypeScript.
• Umbrales de cobertura en CI.

Ejemplo de funcionamiento

// 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("upstream error");
  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("returns user json", 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

Lo que esto demuestra:

• vi.stubGlobal reemplaza fetch sin refactorización de inyección de dependencias.
• vitest run una sola pasada para CI; vitest en modo de observación localmente.
• La cobertura V8 se integra con Codecov/Sonar.

Análisis profundo

Cómo funciona

• Vitest utiliza el pipeline de transformación de Vite para una transpilación rápida de TS (esbuild/swc).
• Compatible con la API tipo Jest (describe, it, expect, vi).
• environment: "node" evita jsdom a menos que se pruebe el DOM.
• Los hilos del pool ejecutan archivos de prueba en paralelo.

Consejos de configuración

Notas de TypeScript

• vitest/config tipifica defineConfig.
• Los alias de ruta de tsconfig se pueden conectar a través del plugin vite-tsconfig-paths si es necesario.

Errores comunes

• Mezclar Vitest y node:test - Dos ejecutores confunden a los colaboradores. Solución: elige uno por repositorio o por paquete en un monorepo.
• Mocking de módulos ESM - Problemas de hoisting con vi.mock. Solución: usa la fábrica vi.mock e importaciones dinámicas después del mock.
• Pruebas de integración en el pool predeterminado - Condiciones de carrera de la base de datos. Solución: separa vitest.integration.config.ts con fileParallelism: false.
• Cobertura en código solo de rama - Falsa confianza. Solución: combina la cobertura con pruebas de mutación o aserciones de comportamiento con moderación.
• Cambio de instantáneas - Ruido en PR grandes. Solución: prefiere toEqual explícito en campos estables.

Alternativas

Preguntas frecuentes

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

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

Relacionado

• node:test y node:assert - alternativa sin dependencias
• Supertest e integración HTTP - pruebas HTTP
• Mejores prácticas de prueba - comportamiento sobre implementación

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.