Nock : Mocker les requêtes HTTP en Node.js (avec une alternative sans code)

Si vos tests Node.js échouent parce qu'une API tierce est hors service, lente ou soumise à des limites de débit, vous n'avez pas un problème de code. Vous avez un problème de dépendance. La solution consiste à simuler la couche HTTP pour que vos tests unitaires s'exécutent de la même manière à chaque fois, et nock est le package npm vers lequel la plupart des développeurs Node se tournent. Ce guide explique ce qu'est nock, présente un petit exemple fonctionnel et indique où un serveur de maquette partagé est plus approprié que l'interception en cours de processus. Pour la référence complète de la bibliothèque, le dépôt GitHub de nock est la source de vérité.

Qu'est-ce que nock ?

nock est une bibliothèque de simulation et d'attentes de serveur HTTP pour Node.js. Elle fonctionne en surchargeant les modules http et https de Node à l'exécution, de sorte que toute requête sortante effectuée par votre code peut être interceptée et traitée avec une réponse préenregistrée. Rien ne quitte votre machine. L'appel réseau ne se produit jamais.

C'est important pour les tests unitaires. Lorsque vous testez une fonction qui appelle une API externe, vous ne voulez pas solliciter le service réel. Les appels réels sont lents, ils coûtent de l'argent, ils peuvent échouer pour des raisons non liées à votre code, et ils rendent votre suite de tests non déterministe. nock vous permet de dire : « quand mon code fait une requête GET à cette URL, renvoie ce JSON exact avec ce code de statut. » Votre test vérifie ensuite comment votre fonction gère cette réponse.

nock est spécifique à Node.js. Il s'intègre à la pile HTTP native, il fonctionne donc avec fetch, axios, got, node-fetch et tout autre élément construit sur http/https. Il compte des millions de téléchargements hebdomadaires et est un choix par défaut pour les tests de backend depuis des années. Vous l'installez en tant que dépendance de développement car il ne s'exécute que dans les tests, jamais en production.

Un petit exemple de nock

Supposons que vous ayez une fonction qui récupère un utilisateur depuis une API. Voici la fonction :

// user-service.js
export async function getUser(id) {
  const res = await fetch(`https://api.example.com/users/${id}`);
  if (!res.ok) throw new Error(`Request failed: ${res.status}`);
  return res.json();
}

Voici maintenant un test qui utilise nock pour intercepter la requête :

// user-service.test.js
import nock from 'nock';
import { getUser } from './user-service.js';

test('returns the user when the API responds', async () => {
  nock('https://api.example.com')
    .get('/users/42')
    .reply(200, { id: 42, name: 'Ada Lovelace' });

  const user = await getUser(42);
  expect(user).toEqual({ id: 42, name: 'Ada Lovelace' });
});

Lisez-le de haut en bas. nock('https://api.example.com') définit l'hôte que vous souhaitez intercepter. .get('/users/42') correspond à la méthode et au chemin. .reply(200, {...}) définit le statut et le corps à renvoyer. Lorsque getUser(42) s'exécute, l'appel réseau réel est remplacé et votre réponse préenregistrée est renvoyée à la place.

Vous pouvez simuler des erreurs de la même manière, c'est la partie que les gens oublient de tester :

test('throws when the API returns 500', async () => {
  nock('https://api.example.com')
    .get('/users/99')
    .reply(500);

  await expect(getUser(99)).rejects.toThrow('Request failed: 500');
});

Tester le chemin d'échec est l'endroit où la simulation prend tout son sens. Vous ne pouvez pas faire en sorte qu'une API en direct renvoie de manière fiable une erreur 500 à la demande, mais vous pouvez en simuler une en une seule ligne. Si la simulation d'erreurs est votre objectif principal, ce guide sur la façon de simuler une réponse d'erreur interne du serveur 500 approfondit le sujet.

Fonctionnalités utiles de nock à connaître

