Nivel inicial10 min de lectura · Publicado el

Instalar Jest en un proyecto de JavaScript (npm y ESM)

Instalar Jest en JavaScript: el test pide que sumar(2, 3) dé 5 y Jest lo comprueba con npm test: PASS, 1 passed. Jest: tu primer test en verderubentejera.com sumar.test.jsexpect(sumar(2, 3)) .toBe(5)PASS1 passednpm test
Como quien revisa un examen con las respuestas delante: tú pones la esperada (sumar(2, 3) debe dar 5) y Jest comprueba tu código con cada npm test. No lo arregla: te dice si pasa (PASS) o falla.

Jest es una herramienta para escribir y ejecutar tests en JavaScript: busca los ficheros de test de tu proyecto, los ejecuta y te dice cuáles pasan y cuáles fallan. Es como quien revisa un examen con las respuestas delante: tú pones las respuestas esperadas una vez y él comprueba tu código cada vez que lo entregas. No lo arregla: te dice qué pasa y qué falla.

Esta guía está probada con Jest 30.5.2, Node 24 y npm 11. Jest 30 necesita Node 18 o superior.

1. Crea el package.json

El package.json es la ficha del proyecto: guarda su nombre, sus dependencias y los comandos que puedes lanzar. Si tu proyecto ya lo tiene, salta al paso 2. Necesitas Node.js y npm; en Ubuntu, sigue instalar Node.js en Ubuntu.

npm init          # te hace preguntas una a una (nombre, versión…)
npm init --yes    # lo crea con los valores por defecto

2. Instala Jest con npm install

npm install --save-dev jest

--save-dev (o su forma corta, -D) lo instala como dependencia de desarrollo: la necesitas para programar y probar, pero no forma parte de lo que se ejecuta en producción.

Si usas otro gestor de paquetes, el equivalente es yarn add --dev jest, pnpm add --save-dev jest o bun add --dev jest.

3. Añade el script de test

Abre el package.json y deja la sección scripts así:

{
  "scripts": {
    "test": "jest"
  }
}

También puedes hacerlo sin abrir el fichero:

npm pkg set scripts.test=jest

4. Escribe tu primer test

Crea un fichero sumar.js con el código que quieres probar:

function sumar(a, b) {
  return a + b;
}

module.exports = { sumar };

Y, a su lado, el test en sumar.test.js:

const { sumar } = require("./sumar");

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

describe agrupa los tests, it describe un caso concreto y expect(...).toBe(...) comprueba el resultado. A esa última parte se le llama matcher: tienes la lista completa en la documentación de expect. La estructura de un test se explica con más calma en Composición de un test en TDD y sus métodos.

5. Lanza los tests

npm test

Si todo va bien, verás algo así:

PASS ./sumar.test.js
  sumar
    ✓ suma dos números (2 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        0.218 s, estimated 1 s

La salida del artículo original, de 2018, era la del test de ejemplo verdadero es verdadero, en una carpeta test con un fichero spec.js. El formato apenas ha cambiado:

PASS test/spec.js
  test de prueba
    ✓ verdadero es verdadero (5ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.252s
Ran all test suites.

Haz la prueba: cambia el 5 por un 6 y vuelve a lanzar npm test. Ver fallar un test una vez te confirma que de verdad comprueba algo.

Primero en rojo, luego en verde.

Ejecutar los tests al guardar: –watch y –watchAll

Para no lanzar npm test a mano cada vez, Jest puede quedarse vigilando tus ficheros y repetir los tests al guardar:

{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch"
  }
}

Y lo arrancas con npm run test:watch. Hay dos variantes:

Opción Qué repite al guardar Requisito
jest --watch Solo los tests relacionados con los ficheros que han cambiado El proyecto debe ser un repositorio de Git (o Mercurial)
jest --watchAll Todos los tests Ninguno: úsala si el proyecto no tiene Git

Es mejor dejarlo en un script aparte (test:watch) que cambiar el test principal: así npm test sigue terminando y sirve también para la integración continua.

Jest con módulos ESM (import y export)

Si tu package.json tiene "type": "module", o escribes los tests con import y export, Jest falla con un error así:

Must use import to load ES Module: …/sumar.test.js

Qué cambia entre import/export y require se explica en exportar e importar funciones en JavaScript.

Jest ofrece soporte para ESM, pero experimental: hay que arrancarlo con la opción --experimental-vm-modules de Node. La forma que funciona igual en Windows, macOS y Linux es poner esa opción en el script:

{
  "type": "module",
  "scripts": {
    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
  }
}

Con eso ya puedes escribir el código y el test con import:

// sumar.js
export function sumar(a, b) {
  return a + b;
}
// sumar.test.js
import { sumar } from "./sumar.js";

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

Node mostrará el aviso ExperimentalWarning: VM Modules is an experimental feature. Es normal y no afecta a los resultados. En ESM, si necesitas el objeto jest (por ejemplo, para jest.fn()), impórtalo: import { jest } from "@jest/globals";.

Tests que usan el navegador: jsdom

Por defecto, Jest ejecuta los tests en un entorno de Node, sin window, document ni localStorage. Si tu código los usa, necesitas jsdom, una simulación del navegador escrita en JavaScript. Desde Jest 28 se instala aparte:

npm install --save-dev jest-environment-jsdom

Y se activa en el package.json:

{
  "jest": {
    "testEnvironment": "jsdom"
  }
}

Si solo lo necesitan algunos tests, deja el entorno por defecto y añade este comentario al principio de esos ficheros:

/**
 * @jest-environment jsdom
 */

Si no instalas el paquete, Jest te avisa: Test environment jest-environment-jsdom cannot be found.

El error «localStorage is not available for opaque origins»

En 2018, con Jest 23, los tests con jsdom fallaban con este error (issue 2304 de jsdom):

SecurityError: localStorage is not available for opaque origins

La solución era añadir la opción testURL al package.json. Así quedaba entonces:

{
  "name": "pruebajest2",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "jest"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "jest": "^23.4.2"
  },
  "jest": {
    "verbose": true,
    "testURL": "http://localhost/"
  }
}

