Quick start
Set up with an AI agent (recommended)
Section titled “Set up with an AI agent (recommended)”Copy this and paste it into your AI coding agent (Claude Code, Cursor, …):
Set up test-proxy-recorder for end-to-end tests in this project, then follow theinstructions that `init` prints. Run these commands:
npm install --save-dev test-proxy-recorder npx @tanstack/intent@latest install
Then run init, passing this project's backend API base URL as the target — findit yourself from the app's env/config (the URL the app calls in dev); don'tassume 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 atthe proxy in dev/test only, tag server-side fetches (Next.js), add a smoke test,and verify record → replay.The agent adds the skills, scaffolds everything with init (config, Playwright fixture, teardown, scripts, and — on Next.js — registerProxyFetch() in your root layout), then finishes the wiring init can’t guess from the prompt init prints. Want a finished setup to copy from? See the examples.
Or wire it by hand
Section titled “Or wire it by hand”init writes everything and overwrites nothing:
test-proxy-recorder.config.tsplaywright.config.tsapp/layout.tsx # Next.js only — adds registerProxyFetch() to tag SSR fetchese2e/fixtures.ts # record vs replaye2e/global-teardown.tspackage.json # + proxy / test:e2e scripts1. Point your app’s API at the proxy
Section titled “1. Point your app’s API at the proxy”The one thing init can’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:
// TEST_PROXY_RECORDER_ENABLED is 'true' or '1' for the e2e run only.const recorderEnv = process.env.TEST_PROXY_RECORDER_ENABLED ?? '';const API_BASE = ['true', '1'].includes(recorderEnv) ? 'http://localhost:8100' // proxy address from `init` : 'https://api.example.com';2. Tag server-side fetches (Next.js only)
Section titled “2. Tag server-side fetches (Next.js only)”Browser requests already carry the recording-session id (Playwright sets it). For server-side fetches (SSR, Server Components), add one line to your root layout so they’re tagged too — init does this for you:
import { registerProxyFetch } from 'test-proxy-recorder/nextjs';
registerProxyFetch(); // no-op in production unless TEST_PROXY_RECORDER_ENABLED=true
export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en"> <body>{children}</body> </html> );}Using axios for server-side calls? Use registerProxyAxios(instance) instead. Record against a production build (next build && next start), not next dev. Browser-only apps (SPA, extension) can skip this step.
3. Record once, replay forever
Section titled “3. Record once, replay forever”Tests use your dev backend and its database. The test:e2e scripts test a production build of the app when init found one (a preview script, or Next.js start), and a plain npx playwright test or --ui uses your dev server, so you can rerun a failing test by hand and reproduce the bug in the browser. Before recording, start dev and put the dev database in the state the tests expect with your own seed script.
# Sets RECORD_MODE=1 — capture real responsesnpm run test:e2e:record
# Then commit the recordings; npm run test:e2e replays themgit add e2e/recordings/ && git commit -m "add e2e recordings"CI now replays with the backend off — same responses every time.
More detail: manual setup · how it works · AI agent skills.