Módulo assert

Módulo assert

El módulo assert es una herramienta nativa de Node.js que permite verificar que el código funciona correctamente mediante pruebas unitarias. Proporciona un conjunto de funciones de aserción que comprueban si las condiciones esperadas se cumplen, lanzando errores cuando no es así.

El siguiente diagrama resume visualmente los conceptos clave introducidos en esta sección:

flowchart TD
    A["node:assert"] --> B[strict.equal]
    A --> C[strict.deepEqual]
    A --> D[strict.ok]
    A --> E[strict.throws]
    A --> F[strict.rejects]
    A --> G[strict.match]
    H["node:test"] --> I["describe / it"]
    I --> J[assert.*]
    J --> K{"¿Aserción cumple?"}
    K -- no --> L[AssertionError]

Las pruebas unitarias son fundamentales en el desarrollo profesional porque permiten detectar errores antes de que lleguen a producción y dan confianza para modificar código existente. El módulo assert viene incluido con Node.js, por lo que no se necesita instalar dependencias adicionales.

En las versiones modernas de Node.js (22 LTS y 24 LTS), assert se combina habitualmente con el runner nativo node:test, que ejecuta tests estructurados en suites sin necesidad de frameworks externos como Jest o Mocha.

Importación y configuración básica

Para utilizar el módulo assert, impórtalo con el prefijo node: y en su versión strict, que aplica comparaciones rigurosas por defecto:

import assert from 'node:assert/strict';

La versión strict utiliza comparaciones estrictas (===) en lugar de las comparaciones flexibles (==) que usa la versión no estricta. En código nuevo siempre se prefiere node:assert/strict.

Funciones básicas de aserción

El módulo assert proporciona varias funciones para verificar diferentes condiciones.

assert.strictEqual() comprueba que dos valores sean idénticos:

import assert from 'node:assert/strict';

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

assert.strictEqual(sumar(2, 3), 5);
console.log('Test de suma: OK');

assert.deepStrictEqual() verifica que dos objetos o arrays tengan la misma estructura y valores:

import assert from 'node:assert/strict';

const empleado = {
  nombre: 'María González',
  email: 'maria.gonzalez@iberbyte.es',
  activo: true
};

const empleadoEsperado = {
  nombre: 'María González',
  email: 'maria.gonzalez@iberbyte.es',
  activo: true
};

assert.deepStrictEqual(empleado, empleadoEsperado);
console.log('Test de objeto: OK');

assert.throws() verifica que una función lance un error cuando debería:

import assert from 'node:assert/strict';

function dividir(a, b) {
  if (b === 0) {
    throw new RangeError('División por cero no permitida');
  }
  return a / b;
}

// Verifica que se lanza el error esperado
assert.throws(
  () => dividir(10, 0),
  RangeError,
  'Se esperaba un RangeError al dividir por cero'
);
console.log('Test de error: OK');

Creando el primer archivo de tests

Para organizar los tests, se separan en archivos independientes. Supongamos que tenemos un módulo calculadora.js:

// calculadora.js
export function sumar(a, b) {
  return a + b;
}

export function restar(a, b) {
  return a - b;
}

export function multiplicar(a, b) {
  return a * b;
}

El archivo de tests calculadora.test.js puede combinar node:assert/strict con node:test. Esta es la forma preferida en Node.js moderno:

// calculadora.test.js
import { test, describe } from 'node:test';
import assert from 'node:assert/strict';
import { sumar, restar, multiplicar } from './calculadora.js';

describe('Calculadora', () => {
  test('suma de números positivos', () => {
    assert.strictEqual(sumar(5, 3), 8);
  });

  test('suma con cero', () => {
    assert.strictEqual(sumar(5, 0), 5);
  });

  test('resta básica', () => {
    assert.strictEqual(restar(10, 4), 6);
  });

  test('multiplicación básica', () => {
    assert.strictEqual(multiplicar(3, 4), 12);
  });
});

Para ejecutar los tests, usa el comando nativo:

node --test calculadora.test.js

