@playwright-backend-mocks/proxy

Standalone proxy, coordinator, and REST API for Playwright Backend Mocks — the process that sits between your Playwright tests and Node app.

Documentation · Getting started · Proxy ops · GitHub

Run the real app. Mock only the outside world.

Good e2e tests cover your UI and your server — then fake Stripe, email, and every other third party at the boundary. Playwright can do the browser half. This library makes the server half just as easy.

Your UI and server stay real. Tests use backendMocks.route() for the outbound HTTP your Node process makes — the calls that never show up in the browser Network tab.

test("declined card shows an error", async ({ page, backendMocks }) => {
  await backendMocks.route("https://api.stripe.com/**", async (route) => {
    await route.fulfill({
      status: 402,
      json: { error: "card_declined" },
    });
  });

  await page.goto("/checkout");
  await page.getByRole("button", { name: "Pay" }).click();
  await expect(page.getByText("Your card was declined")).toBeVisible();
});

Role in the system

This package is the coordinator. Playwright workers and Node agents connect over WebSockets. When the app reports outbound traffic, the proxy broadcasts claims, picks an owning test (or passthrough / loud ambiguity), relays the settle decision back to Node, and records history for debugging.

| Process | Package | Responsibility | | --- | --- | --- | | Playwright worker | @playwright-backend-mocks/playwright | backendMocks.route(), matching, settle | | Proxy coordinator | @playwright-backend-mocks/proxy | Claims, decisions, history, REST | | Node app | @playwright-backend-mocks/node | Intercepts outbound HTTP / WebSocket |

It is not magic — a small local process your Playwright tests control:

1. Start the proxy — matches routes, returns decisions, exposes request history over REST.
2. Route Node HTTP through it — startBackendMocks() pauses outbound calls and asks the proxy.
3. Control it from Playwright — handlers run in the test and fulfill / continue / abort.

When your app makes an outbound call:

1. @mswjs/interceptors pauses the request inside the Node process.
2. The Node agent forwards it to this proxy.
3. The proxy matches it against the owning test’s backendMocks.route() handlers.
4. The Playwright handler settles with fulfill, continue, or abort.
5. The decision returns to the app as a mocked or real response.

Unmatched requests pass through to the real network.

Install

npm install -D @playwright-backend-mocks/proxy \
  @playwright-backend-mocks/playwright \
  @playwright-backend-mocks/node

Keep the @playwright-backend-mocks/* packages on the same version.

CLI

Binary: playwright-backend-mocks-proxy

playwright-backend-mocks-proxy --host 127.0.0.1 --port 4310

Typical Playwright webServer entry:

{
  command: "playwright-backend-mocks-proxy --host 127.0.0.1 --port 4310",
  url: "http://127.0.0.1:4310/health",
  reuseExistingServer: !process.env.CI,
}

While the proxy is running you can inspect traffic via REST (or the optional dashboard):

• GET /api/history — HTTP timeline
• GET /api/ws — WebSocket connections and events
• GET /api/history/:id/har — download one HTTP request as HAR

See Observability.

Related packages

| Package | Role | | --- | --- | | @playwright-backend-mocks/playwright | Playwright backendMocks fixture | | @playwright-backend-mocks/node | Agent that intercepts outbound traffic in the app | | @playwright-backend-mocks/dashboard | Optional read-only traffic UI | | @playwright-backend-mocks/protocol | Shared wire types (usually a transitive dependency) |

License

MIT