test-proxy-recorder

VCR for Playwright. Record real API responses once, replay them deterministically on CI. Covers Next.js SSR, browser, and WebSocket traffic — no backend, no hand-written mocks.

The proxy records real API responses during a test run, then replays them on CI. Tests stay fast and deterministic, and you never maintain mock fixtures by hand.

The footprint is small: one dev-dependency and a lightweight proxy that runs alongside your app during the test run — not a service you deploy or operate. You point your app’s API base URL at it once; record against the real backend, then replay from disk on CI.

                        Record mode                          Replay mode

  Browser/App ──> Proxy ──> Real API        Browser/App ──> Proxy ──> Disk
                    │                                         │
                    └──> saves to disk                        └──> serves saved responses
                         (.mock.json)                              (.mock.json)

Why

• No backend on CI — record once against the real API, replay on every CI run.
• No manual mocks — capture real interactions instead of hand-writing fixtures.
• SSR support — records server-side requests from Next.js and similar frameworks.
• Browser-side support — records browser fetch calls, Chrome extension API calls, analytics, and more.
• Deterministic — the same responses every time, with no flaky network.
• WebSocket support — records and replays WebSocket connections.

Comparison

The mocking tools are good at different jobs. test-proxy-recorder is the one that records real traffic across SSR, browser, and WebSockets without hand-written mocks — that combination is the gap the others leave open.

Feature	test-proxy-recorder	routeFromHAR	MSW	Polly.js	playwright-network-cache	Mocky Balboa
Record real traffic	✅	✅	❌	✅	✅	❌
Server-side (SSR)	✅	❌	✅	⚠️	❌	✅
Browser-side	✅	✅	✅	✅	✅	✅
WebSocket	✅	❌	✅	❌	❌	❌
Playwright-native	✅	✅	❌	❌	✅	✅
Maintained	✅	✅	✅	❌	✅	✅

⚠️ Polly.js intercepts Node HTTP, so SSR mocking is possible inside the app process, but not as part of a Playwright run. MSW and Mocky Balboa replay real responses too — but you hand-write the mocks rather than recording them.

When to reach for something else

• All your traffic is browser-side — Playwright’s built-in routeFromHAR is zero-dependency. Start there; add this when SSR shows up.
• You want to hand-craft responses or force error/edge cases — MSW’s authored handlers and large ecosystem fit that better, and work far beyond Playwright.
• Lightweight browser-only caching, no SSR — playwright-network-cache does just that with less to set up.

Polly.js is the inspiration for this approach (record/replay HTTP, “VCR for JS”); it’s now effectively unmaintained, which is part of why this exists.

Start here

Quick start Scaffold the whole setup with one init command.

Manual setup Wire it up by hand for full-stack or browser-only apps.

How it works The proxy and HAR recording mechanisms.

API reference playwrightProxy, setProxyMode, defineConfig, and the Next.js helpers.

Requirements

• Node.js >= 20.0.0
• @playwright/test >= 1.0.0 (peer dependency)