← Blog

BLOG

Custom User Agent: Set and Verify It in Playwright

Learn how to set a custom user agent in Playwright, verify browser and server behavior, and understand the limits of user-agent overrides.

10 min readRemote Browser
Ivory computer towers connected across terracotta platforms in a quiet desert landscape
The infrastructure behind your browserREMOTE BROWSER / ILLUSTRATION

A custom user agent is a value you choose for the User-Agent HTTP request header instead of the browser’s default. In browser automation, the usual way to set one is to configure the browser context before creating a page and navigating.

For example, Playwright’s browser.newContext({ userAgent: "..." }) applies the configured value to pages in that context. You can use this to test server-side routing, identify an authorized automation client, or reproduce a compatibility issue. Verify both the request received by your server and the browser’s JavaScript-visible value: a header-only change is not always equivalent to a browser-level override.

Changing the user agent does not change Chromium into another browser or device. Other signals, including User-Agent Client Hints, viewport size, touch support, and actual browser behavior, may remain different.

When to use a custom user agent

A user-agent override is useful when you need to control one input to a web application or test environment.

Common cases include:

  • Testing server-side behavior. Confirm that an application returns the expected response for a particular user-agent string.
  • Identifying an automation client. Use a recognizable string for a crawler or integration operating with permission, particularly on infrastructure you control.
  • Reproducing compatibility issues. Compare responses with and without an override while keeping the browser version and test data stable.
  • Testing application logic. Exercise code that reads navigator.userAgent or branches on the request header.
  • Running separate test scenarios. Assign different user agents to isolated browser contexts rather than changing a shared browser configuration between tests.

Use a representative, documented value for the scenario. An arbitrary string such as ExampleTestBot/1.0 is useful for testing identification, but it is not a realistic substitute for testing a particular mobile browser. If the goal is device compatibility, start with a known device configuration and test the other relevant browser settings too.

For background on what the browser normally sends, see Browser User Agent: What It Is and How to Control It. This guide focuses on configuring and validating an override in an automation workflow.

Choose where to set the user agent

The right mechanism depends on whether you are making an HTTP request or driving a browser.

MethodScopeUseful forImportant limitation
HTTP client request headerRequests made by that clientTesting an endpoint without rendering a pageDoes not configure browser JavaScript or browser navigation
Playwright context userAgentPages created in that contextBrowser tests and isolated automation scenariosDoes not make all device or browser characteristics match the string
Browser launch settingThe browser process, depending on the settingEnvironments where one value is appropriate for the whole browserLess convenient when concurrent tests need different values
Chrome DevTools Protocol overrideA CDP target/session, depending on the commandChromium-specific control where context options are insufficientMore protocol-specific; scope and metadata need careful testing
Browser developer toolsAn interactive browser sessionManual investigationEasy to forget or misconfigure; not a reproducible automation setup

For most Playwright tests, prefer the context option. It is explicit, can be configured before the first navigation, and allows separate scenarios to run without changing a shared process-wide setting.

Setting only a User-Agent header through an HTTP client—or through a request interception layer—is different. A page may still see a different value through navigator.userAgent. A proxy or gateway may also modify headers after the automation client observes them.

Set a custom user agent with Playwright and CDP

The following TypeScript example connects to an existing Chromium browser over the Chrome DevTools Protocol, creates a new context with a custom user agent, and checks the value visible in the page.

The example requires:

  1. Node.js and the playwright and tsx packages.
  2. A Chromium CDP endpoint that permits the client to create a browser context.
  3. An HTTP or HTTPS test page you control, reachable from the browser host.

Install the dependencies:

npm install playwright
npm install --save-dev tsx typescript

Save the following as custom-user-agent.ts:

import { chromium } from "playwright";

