Playwright Tips: Using Custom Headers in Playwright for Worker-Specific Response Handling

So a little bit context first - As our test suites grow in complexity and execution parallelism, pinpointing the origin of specific network requests and responses becomes increasingly crucial dude to some random flakiness.

In our Playwright automation framework, we recently encountered a scenario where we needed to intercept a response from a particular worker instance in our parallel test execution. This led us to devise a solution leveraging Playwright's request interception capabilities and custom headers.

When running Playwright tests in parallel using multiple workers, identifying which worker initiated a specific network request can be challenging. This is especially true when dealing with APIs that might behave slightly differently based on the context of the worker or the test being executed. In our case, we needed to verify the response of a specific API call triggered by an action within a particular test running on a specific worker. Using the builtin page.waitForResponse() with a URL matcher wasn't sufficient because multiple workers could potentially trigger the same API call around the same time. We needed a more precise way to target the response we were interested in.

Therefore, our approach was to inject a custom header into the outgoing request from a specific worker instance. This unique header would then allow us to identify the corresponding response. Playwright's page.route() API provides a powerful mechanism to intercept and modify requests before they are sent.

Here's an example of how we implemented this solution:

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

async function waitForResponseOfSpecificWorkerInstance(
  page: Page,
  partialRoute: string,
  uniqueIdentifier: string,
  timeout = 21000,
): Promise<Response> {
  const regexRoute = new RegExp(partialRoute)

  await page.route('**/*', route => {
    const url = route.request().url()
    const urlObj = new URL(url)
    const pathname = urlObj.pathname

    if (regexRoute.test(pathname)) {
      const newHeaders = { ...route.request().headers() }
      newHeaders['X-Unique-Identifier'] = uniqueIdentifier
      route.continue({ headers: newHeaders })
    } else {
      route.continue()
    }
  })

  const response = await page.waitForResponse(
    response => {
      const requestHeaders = response.request().headers()
      return (
        regexRoute.test(response.url()) &&
        requestHeaders['x-unique-identifier'] === uniqueIdentifier
      );
    },
    { timeout },
  );
  return response
}

Let's break down what this simple function does:

waitForResponseOfSpecificWorkerInstance(page, partialRoute, uniqueIdentifier, timeout):

• Takes the Playwright Page object, a partialRoute (a string or regular expression to match the URL), a uniqueIdentifier (a string to identify the worker instance), and an optional timeout as arguments.
• Returns a Promise that resolves with the intercepted Response object.

const regexRoute = new RegExp(partialRoute)

Creates a regex from the partialRoute variable to allow for flexible URL matching.

await page.route('**/*', route => { ... });

This is the heart of the request interception. page.route('**/*') intercepts all network requests made by the page. The provided callback function is executed for each intercepted request.

const url = route.request().url()
const pathname = new URL(url).pathname

if (regexRoute.test(pathname)) { ... }

Extracts the URL and then specifically the pathname from the intercepted request. We often focus on the pathname for route matching. Then we check if the pathname of the current request matches the provided partialRoute.

const newHeaders = { ...route.request().headers() }

newHeaders['X-Unique-Identifier'] = uniqueIdentifier

Creates a copy of the existing request headers. It's important to copy the headers to avoid modifying the original object directly. Then we inject our custom header. We add a new header named X-Unique-Identifier with the value of the uniqueIdentifier variable that was passed to the function as an argument.

route.continue({ headers: newHeaders })
else { route.continue() }

Allows the intercepted request to continue to the server, but now with our newly added custom header. If the request URL doesn't match our target partialRoute, we simply allow the request to continue without modification.

const response = await page.waitForResponse(response => { ... }, { timeout })

This is where we wait for the specific response we are interested in. The callback function within waitForResponse checks two conditions:

• regexRoute.test(response.url()) Ensures the response URL matches our target route. requestHeaders['x-unique-identifier'] === uniqueIdentifier Checks if the request that led to this response had our custom X-Unique-Identifier header with the expected value.

And finally, once a matching response is found (both URL and custom header match), the promise resolves with the Response object and returns it.

Now, lets take a look at how we can use this function in a test:

import { test, expect } from '@playwright/test'
import { waitForResponseOfSpecificWorkerInstance } from './utils' // Assuming the function is in a utils.ts file

test('Edit refresh lock', async ({ app, api }, testInfo) => {
  // Assuming 'app' and 'api' is a fixture object containing your page objects and api helper function like waitForResponseOfSpecificWorkerInstance

  const responsePromise = api.waitForResponseOfSpecificWorkerInstance(
    app.myPage,
    '/api/v1/example/',
    `worker_${testInfo.workerIndex}`,
  )

 // Perform some action that will trigger the API call

  const response = await responsePromise
  expect(response.status()).toBe(200)
})

In this example:

• We use testInfo.workerIndex (testInfo is a built-in fixture of Playwright) to get a unique identifier for the current worker running the test. This ensures that each parallel test execution will have a distinct X-Unique-Identifier header.
• We call our waitForResponseOfSpecificWorkerInstance function before performing the action that triggers the API call.
• We pass the page object, the partial route of the API endpoint we're interested in (/api/v1/example/), and the unique worker identifier as a string.
• The test then proceeds to perform the action on the browser.
• We await the responsePromise, which will resolve only when a response from the /api/v1/example/ endpoint is received and its corresponding request had the X-Unique-Identifier header matching the current worker's index.

By doing that simple trick, we can now precisely target and handle responses from specific worker instances in our parallel test execution, reduce flakiness (even in parallel execution) and enhanced debugging abilities.