Tests natifs de Node.js : assertions

Le module node:assert fournit les vérifications. Utiliser sa version stricte :

import assert from 'node:assert/strict';

Comparaisons de base

assert.equal(somme(1, 2), 3); // égalité stricte (===)
assert.notEqual(a, b);
assert.ok(valeur); // truthy (ou assert(valeur))
assert.deepEqual({ a: 1, b: [1, 2] }, { a: 1, b: [1, 2] }); // égalité de contenu, stricte
assert.notDeepEqual(x, y);
assert.strictEqual(a, b); // équivalent de equal en mode strict
assert.match('bonjour monde', /monde/);
assert.doesNotMatch('bonjour', /au revoir/);
assert.fail('ne devrait pas arriver');

Assertion	Quand
`equal` / `strictEqual`	Primitives (nombres, chaînes, booléens), identité d’un objet
`deepEqual` (strict)	Contenu d’objets et de tableaux, types compris
`ok`	Valeur « vraie » (moins précis : préférer `equal` quand c’est possible)
`match`	Chaîne correspondant à une expression régulière

En mode strict, assert.deepEqual équivaut à deepStrictEqual : { a: 1 } et { a: '1' } sont différents. Les nombres décimaux demandent une marge :

assert.ok(Math.abs(0.1 + 0.2 - 0.3) < Number.EPSILON);

Tester les erreurs

function diviser(a, b) {
  if (b === 0) throw new RangeError('division par zéro');
  return a / b;
}

assert.throws(() => diviser(1, 0), RangeError);
assert.throws(() => diviser(1, 0), {
  name: 'RangeError',
  message: 'division par zéro',
});
assert.throws(() => diviser(1, 0), /division/);
assert.doesNotThrow(() => diviser(4, 2));

Envelopper l’appel dans une fonction : assert.throws(diviser(1, 0)) lèverait l’erreur avant l’assertion.

Promesses

await assert.rejects(chargerClient(999), { message: /introuvable/ });
await assert.rejects(() => chargerClient(999), Error);
await assert.doesNotReject(chargerClient(1));

const client = await chargerClient(1);
assert.equal(client.nom, 'Alice');

assert.rejects et doesNotReject renvoient une promesse : toujours l’attendre (await), sinon l’échec passe inaperçu.

Comparer des objets partiellement

deepEqual exige l’égalité complète. Pour vérifier seulement certains champs :

const reponse = await creerClient({ nom: 'Alice' });
assert.equal(reponse.nom, 'Alice');
assert.ok(typeof reponse.id === 'string');
assert.partialDeepStrictEqual(reponse, { nom: 'Alice' }); // Node.js récent

partialDeepStrictEqual n’existe que dans les versions récentes : tester la disponibilité (typeof assert.partialDeepStrictEqual) ou vérifier champ par champ. Pour des valeurs variables (identifiant, date), les écarter de la comparaison :

const { id, creeLe, ...reste } = reponse;
assert.deepEqual(reste, { nom: 'Alice', actif: true });

Messages d’erreur

assert.equal(total, 4900, `Le total attendu est 4900, reçu ${total}`);
assert.deepEqual(resultat, attendu, 'La liste filtrée est incorrecte');

Un message explicite accélère le diagnostic ; assert affiche déjà un diff coloré pour deepEqual.

Assertions du contexte de test

Dans un test, t.assert expose les mêmes fonctions liées au test : le nombre d’assertions est compté, et t.plan permet d’exiger un nombre précis.

import { test } from 'node:test';

test('compte les assertions', (t) => {
  t.plan(2);
  t.assert.equal(1 + 1, 2);
  t.assert.ok(true);
});

t.plan(n) vérifie que le test a fait exactement n assertions : utile pour des tests de rappels asynchrones où une assertion peut ne jamais être atteinte.

Snapshots

Les versions récentes de Node.js proposent des snapshots dans le contexte de test :

test('formate la facture', (t) => {
  t.assert.snapshot(formaterFacture(donnees));
});

Le fichier de référence est créé avec node --test --test-update-snapshots. À utiliser avec modération, comme avec tout snapshot (voir Vitest : couverture et snapshots) ; disponible selon la version de Node.js.

Bonnes pratiques

Une assertion principale par test, nommée comme un comportement.
deepEqual pour les contenus, equal pour les valeurs simples.
Tester aussi les cas d’erreur (entrées invalides, ressources absentes).
Pas de logique conditionnelle dans les tests (un if rend l’échec incertain).
Données de test déterministes (pas de date ni d’aléatoire sans contrôle : voir Mocks et minuteurs).

Dépannage

Symptôme	Piste
`assert.equal(1, '1')` passe	`node:assert` sans `/strict` : utiliser `node:assert/strict`
`deepEqual` échoue pour des objets semblables	Types différents (`1` et `'1'`), prototypes (classe contre objet simple), propriétés `undefined`
`assert.throws` ne détecte pas l’erreur	Appel non enveloppé dans une fonction
`rejects` ne détecte rien	`await` manquant, ou la fonction lève de façon synchrone
Message d’erreur tronqué	Comparer des valeurs plus petites, ou exporter le diff
`partialDeepStrictEqual is not a function`	Version de Node.js plus ancienne