Quelques méthodes reviennent constamment une fois que vous maîtrisez les bases.

• .persist() maintient un intercepteur actif sur plusieurs appels. Par défaut, nock supprime un intercepteur après qu'il ait été mis en correspondance une fois, ce qui est excellent pour affirmer qu'une requête s'est produite exactement une seule fois. Utilisez .persist() lorsque le même point de terminaison est sollicité à plusieurs reprises dans un même test.
• .times(n) met en correspondance la même requête un nombre défini de fois avant que l'intercepteur n'expire.
• .delay(ms) simule une réponse lente pour que vous puissiez tester la gestion des délais d'attente.
• La correspondance par RegExp permet à l'hôte ou au chemin d'être un motif au lieu d'une chaîne fixe, utile lorsque les identifiants ou les chaînes de requête varient.
• nock.cleanAll() efface tous les intercepteurs. Exécutez-le entre les tests pour que les simulations d'un test ne s'immiscent pas dans le suivant.

Une habitude à prendre tôt : assurez-vous que toutes vos maquettes ont bien été utilisées. Appelez scope.done() sur un intercepteur (ou nock.isDone()) et le test échoue si une requête attendue n'a jamais été déclenchée. Cela transforme un appel manqué silencieux en un échec retentissant.

Quand nock cesse d'être le bon outil

nock est conçu pour une tâche et l'exécute bien : intercepter le HTTP au sein d'un seul processus Node pendant les tests automatisés. Dès que votre besoin dépasse les limites d'un processus, ce modèle commence à montrer ses limites.

Voici la limitation. Les maquettes nock vivent à l'intérieur de votre fichier de test, dans votre environnement d'exécution, dans votre langage. Un développeur front-end ne peut pas pointer son navigateur vers votre configuration nock. Un ingénieur mobile ne peut pas l'atteindre depuis un simulateur. Votre équipe QA ne peut pas effectuer de vérifications manuelles dessus. Une collection Postman ne peut pas l'atteindre. La maquette n'existe que tant que votre processus Jest ou Mocha est en cours d'exécution, et seulement pour le code dans ce même processus.

C'est parfait pour les tests unitaires et c'est exactement pour cela que nock est conçu. Mais de nombreuses situations réelles nécessitent une maquette qui réside quelque part où tout le monde peut l'atteindre :

• Le front-end a besoin de développer en s'appuyant sur un point de terminaison avant que le back-end n'existe.
• Trois équipes dans des dépôts différents doivent s'entendre sur les mêmes fausses réponses.
• Vous voulez présenter une intégration sans un backend réel.
• Un testeur veut explorer des cas limites manuellement, sans code nécessaire.

Pour ces cas, vous voulez un serveur de maquette, quelque chose qui écoute sur une URL réelle et renvoie des réponses à quiconque l'appelle. Si vous comparez les deux idées, serveur de maquette vs serveur réel et l'explication plus large sur la simulation d'API présentent tous deux les compromis.

nock vs un serveur de maquette hébergé (Apidog)

Pensez-y comme deux couches plutôt qu'une compétition. nock gère l'interception dans le code pour les tests unitaires. Un outil comme Apidog vous offre un serveur de maquette partagé et basé sur un schéma pour tout ce qui se passe en dehors d'un seul processus de test. De nombreuses équipes utilisent les deux.

Apidog génère un serveur de maquette directement à partir de la conception de votre API. Vous définissez un point de terminaison et son schéma, et Apidog sert des réponses réalistes à une URL en direct, avec des règles de simulation intelligentes qui produisent des données plausibles à partir des noms et types de champs. Pas de harnais de test, pas de configuration par test, pas de verrouillage linguistique. Toute personne disposant de l'URL obtient les mêmes réponses.

