vitest para TypeScript: Guía completa

vitest es un framework de pruebas unitarias moderno, rápido y potente, diseñado específicamente para el ecosistema de TypeScript y JavaScript. Se presenta como una alternativa directa a Jest, pero con un enfoque en la velocidad de ejecución y el soporte nativo para Vite. Si utilizas Vite para compilar tu proyecto, vitest es la elección ideal, ya que emplea el mismo plugin y configuración que tu herramienta de compilación principal.

¿Por qué usar vitest? En primer lugar, es increíblemente rápido gracias al uso de esbuild para la transpilación y al soporte nativo de ESM (Módulos ECMAScript). En segundo lugar, ofrece una API enriquecida y compatible con Jest, lo que facilita la migración. En tercer lugar, vitest proporciona soporte integrado para TypeScript, JSX, mocking, cobertura y pruebas de instantáneas (snapshot testing) sin necesidad de instalar paquetes adicionales. Esto lo convierte en la herramienta perfecta tanto para proyectos pequeños como para grandes aplicaciones empresariales.

En este sitio educativo PythonLib, te mostraremos cómo usar vitest para probar código TypeScript. Aprenderás a instalar la librería, escribir tus primeras pruebas, dominar los métodos principales y evitar errores comunes. Al final del artículo, podrás usar vitest con confianza en tus proyectos.

Instalación

La instalación de vitest se realiza a través de npm o yarn. Para un proyecto TypeScript, también necesitarás instalar TypeScript y los tipos para Node.js (si pruebas código del lado del servidor).

npm install -D vitest typescript @types/node

Si usas yarn:

yarn add -D vitest typescript @types/node

Después de la instalación, añade un script en tu package.json:

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

El comando vitest ejecuta las pruebas en modo watch (reinicio automático ante cambios), mientras que vitest run realiza una ejecución única.

Inicio rápido

Crea un archivo sum.ts con una función simple:

// sum.ts
export function sum(a: number, b: number): number {
  return a + b;
}

Ahora, crea un archivo de prueba sum.test.ts:

// sum.test.ts
import { describe, it, expect } from 'vitest';
import { sum } from './sum';

describe('Función sum', () => {
  it('debe sumar dos números correctamente', () => {
    expect(sum(2, 3)).toBe(5);
  });

  it('debe manejar números negativos', () => {
    expect(sum(-1, -2)).toBe(-3);
  });
});

Ejecuta las pruebas:

npm run test

Verás una salida en verde indicando que las pruebas se han superado correctamente. ¡Felicidades, has escrito tu primera prueba con vitest!

Métodos y funciones principales

vitest ofrece una API completa para escribir pruebas. A continuación, se presentan 8 métodos clave con descripciones y ejemplos.

1. describe

Firma: describe(nombre: string, fn: () => void): void

Descripción: Agrupa pruebas relacionadas en un bloque. Mejora la legibilidad y permite aplicar hooks (beforeEach, afterEach) al grupo.

import { describe, it, expect } from 'vitest';

describe('Operaciones matemáticas', () => {
  it('debe sumar', () => {
    expect(1 + 1).toBe(2);
  });

  it('debe restar', () => {
    expect(5 - 3).toBe(2);
  });
});

2. it / test

Firma: it(nombre: string, fn: () => void | Promise<void>, timeout?: number): void

Descripción: Define una prueba individual. Se puede usar tanto it como test; son sinónimos.

import { it, expect } from 'vitest';

it('debe devolver true