FAQ
My parallel replay tests sometimes hit the real backend — why?
Section titled “My parallel replay tests sometimes hit the real backend — why?”You’re likely calling playwrightProxy.teardown() in a per-test hook. It sets the global proxy mode to transparent, and with fullyParallel: true each Playwright worker runs its own test.afterAll. If a fast test finishes and calls teardown() while a slower test is still running, the proxy flips to transparent mid-test and the remaining requests are forwarded to the real backend instead of being replayed. In a record run, teardown() saves and ends every recording session, so the slower test’s remaining requests are not recorded.
// ❌ breaks parallel replay — teardown() affects all sessions globallytest.afterAll(async () => { await playwrightProxy.teardown();});Fix: omit test.afterAll. Session cleanup is automatic via context.on('close') → cleanupSession(). Use a global teardown only if you need to reset the proxy after the entire run.
The session timeout is the other way a replay run reaches the real backend. Every playwrightProxy.before() call restarts it, and proxied requests don’t. If it runs out (120000 ms by default) before the next before() call, the proxy switches to transparent. A test that is still running then sends its remaining requests to the real backend. If one test can run that long, raise the timeout with --timeout on the CLI or timeout in the config.
A replayed request fails with “with this request body” — why?
Section titled “A replayed request fails with “with this request body” — why?”The proxy matches a server-side request by its body as well as its method, path and query, and the request sent a body that no recording has. Usually the body holds a value that changes every run, such as the current date or a random id. Fix the value during tests (a fixed clock, a seeded id generator) and re-record. If the app’s request changed on purpose, re-record the test. GET and HEAD requests are not compared by body.
Can I record with parallel workers?
Section titled “Can I record with parallel workers?”Yes, after 2.0.1. The proxy files each request under the session named in its x-test-rcrd-id header, in record mode as in replay. playwrightProxy.before() sets the header on the page’s requests, and registerProxyFetch() copies it onto server-side ones. When a test ends, the proxy saves that test’s .mock.json and leaves the other tests recording.
What can still stop a parallel record run is the app under test. Tests that reset one database or sign in to one account overwrite each other whatever the proxy does. Record those with one worker, or run one app server per worker, each on its own port and data directory. A suite of 11 tests, each spending 2 to 8 minutes on upstream calls, with one app server per worker, recorded in 11.5 minutes on five workers against 49 on one.
RECORD_MODE=1 npx playwright test --workers 1The test:e2e:record script that init adds and the example apps pass --workers 1. Drop it when your tests share no app state.
Versions up to 2.0.1 hold one recording session for every request. When a second test starts recording there, the proxy saves the first test’s file and switches to the second test, so the first test’s remaining requests go into the second test’s .mock.json. On those versions, record with --workers 1. Replay runs with parallel workers in every version.
Should I commit recordings to git?
Section titled “Should I commit recordings to git?”Yes. Recordings must be in git so CI can replay them with no network — do not add e2e/recordings to .gitignore. To keep large recording files from crowding PR reviews, mark them generated in .gitattributes: GitHub collapses their diffs by default and still shows them on one click, so a field the API renamed stays visible in review. Marking them binary would hide that change entirely.
/e2e/recordings/** linguist-generated=trueDoes the proxy <target-url> matter for browser-only (HAR) recording?
Section titled “Does the proxy <target-url> matter for browser-only (HAR) recording?”No. For browser-only recording the target is irrelevant — the proxy process just needs to run so its /__control endpoint is available for session management. The target only matters when server-side (SSR) requests are also routed through the proxy.
What happens to browser requests outside the url pattern?
Section titled “What happens to browser requests outside the url pattern?”Playwright doesn’t intercept them, so they go to the real network in record and replay alike. Nothing is saved for them. Requests to the proxy (localhost:8100) are the exception. playwrightProxy.before() always sends those on to the proxy, which records and replays them itself.
To keep a test off the network, widen url so the HAR covers the domain, or block the domain with page.route() and route.abort():
import { test } from '@playwright/test';import { playwrightProxy } from 'test-proxy-recorder';
const MODE = process.env.RECORD_MODE ? 'record' : 'replay';
test.beforeEach(async ({ page }, testInfo) => { // The HAR also records and replays the CDN. await playwrightProxy.before(page, testInfo, MODE, { url: /localhost:8100|cdn\.example\.com/, });
// Analytics calls fail instead of reaching the network. await page.route(/analytics\.example\.com/, (route) => route.abort());});How replay matches requests has the details.
Can I record against the Next.js dev server?
Section titled “Can I record against the Next.js dev server?”Prefer next build + next start over next dev for recording and replaying. The dev server is slow and can cause timeouts or flaky recordings.
How do I update a recording?
Section titled “How do I update a recording?”Re-run in record mode (RECORD_MODE=1, the test:e2e:record script) against the real API, then commit the updated files in e2e/recordings/.
Can I force an error, an empty list or a slow response in a replayed test?
Section titled “Can I force an error, an empty list or a slow response in a replayed test?”Yes, for browser requests. Playwright runs route handlers in the reverse order of registration, so a page.route() added after playwrightProxy.before() sees each request first. It can answer the request itself, or call route.fallback() to pass it on to the recordings.
import { test, expect } from '@playwright/test';import { playwrightProxy } from 'test-proxy-recorder';
const CLIENT_SIDE_URL = /localhost:8100/;
test.beforeEach(async ({ page }, testInfo) => { await playwrightProxy.before(page, testInfo, 'replay', { url: CLIENT_SIDE_URL });});
test('shows an error when todos fail to load', async ({ page }) => { // Added after before(), so Playwright runs this handler first. await page.route(CLIENT_SIDE_URL, async (route) => { if (new URL(route.request().url()).pathname === '/todos') { await route.fulfill({ status: 500, json: { error: 'Internal Server Error' } }); return; } await route.fallback(); // every other request is replayed as recorded });
await page.goto('/'); await expect(page.getByText('Could not load todos')).toBeVisible();});For an empty list, fulfil with json: [] instead. For a slow response, wait before calling route.fallback(), for example with await new Promise((resolve) => setTimeout(resolve, 3000)). The recorded response then arrives three seconds late.
Server-side requests never pass through the browser, so page.route() can’t change them. For those, edit the recording in the .mock.json by hand, or record against an API in the state you need. In the file, each recording’s response holds statusCode, headers and body. If you change the body’s length, delete the content-length header too.
Can I use it when the suite tests a deployed environment?
Section titled “Can I use it when the suite tests a deployed environment?”Yes, for browser requests. Playwright intercepts them in the browser, so the HAR records and replays them with no change to the deployed app. Point url at the API domain the browser calls. The proxy still has to run next to the tests, because playwrightProxy.before() sets each test’s mode through its /__control endpoint.
Server-side requests are made by the app’s server, so a proxy in CI never sees the ones a deployed server makes. To record or replay them, run the app’s server in CI next to the proxy. Build and start it for the test run with its API base URL pointed at the proxy and TEST_PROXY_RECORDER_ENABLED=true set. The Next.js and TanStack Start pages show this setup.