node:test y node:assert

Node 24 incluye un ejecutor de pruebas y un módulo de aserciones nativos para que las pruebas unitarias se ejecuten sin Jest o Vitest para la lógica pura de backend.

Receta

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

import assert from "node:assert/strict";
import { describe, it } from "node:test";
 
describe("math", () => {
  it("adds", () => {
    assert.equal(1 + 1, 2);
  });
});

node --import tsx --test

Cuándo usarlo:

• Funciones puras, analizadores y lógica de dominio.
• Quieres cero dependencias del ejecutor de pruebas.
• Librerías que no deben forzar Jest a los consumidores.

Ejemplo de trabajo

// src/pricing/discount.ts
export function applyDiscount(cents: number, percent: number): number {
  if (percent < 0 || percent > 100) throw new Error("invalid percent");
  return Math.round(cents * (1 - percent / 100));
}

// test/pricing/discount.test.ts
import assert from "node:assert/strict";
import { describe, it } from "node:test";
 
import { applyDiscount } from "../../src/pricing/discount.js";
 
describe("applyDiscount", () => {
  it("reduces price by percentage", () => {
    assert.equal(applyDiscount(1000, 10), 900);
  });
 
  it("throws on invalid percent", () => {
    assert.throws(() => applyDiscount(1000, -1), /invalid percent/);
  });
});

{
  "scripts": {
    "test": "node --import tsx --test --test-reporter spec"
  }
}

Lo que esto demuestra:

• Importaciones ESM con extensiones .js para compatibilidad con NodeNext.
• assert.throws valida rutas de error sin una librería de mocking.
• --test-reporter spec proporciona una salida legible en CI.

Inmersión profunda

Cómo funciona

• node:test descubre archivos *.test.ts (o rutas explícitas) y se ejecuta en paralelo por defecto.
• Hooks: before, after, beforeEach, afterEach en el ámbito de describe.
• node:assert/strict lanza AssertionError en caso de desajuste (la igualdad profunda usa reglas === para primitivos).
• Subpruebas a través de anidamiento it o test.context() para una agrupación más granular.

Helpers de aserción

Notas de TypeScript

node --import tsx --test

• El cargador tsx compila TypeScript sobre la marcha para desarrollo y CI.
• La implementación en producción sigue utilizando la compilación tsc; las pruebas no se envían.

Errores comunes

• No hay ergonomía de mock/spy incorporada - Es verboso sin node:test/mock (Node 22+). Solución: usa mock.fn() de node:test o añade Vitest para mocking pesado.
• Pruebas paralelas que comparten estado global - Fallos inestables. Solución: describe(..., { concurrency: 1 }) o aislar el estado por prueba.
• Falta tsx en CI - node --test sin tsx falla en .ts. Solución: tsx como devDependency y --import tsx.
• Ruta de importación .ts en las pruebas - Rompe la resolución de ESM. Solución: importa rutas .js que coincidan con el diseño de emisión.
• Ausencia de pruebas de snapshot - No hay snapshots de Jest. Solución: aserción de campos explícitos o adoptar Vitest para las necesidades de snapshot.

Alternativas

Preguntas frecuentes

node --import tsx --test test/pricing/discount.test.ts

import { mock } from "node:test";
const fn = mock.fn(() => 42);

node --import tsx --experimental-test-coverage --test

Relacionado

• Conceptos básicos de pruebas - visión general de la pirámide
• Vitest - cuando necesitas mocks y vigilancia
• Supertest e integración HTTP - pruebas de capa HTTP

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