Playwright existingResponse Route Request Testing

Playwright request existingResponse route testing lets a test inspect whether a browser Request already has a Response without creating a wait. Capture the routed request, continue the operation, synchronize on a specific response or UI outcome, then call existingResponse(). A null result is meaningful lifecycle evidence, not an automatic test failure.

This API is most useful in collectors, route diagnostics, and post-action assertions that already own their synchronization. It prevents an observer from quietly waiting for network progress. For broader request setup and response assertions, keep the direct Playwright API testing boundary distinct from browser routes, and use the route and Service Worker debugging guide when interception itself is missing.

Define the Request Lifecycle Decision

Decide what the inspection must tell you now. A non-blocking question is precise: "At the moment this routed request is classified, have response headers arrived?" A waiting question is different: "What response will this request eventually receive?" existingResponse() answers only the first question.

The browser request lifecycle normally advances through request, response, and request-finished events. Routing happens before a request reaches its eventual response. That chronology creates three useful states:

• Pending: the Request exists, but existingResponse() returns null.
• Responded: headers arrived, so existingResponse() returns a browser Response.
• Failed before response: the request failure is available and no Response was associated.

Do not collapse pending and failed into the same meaning. Both can have a null response, but one may still progress. Pair the current response snapshot with an event name, timestamp, request failure state, and the test action that owned the request.

Start from a user outcome. A profile-save test should prove that the form reaches its saved state or shows the documented error. Route evidence explains whether the target request was still pending, returned a status, redirected, or failed at transport. A response object alone does not prove that the application rendered or persisted the correct state.

Keep mocking claims honest. If the test fulfills the route, it verifies client handling of the controlled response. If it continues to a live service, it adds integration evidence. If it replays a recording, it verifies behavior against a reviewed fixture. The Playwright HAR mocking guide explains that replay boundary in detail.

Check Version Support and Event Semantics

The Playwright release notes introduce request.existingResponse() in version 1.59. The installed 1.61.1 TypeScript signature is synchronous: existingResponse(): Response | null. There is no await, timeout, or hidden retry.

The Playwright network guide describes the normal browser event order. request fires when the page issues the request. response fires when status and headers arrive. requestfinished follows after the body completes. requestfailed replaces completion when transport fails, although a response event may already have occurred in some failure paths.

Treat response association as a headers milestone, not proof that the complete body is available or valid. At the response event, status and headers can support routing decisions while body download may still be active. If an assertion reads JSON, verifies encoded size, or compares completed timing, synchronize on request-finished or await the relevant body method through the Response. existingResponse() can identify the associated object at either point, but it does not promote an early checkpoint into completion. Record the checkpoint name in diagnostics so reviewers know whether a missing body field reflects timing, unsupported metadata, or a product defect. Likewise, do not call request.sizes() from an early snapshot and label unavailable timing as zero. Run completion-dependent enrichment after the finished event, bound its tasks, and keep the fast snapshot focused on status association.

HTTP status errors are not transport failures. A 404, 422, or 503 still produces a browser Response and normally reaches request-finished. Assert the documented status and user behavior instead of waiting for requestfailed.

Version-check the process that runs tests. A package range or editor type cache can differ from the executable installed in CI. Record @playwright/test version in diagnostic metadata, especially while a shared framework supports projects on both sides of 1.59.

Understand the object type too. Browser events and route handlers expose Playwright Request, which can call existingResponse(). APIRequestContext.get() and related methods return APIResponse directly. route.fetch() also returns an APIResponse, not the browser Response associated with the intercepted Request. Mixing those objects produces incorrect identity assumptions and often confusing TypeScript casts.

Build the Smallest Route Correlation

The clearest example captures the Request in a route handler, confirms that no response exists at interception, continues the request, then waits for the matching response outside the handler. Once headers have arrived, the saved request can report that same browser Response synchronously.

Example 1: Correlate a routed request after its response arrives

import { expect, test, type Request, type Response } from '@playwright/test';

