Grave uma vez.
Reproduza para sempre.

Configure em três passos

Gere tudo com um comando, aponte sua API para o proxy, depois grave e faça commit. Aplicação somente de navegador? init pula a etapa de SSR para você.

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.

Ou configure à mão:

1. Instale e gere

   init escreve a config do proxy, uma fixture do Playwright, um teardown global e os scripts de package.json e (no Next.js) conecta a marcação das buscas SSR ao seu root layout — de forma não destrutiva.

   npm install --save-dev test-proxy-recorder
   # http://localhost:3002 is your API endpoint; 8100 is the proxy. Flags are optional.
   npx test-proxy-recorder init http://localhost:3002 --port 8100 --dir ./e2e/recordings

2. Aponte a API da sua aplicação para o proxy

   A única coisa que o init não consegue adivinhar: qual variável de ambiente guarda a URL base da sua API. Aponte-a para o proxy quando o recorder estiver habilitado e para o backend real caso contrário — o proxy nunca roda em produção.

   // Point your app at the proxy when the recorder is enabled, at the real backend otherwise.
   // The proxy never runs in production — TEST_PROXY_RECORDER_ENABLED is set only for e2e.
   const API_BASE =
     process.env.NODE_ENV === 'production' && !process.env.TEST_PROXY_RECORDER_ENABLED
       ? 'https://api.example.com'
       : 'http://localhost:8100'; // proxy address from `init`
   
   const res = await fetch(`${API_BASE}/todos`);

   No Next.js, o init também adiciona registerProxyFetch() ao seu root layout para marcar as chamadas fetch do lado do servidor — um no-op em produção:

   // app/layout.tsx — tag server-side fetches so SSR is recorded/replayed
   import { registerProxyFetch } from 'test-proxy-recorder/nextjs';
   
   registerProxyFetch(); // no-op in production unless TEST_PROXY_RECORDER_ENABLED=true

3. Grave, faça commit, reproduza

   Defina MODE = 'record', execute uma vez contra a API real, depois mude para 'replay' e faça commit. As gravações vivem no git — é isso que torna a CI determinística. Não as coloque no .gitignore.

   import { test, expect } from '@playwright/test';
   import { playwrightProxy } from 'test-proxy-recorder';
   
   // Full-stack: the browser also talks to the proxy, so match its URL.
   // (Browser-only app? Match your real API domain instead, e.g. /api\.example\.com/.)
   const CLIENT_SIDE_URL = /localhost:8100/;
   
   // 'record' hits the real API and saves responses.
   // 'replay' serves them from disk — no network needed.
   const MODE = 'replay' as const;
   
   test.beforeEach(async ({ page }, testInfo) => {
     await playwrightProxy.before(page, testInfo, MODE, { url: CLIENT_SIDE_URL });
   });
   
   test('homepage loads', async ({ page }) => {
     await page.goto('/');
     await expect(page.getByText('Welcome')).toBeVisible();
   });

   # 1. Set MODE = 'record' in your test file, run against the real API
   npx playwright test --ui       # recordings written to e2e/recordings/
   
   # 2. Flip MODE back to 'replay' and commit the recordings
   git add e2e/recordings/
   git commit -m "add e2e recordings"