Introducción a Vitest en React

Vitest es el runner de tests nativo del ecosistema Vite. Comparte el mismo pipeline de transformación, los mismos plugins y la misma configuración que la aplicación, por lo que no hace falta duplicar reglas de Babel o de TypeScript para que el código de producción y el código de test se comporten igual. En un proyecto React moderno, Vitest es la opción por defecto y sustituye a alternativas más lentas como Jest cuando ya se trabaja con Vite.

Instalación y configuración

El primer paso es añadir las dependencias de desarrollo: el propio vitest, el entorno jsdom para simular el DOM del navegador y las utilidades de @testing-library/react junto con @testing-library/jest-dom para assertions sobre elementos.

npm install -D vitest jsdom @testing-library/react @testing-library/jest-dom

A continuación, se configura Vitest en el fichero vite.config.ts del proyecto. Si usas TypeScript, se añade una directiva triple slash en la primera línea para habilitar el tipado de los globales como describe, it y expect.

/// <reference types="vitest" />
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom",
    globals: true,
    setupFiles: "./src/test-setup.ts",
    css: true,
  },
});

La opción environment: "jsdom" es imprescindible para renderizar componentes React en un DOM virtual durante los tests. La opción globals: true expone describe, it y expect sin necesidad de importarlos en cada archivo, siguiendo la ergonomía habitual de Jest.

El fichero de setup inicializa las extensiones de Testing Library y limpia el DOM entre tests:

// src/test-setup.ts
import "@testing-library/jest-dom/vitest";
import { cleanup } from "@testing-library/react";
import { afterEach } from "vitest";

afterEach(() => {
  cleanup();
});

El setup se ejecuta una sola vez al arrancar Vitest. Gracias a afterEach cada test queda aislado y no ve nodos renderizados por otros tests anteriores, lo cual elimina una fuente muy común de tests intermitentes.

Scripts de npm y primer test

Para lanzar los tests desde la línea de comandos se añaden dos scripts en package.json. El modo watch recompila en cada cambio y el modo run ejecuta los tests una sola vez, que es lo que espera un entorno de CI.

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

El primer test sirve para validar que la instalación funciona. Se puede probar con una función pura:

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

// src/utils/sumar.test.ts
import { describe, it, expect } from "vitest";
import { sumar } from "./sumar";

describe("sumar", () => {
  it("devuelve la suma de dos números positivos", () => {
    expect(sumar(2, 3)).toBe(5);
  });

  it("trata el cero como elemento neutro", () => {
    expect(sumar(10, 0)).toBe(10);
  });
});

Al lanzar npm run test, Vitest detecta automáticamente los archivos con patrón *.test.ts, *.test.tsx, *.spec.ts o *.spec.tsx, los compila con Vite y ejecuta cada it dentro de su describe. La consola muestra un informe jerárquico con el estado de cada bloque.

Matchers más usados

El objeto expect devuelve una cadena de matchers que describen la comprobación. Los matchers esenciales para tests de funciones puras son toBe, toEqual, toBeTruthy, toBeFalsy, toContain, toHaveLength y toThrow.

expect(sumar(2, 3)).toBe(5);
expect({ nombre: "Ana" }).toEqual({ nombre: "Ana" });
expect([1, 2, 3]).toContain(2);
expect("Hola mundo").toHaveLength(10);
expect(() => { throw new Error("fallo"); }).toThrow("fallo");

La diferencia clave entre toBe y toEqual es que toBe usa igualdad estricta (===), ideal para primitivos, mientras que toEqual compara las propiedades recursivamente, ideal para objetos y arrays. Equivocarse entre una y otra es una de las causas más frecuentes de falsos negativos al empezar con tests.

Cuando se añade el paquete @testing-library/jest-dom, se extienden los matchers con afirmaciones específicas del DOM como toBeInTheDocument, toHaveTextContent, toHaveClass, toBeVisible y toBeDisabled. Estos matchers son los que se usan en la siguiente lección para testear componentes.

Modo watch y salida por terminal

Durante el desarrollo, lo habitual es mantener Vitest abierto en modo watch. El runner vuelve a ejecutar solo los tests afectados cuando detecta cambios en el código, lo que ofrece un feedback casi instantáneo.

npm run test

La interfaz de terminal permite filtrar por nombre de test pulsando p (filtrar por patrón de archivo) o t (filtrar por nombre de test). Para un entorno de integración continua, el modo run es el adecuado porque sale con código de error si algún test falla:

npm run test:run

Vitest integra cobertura de código vía @vitest/coverage-v8. Al ejecutarlo genera un informe HTML en coverage/ que se puede abrir en el navegador para revisar qué líneas y ramas no están cubiertas. En un proyecto B2B esta cobertura suele fijarse en torno al 80 por ciento como umbral mínimo aceptable.