Skip to content

Quick start

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 the
instructions 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 — 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.

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.

init writes everything and overwrites nothing:

test-proxy-recorder.config.ts
playwright.config.ts
app/layout.tsx # Next.js only — adds registerProxyFetch() to tag SSR fetches
e2e/fixtures.ts # record vs replay
e2e/global-teardown.ts
package.json # + proxy / test:e2e scripts

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';

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:

app/layout.tsx
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.

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.

Terminal window
# Sets RECORD_MODE=1 — capture real responses
npm run test:e2e:record
# Then commit the recordings; npm run test:e2e replays them
git 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.