test('correlates the saved profile request without a second wait', async ({ page }) => {
  let routedRequest: Request | undefined;
  let responseAtInterception: Response | null | undefined;

  await page.route('**/api/profile', async (route, request) => {
    responseAtInterception = request.existingResponse();
    routedRequest = request;
    await route.continue();
  });

  await page.goto('/settings/profile');
  await page.getByLabel('Display name').fill('QA Operator');

  const responsePromise = page.waitForResponse(response =>
    response.url().endsWith('/api/profile') &&
    response.request().method() === 'PUT',
  );

  await page.getByRole('button', { name: 'Save profile' }).click();
  const response = await responsePromise;

  if (!routedRequest) throw new Error('Profile route was not observed');
  expect(responseAtInterception).toBeNull();
  expect(routedRequest.existingResponse()).toBe(response);
  expect(response.status()).toBe(204);
  await expect(page.getByRole('status')).toHaveText('Profile saved');
});

The saved interception snapshot documents the expected lifecycle rather than treating null as surprising. page.waitForResponse() owns the wait because the click should produce one exact response. After that synchronization, existingResponse() is a zero-wait correlation check and should return the same object delivered by the response event.

Register the response wait before the click. Register the route before navigation if startup can issue the target request. Match method and URL together when the endpoint also receives reads or background refreshes.

Avoid placing await request.response() inside a broad request listener. Event emitters do not automatically wait for asynchronous listeners, and a collector can accumulate unresolved tasks for requests that fail or outlive the test. Keep waiting in the scenario or a lifecycle-managed helper with a clear timeout.

Capture Response Evidence Without Blocking Collectors

A diagnostic collector often needs a snapshot of many requests at a known checkpoint. existingResponse() supports that because it never changes the checkpoint by waiting. Store only selected metadata and classify the absence of a response with the event that triggered collection.

Example 2: Build a bounded request outcome collector

import type { Page, Request } from '@playwright/test';

type RequestOutcome = {
  event: 'finished' | 'failed';
  method: string;
  path: string;
  status: number | null;
  failure: string | null;
};

export function collectApiOutcomes(page: Page): RequestOutcome[] {
  const outcomes: RequestOutcome[] = [];

  const record = (event: RequestOutcome['event'], request: Request) => {
    const url = new URL(request.url());
    if (!url.pathname.startsWith('/api/')) return;

    outcomes.push({
      event,
      method: request.method(),
      path: url.pathname,
      status: request.existingResponse()?.status() ?? null,
      failure: request.failure()?.errorText ?? null,
    });
  };

  page.on('requestfinished', request => record('finished', request));
  page.on('requestfailed', request => record('failed', request));
  return outcomes;
}

At request-finished, a completed HTTP response should be available. At request-failed, status may remain null, or a response may exist if failure happened after headers. Keeping both fields preserves that distinction.

The helper intentionally stores a pathname rather than the complete URL. Query strings commonly contain search text, account identifiers, signed values, or tokens. It omits request and response bodies. Add a safe correlation ID only when the application generates one specifically for test diagnostics.

Collectors need teardown. If a helper can be installed repeatedly on a shared page, return listener functions or a disposal callback and remove them after the case. Duplicate listeners can create duplicate records that look like retry behavior. A test-scoped page avoids much of this risk.

For richer chronology, align the outcome list with a trace rather than adding more fields to every log line. The trace, video, and screenshot evidence pipeline shows how to retain attempt-level artifacts without turning console output into an uncontrolled network dump.

Design Positive, Negative, and Boundary Tests

Test lifecycle states, not only status values. The API's value is its ability to report the current association without waiting, so coverage should prove both Response and null are interpreted correctly.

1. Capture a routed live request and assert null before continuation.
2. Synchronize on its response and assert that the saved Request returns the same Response.
3. Return a documented HTTP error and prove it still creates a Response with the expected status.
4. Abort a request before headers and prove the final classification has no Response plus a request failure.
5. Exercise a redirect and inspect every Request-Response pair rather than only the destination.
6. Run parallel cases with separate pages and collectors to detect listener or request leakage.

Use this failure matrix as a review contract:

Keep fault injection explicit. route.abort() can model a transport failure. route.fulfill({ status: 503 }) models an HTTP response. Those are not interchangeable: the application may retry one, render different messaging, or emit different telemetry.

When route events disappear, check Service Worker ownership before changing the assertion. The routing and Service Worker diagnostic path helps identify whether the page route, context route, or worker handled the request.

