Graba y reproduce llamadas a la API en pruebas de Playwright, incluidas las peticiones del lado del servidor

Graba una vez.
Reproduce para siempre.

Graba las respuestas de la API que recibe tu app durante una ejecución local de Playwright, WebSockets incluidos, y luego las reproduce en CI con tu backend apagado.

npm i -D test-proxy-recorder Dar estrella en GitHub

v2.1.0 · MIT · TypeScript · Node ≥ 20 · SSR de Next.js y TanStack Start, SPAs, extensiones de Chrome, WebSockets

REC · MODE=record · local run

saved todos__adds-a-todo.mock.json

REPLAY · MODE=replay · CI

200 OK · 3 ms · from disk

Míralo grabar y luego reproducir

Una ejecución de Playwright graba respuestas reales en disco; cambia a reproducir y la misma suite pasa con el backend apagado.

Dos formas de grabar

Las peticiones se originan en dos lugares, así que hay dos formas de grabarlas, y el proceso del proxy se ejecuta en ambas. Todo lo que se envía al proxy (fetch del lado del servidor, llamadas del navegador a través de una URL base de la API compartida con el servidor, WebSockets) se reproduce desde el .mock.json de la prueba. Las llamadas del navegador a otros hosts que coinciden con el patrón url de tu fixture se reproducen desde el .har de la prueba.

Proxy

.mock.json

SSR de Next.js / TanStack Start → proxy → API real

Para apps full-stack donde el servidor llama a la API.

Se sitúa entre tu servidor y la API. Graba las peticiones del lado del servidor: los fetch de Server Components y de SSR, los route handlers y cualquier cosa que llame tu backend-for-frontend.

Las peticiones del lado del servidor de cada prueba llevan el id de esa prueba, así que las pruebas que se ejecutan en paralelo nunca comparten una grabación.

HAR

.har

navegador → interceptación HAR → API real

Para SPAs, extensiones y apps solo de navegador.

Intercepta en el propio navegador y guarda un archivo HTTP Archive (HAR). Graba las llamadas fetch del lado del cliente, el tráfico de API de extensiones de Chrome, la analítica y las APIs de terceros, siempre que coincidan con el patrón url de tu fixture.

Frente a routeFromHAR a secas, añade un HAR por prueba y enmascara las cabeceras de autenticación.

Cómo es una grabación

Un archivo por prueba
Cada prueba escribe su propio archivo, con el nombre de la prueba, así que npx playwright test -g "adds a todo" vuelve a grabar solo esa prueba. Las pruebas se graban en workers paralelos igual que se reproducen, salvo que compartan una base de datos o una cuenta.
El id de la prueba
Playwright envía x-test-rcrd-id con cada petición que hace una prueba, y registerProxyFetch() lo copia en los fetch propios de tu servidor. El proxy lo lee para grabar cada prueba en su propio archivo y reproducirla desde ahí, incluso cuando las pruebas se ejecutan en paralelo.
Secretos
Las cabeceras Authorization, Cookie y Set-Cookie pasan a ser [REDACTED] en los archivos .mock.json antes de escribirse, y en los archivos .har cuando termina la ejecución. Para los secretos dentro de los cuerpos de respuesta necesitas patrones propios. Enmascaramiento de secretos →
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
}
]
}
Parte de una grabación real, de 2.6 KB en total: el POST de una prueba, con su cabecera Authorization enmascarada. El archivo completo también contiene el GET que vino después, todas las cabeceras y una marca de tiempo para cada petición.

Dónde encaja

Las herramientas de mocking son buenas para trabajos distintos. La combinación de abajo — grabar tráfico real a través de SSR, navegador y WebSockets, sin mocks escritos a mano — es el hueco que las demás dejan abierto.

Comparación de características de test-proxy-recorder frente a routeFromHAR de Playwright, MSW, Polly.js, playwright-network-cache y Mocky Balboa.
Característicatest-proxy-recorderPlaywright routeFromHARMSWPolly.jsplaywright-network-cacheMocky Balboa
Graba tráfico realSíSíNoSíSíNo
Lado del servidor (SSR)SíNoSíParcialNoSí
Lado del navegadorSíSíSíSíSíSí
WebSocketSíNoSíNoNoNo
Nativo de PlaywrightSíSíSíNoSíSí
MantenidoSíSíSíNoSíSí

Polly.js graba dentro del proceso en el que se ejecuta, así que, para las peticiones del lado del servidor, tiene que ejecutarse dentro del servidor de tu app. MSW y Mocky Balboa también hacen mocking de las peticiones del lado del servidor, pero las respuestas las escribes tú. La comparación completa, con fuentes y cuándo elegir otra herramienta, está en la documentación.