Pour être clair sur la portée : Apidog ne remplace pas nock dans vos tests unitaires Jest ou Mocha. Si vous avez besoin d'intercepter un appel fetch dans un seul test et d'affirmer le résultat, nock reste le bon outil. Apidog intervient lorsque la maquette nécessite une adresse que d'autres personnes et d'autres outils peuvent atteindre. Pour un aperçu pratique côté serveur, consultez le guide pratique sur la simulation d'une API pour les tests. Vous pouvez télécharger Apidog et lancer une maquette à partir d'un fichier OpenAPI existant en quelques minutes.

Autres alternatives à nock

nock n'est pas la seule bibliothèque dans ce domaine, et le bon choix dépend de l'endroit où votre code s'exécute.

• MSW (Mock Service Worker) intercepte les requêtes au niveau du réseau en utilisant un service worker dans le navigateur et un intercepteur Node sur le serveur. Les mêmes définitions de maquette fonctionnent dans les deux cas, c'est pourquoi de nombreuses équipes l'utilisent par défaut pour le JavaScript full-stack. La documentation officielle de MSW explique le modèle.
• Les simulations manuelles de Jest vous permettent de remplacer un module comme axios par un faux. C'est plus simple que nock pour un petit cas, mais cela vous lie à un seul client HTTP. Le tutoriel de simulation Jest couvre ce modèle.
• Les doubles de test intégrés dans le propre exécuteur de tests de Node ou des bibliothèques comme Sinon peuvent simuler la fonction qui effectue l'appel, bien que vous perdiez la correspondance au niveau HTTP de nock.

La question décisive est toujours la même. Testez-vous la logique au sein d'un seul processus, ou avez-vous besoin d'une fausse API qui réside sur le réseau ? nock et MSW répondent à la première question. Un serveur de maquette hébergé répond à la seconde.

Questions fréquentes

nock est-il gratuit ?

Oui. nock est open source sous licence MIT et peut être installé gratuitement depuis npm. Vous l'ajoutez en tant que dépendance de développement et l'utilisez dans votre suite de tests sans frais.

nock fonctionne-t-il avec fetch et axios ?

Oui. Parce que nock intercepte au niveau de la couche http/https de Node, il fonctionne avec n'importe quel client construit sur ces modules, y compris les natifs fetch, axios, got et node-fetch. Vous écrivez le même intercepteur quelle que soit celui que votre code utilise.

Puis-je utiliser nock dans le navigateur ?

Non. nock est uniquement pour Node.js car il patch les modules HTTP de Node, qui n'existent pas dans le navigateur. Pour la simulation côté navigateur, utilisez MSW ou dirigez votre front-end vers un serveur de maquette hébergé. Cet aperçu des API de simulation en JavaScript explore les options pour le navigateur.

Quelle est la différence entre nock et un serveur de maquette ?

nock intercepte les requêtes au sein de votre processus de test et n'ouvre jamais de port réel. Un serveur de maquette écoute sur une URL réelle que tout client peut appeler. Utilisez nock pour les tests unitaires ; utilisez un serveur de maquette lorsque le front-end, l'assurance qualité ou d'autres équipes ont besoin d'atteindre les mêmes fausses réponses.

En résumé

nock est le choix fiable pour la simulation HTTP dans les tests unitaires Node.js. Il intercepte les requêtes sortantes en cours de processus, renvoie les réponses que vous définissez, et rend votre suite de tests rapide et déterministe, y compris les chemins d'erreur que vous ne pouvez pas déclencher contre une API en direct. Continuez à l'utiliser pour cela.

Lorsque la maquette doit quitter votre fichier de test, lorsque le front-end, l'assurance qualité ou une autre équipe doit atteindre le même point de terminaison, optez plutôt pour un serveur de maquette partagé. Apidog en génère un à partir de votre schéma d'API et sert des données réalistes à une URL en direct, afin que tout le monde développe selon le même contrat avant que le backend ne soit prêt. Téléchargez Apidog et transformez votre spécification OpenAPI en une maquette fonctionnelle en quelques minutes.