Concepto clave: node:test es el runner oficial de Node.js desde la versión 18 y estable desde la 20. Combina descubrimiento automático de archivos *.test.js, paralelización, informes TAP y cobertura integrada. No requiere instalar Jest, Mocha ni Vitest para la mayoría de casos.

Organizando tests sin runner externo

En scripts pequeños, o cuando se quiere mostrar la lógica de aserción sin el runner, también se puede estructurar con funciones simples. Aun así, en proyectos profesionales se recomienda node:test:

import assert from 'node:assert/strict';
import { sumar, restar } from './calculadora.js';

function testSumar() {
  assert.strictEqual(sumar(2, 3), 5);
  assert.strictEqual(sumar(-1, 1), 0);
  assert.strictEqual(sumar(0, 0), 0);
  console.log('Tests de sumar: OK');
}

function testRestar() {
  assert.strictEqual(restar(5, 3), 2);
  assert.strictEqual(restar(0, 5), -5);
  assert.strictEqual(restar(10, 10), 0);
  console.log('Tests de restar: OK');
}

try {
  testSumar();
  testRestar();
  console.log('Suite de tests completada');
} catch (error) {
  console.error('Error en tests:', error.message);
  process.exit(1);
}

Probando funciones asíncronas

Al trabajar con funciones asíncronas, los tests se marcan como async y usan await. Para aserciones sobre promesas rechazadas existe assert.rejects, equivalente asíncrono de assert.throws.

Supongamos una función que simula una operación asíncrona:

// async-utils.js
export function operacionAsincrona(valor) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (valor > 0) {
        resolve(valor * 2);
      } else {
        reject(new RangeError('El valor debe ser positivo'));
      }
    }, 100);
  });
}

El archivo de tests correspondiente:

// async-utils.test.js
import { test, describe } from 'node:test';
import assert from 'node:assert/strict';
import { operacionAsincrona } from './async-utils.js';

describe('operacionAsincrona', () => {
  test('devuelve el doble si el valor es positivo', async () => {
    const resultado = await operacionAsincrona(5);
    assert.strictEqual(resultado, 10);
  });

  test('rechaza con RangeError si el valor es negativo', async () => {
    await assert.rejects(
      () => operacionAsincrona(-1),
      RangeError
    );
  });

  test('rechaza con mensaje específico si el valor es cero', async () => {
    await assert.rejects(
      () => operacionAsincrona(0),
      { message: 'El valor debe ser positivo' }
    );
  });
});

Buenas prácticas para tests básicos

Al escribir tests con el módulo assert, conviene seguir algunas prácticas recomendadas:

• Nombres descriptivos: cada test debe tener un nombre que explique claramente qué se está probando.
• Un concepto por test: cada test debe verificar una sola funcionalidad específica.
• Casos límite: incluye tests para valores extremos (cero, negativos, cadenas vacías, null, undefined).
• Mensajes claros: usa mensajes descriptivos en las aserciones para facilitar la depuración.

import { test, describe } from 'node:test';
import assert from 'node:assert/strict';

function validarEmail(email) {
  if (!email || typeof email !== 'string' || !email.includes('@')) {
    throw new TypeError('Email inválido');
  }
  return true;
}

describe('validarEmail', () => {
  test('acepta un email correcto', () => {
    assert.strictEqual(validarEmail('maria.gonzalez@iberbyte.es'), true);
  });

  test('rechaza email vacío', () => {
    assert.throws(() => validarEmail(''), TypeError);
  });

  test('rechaza email sin arroba', () => {
    assert.throws(() => validarEmail('usuarioejemplo.com'), TypeError);
  });

  test('rechaza null y undefined', () => {
    assert.throws(() => validarEmail(null), TypeError);
    assert.throws(() => validarEmail(undefined), TypeError);
  });
});

El módulo assert proporciona una base sólida para comenzar con el testing unitario en Node.js. Combinado con node:test cubre la mayoría de necesidades de proyectos backend sin depender de frameworks externos. Para testing de APIs HTTP se complementa con Supertest, y para mocks con node:test.mock, temas que se tratan en lecciones posteriores del itinerario.