User-Agent Client Hints Emulation

[sadym-chromium]

Currently, there is a fundamental disconnect between network-level identity and the navigator.userAgentData Web API. While automation tools can use network.setExtraHeaders to inject Sec-CH-UA-* headers (like Sec-CH-UA-Mobile: ?1) into outgoing requests, they cannot modify the underlying browser state that feeds the navigator API.

This results in a fragmented environment where:

1. Headers say the device is mobile.
2. Web APIs report the device is desktop.

Because the UA-CH specification designed navigator.userAgentData.mobile and high-entropy hints (like model and platformVersion) to be the primary signals for modern web applications, the inability to override these values makes full mobile emulation impossible.

Scenarios

API-Driven Responsive Logic

Enabling tests for applications that toggle between mobile and desktop UI components based on the navigator.userAgentData.mobile boolean rather than just screen width.

High-Entropy Hardware Simulation

Simulating specific mobile hardware profiles (e.g., model: "Pixel 8", platform: "Android") to validate device-specific performance optimizations or feature availability.

Proposed Solution

Specify a new WebDriver BiDi command emulation.setClientHintsUserAgentOverride:

emulation.SetClientHintsUserAgentOverrideCommand = {
  method: "emulation.setClientHintsUserAgentOverride",
  params: {
    clientHints: emulation.ClientHintsUserAgentMetadata / null,
    ? contexts: [+browsingContext.BrowsingContext],
    ? userContexts: [+browser.UserContext],
  }
}

emulation.ClientHintsUserAgentMetadata = {
  ? brands: [* emulation.BrandVersion],
  ? fullVersionList: [* emulation.BrandVersion],
  ? platform: text,
  ? platformVersion: text,
  ? architecture: text,
  ? model: text,
  ? mobile: bool,
  ? bitness: text,
  ? wow64: bool,
  ? formFactors: [* text];
}

emulation.BrandVersion = {
  brand: text,
  version: text
}

Alternative solution

Extend existing emulation.setUserAgentOverride command:

emulation.SetUserAgentOverrideParameters = {
  userAgent: text / null,
  ? clientHints: emulation.ClientHintsUserAgentMetadata / null,
  ? contexts: [+browsingContext.BrowsingContext],
  ? userContexts: [+browser.UserContext],
}

[miketaylr]

To enable cross-browser, consistent mobile emulation, we propose to extend emulation.setUserAgentOverride with clientHints field:

Hey @sadym-chromium, thanks for filing the issue. I'm not a WebDriver/automation expert, so I have no useful opinions between the proposed and alternative solution. But extending the existing SetUserAgentOverrideParameters makes sense to me.

I'm happy to review a pull request, if you'd like to send one (I assume you would define this over in the bidi spec, but we can create an Automation section here and link to it).

[sadym-chromium]

done in #387