Compare Waiting, Snapshot, and Route APIs

Choose one owner for network synchronization. A helper that mixes route continuation, response waiting, retries, and UI assertion can make a timeout impossible to assign.

Use existingResponse() when waiting would be a side effect. Use page.waitForResponse() when a user action owns a specific expected response. Use request.response() when code has one known request and intentionally waits for its resolution. Use route.fetch() when a route must fetch and modify the upstream result before fulfillment.

HAR replay and WebSocket routing belong to different boundaries. A HAR can serve recorded HTTP exchanges; Playwright WebSocket mocking controls full-duplex messages. The official WebSocketRoute API exposes socket-specific methods rather than a browser Request.existingResponse() lifecycle.

If the test mainly needs a stable response graph, prefer HAR network replay. If it needs a current live contract, prefer direct or browser integration checks. The non-waiting snapshot is an observability tool, not a substitute for either strategy.

Handle Redirects, Routes, and Protocol Boundaries

Redirects create a new browser Request for each hop. Link them through redirectedFrom() and redirectedTo(). Calling existingResponse() only on the final request tells you nothing about the status or Location header of earlier requests.

This matters for authentication and security. An API call that unexpectedly redirects to sign-in may finish with a 200 HTML page. A final-status assertion alone can pass while JSON parsing later fails. Assert allowed redirect count, target origin, relevant status, and final content type without logging signed locations.

Routes add another chronology. A page route sees a new request before its response, so existingResponse() is normally null. route.continue() releases the request but does not mean response headers are already available. Synchronize outside the handler. If the handler calls route.fetch(), inspect the returned APIResponse directly, then fulfill or otherwise complete the route according to the test design.

Layered routes require ownership. A page route may override a context route, and fallback() may pass control to another handler. Record which handler matched and which one completed the route, but keep logs free of raw headers and bodies. If a route is intended only for observation, avoid modifying request fields.

Protocol metadata can supplement the response. Browser Response supports HTTP version, server address, and security details where available. These are asynchronous methods and may be environment-specific, so collect them in a bounded post-response step rather than the synchronous snapshot. For API clients, use their own response type and Playwright API testing patterns.

Protect Secrets in Network Diagnostics

existingResponse() itself returns an object reference; the security risk begins when code reads and publishes its data. Response headers can contain cookies, tracing tokens, internal hosts, cache metadata, and signed locations. Bodies can contain credentials and personal records. Request URLs may carry sensitive query values even when no body is logged.

Create an allowlist for diagnostic fields. Method, normalized pathname, selected status, event phase, retry index, and a synthetic test correlation ID are often enough. Avoid allHeaders(), body(), or complete URLs in generic collectors. If a specific incident requires more detail, put that capture behind an approved, short-lived diagnostic mode with restricted artifacts.

Traces and HAR files can duplicate the same network values. The official Tracing API explains trace lifecycle, but retention remains the team's responsibility. Apply one policy across trace, HAR, JSON summaries, reporter attachments, and logs. A sanitized summary does not compensate for an unrestricted trace archive.

Use limited test identities and synthetic records. Never make a personal access token part of an expected assertion string. Do not publish failure text blindly because proxies and application code can include target addresses or configuration. Normalize known environmental values before attachment, while preserving a rule identifier and enough context for ownership.

Review AI-generated network helpers with the QABattle evidence checklist. Generated code often logs entire objects for convenience, starts listeners without removing them, or waits inside callbacks without draining tasks. Those patterns deserve explicit rejection in a shared framework.

Debug Null, Stale, or Misattributed Responses

A null value is a timestamped observation. Diagnose when and where it was read before adding a wait.

Check the method as well as path. A background GET and user-triggered PUT can share a URL. Check page or frame ownership when several surfaces call the same endpoint. Navigation requests can exist before their Frame is available, and Service Worker requests do not have an ordinary initiating frame.

Use Playwright CLI trace analysis to compare the action, route, response, and assertion chronology. Do not increase a timeout until evidence shows the expected request is progressing slowly. A wider timeout cannot make a mismatched predicate observe the right object.

If response association appears stale across tests, inspect shared page fixtures and module-level variables. A browser Request should remain tied to its original response, but your reference can point to an earlier request when state is reused. Store records inside the test or fixture instance, include the retry index, and clear listeners during teardown.

