MSW intercepte les requêtes HTTP au niveau de la couche réseau au lieu de remplacer la fonction fetch ou le module client dans le code de votre application. Le même ensemble de handlers sert les tests dans Node, l'application qui tourne dans un navigateur et les stories dans Storybook. La version actuelle est la 2.15.0, sortie le 8 juillet 2026, sous licence MIT, dépôt mswjs/msw.
Comment fonctionne l'interception
La différence avec le remplacement de modules est mécanique, pas esthétique. Quand un test appelle vi.mock('./api-client') ou affecte votre propre fonction à globalThis.fetch, vous testez du code qui n'est plus le même code. La couche que vous avez remplacée cesse d'exister, avec sa gestion des en-têtes, ses nouvelles tentatives, la sérialisation du corps de requête et l'interprétation des codes de statut. L'application sait qu'elle est testée, car elle a reçu un objet différent de celui qu'elle reçoit en production.
MSW travaille un étage plus bas. Dans le navigateur, il enregistre un Service Worker qui attrape l'événement fetch côté navigateur et renvoie la requête dans la page, où vos handlers s'exécutent et où le résultat revient comme une réponse HTTP ordinaire. Dans Node, il fait la même chose via le paquet @mswjs/interceptors, qui enveloppe le module http intégré, XMLHttpRequest et le fetch global. Dans les deux cas, le code de l'application reste intact : pas de client injecté, pas de branche if (process.env.MOCK), pas de chemin de code qui n'existe que dans les tests.
La conséquence pratique est que vous testez votre vrai client HTTP. Si vous utilisez axios avec un intercepteur qui attache un token, cet intercepteur s'exécute. Si TanStack Query relance après une réponse 500, la nouvelle tentative part réellement et frappe le handler une seconde fois. C'est un avantage et un piège à la fois, car les tests cessent d'être aussi platement déterministes qu'avec une fonction remplacée qui renvoie une valeur fixe.
Ce que MSW ne fait pas mérite d'être dit clairement. Il ne vérifie pas que vos mocks correspondent à ce que le serveur renvoie vraiment. Les handlers sont votre idée de l'API, et les idées vieillissent. Une suite de tests verte construite sur MSW est d'accord avec le contrat tel qu'il était il y a six mois, si personne n'a mis à jour les handlers. Le détecter exige des tests de contrat ou des mocks générés à partir d'un schéma OpenAPI, qui sont des outils distincts.
Version, licence et état du projet
La version 2.15.0 est sortie le 8 juillet 2026, la précédente, 2.14.7, un jour plus tôt. Le dépôt compte environ 18,1 mille étoiles, 617 forks et 41 issues ouvertes, il n'est pas archivé, et le dernier changement sur la branche principale date du 24 juillet 2026. Le registre npm indique un seul mainteneur du paquet, kettanaito, et c'est le risque organisationnel le plus sérieux autour de cette bibliothèque. Il n'y a ni offre payante ni accord de support, le financement passe par GitHub Sponsors, et le projet repose sur une personne plus une poignée de contributeurs.
La licence est un cas rare où trois sources concordent totalement. Le fichier LICENSE.md du dépôt porte le texte MIT avec un copyright détenu par Artem Zakharchenko. Le champ license du registre npm indique MIT. Le paquet publié, 1,24 Mo répartis sur 670 fichiers, livre ce même LICENSE.md à sa racine. La dépendance @mswjs/interceptors, sur laquelle repose tout le côté Node, est elle aussi sous MIT.
Il y a pourtant un détail qui n'apparaît que lorsque vous auditez votre propre dépôt. Le fichier mockServiceWorker.js que MSW copie dans votre répertoire public, et qui atterrit ensuite dans votre dépôt, ne porte aucune mention de licence dans son en-tête. Il n'a qu'un commentaire avec le nom du projet, un lien vers GitHub et une demande de ne pas le modifier. Un scanner de licences qui parcourt votre code verra donc un fichier de plusieurs centaines de lignes d'origine étrangère sans attribution. Si votre entreprise produit une nomenclature logicielle, ajoutez-le à la main ou excluez-le délibérément plutôt que par oubli.
Le poids des dépendances est réel. Le paquet déclare dix-huit dépendances de production, dont graphql en ^16.13.2, yargs, tough-cookie et @inquirer/confirm. Le paquet graphql atterrit dans votre node_modules même si vous ne mockez jamais une seule requête GraphQL. Le champ engines exige Node 18 ou plus récent, et typescript en >= 4.8.x est une dépendance pair marquée optionnelle.
La version 2.15.0 montre aussi des signes d'une refonte prochaine de l'interface. L'option waitUntilReady est marquée dépréciée, le type LifeCycleEventsMap cède la place à HttpNetworkFrameEventMap, et la classe SetupServerCommonApi est dépréciée au profit de l'interface defineNetwork disponible sous le chemin d'export msw/experimental. La bibliothèque est stable à l'usage quotidien, mais si vous planifiez un déploiement plus large, prévoyez un travail de migration à la prochaine version majeure.
Installation et fichier du worker
L'installation tient en deux commandes, et la seconde est celle que tout le monde oublie.
npm install --save-dev msw
# copies mockServiceWorker.js into the given public directory
npx msw init ./public --saveLa commande init prend un chemin de répertoire plus deux options : --save, qui enregistre ce chemin dans votre package.json, et --cwd, qui désigne le répertoire du projet quand vous lancez la commande depuis ailleurs. Le résultat de --save est une entrée qui ressemble à ceci.
{
"name": "my-application",
"msw": {
"workerDirectory": ["public"]
}
}Cette entrée n'est pas cosmétique. Le paquet msw a un script postinstall qui lit le package.json du répertoire désigné par la variable INIT_CWD, cherche la clé msw.workerDirectory, et s'il la trouve, relance init pour rafraîchir le fichier du worker après une mise à jour de la bibliothèque. Sans cette entrée, le script se termine immédiatement et ne fait rien.
C'est de là que vient l'échec le plus courant sur un serveur de build. Installer avec l'option --ignore-scripts, fréquente dans les pipelines d'intégration continue durcis, saute ce script, si bien que le répertoire public garde un worker d'une version plus ancienne. La bibliothèque le détecte d'elle-même : le fichier du worker contient une constante INTEGRITY_CHECKSUM, comparée à la valeur intégrée dans la bibliothèque, et en cas de différence un avertissement dans la console vous dit de relancer init.
Le coût de cet arrangement est exactement celui qu'on imagine. Votre répertoire public contient un fichier supplémentaire servi à /mockServiceWorker.js, qu'il ne faut pas modifier et qui doit vivre dans le dépôt. Un Service Worker s'applique dans le périmètre défini par le répertoire depuis lequel il est servi, donc une application hébergée sous un sous-chemin doit passer sa propre adresse dans l'option serviceWorker.url. L'environnement de test Node n'utilise pas du tout ce fichier, ce qui fait deux chemins de configuration distincts pour un seul ensemble de handlers.
Les handlers, le cœur de la configuration
Les handlers sont partagés entre tous les environnements et vivent dans un seul fichier. Voici un ensemble qui utilise de vrais noms de l'interface 2.15.0.
// src/mocks/handlers.ts
import { http, HttpResponse, graphql, delay, passthrough } from 'msw'
export const handlers = [
http.get('/api/projects/:projectId', ({ params, cookies, request }) => {
if (!cookies.sessionToken) {
return new HttpResponse(null, { status: 401 })
}
return HttpResponse.json({
id: params.projectId,
name: 'Catalogue migration',
ownerId: 'user-42',
updatedAt: '2026-08-19T09:12:00.000Z'
})
}),
http.post('/api/projects', async ({ request }) => {
const payload = (await request.json()) as { name: string }
await delay(120)
return HttpResponse.json({ id: 'project-77', name: payload.name }, { status: 201 })
}),
http.get('/api/reports/export', () => HttpResponse.error(), { once: true }),
graphql.query('ListMembers', () =>
HttpResponse.json({
data: { members: [{ id: 'user-42', role: 'OWNER' }] }
})
),
http.get('https://cdn.example.com/*', () => passthrough())
]Plusieurs choses dans ce code se comportent autrement que l'intuition ne le suggère. Le resolver reçoit un objet avec les champs request, requestId, params et cookies, où params est typé à partir du motif de chemin et cookies est un simple dictionnaire de chaînes. Vous renvoyez un objet Response standard, et la classe HttpResponse n'est qu'une enveloppe pratique avec les méthodes json, text, xml, html, arrayBuffer, formData et error.
L'option { once: true } fait répondre un handler une seule fois, après quoi le handler suivant qui correspond prend le relais. C'est ainsi qu'on teste les nouvelles tentatives : la première échoue, la seconde revient propre. La fonction delay prend un nombre de millisecondes ou l'un des modes real et infinite, ce dernier ne répondant jamais et servant à éprouver les états de chargement. La fonction passthrough laisse une requête atteindre sa vraie destination, ce qui aide pour les ressources statiques et les domaines tiers.
La correspondance des chemins repose sur path-to-regexp version 6, donc :projectId et l'astérisque se comportent comme dans un routeur typique. Un chemin relatif est comparé à l'adresse de la page courante, une adresse absolue est comparée littéralement. Au-delà de http et graphql, la bibliothèque propose aussi ws pour les WebSockets et sse pour les événements envoyés par le serveur.
Node, Vitest et la frontière des tests
Pour les tests qui tournent dans Node, on utilise setupServer depuis le sous-chemin msw/node. Le nom induit en erreur, car rien ici n'écoute sur un port, c'est simplement un interrupteur d'interception.
// src/mocks/node.ts
import { setupServer } from 'msw/node'
import { handlers } from './handlers'
export const server = setupServer(...handlers)// vitest.setup.ts
import { afterAll, afterEach, beforeAll } from 'vitest'
import { server } from './src/mocks/node'
beforeAll(() => {
server.listen({ onUnhandledRequest: 'error' })
})
afterEach(() => {
server.resetHandlers()
})
afterAll(() => {
server.close()
})Définir onUnhandledRequest à error est la décision qui augmente le plus la valeur d'une telle suite. Les valeurs acceptées sont bypass, warn, error et une fonction de rappel personnalisée, avec warn par défaut. Avec warn, une requête qu'aucun handler n'a couverte part vers le vrai réseau, et le test réussit ou échoue selon que la connexion est disponible ou non. Avec error, vous apprenez tout de suite que quelque chose n'est pas mocké.
Pour remplacer une réponse dans un seul test, on utilise server.use, et server.resetHandlers dans afterEach rétablit l'état initial. Quand les tests tournent en parallèle dans un seul processus, resetHandlers seul ne suffit pas, car deux tests peuvent écraser les handlers l'un de l'autre. C'est à cela que sert server.boundary : il enveloppe une fonction et confine les changements réseau à cet appel.
import { expect, test } from 'vitest'
import { http, HttpResponse } from 'msw'
import { server } from './src/mocks/node'
test(
'shows a message when the project list is unavailable',
server.boundary(async () => {
server.use(
http.get('/api/projects/:projectId', () => new HttpResponse(null, { status: 503 }))
)
server.events.on('request:unhandled', ({ request }) => {
console.warn('no handler for', request.url)
})
const response = await fetch('/api/projects/project-77')
expect(response.status).toBe(503)
})
)L'émetteur server.events porte les événements request:start, request:match, request:unhandled, request:end, response:mocked et response:bypass. Pour diagnostiquer un test au comportement étrange, s'abonner à request:unhandled désigne le coupable plus vite que la lecture des logs de l'application. La configuration pour Vitest se résume à nommer le fichier de setup dans le champ setupFiles, et pour les projets en TypeScript, les types sont livrés avec le paquet, sans lot de déclarations séparé.
Navigateur, Storybook et React Native
Dans le navigateur, on utilise setupWorker depuis le sous-chemin msw/browser à la place de setupServer, et le démarrage est asynchrone, car l'enregistrement d'un Service Worker prend un moment.
// src/mocks/browser.ts
import { setupWorker } from 'msw/browser'
import { handlers } from './handlers'
export const worker = setupWorker(...handlers)
// src/main.tsx
async function enableMocking() {
if (process.env.NODE_ENV !== 'development') {
return
}
const { worker } = await import('./mocks/browser')
return worker.start({
onUnhandledRequest: 'bypass',
quiet: false,
serviceWorker: {
url: '/mockServiceWorker.js'
}
})
}
enableMocking().then(() => {
renderApplication()
})La vérification de l'environnement et l'import dynamique ensemble gardent MSW hors du bundle de production. C'est important, car un appel à setupWorker lancé par accident en production interceptera le trafic des vrais utilisateurs. L'option quiet fait taire la journalisation des requêtes interceptées dans la console, et findWorker permet de fournir votre propre fonction de recherche parmi les workers enregistrés quand l'application en a déjà un. L'appel à worker.start renvoie une promesse qu'il faut attendre avant le rendu, sinon les premières requêtes de l'application partent avant que le worker ne soit actif.
Le même couple de fichiers sert Storybook, où worker.start s'exécute une fois dans la configuration de l'aperçu et où chaque story remplace des réponses via worker.use. Un composant React montré dans le catalogue de composants et le même composant dans un test unitaire reçoivent alors des données identiques, sans que deux jeux d'objets d'exemple dérivent l'un de l'autre au bout de quelques semaines.
React Native a son propre sous-chemin msw/native, qui exporte un setupServer adapté à un environnement sans Service Worker. Le paquet expose aussi msw/core/http, msw/core/graphql et msw/core/ws, utiles quand vous construisez votre propre couche utilitaire et préférez ne pas importer toute la racine du paquet.
MSW face aux alternatives
| Outil | Couche d'interception | Où il fonctionne | Mêmes mocks réutilisés ailleurs |
|---|---|---|---|
| MSW | Service Worker dans le navigateur, intercepteurs de modules dans Node | Tests Node, navigateur, Storybook, React Native | oui, un seul fichier de handlers |
| nock | le module http intégré dans Node | Node uniquement | non, ne fonctionne pas dans un navigateur |
page.route dans Playwright | contexte du navigateur piloté par l'outil | tests Playwright uniquement | non |
cy.intercept dans Cypress | une couche de proxy devant le navigateur | tests Cypress uniquement | non |
remplacement de globalThis.fetch | une seule fonction globale | partout où le code appelle fetch directement | en partie, rate les clients HTTP |
| serveur de stub local | un vrai port TCP | partout, une fois l'adresse de base changée | oui, au prix d'un processus et de configuration |
Le choix n'est pas binaire et ces outils ne s'excluent pas. Dans un projet avec des tests unitaires dans Vitest, un catalogue de composants dans Storybook et des tests de navigateur, MSW relie les deux premiers environnements avec un seul ensemble de handlers, tandis que les tests de parcours utilisateur complets se font mieux contre un vrai backend. Si vous n'écrivez qu'un backend Node et ne mockez jamais rien dans un navigateur, nock est plus léger et n'a besoin d'aucun fichier dans un répertoire public.
Le meilleur argument en faveur de MSW apparaît quand le même ensemble de mocks commence à servir plusieurs consommateurs. Une seule source de vérité sur ce que l'API renvoie, au lieu de trois copies divergentes entre les tests, Storybook et le mode de développement sans backend.
Erreurs courantes
La première est un fichier de worker périmé. Après avoir augmenté la version de la bibliothèque, le répertoire public garde l'ancien mockServiceWorker.js, et une installation qui saute les scripts ne le rafraîchira pas. Le symptôme est un avertissement de somme de contrôle différente ou un comportement étrange sur certaines requêtes. Le remède est un nouveau npx msw init ./public --save.
La deuxième est de laisser onUnhandledRequest à sa valeur par défaut. La valeur par défaut est warn, donc une requête non mockée part vers le vrai réseau et le test est lent ou en échec selon l'heure de la journée. Définissez error dans les tests, et en général bypass dans le navigateur pendant le développement.
La troisième est de ne pas attendre worker.start. La méthode renvoie une promesse, et le Service Worker a besoin d'un moment pour s'activer. Rendre l'application avant qu'elle ne soit résolue laisse les premières requêtes échapper aux mocks et finir en 404 du serveur de développement.
La quatrième est de mélanger la portée des handlers entre les tests. Sans server.resetHandlers dans afterEach, un remplacement d'un test se propage au suivant, et avec des tests parallèles il faut aussi server.boundary, car la réinitialisation seule ne sépare pas les états.
La cinquième est de traiter MSW comme une preuve de conformité de l'API. Des tests verts disent seulement que le code fonctionne face à votre idée de la réponse du serveur. Des réponses générées à partir d'un schéma, ou des tests de contrat, sont une protection distincte que cette bibliothèque ne remplace pas.
La sixième est d'oublier la portée du Service Worker pour une application servie depuis un sous-chemin. Le worker ne couvre que les chemins situés sous le répertoire depuis lequel il a été récupéré, donc une application sous une adresse préfixée a besoin d'un serviceWorker.url correct, sinon l'enregistrement réussit alors que l'interception n'a jamais lieu.
FAQ
MSW convient-il à un usage en production ?
Il n'est pas fait pour cela, et le faire tourner en production revient à intercepter le trafic de vrais utilisateurs. Gardez le code de démarrage du worker derrière une vérification d'environnement et un import dynamique pour que la bibliothèque n'entre jamais dans le bundle de production.
En quoi est-ce différent de remplacer fetch dans Vitest ?
Remplacer fetch retire du test toute la couche du client HTTP avec sa logique. MSW la laisse intacte et ne substitue la réponse qu'au niveau réseau, si bien que vos intercepteurs, vos nouvelles tentatives et la gestion des en-têtes s'exécutent tous dans le test. Cette même définition de mock fonctionne ensuite dans le navigateur.
Le fichier du worker doit-il vivre dans le dépôt ?
Oui, mockServiceWorker.js doit se trouver dans le répertoire public et être servi avec l'application, donc il va dans le dépôt. La commande init le rafraîchit, en s'exécutant automatiquement après l'installation quand package.json porte la clé msw.workerDirectory.
MSW fonctionne-t-il avec axios et Apollo Client ?
Oui, car l'interception se fait en dessous de ces bibliothèques. Axios utilise XMLHttpRequest dans le navigateur et le module http dans Node, Apollo Client utilise fetch, et chacune de ces voies est couverte. Les requêtes GraphQL peuvent aussi être décrites avec des handlers graphql.query et graphql.mutation plutôt que d'être associées par adresse.
Que faire quand une requête ne correspond à aucun handler ?
Définissez onUnhandledRequest à error et abonnez-vous à l'événement request:unhandled via server.events.on pour voir l'adresse exacte. Les causes habituelles sont un chemin relatif là où il en fallait un absolu pour une requête inter-domaines, et une faute de frappe dans le nom d'un paramètre de chemin.
L'interface complète est décrite dans la documentation de MSW, avec le code source et les issues dans le dépôt GitHub.