Enregistrer et rejouer les appels d'API dans les tests Playwright, y compris les requêtes côté serveur

Enregistrez une fois.
Rejouez pour toujours.

Enregistre les réponses d'API que votre app reçoit pendant une exécution Playwright en local, WebSockets compris, puis les rejoue en CI avec votre backend éteint.

npm i -D test-proxy-recorder Mettre une étoile sur GitHub

v2.1.0 · MIT · TypeScript · Node ≥ 20 · SSR Next.js & TanStack Start, SPA, extensions Chrome, WebSockets

REC · MODE=record · local run

saved todos__adds-a-todo.mock.json

REPLAY · MODE=replay · CI

200 OK · 3 ms · from disk

Voyez-le enregistrer, puis rejouer

Une exécution Playwright enregistre de vraies réponses sur le disque ; basculez en rejeu et la même suite passe avec le backend éteint.

Deux façons d'enregistrer

Les requêtes partent de deux endroits, il y a donc deux façons de les enregistrer, et le processus du proxy tourne dans les deux cas. Tout ce qui est envoyé au proxy (fetches côté serveur, appels du navigateur via une URL de base d'API partagée avec le serveur, WebSockets) est rejoué depuis le .mock.json du test. Les appels du navigateur vers d'autres hôtes qui correspondent au motif url de votre fixture sont rejoués depuis le .har du test.

Proxy

.mock.json

SSR Next.js / TanStack Start → proxy → vraie API

Pour les apps full-stack où le serveur appelle l'API.

Se place entre votre serveur et l'API. Enregistre les requêtes côté serveur : fetches des Server Components et du SSR, route handlers, tout ce que votre backend-for-frontend appelle.

Les requêtes côté serveur de chaque test portent l'id de ce test, donc des tests exécutés en parallèle ne partagent jamais un enregistrement.

HAR

.har

navigateur → interception HAR → vraie API

Pour les SPA, les extensions et les apps uniquement navigateur.

Intercepte dans le navigateur lui-même et sauvegarde un fichier HTTP Archive (HAR). Enregistre les appels fetch côté client, le trafic des API d'extensions Chrome, l'analytics et les API tierces, dès lors qu'ils correspondent au motif url de votre fixture.

Par rapport à un simple routeFromHAR, il ajoute un HAR par test et masque les en-têtes d'authentification.

À quoi ressemble un enregistrement

Un fichier par test
Chaque test écrit son propre fichier, nommé d'après le test, donc npx playwright test -g "adds a todo" ne réenregistre que celui-là. Les tests s'enregistrent sur des workers en parallèle, comme pour le rejeu, sauf s'ils partagent une même base de données ou un même compte.
L'id du test
Playwright envoie x-test-rcrd-id avec chaque requête d'un test, et registerProxyFetch() le recopie sur les fetches que fait votre serveur. Le proxy le lit pour enregistrer chaque test dans son propre fichier et le rejouer depuis ce fichier, même quand les tests tournent en parallèle.
Secrets
Les en-têtes Authorization, Cookie et Set-Cookie deviennent [REDACTED] dans les fichiers .mock.json avant leur écriture, et dans les fichiers .har à la fin de l'exécution. Les secrets contenus dans les corps de réponse demandent vos propres motifs. Masquage des secrets →
e2e/recordings/todos__adds-a-todo.mock.json
{
"id": "todos__adds-a-todo",
"recordings": [
{
"request": {
"method": "POST",
"url": "/todos",
"headers": {
"authorization": "[REDACTED]",
"x-test-rcrd-id": "todos__adds-a-todo"
},
"body": "{\"title\":\"Buy groceries\"}"
},
"response": {
"statusCode": 201,
"body": "{\"id\":7,\"title\":\"Buy groceries\",\"done\":false}"
},
"key": "POST_todos.json",
"sequence": 0
}
]
}
Extrait d'un vrai enregistrement, 2.6 KB au total : le POST d'un test, avec son en-tête Authorization masqué. Le fichier complet contient aussi le GET qui a suivi, tous les en-têtes et un horodatage pour chaque requête.

Où il se situe

Les outils de mocking excellent à des tâches différentes. La combinaison ci-dessous — enregistrer du trafic réel à travers le SSR, le navigateur et les WebSockets, sans mocks écrits à la main — est le vide que les autres laissent ouvert.

Comparaison des fonctionnalités de test-proxy-recorder avec Playwright routeFromHAR, MSW, Polly.js, playwright-network-cache et Mocky Balboa.
Fonctionnalitétest-proxy-recorderPlaywright routeFromHARMSWPolly.jsplaywright-network-cacheMocky Balboa
Enregistre le trafic réelOuiOuiNonOuiOuiNon
Côté serveur (SSR)OuiNonOuiPartielNonOui
Côté navigateurOuiOuiOuiOuiOuiOui
WebSocketOuiNonOuiNonNonNon
Natif PlaywrightOuiOuiOuiNonOuiOui
MaintenuOuiOuiOuiNonOuiOui

Polly.js enregistre dans le processus où il s'exécute : pour les requêtes côté serveur, il doit donc tourner dans le serveur de votre app. MSW et Mocky Balboa mockent aussi les requêtes côté serveur, mais vous écrivez les réponses vous-même. La comparaison complète, avec les sources et les cas où choisir un autre outil, se trouve dans les docs.

La contrepartie est une première mise en place plus lourde qu'avec les outils limités au navigateur : un processus proxy tourne à côté de vos tests et, pour les requêtes côté serveur, l'URL de base de l'API de votre app pointe vers lui pendant les tests.

Fonctionne avec votre vrai fournisseur d'authentification

Connectez-vous via Cognito, Auth0, Clerk ou WorkOS — pour de vrai, à chaque exécution. Seule l'API de votre app est enregistrée ; l'authentification reste en direct, vos données passent hors ligne.

// e2e/auth.setup.ts — log in for real, once. Never recorded.
import { test as setup } from '@playwright/test';
import { setProxyMode } from 'test-proxy-recorder';
setup('authenticate', async ({ page }) => {
await setProxyMode('transparent'); // login bypasses the recorder
await page.goto('/login');
await page.getByTestId('email').fill(process.env.TEST_EMAIL!);
await page.getByTestId('password').fill(process.env.TEST_PASSWORD!);
await page.getByTestId('signinButton').click();
await page.waitForURL('/dashboard');
// Reused by every test — they start already signed in.
await page.context().storageState({ path: 'e2e/.auth/state.json' });
});

Démarrage rapide

Scaffoldez tout avec une commande, pointez votre API vers le proxy, puis enregistrez et committez. App uniquement navigateur ? init saute l'étape SSR pour vous.

Ce qui change dans votre dépôt

  • Dans votre suite de tests : une fixture Playwright, le processus du proxy (il ne tourne que pendant les tests) et des enregistrements committés dans git.
  • Dans votre app, uniquement pour les requêtes côté serveur : pointez l'URL de base de l'API vers le proxy pendant les tests, et appelez registerProxyFetch() une fois, dans app/layout.tsx sur Next.js ou src/router.tsx sur TanStack Start. Il recopie l'id du test sur chaque fetch côté serveur et ne fait rien en production, sauf si TEST_PROXY_RECORDER_ENABLED est défini.
  • Avec le prompt pour agent : @tanstack/intent ajoute au fichier de configuration de votre agent, par exemple CLAUDE.md, des consignes pour charger les skills de cette bibliothèque.
  • Vous testez un environnement déployé ? HAR enregistre ses appels navigateur sans aucun changement dans l'app, mais les pages elles-mêmes se chargent toujours depuis ce serveur. Pour rejouer aussi les appels côté serveur, lancez l'app en CI à côté du proxy.

Collez ceci dans Claude Code, Cursor ou un autre agent de codage. Il lance d'abord @tanstack/intent, qui ajoute des consignes au fichier de configuration de votre agent, par exemple CLAUDE.md, pour que l'agent charge les skills de configuration de cette bibliothèque. Ensuite, il installe le paquet, trouve l'URL de votre backend dans la configuration de l'app, lance init et termine le branchement à partir de sa sortie.

Set up test-proxy-recorder for end-to-end tests in this project, then follow the instructions that `init` prints. Run these commands:
npx @tanstack/intent@latest install
npm install --save-dev test-proxy-recorder
Then run init, passing this project's backend API base URL as the target — find it yourself from the app's env/config (the URL the app calls in dev); don't assume the default:
npx test-proxy-recorder init <your-backend-api-url> --port 8100 --dir ./e2e/recordings
Then complete the app-specific steps init prints: point the app's API base URL at the proxy in dev/test only, tag server-side fetches (Next.js), add a smoke test, and verify record → replay.

Guide de configuration complet →

Questions sur le rejeu

Comment les requêtes sont-elles mises en correspondance ?
Le proxy met en correspondance un appel côté serveur selon sa méthode, son chemin, sa query string exacte et son corps, si bien que des appels envoyés en parallèle reçoivent chacun leur propre réponse, et sert les appels répétés dans l'ordre où ils ont été enregistrés. Les appels du navigateur sont eux aussi mis en correspondance selon la méthode, l'URL et le corps. Une query string ou un corps qui change à chaque exécution, comme un horodatage, ne correspond jamais, et aucune option ne permet d'ignorer une valeur : gardez donc ces valeurs fixes pendant les tests. Correspondance des requêtes en rejeu →
Et si un enregistrement manque ?
Le proxy répond 404 en nommant la requête et le test. Un appel fait plus de fois qu'il n'a été enregistré reçoit de nouveau la dernière réponse, avec un avertissement dans le log du proxy. Dans le navigateur, Playwright interrompt un appel qui correspond au motif url que votre fixture passe à before() mais qui n'est pas dans le HAR ; les autres appels atteignent le réseau.
Quand le rejeu atteint-il la vraie API ?
Le rejeu n'atteint la vraie API qu'une fois que le proxy a quitté le mode rejeu, et le proxy garde un seul mode pour tous les tests en cours. Il quitte le mode rejeu 120 secondes après le démarrage du dernier test, ou quand un hook par test appelle teardown(). Sans backend lancé en CI, un tel appel échoue au lieu de passer. Timeout de session et teardown →
Que se passe-t-il quand l'API change ?
Avec un client d'API typé, mettre à jour le client pour un champ modifié fait échouer les tests rejoués qui l'utilisent, car les enregistrements contiennent encore l'ancien champ. Cela vous indique ce qui a changé, et réenregistrer corrige les tests avec moins de travail que de modifier des mocks écrits à la main.
Comment tester les erreurs et les cas limites ?
Dans le navigateur, un page.route() ajouté après before() a priorité sur l'enregistrement. Les réponses côté serveur se modifient dans le fichier .mock.json. Forcer une réponse →

Arrêtez d'écrire des mocks à la main

Votre API donne déjà les bonnes réponses. Enregistrez-les.

npm i -D test-proxy-recorder Mettre une étoile sur GitHub

Si ça vous a épargné un après-midi, une étoile prend une seconde — c'est ainsi que la prochaine personne le trouve, et cela dit à un mainteneur solo de continuer à construire. Vous avez un souci ou une idée ? Ouvrir une issue ou rejoindre Discord.