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.

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.userAgentor 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.
| Method | Scope | Useful for | Important limitation |
|---|---|---|---|
| HTTP client request header | Requests made by that client | Testing an endpoint without rendering a page | Does not configure browser JavaScript or browser navigation |
Playwright context userAgent | Pages created in that context | Browser tests and isolated automation scenarios | Does not make all device or browser characteristics match the string |
| Browser launch setting | The browser process, depending on the setting | Environments where one value is appropriate for the whole browser | Less convenient when concurrent tests need different values |
| Chrome DevTools Protocol override | A CDP target/session, depending on the command | Chromium-specific control where context options are insufficient | More protocol-specific; scope and metadata need careful testing |
| Browser developer tools | An interactive browser session | Manual investigation | Easy 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:
- Node.js and the
playwrightandtsxpackages. - A Chromium CDP endpoint that permits the client to create a browser context.
- An HTTP or HTTPS test page you control, reachable from the browser host.
Install the dependencies:
npm install playwright
npm install --save-dev tsx typescriptSave 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.tsCDP_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.userAgentCompare 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.