Hoy ya no hace falta. En Jest 30, jsdom usa por defecto la dirección http://localhost, así que localStorage funciona sin configurar nada. Además, testURL ya no existe: si la pones, Jest avisa de que se sustituyó por testEnvironmentOptions.url. Si necesitas otra dirección:

{
  "jest": {
    "testEnvironment": "jsdom",
    "testEnvironmentOptions": {
      "url": "https://example.com/"
    }
  }
}

La opción "verbose": true de aquel package.json tampoco es necesaria cuando ejecutas un solo fichero: Jest ya muestra cada test por separado. Con varios ficheros, sí sirve para ver el detalle de cada test.

Comandos útiles

Comando Qué hace
npx jest sumar Ejecuta solo los ficheros de test cuyo nombre contiene «sumar»
npx jest --coverage Muestra qué porcentaje del código cubren tus tests
npm init jest@latest Genera un fichero de configuración de Jest con un asistente

¿Jest u otra opción? node:test y Vitest

Jest no es la única opción. Dos alternativas actuales:

  • node:test, el ejecutor de tests que viene con Node. Es estable desde Node 20 y no necesita instalar nada: lanzas node --test y busca, entre otros, los ficheros *.test.js y los de la carpeta test. Las comprobaciones se hacen con node:assert.
  • Vitest, pensado para proyectos que usan Vite. La versión 5.1 necesita Node 22.12 o superior. Se instala con npm install -D vitest y trabaja con ESM sin opciones extra. Su API (describe, it, expect) es muy parecida a la de Jest.

El mismo test con node:test, sin instalar ninguna dependencia:

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { sumar } from "./sumar.js";

describe("sumar", () => {
  it("suma dos números", () => {
    assert.equal(sumar(2, 3), 5);
  });
});

Si empiezas un proyecto ESM o con Vite, Vitest o node:test te ahorran la configuración experimental. Si el proyecto ya usa Jest, o trabajas con CommonJS, Jest sigue siendo una opción sólida.

Tests y programación con IA

Desde el enfoque de IA Limpia, tener npm test funcionando es el primer paso antes de dejar que un agente de IA toque el código: los tests son la forma rápida de comprobar que lo que ha generado hace lo que debe y que no ha roto lo que ya funcionaba. Si el agente puede lanzar npm test por sí mismo, también puede detectar sus propios errores antes de que los revises tú.

Siguiente paso

Fuentes

Comprobado en noviembre de 2026 en la documentación oficial de Jest 30.5: Getting Started, ECMAScript Modules, Configuration (testEnvironment, testEnvironmentOptions, testMatch, verbose), CLI (--watch, --watchAll, --coverage) y From v29 to v30 (Node 18 o superior). Para las alternativas: Test runner de Node 24 y guía de Vitest 5.1.

Ejecutado con Node 24.21.0, npm 11.19.0, Jest 30.5.2, jest-environment-jsdom 30.5.2 y Vitest 5.1.0 en Linux: instalación, primer test, cobertura, jsdom (con y sin el paquete), el aviso de testURL, ESM con y sin --experimental-vm-modules, node --test y vitest run. El modo watch y npm init jest@latest son interactivos y solo se han comprobado en la documentación. La salida y el package.json de 2018 son de Rubén, con Jest 23.