Cada framework de pruebas que has utilizado, ya sea Jest, Mocha o node:test, se basa en una idea simple: establecer lo que esperas y luego lanzar un error si la realidad no coincide. Node.js incluye esa idea como un módulo incorporado llamado assert. Sin instalación, sin dependencia, simplemente lo requires y empiezas a verificar suposiciones.
El módulo assert vale la pena conocerlo por sí mismo. Impulsa comprobaciones rápidas de cordura en scripts, sustenta muchos ejecutores de pruebas y te enseña lo que realmente es una aserción antes de que cualquier framework la vista. Esta guía cubre los métodos importantes, la distinción entre estricto y legado que confunde a la gente, cómo afirmar sobre errores y código asíncrono, y cómo el mismo módulo te ayuda a validar respuestas de API.
Qué hace el módulo assert
Una aserción es una declaración que debe ser verdadera para que tu programa sea considerado correcto. Cuando escribes assert.strictEqual(total, 100), estás declarando que total debe ser igual a 100. Si lo es, no sucede nada y la ejecución continúa. Si no lo es, assert lanza un AssertionError que detiene la ejecución y te dice qué salió mal.
Importa el módulo. La forma moderna y recomendada es la versión estricta:
const assert = require('node:assert/strict');
// or with ES modules:
// import assert from 'node:assert/strict';
La aserción más simple verifica que un valor sea verdadero (truthy):
const user = getUser(42);
assert(user, 'getUser should return a user object');
El primer argumento es el valor bajo prueba. El segundo, opcional, es un mensaje que se muestra cuando la aserción falla. Siempre escribe ese mensaje. Un fallo que dice "getUser should return a user object" es mucho más útil que un simple AssertionError. Comprender las aserciones también ayuda cuando pasas a aserciones de API dedicadas en una herramienta de pruebas.
Modo estricto versus modo legado
Esto es lo más importante que hay que entender bien. El módulo assert tiene dos modos.
El modo legado, que se obtiene de require('node:assert'), utiliza igualdad flexible (==) para assert.equal y assert.deepEqual. Eso significa que assert.equal(1, '1') pasa, porque 1 == '1' es verdadero en JavaScript. La igualdad flexible es una fuente conocida de errores.
El modo estricto, que se obtiene de require('node:assert/strict'), utiliza igualdad estricta (===) para todo. assert.equal(1, '1') falla, como debería, porque los tipos difieren.
const looseAssert = require('node:assert');
looseAssert.equal(1, '1'); // pasa, sorprendente y peligroso
const strict = require('node:assert/strict');
strict.equal(1, '1'); // lanza AssertionError, correcto
Usa el modo estricto. No hay una buena razón para aceptar la igualdad flexible en las pruebas. El resto de esta guía asume node:assert/strict, donde assert.equal se comporta de manera idéntica a assert.strictEqual.
Comparando valores: equal y strictEqual
assert.strictEqual(actual, expected) verifica que dos valores sean idénticos con ===. Es la herramienta principal para tipos primitivos como números, cadenas y booleanos.
const assert = require('node:assert/strict');
function priceWithTax(price, rate) {
return price + price * rate;
}
assert.strictEqual(priceWithTax(100, 0.08), 108, 'el cálculo del impuesto debe sumar un 8 por ciento');
assert.strictEqual(typeof priceWithTax(100, 0.08), 'number', 'el resultado debe ser un número');
También existe assert.notStrictEqual, que pasa cuando los dos valores no son idénticos. Úsalo para confirmar que un valor ha cambiado:
const before = getCacheKey();
refreshCache();
const after = getCacheKey();
assert.notStrictEqual(before, after, 'la clave de caché debe cambiar después de la actualización');
Para objetos y arrays, strictEqual no ayudará. Dos literales de objeto con el mismo contenido son referencias diferentes, por lo que === devuelve falso. Para eso sirve la igualdad profunda.
Comparando objetos: deepStrictEqual
assert.deepStrictEqual(actual, expected) compara la estructura y los valores de forma recursiva. Dos objetos pasan si cada clave contiene un valor estrictamente igual, en todos los niveles.
const assert = require('node:assert/strict');
function buildOrder(id, items) {
return { id, items, status: 'pending' };
}
assert.deepStrictEqual(
buildOrder(7, ['keyboard', 'mouse']),
{ id: 7, items: ['keyboard', 'mouse'], status: 'pending' },
'el objeto de pedido debe coincidir con la forma esperada'
);
Este es el método que más utilizarás al probar funciones que devuelven objetos, y especialmente al probar respuestas de API, ya que los cuerpos JSON son objetos. Su contraparte, assert.notDeepStrictEqual, pasa cuando las estructuras difieren.
Una advertencia: deepStrictEqual también verifica los tipos. Una propiedad que contenga el número 7 no coincidirá con una propiedad que contenga la cadena '7'. Esa estrictez es una característica; detecta la deriva de tipos en tus datos. Si estás probando funciones con muchas combinaciones de entrada, nuestra guía sobre pruebas de API basadas en datos con CSV y JSON muestra cómo escalar las aserciones a través de conjuntos de datos.
Cuando deepStrictEqual falla, Node imprime una diferencia que resalta exactamente qué propiedades no coinciden. Esa diferencia es una de las cosas más útiles del módulo. En lugar de mirar dos objetos grandes tratando de detectar la diferencia, lees unas pocas líneas resaltadas. Para datos anidados, eso por sí solo justifica usar deepStrictEqual en lugar de verificar manualmente cada campo con strictEqual.
Coincidencia parcial con assert.match y assert.ok
No todas las comprobaciones necesitan una igualdad completa. A veces, solo te importa que un valor parezca aproximadamente correcto. assert.ok(value) pasa siempre que el valor sea verdadero (truthy), lo cual es la herramienta adecuada para las comprobaciones de "esto debería existir": una cadena no vacía, un objeto definido, un recuento distinto de cero.
assert.match(string, regexp) verifica que una cadena coincida con una expresión regular, y assert.doesNotMatch verifica lo contrario. Son útiles para valores cuyo contenido exacto varía pero cuya forma es fija.
const assert = require('node:assert/strict');
function generateOrderId() {
return 'ORD-' + Date.now();
}
const id = generateOrderId();
// el timestamp exacto cambia, así que afirma el formato, no el valor
assert.match(id, /^ORD-\d+$/, 'el id de pedido debe ser ORD- seguido de dígitos');
assert.ok(id.length > 4, 'el id de pedido no debe estar vacío');
Este patrón es importante especialmente para las pruebas de API, donde las respuestas contienen marcas de tiempo, IDs generados y tokens que no puedes predecir. Afirmas el formato con match y la existencia con ok, y reservas strictEqual para los valores que realmente controlas.
Afirmando que el código lanza errores
A veces, el comportamiento correcto significa lanzar un error. assert.throws(fn, expectedError) ejecuta una función y solo pasa si esta lanza un error.
const assert = require('node:assert/strict');
function parsePort(value) {
const port = Number(value);
if (!Number.isInteger(port) || port < 1 || port > 65535) {
throw new RangeError('port must be an integer between 1 and 65535');
}
return port;
}
// pasa: la entrada inválida debe lanzar un RangeError
assert.throws(
() => parsePort('70000'),
RangeError,
'un puerto fuera de rango debe lanzar RangeError'
);
// también puedes hacer coincidir el mensaje de error con una expresión regular
assert.throws(
() => parsePort('abc'),
/must be an integer/,
'un puerto no numérico debe lanzar un error descriptivo'
);
// pasa: la entrada válida no debe lanzar un error
assert.doesNotThrow(
() => parsePort('8080'),
'un puerto válido no debe lanzar un error'
);
Ten en cuenta que pasas una función, no una llamada. assert.throws(parsePort('70000')) ejecutaría parsePort antes de que assert lo vea, y el error escaparía sin ser capturado. Siempre envuélvelo: () => parsePort('70000').
Afirmando sobre código asíncrono: rejects
El código moderno de Node.js está lleno de promesas, y una promesa rechazada es el equivalente asíncrono de un error lanzado. assert.rejects y assert.doesNotReject manejan ese caso. Ambos devuelven promesas, por lo que debes usar await con ellas.
const assert = require('node:assert/strict');
async function fetchUser(id) {
if (typeof id !== 'number') {
throw new TypeError('id must be a number');
}
// ... la búsqueda real iría aquí
return { id, name: 'Dana Lee' };
}
async function runTests() {
// pasa: entrada incorrecta rechaza con un TypeError
await assert.rejects(
fetchUser('not-a-number'),
TypeError,
'el id de tipo string debe ser rechazado'
);
// pasa: entrada buena resuelve sin rechazar
await assert.doesNotReject(
fetchUser(101),
'un id válido debe resolverse limpiamente'
);
}
runTests();
Olvidar usar await en una llamada a assert.rejects es un error común. Sin await, la función de prueba termina antes de que la aserción se resuelva, y un fallo se convierte en un rechazo no manejado en lugar de un error de prueba claro.
Usando assert para probar respuestas de API
El módulo assert es realmente útil para verificar la salida de una solicitud HTTP. Después de obtener un endpoint, tienes un código de estado y un cuerpo JSON, y ambos son elementos sobre los que hacer aserciones.
const assert = require('node:assert/strict');
async function testGetUser() {
const res = await fetch('https://api.example.com/users/101');
// verificar el código de estado
assert.strictEqual(res.status, 200, 'GET /users/101 debe devolver 200');
const body = await res.json();
// verificar la forma y los tipos de la respuesta
assert.strictEqual(typeof body.id, 'number', 'el id debe ser un número');
assert.strictEqual(body.id, 101, 'el id debe coincidir con el usuario solicitado');
assert.ok(body.name, 'la respuesta debe incluir un nombre');
assert.ok(Array.isArray(body.roles), 'los roles deben ser un array');
}
testGetUser().then(
() => console.log('Prueba de API superada'),
(err) => { console.error('Prueba de API fallida:', err.message); process.exitCode = 1; }
);
Este patrón funciona y enseña los fundamentos. Pero para un conjunto de pruebas de API real, querrás ejecuciones estructuradas, reintentos, manejo de entornos e informes que assert por sí solo no proporciona. Nuestras guías sobre cómo escribir scripts de prueba automatizados y el framework de automatización de API pytest cubren ese siguiente paso.
Si prefieres no construir manualmente un arnés de prueba, Apidog te permite definir solicitudes de API y adjuntar aserciones visuales sobre códigos de estado, encabezados y campos JSON sin escribir ningún código de aserción. Puedes encadenar solicitudes en escenarios de prueba automatizados, ejecutarlos en CI/CD y aún así recurrir a scripts personalizados cuando necesites el control que te brinda assert. Es un camino más rápido de "Tengo un endpoint" a "Tengo un conjunto de pruebas", y puedes descargar Apidog y usarlo gratis. Junto con Apidog, el módulo assert de Node.js cubre tanto comprobaciones rápidas como suites completas.
Preguntas frecuentes
¿Necesito instalar el módulo assert?
No. assert está incorporado en Node.js. Impórtalo con require('node:assert/strict') o require('node:assert'). No hay ningún paquete npm que instalar ni dependencia que gestionar. El prefijo node: hace explícito que estás cargando un módulo central.
¿Cuál es la diferencia entre assert.equal y assert.strictEqual?
En modo legado, assert.equal usa igualdad flexible (==) y assert.strictEqual usa igualdad estricta (===). En modo estricto, cargado a través de node:assert/strict, assert.equal se comporta de manera idéntica a assert.strictEqual. Siempre usa el modo estricto para que la coerción de tipos nunca pase una prueba silenciosamente.
¿Cuándo debo usar deepStrictEqual en lugar de strictEqual?
Usa strictEqual para tipos primitivos: números, cadenas, booleanos. Usa deepStrictEqual para objetos y arrays, porque strictEqual compara referencias y dos objetos separados nunca son iguales por referencia. Siempre que hagas una aserción sobre un cuerpo JSON o un objeto devuelto, opta por deepStrictEqual.
¿Debo usar el módulo assert o un framework de pruebas como Jest?
Para scripts rápidos y aprendizaje, assert puro está bien. Para un conjunto de pruebas real, usa un framework. Node.js también incluye un ejecutor de pruebas incorporado, node:test, que se combina naturalmente con assert y te brinda organización de pruebas, informes y paralelismo sin una dependencia externa.
¿Cómo afirmo que una función asíncrona se rechaza?
Usa assert.rejects, y recuerda usar await. Pasa la promesa o una llamada a función asíncrona, opcionalmente con un tipo de error esperado o una expresión regular para el mensaje. assert.rejects(somePromise, TypeError) solo pasa si la promesa se rechaza con un TypeError. Sin await, un fallo se convierte en un rechazo no manejado en lugar de un error de aserción claro.