La contrapartida es una primera configuración más laboriosa que con las herramientas solo de navegador: un proceso de proxy se ejecuta junto a tus pruebas y, para las peticiones del lado del servidor, la URL base de la API de tu app apunta a él durante las ejecuciones de prueba.

Funciona con tu proveedor de auth real

Inicia sesión a través de Cognito, Auth0, Clerk o WorkOS — de verdad, en cada ejecución. Solo se graba la API de tu app; la auth se mantiene en vivo y tus datos quedan sin conexión.

// 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' });
});

Inicio rápido

Genera todo el andamiaje con un solo comando, apunta tu API al proxy, luego graba y haz commit. ¿App solo de navegador? init se salta el paso de SSR por ti.

Qué cambia en tu repo

  • En tu suite de pruebas: un fixture de Playwright, el proceso del proxy (solo se ejecuta durante las pruebas) y las grabaciones, versionadas en git.
  • En tu app, solo para las peticiones del lado del servidor: apunta la URL base de la API al proxy durante las ejecuciones de prueba y llama a registerProxyFetch() una vez, en app/layout.tsx en Next.js o en src/router.tsx en TanStack Start. Copia el id de la prueba en cada fetch del lado del servidor y no hace nada en producción salvo que TEST_PROXY_RECORDER_ENABLED esté definida.
  • Con el prompt para el agente: @tanstack/intent añade al archivo de configuración de tu agente, como CLAUDE.md, una guía para cargar las skills de esta librería.
  • ¿Pruebas un entorno desplegado? HAR graba sus llamadas del navegador sin cambios en la app, pero las páginas en sí siguen cargándose desde ese servidor. Para reproducir también las llamadas del lado del servidor, ejecuta la app en CI junto al proxy.

Pega esto en Claude Code, Cursor u otro agente de codificación. Primero ejecuta @tanstack/intent, que añade una guía al archivo de configuración de tu agente, como CLAUDE.md, para que el agente cargue las skills de configuración de esta librería. Después instala el paquete, busca la URL de tu backend en la configuración de la app, ejecuta init y termina el cableado a partir de su salida.

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.

Guía de configuración completa →

Preguntas sobre la reproducción

¿Cómo se emparejan las peticiones?
El proxy empareja una llamada del lado del servidor por su método, su ruta, su cadena de consulta (query string) exacta y su cuerpo, así que las llamadas enviadas en paralelo reciben cada una su propia respuesta, y sirve las llamadas repetidas en el orden en que se grabaron. Las llamadas del navegador se emparejan también por método, URL y cuerpo. Una cadena de consulta o un cuerpo que cambia en cada ejecución, como una marca de tiempo, nunca coincide, y no hay ninguna opción para ignorar un valor, así que mantén esos valores fijos durante las pruebas. Cómo se emparejan las peticiones al reproducir →
¿Y si falta una grabación?
El proxy responde con un 404 que indica la petición y la prueba. Una llamada que se hace más veces de las que se grabó recibe de nuevo la última respuesta, con un aviso en el log del proxy. En el navegador, Playwright aborta una llamada que coincide con el patrón url que tu fixture pasa a before() pero que no está en el HAR; las demás llamadas llegan a la red.
¿Cuándo llega la reproducción a la API real?
La reproducción solo llega a la API real cuando el proxy sale del modo replay, y el proxy mantiene un único modo para todas las pruebas en curso. Sale del modo replay 120 segundos después del inicio de la última prueba, o cuando un hook por prueba llama a teardown(). Sin un backend en ejecución en CI, una petición que llegue a la API real falla en lugar de pasar. Timeout de sesión y teardown →
¿Qué pasa cuando cambia la API?
Con un cliente de API tipado, actualizar el cliente por un campo que ha cambiado hace fallar las pruebas reproducidas que lo usan, porque las grabaciones aún contienen el campo antiguo. Eso te señala el cambio, y volver a grabar arregla las pruebas con menos trabajo que editar mocks escritos a mano.
¿Cómo pruebo errores y casos límite?
En el navegador, un page.route() registrado después de before() tiene prioridad sobre la grabación. Las respuestas del lado del servidor se editan en el archivo .mock.json. Forzar una respuesta →

Deja de escribir mocks a mano

Tu API ya da las respuestas correctas. Grábalas.

npm i -D test-proxy-recorder Dar estrella en GitHub

Si te ahorró una tarde, una estrella cuesta un segundo — así es como la encuentra la siguiente persona, y le dice a un mantenedor en solitario que siga construyendo. ¿Topaste con un problema o tienes una idea? Abre un issue o únete a Discord.