Record once.
Replay forever.

Set up in three steps

Scaffold everything with one command, point your API at the proxy, then record and commit. Browser-only app? initskips the SSR step for you.

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.

Or wire it up by hand:

1. Install & scaffold

   init writes the proxy config, a Playwright fixture, a global teardown,package.json scripts, and (on Next.js) wires SSR fetch tagging into your root layout — non-destructively.

   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. Point your app's API at the proxy

   The one thing initcan't guess: which env var holds your API base URL. Point it at the proxy when the recorder is enabled, at the real backend otherwise — the proxy never runs in production.

   // 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`);

   On Next.js, initalso adds registerProxyFetch()to your root layout to tag server-side fetchcalls — a no-op in production:

   // 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. Record, commit, replay

   Set MODE = 'record', run once against the real API, then flip to 'replay'and commit. Recordings live in git — that's what makes CI deterministic. Don't gitignore them.

   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"