Add a Deterministic CI Gate

The CI gate should prove product behavior, request-response correlation, and evidence hygiene. Treat missing target traffic differently from a returned error status. Both may block release, but they route to different owners and need different artifacts.

Example 3: Gate the expected outcome without waiting in the snapshot

import { expect, test, type Request } from '@playwright/test';

test('gates the account deactivation response', async ({ page }) => {
  let target: Request | undefined;
  page.on('request', request => {
    const url = new URL(request.url());
    if (request.method() === 'DELETE' && url.pathname === '/api/account')
      target = request;
  });

  await page.goto('/settings/account');
  const responsePromise = page.waitForResponse(response =>
    response.request().method() === 'DELETE' &&
    new URL(response.url()).pathname === '/api/account',
  );

  await page.getByRole('button', { name: 'Deactivate account' }).click();
  await page.getByRole('button', { name: 'Confirm deactivation' }).click();
  const response = await responsePromise;

  if (!target) throw new Error('Expected DELETE /api/account request');
  expect(target.existingResponse()).toBe(response);
  expect(response.status()).toBe(204);
  await expect(page.getByRole('heading', { name: 'Account deactivated' })).toBeVisible();
});

Apply these gate rules in CI:

1. Block when the user outcome or documented HTTP contract fails.
2. Block when the expected request is absent, duplicated unexpectedly, or associated with another action.
3. Classify a null response only after checking the lifecycle event and request failure state.
4. Keep mocked, replayed, and live cases in separate report dimensions.
5. Reject attachments containing unapproved URL components, headers, bodies, or secrets.
6. Retain the smallest safe summary plus trace or HAR only under the configured failure policy.

Repeat critical route tests with multiple workers to reveal global collectors and shared mutable request references. Do not turn retries into the gate. A passing retry after a correlation failure should remain visible as a flaky result and retain both attempts when the evidence policy permits it.

Frequently Asked Questions

What does request.existingResponse() return?

It synchronously returns the browser Response already associated with that Request, or null when response headers have not arrived. It never waits for future network progress. This makes it useful for snapshots and event-time classification where starting an unresolved promise would hide the request's current lifecycle state.

Is existingResponse available inside a route handler?

For a newly intercepted browser request, expect existingResponse() to be null because routing occurs before the response is received. Save the Request if needed, continue or fulfill the route, and inspect it after a matching response event. Use route.fetch() separately when the handler itself must obtain a network response.

How is existingResponse() different from response()?

existingResponse() is synchronous and reports only what is available now. response() returns a promise that waits for a matching Response or resolves to null after a failure. Choose the first for non-blocking observation and the second when the current operation explicitly owns waiting for request completion.

Does an HTTP 404 produce an existing response?

Yes. HTTP error statuses such as 404 or 503 are completed HTTP responses, not request transport failures. After response headers arrive, existingResponse() can return the Response and its status. A DNS error, refused connection, or failure before response headers normally leaves no associated response and should be classified through request failure evidence.

How should redirects be handled with existingResponse()?

Each redirect hop has its own Request and Response pair. Walk redirectedFrom() or redirectedTo() when the chain matters, then inspect existingResponse() on each completed Request. Do not assume the final request's Response describes earlier status codes, locations, or security boundaries in the chain.

Can existingResponse() be used with APIRequestContext?

No. existingResponse() belongs to the browser-side Request created by page network activity. APIRequestContext methods return APIResponse directly, so there is no browser Request lifecycle to query this way. Keep browser interception evidence and direct API client evidence separate in helpers, types, and reports.

Practice Non-Blocking Network Diagnosis

Choose one route-heavy test that currently waits in a generic listener. Move synchronization to the user action, retain the routed Request, and use existingResponse() only at named lifecycle checkpoints. Add one HTTP error, one pre-response transport failure, and one redirect case so null and Response each have an explicit meaning.

Then attach a safe outcome summary, compare it with the trace chronology, and run the case in parallel. Bring that implementation to QABattle's automation battles and practice explaining which component owns every wait, why the route starts with no response, and which evidence blocks release. A strong solution makes timing visible without turning observation into another source of timing.