Chaque framework de test que vous avez utilisé, qu'il s'agisse de Jest, Mocha ou node:test, repose sur une idée simple : énoncer ce que vous attendez, puis lever une erreur si la réalité ne correspond pas. Node.js intègre cette idée sous la forme d'un module intégré appelé assert. Aucune installation, aucune dépendance, il suffit de le require et de commencer à vérifier les hypothèses.
Le module assert mérite d'être connu en soi. Il permet des vérifications rapides dans les scripts, il sous-tend de nombreux test runners, et il vous apprend ce qu'est réellement une assertion avant qu'un framework ne l'habille. Ce guide couvre les méthodes importantes, la distinction strict/héritée qui peut prêter à confusion, comment faire des assertions sur les erreurs et le code asynchrone, et comment le même module vous aide à valider les réponses API.
Ce que fait le module assert
Une assertion est une déclaration qui doit être vraie pour que votre programme soit considéré comme correct. Lorsque vous écrivez assert.strictEqual(total, 100), vous déclarez que total doit être égal à 100. Si c'est le cas, rien ne se passe et l'exécution continue. Si ce n'est pas le cas, assert lève une AssertionError qui arrête l'exécution et vous indique ce qui n'a pas fonctionné.
Importez le module. La forme moderne et recommandée est la version stricte :
const assert = require('node:assert/strict');
// ou avec les modules ES :
// import assert from 'node:assert/strict';
L'assertion la plus simple vérifie qu'une valeur est vraie (truthy) :
const user = getUser(42);
assert(user, 'getUser should return a user object');
Le premier argument est la valeur testée. Le second, facultatif, est un message affiché lorsque l'assertion échoue. Écrivez toujours ce message. Un échec qui dit "getUser should return a user object" est bien plus utile qu'une simple AssertionError. Comprendre les assertions est également utile lorsque vous passez à des assertions API dédiées dans un outil de test.
Mode strict versus mode hérité
C'est la chose la plus importante à bien comprendre. Le module assert a deux modes.
Le mode hérité, que vous obtenez avec require('node:assert'), utilise l'égalité lâche (==) pour assert.equal et assert.deepEqual. Cela signifie que assert.equal(1, '1') passe, car 1 == '1' est vrai en JavaScript. L'égalité lâche est une source bien connue de bugs.
Le mode strict, que vous obtenez avec require('node:assert/strict'), utilise l'égalité stricte (===) pour tout. assert.equal(1, '1') échoue, comme il se doit, car les types diffèrent.
const looseAssert = require('node:assert');
looseAssert.equal(1, '1'); // passe, surprenant et dangereux
const strict = require('node:assert/strict');
strict.equal(1, '1'); // lève AssertionError, correct
Utilisez le mode strict. Il n'y a aucune bonne raison d'accepter l'égalité lâche dans les tests. Le reste de ce guide suppose l'utilisation de node:assert/strict, où assert.equal se comporte comme assert.strictEqual.
Comparaison de valeurs : equal et strictEqual
assert.strictEqual(actual, expected) vérifie que deux valeurs sont identiques avec ===. C'est la bête de somme pour les primitives comme les nombres, les chaînes de caractères et les booléens.
const assert = require('node:assert/strict');
function priceWithTax(price, rate) {
return price + price * rate;
}
assert.strictEqual(priceWithTax(100, 0.08), 108, 'le calcul de la taxe devrait ajouter 8 pour cent');
assert.strictEqual(typeof priceWithTax(100, 0.08), 'number', 'le résultat devrait être un nombre');
Il existe également assert.notStrictEqual, qui passe lorsque les deux valeurs ne sont pas identiques. Utilisez-le pour confirmer qu'une valeur a changé :
const before = getCacheKey();
refreshCache();
const after = getCacheKey();
assert.notStrictEqual(before, after, 'la clé de cache devrait changer après l\'actualisation');
Pour les objets et les tableaux, strictEqual ne sera pas d'une grande aide. Deux littéraux d'objet avec le même contenu sont des références différentes, donc === renvoie faux. C'est pour cela qu'il y a l'égalité profonde.
Comparaison d'objets : deepStrictEqual
assert.deepStrictEqual(actual, expected) compare la structure et les valeurs de manière récursive. Deux objets passent si chaque clé contient une valeur strictement égale, jusqu'au fond.
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' },
'l\'objet commande devrait correspondre à la forme attendue'
);
C'est la méthode que vous utiliserez le plus souvent pour tester les fonctions qui renvoient des objets, et surtout pour tester les réponses d'API, puisque les corps JSON sont des objets. Son homologue assert.notDeepStrictEqual passe lorsque les structures diffèrent.
Une mise en garde : deepStrictEqual vérifie également les types. Une propriété contenant le nombre 7 ne correspondra pas à une propriété contenant la chaîne de caractères '7'. Cette rigueur est une fonctionnalité ; elle détecte la dérive de type dans vos données. Si vous testez des fonctions avec de nombreuses combinaisons d'entrées, notre guide sur le test d'API axé sur les données avec CSV et JSON montre comment adapter les assertions à travers les ensembles de données.
Lorsque deepStrictEqual échoue, Node affiche un diff qui met en évidence exactement les propriétés qui ne concordent pas. Ce diff est l'une des choses les plus utiles du module. Au lieu de regarder deux grands objets en essayant de repérer la différence, vous lisez quelques lignes surlignées. Pour les données imbriquées, cela seul justifie d'utiliser deepStrictEqual plutôt que de vérifier manuellement chaque champ avec strictEqual.
Correspondance partielle avec assert.match et assert.ok
Toutes les vérifications n'ont pas besoin d'une égalité complète. Parfois, vous vous souciez seulement qu'une valeur semble globalement correcte. assert.ok(value) passe chaque fois que la valeur est vraie (truthy), ce qui est le bon outil pour les vérifications "cela devrait exister" : une chaîne non vide, un objet défini, un nombre non nul.
assert.match(string, regexp) vérifie qu'une chaîne correspond à une expression régulière, et assert.doesNotMatch vérifie l'inverse. Ceux-ci sont utiles pour les valeurs dont le contenu exact varie mais dont la forme est fixe.
const assert = require('node:assert/strict');
function generateOrderId() {
return 'ORD-' + Date.now();
}
const id = generateOrderId();
// l'horodatage exact change, donc affirmer le format, pas la valeur
assert.match(id, /^ORD-\d+$/, 'l\'id de commande devrait être ORD- suivi de chiffres');
assert.ok(id.length > 4, 'l\'id de commande ne devrait pas être vide');
Ce modèle est particulièrement important pour les tests d'API, où les réponses contiennent des horodatages, des identifiants générés et des jetons que vous ne pouvez pas prédire. Vous affirmez le format avec match et l'existence avec ok, et vous réservez strictEqual pour les valeurs que vous contrôlez réellement.
Affirmer qu'un code lève une erreur
Parfois, un comportement correct signifie lever une erreur. assert.throws(fn, expectedError) exécute une fonction et ne passe que si elle lève une erreur.
const assert = require('node:assert/strict');
function parsePort(value) {
const port = Number(value);
if (!Number.isInteger(port) || port < 1 || port > 65535) {
throw new RangeError('le port doit être un entier entre 1 et 65535');
}
return port;
}
// passe : une entrée invalide devrait lever une RangeError
assert.throws(
() => parsePort('70000'),
RangeError,
'un port hors de portée devrait lever une RangeError'
);
// vous pouvez également faire correspondre le message d'erreur avec une regex
assert.throws(
() => parsePort('abc'),
/doit être un entier/,
'un port non numérique devrait lever une erreur descriptive'
);
// passe : une entrée valide ne devrait pas lever d'erreur
assert.doesNotThrow(
() => parsePort('8080'),
'un port valide ne devrait pas lever d\'erreur'
);
Notez que vous passez une fonction, pas un appel. assert.throws(parsePort('70000')) exécuterait parsePort avant qu'assert ne le voie, et l'erreur s'échapperait sans être interceptée. Toujours l'envelopper : () => parsePort('70000').
Assertion sur du code asynchrone : rejects
Le code Node.js moderne est rempli de promesses, et une promesse rejetée est l'équivalent asynchrone d'une erreur levée. assert.rejects et assert.doesNotReject gèrent ce cas. Tous deux renvoient des promesses, vous devez donc les await.
const assert = require('node:assert/strict');
async function fetchUser(id) {
if (typeof id !== 'number') {
throw new TypeError('l\'id doit être un nombre');
}
// ... la recherche réelle se ferait ici
return { id, name: 'Dana Lee' };
}
async function runTests() {
// passe : une mauvaise entrée rejette avec une TypeError
await assert.rejects(
fetchUser('not-a-number'),
TypeError,
'un id de type chaîne de caractères devrait rejeter'
);
// passe : une bonne entrée résout sans rejeter
await assert.doesNotReject(
fetchUser(101),
'un id valide devrait se résoudre proprement'
);
}
runTests();
Oublier d'await un appel à assert.rejects est une erreur courante. Sans await, la fonction de test se termine avant que l'assertion ne soit résolue, et un échec devient un rejet non géré au lieu d'une erreur de test claire.
Utilisation de assert pour tester les réponses d'API
Le module assert est réellement utile pour vérifier la sortie d'une requête HTTP. Après avoir récupéré un point d'accès, vous avez un code d'état et un corps JSON, et les deux sont des éléments sur lesquels faire des assertions.
const assert = require('node:assert/strict');
async function testGetUser() {
const res = await fetch('https://api.example.com/users/101');
// vérifier le code d'état
assert.strictEqual(res.status, 200, 'GET /users/101 devrait renvoyer 200');
const body = await res.json();
// vérifier la forme et les types de la réponse
assert.strictEqual(typeof body.id, 'number', 'l\'id devrait être un nombre');
assert.strictEqual(body.id, 101, 'l\'id devrait correspondre à l\'utilisateur demandé');
assert.ok(body.name, 'la réponse devrait inclure un nom');
assert.ok(Array.isArray(body.roles), 'les rôles devraient être un tableau');
}
testGetUser().then(
() => console.log('Test API réussi'),
(err) => { console.error('Test API échoué :', err.message); process.exitCode = 1; }
);
Ce modèle fonctionne et enseigne les fondamentaux. Mais pour une véritable suite de tests API, vous voudrez des exécutions structurées, des réessais, la gestion des environnements et des rapports que assert brut ne fournit pas. Nos guides sur comment écrire des scripts de test automatisés et le framework d'automatisation d'API pytest couvrent cette étape suivante.
Si vous préférez ne pas construire manuellement un harnais de test, Apidog vous permet de définir des requêtes API et d'attacher des assertions visuelles sur les codes d'état, les en-têtes et les champs JSON sans écrire de code d'assertion. Vous pouvez enchaîner des requêtes dans des scénarios de test automatisés, les exécuter en CI/CD, et toujours utiliser des scripts personnalisés lorsque vous avez besoin du contrôle que assert vous offre. C'est un chemin plus rapide de "J'ai un point d'accès" à "J'ai une suite de tests", et vous pouvez télécharger Apidog et l'utiliser gratuitement. Avec Apidog, le module assert de Node.js couvre à la fois les vérifications rapides et les suites complètes.
Questions fréquemment posées
Dois-je installer le module assert ?
Non. assert est intégré à Node.js. Importez-le avec require('node:assert/strict') ou require('node:assert'). Il n'y a pas de package npm à installer et aucune dépendance à gérer. Le préfixe node: indique explicitement que vous chargez un module central.
Quelle est la différence entre assert.equal et assert.strictEqual ?
En mode hérité, assert.equal utilise l'égalité lâche (==) et assert.strictEqual utilise l'égalité stricte (===). En mode strict, chargé via node:assert/strict, assert.equal se comporte de manière identique à assert.strictEqual. Utilisez toujours le mode strict afin que la conversion de type ne fasse jamais passer un test silencieusement.
Quand dois-je utiliser deepStrictEqual au lieu de strictEqual ?
Utilisez strictEqual pour les primitives : nombres, chaînes de caractères, booléens. Utilisez deepStrictEqual pour les objets et les tableaux, car strictEqual compare les références et deux objets distincts ne sont jamais référentiellement égaux. Chaque fois que vous faites une assertion sur un corps JSON ou un objet retourné, utilisez deepStrictEqual.
Dois-je utiliser le module assert ou un framework de test comme Jest ?
Pour les scripts rapides et l'apprentissage, assert brut est suffisant. Pour une véritable suite de tests, utilisez un framework. Node.js fournit également un exécuteur de tests intégré, node:test, qui se couple naturellement avec assert et vous offre l'organisation des tests, les rapports et le parallélisme sans dépendance externe.
Comment puis-je affirmer qu'une fonction asynchrone rejette ?
Utilisez assert.rejects, et n'oubliez pas de l'await. Passez la promesse ou un appel de fonction asynchrone, éventuellement avec un type d'erreur attendu ou une regex de message. assert.rejects(somePromise, TypeError) passe uniquement si la promesse rejette avec une TypeError. Sans await, un échec devient un rejet non géré plutôt qu'une erreur d'assertion claire.