async function main() {
  const cdpUrl = process.env.CDP_URL;
  const testUrl = process.env.TEST_URL;
  const userAgent =
    process.env.TEST_USER_AGENT ?? "ExampleAutomationTest/1.0";

  if (!cdpUrl || !testUrl) {
    throw new Error("Set CDP_URL and TEST_URL before running the test.");
  }

  const browser = await chromium.connectOverCDP(cdpUrl);

  try {
    // Create the context before opening a page or making a navigation.
    const context = await browser.newContext({ userAgent });

    try {
      const page = await context.newPage();

      // Observe the navigation request as Playwright sees it.
      page.on("request", async (request) => {
        if (request.isNavigationRequest() && request.frame() === page.mainFrame()) {
          try {
            const headers = await request.allHeaders();
            console.log("Navigation URL:", request.url());
            console.log("Playwright-observed User-Agent:", headers["user-agent"]);
          } catch (error) {
            console.error("Could not inspect request headers:", error);
          }
        }
      });

      const response = await page.goto(testUrl, {
        waitUntil: "domcontentloaded",
        timeout: 30_000,
      });

      if (!response) {
        throw new Error("Navigation did not produce an HTTP response.");
      }

      const navigatorUserAgent = await page.evaluate(() => navigator.userAgent);

      console.log("HTTP status:", response.status());
      console.log("navigator.userAgent:", navigatorUserAgent);

      if (navigatorUserAgent !== userAgent) {
        throw new Error("The page-visible user agent did not match the configured value.");
      }
    } finally {
      await context.close();
    }
  } finally {
    // Disconnect the Playwright client. Hosted providers may have separate
    // session termination or billing controls; follow their lifecycle docs.
    await browser.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Run it with your own endpoint and test URL:

CDP_URL="wss://YOUR_CDP_ENDPOINT" \
TEST_URL="https://YOUR_TEST_HOST/user-agent-check" \
npx tsx custom-user-agent.ts

CDP_URL is a placeholder, not a Remote Browser endpoint format. Obtain the actual connection details from your browser provider. Treat the endpoint as a credential: anyone with access may be able to control the browser. Avoid putting it in source control or shared logs.

The test page does not need special JavaScript, but its server should log the incoming User-Agent header if you want an authoritative check of what reached the server. Restrict access to that test page and its logs as appropriate.

Playwright documents connectOverCDP and its Chromium limitation in the BrowserType API reference. CDP connections have different capabilities from Playwright’s native protocol connection, so check your provider’s support before relying on a particular operation.

Using the example with a hosted browser

Remote Browser provides hosted Chromium sessions with CDP access. The same context-level pattern can be used in a hosted workflow when the connected session permits context creation. Consult the documentation for current connection and session setup details rather than assuming a URL structure or session-creation parameter.

A remote browser runs on a different machine from your script. As a result, localhost in TEST_URL refers to the browser host, not necessarily your laptop or CI worker. Use a test endpoint reachable from the hosted session, and do not expose an internal service publicly just to run a quick check.

Some providers give you a preconfigured context or restrict creation of additional contexts. If browser.newContext() fails, check their documentation for supported session configuration. An existing context cannot generally be retrofitted with Playwright’s context-creation userAgent option; create a correctly configured context or use a provider-supported alternative.

Verify the value at three layers

A reliable test distinguishes configuration from observation. Setting an option without inspecting the result can hide errors in session setup, redirects, proxies, or application caching.

1. Check the page-visible value

The example reads:

navigator.userAgent

Compare this with the value configured in the context. If they differ, confirm that the page was created in the intended context and that the application has not navigated through an unexpected flow.

This check matters for applications that perform client-side user-agent detection. It does not, by itself, prove what a server received.

2. Inspect the request in Playwright

The example logs headers returned by request.allHeaders() for main-frame navigation requests. This helps confirm what Playwright observed, including requests following a redirect.

It is a diagnostic view, not proof of the final bytes received by the destination. Network intermediaries can change headers after the browser-side observation. Also, a page can make additional requests to APIs or other origins; inspect those separately if they are part of your test.

3. Check the receiving server

For an endpoint you control, record the incoming User-Agent at the application or edge and compare it with the expected value. Include a test-run identifier in the request URL or your server-side logs so concurrent runs are not confused.

Be deliberate about logging. User-agent strings can contribute to identifying a client, and other request headers may contain cookies or authorization credentials. Log only the fields needed for the test, restrict access, and apply your normal retention policy.

For third-party sites, you may not be able to inspect server logs. In that case, browser-side observations are useful evidence, but they do not establish exactly how the destination received or interpreted the request.

Understand User-Agent Client Hints and device settings

Modern Chromium can expose browser and platform information through User-Agent Client Hints, including Sec-CH-UA request headers and the navigator.userAgentData JavaScript API where available. Servers can also request additional hints; their availability depends on browser behavior, origin, and server configuration.

A custom userAgent string alone should not be treated as proof that those hints match it. Depending on the browser and override mechanism, hints may be absent, unchanged, or otherwise inconsistent with the intended profile. Inspect what your actual browser and server observe.

Similarly, a mobile-looking user-agent string does not automatically give you:

  • A mobile viewport or device pixel ratio.
  • Touch input or mobile layout behavior.
  • The rendering engine of a different browser.
  • A matching operating system, installed fonts, or network location.

For device-oriented testing, configure the relevant Playwright context options together and validate the resulting behavior. Even then, desktop Chromium emulation is not the same as running a test on a physical device or a different browser engine.

Troubleshoot common mismatches

The server sees the default user agent

Check that you set userAgent on the context that created the page, before navigation. Creating another page in an old context will not use the new context’s settings. Then inspect redirect requests and any proxy or gateway between the browser and server.

Also check the server’s logging location: a reverse proxy and an application behind it may observe different headers if one rewrites them.

JavaScript and the request header disagree

This often indicates that the override was applied only at the HTTP header or proxy layer. Use the context option for a browser-level test, then compare navigator.userAgent, Playwright’s request observation, and server logs. Avoid adding a separate manual header override unless the test specifically needs to examine that mismatch.

The response does not change

The site may ignore the user agent, use Client Hints or cookies, cache responses, or branch on another input. Compare status, response headers, and response body using a controlled test endpoint. When you control the server, verify cache behavior and Vary headers so one test response is not accidentally reused for another.

A remote test cannot reach the endpoint

Confirm DNS, network policy, TLS configuration, and whether the URL is reachable from the browser host. A development server bound only to your local machine will not normally be reachable from hosted Chromium. Use an approved test environment rather than weakening network controls.

Production checklist

Before relying on a custom user agent in a recurring workflow:

  • Keep the value intentional. Document what it represents and why the test needs it.
  • Scope it per context. Avoid sharing one configured context between unrelated tenants or test scenarios.
  • Set it before navigation. Initial requests, redirects, and client-side code may already have used the default otherwise.
  • Test the receiving edge. Compare server observations with browser-side values where you have access.
  • Track browser updates. A hard-coded browser version can become misleading as the actual Chromium version changes.
  • Avoid treating it as access control. A user-agent string is client-supplied and can be changed; it does not authenticate a user or bot.
  • Respect site rules and rate limits. An override is a testing and identification tool, not a guarantee of access or a way to bypass restrictions.

Remote Browser’s hosted sessions can provide a consistent place to run these checks alongside existing Playwright workflows. Evaluate session isolation, network access, and lifecycle controls for your workload; see the remote browser for AI agents guide for the broader runtime considerations and pricing for current usage details.