Support emulation of the User-Agent

[sadym-chromium]

it should be possible to set a custom user agent:

1. per browsing context with sub-contexts
2. per user context (requires decision from Support user context configuration #775)

The emulation should affect the output of Web APIs observable to the page as well as the network headers for outgoing requests.

[whimboo]

Commands for this could be browsingContext.setUserAgent and browsingContext.getUserAgent. Passing null as user agent should reset the formerly set custom user agent.

[whimboo]

Actually retrieving the current user agent could be done by script evaluation and returning navigation.userAgent. So we probably only need a way to set a custom user agent.

[thiagowfx]

Isn't this a duplicate of #446? cc @OrKoN

[OrKoN]

No, it is not: #446 is about getting the original non-emulated user agent from a browser binary without a need to have browsing contexts.

[mathiasbynens]

I wanted to bring up User-Agent Client Hints. Although it’s a separate feature, it’s somewhat related to User-Agent string emulation, and as a user you’d probably want to emulate both the User-Agent string + the Client Hints accordingly (since otherwise it’s trivial for the target page to detect emulation).

Our options are:

A. include Client Hints support as part of this API
B. provide a separate API for Client Hints
C. support User-Agent emulation without Client Hints emulation

An example of A would be CDP’s Emulation.setUserAgentOverride which accepts an optional userAgentMetadata param that configures the Client Hints.

[css-meeting-bot]

The Browser Testing and Tools Working Group just discussed Emulation features - User agent override.

The full IRC log of that discussion

<AutomatedTester> topic: Emulation features - User agent override
<AutomatedTester> github: https://github.com//issues/448
<AutomatedTester> q?
<orkon> q+
<AutomatedTester> ack next
<AutomatedTester> orkon: allows you to set to the custom UA and is related to client hints
<AutomatedTester> ... in CDP you can do UA and client hints in 1 command?
<AutomatedTester> q+
<gsnedders> q+
<jgraham> q+
<AutomatedTester> ... client hints is allows you set up things that can affect the UA
<orkon> https://wicg.github.io/ua-client-hints/
<shs96c> q+
<sadym> q+
<AutomatedTester> AutomatedTester: I see little to no value in being able to change the UA for people. Users will assume that by making Chrome change their UA to be like firefox that it will act like firefox and there might actually be interoperable issues that then exposed where since we are making sure that things work cross browser they should be encouraged to use the relavant browser. E.g. pretending to be a mobile safari in chrome isnt going to
<AutomatedTester> give the same result
<AutomatedTester> ack next
<AutomatedTester> ack next
<AutomatedTester> Sam Sneddon [:gsnedders]: I was going to point out that Mozilla is apposed to UACH? and that Apple has some concerns
<AutomatedTester> ... I think we should avoid doing things that builds on other specs that dont have cross browser buy in
<AutomatedTester> ack next
<AutomatedTester> jgraham: UA stance for Mozilla is negative so we can do this as a chrome specific extension
<AutomatedTester> ... UA Client hints has some privacy concerns. This can be then covered in a chrome extension method
<AutomatedTester> ... on the overall value in doing this is value for people testing their site where the version numbers for example
<orkon> q+
<AutomatedTester> ... there are use cases internally for browser vendors
<AutomatedTester> ... in firefox people can set this in prefs but wont be in a specific tests
<AutomatedTester> q?
<AutomatedTester> ack next
<whimboo> q+
<AutomatedTester> shs96c: UA string makes sense but I am curious if this will be used in network interception
<jgraham> Request interception doesn't affect �navigator.userAgent�
<gsnedders> s/in a chrome extension method/in a chrome extension method or defined in the UACH spec, slight preference towards the UACH spec because then others can implement it/
<jgraham> q+
<AutomatedTester> ... I have a concern that if we allow this that we are going to encourage people to use a specific browser and wont have a positive impact on a interoperable web
<AutomatedTester> q?
<AutomatedTester> ack next
<AutomatedTester> sadym (IRC): it is way more expensive to test on some devices and I don't think it will encourage people to use the wrong browser
<AutomatedTester> shs96c: I think that having the UA set can be useful but pretending to be a different browser is bad
<AutomatedTester> ack next
<AutomatedTester> orkon
<AutomatedTester> orkon: Let's drop CH as that is out of scope. UA changes can be good for browsers vendors but not for the average tester
<AutomatedTester> ... what is webkits stance on changing this?
<AutomatedTester> Sam Sneddon [:gsnedders]: I think this is fine. we already can do this its just exposing to webdriver
<AutomatedTester> ack next
<whimboo> > Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36
<AutomatedTester> whimboo: I wanted to mention setting UA is hard to interpret
<AutomatedTester> ... e.g. using this example it doesn't show what the browser is and can lead to false assumptions on the browser
<AutomatedTester> ack next
<AutomatedTester> ... if we take this into account that we give them presets that they can use
<AutomatedTester> jgraham: I think there are use cases for this. The concerns raised are reasonable. I think its on clients to not overly expose this
<AutomatedTester> ... if we have cases where can create the issues on a desktop instead of a mobile device then its fine but we shouldnt encourage people to use that as the final testing value
<AutomatedTester> ... and to whimboo 's point we should give them something they can edit rather than make it all up and get it all wrong
<AutomatedTester> q?
<orkon> q+

[thiagowfx]

Let's start with C).

From the IRC log above:

orkon: Let's drop CH as that is out of scope. UA changes can be good for browsers vendors but not for the average tester

It seems that we do not want to pursue client hints. @OrKoN could you confirm this?

[thiagowfx]

I am intending to add this command as part of the "browsingContext" module (e.g. instead of a new"emulation" module).

[christian-bromann]

Within the WebdriverIO framework we are using script.addPreloadScript to emulate this Web API, e.g.

await this.scriptAddPreloadScript({
    functionDeclaration: /*js*/`() => {
        Object.defineProperty(navigator, 'userAgent', {
            value: ${JSON.stringify(options)}
        })
    }`
})

Is there any advantage to have this handled through the protocol?

[thiagowfx]

Is there any advantage to have this handled through the protocol?

I don't know, hopefully someone else can answer it. I can only imagine that if it was that easy then it would have been brought up before during the WG meeting.

[OrKoN]

Within the WebdriverIO framework we are using script.addPreloadScript to emulate this Web API, e.g.

await this.scriptAddPreloadScript({
    functionDeclaration: /*js*/`() => {
        Object.defineProperty(navigator, 'userAgent', {
            value: ${JSON.stringify(options)}
        })
    }`
})

Is there any advantage to have this handled through the protocol?

I believe this would not be used for outgoing network requests. While it's possible to solve it via request interception, it is often easier to change it at once.

@thiagowfx Client Hints are completely out of scope for the WebDriver BiDi spec. I recall there were also some concerns from Selenium about adding this feature. Perhaps, we need to discuss again given that we have a draft. In Puppeteer, the feature would allow supporting https://pptr.dev/api/puppeteer.page.setuseragent/.

[OrKoN]

There are two options to move forward with this:

1. Implement client side using preload scripts + request interception

   Pros: Does not require spec changes.
   Cons: Request interception introduces round-trips for each request reducing performance if the use case involves only changing the user agent. Complexity moves to the client.

2. Implement browsingContext.setUserAgent as part of the protocol.

   Pros: No performance degradation; simple client implementation.
   Cons: Requires extending the spec with something that already can be done by other (although less efficient) means.

[css-meeting-bot]

The Browser Testing and Tools Working Group just discussed Support emulation of the User-Agent.

The full IRC log of that discussion

<AutomatedTester> topic: Support emulation of the User-Agent
<AutomatedTester> github: https://github.com//issues/448
<AutomatedTester> orkon: this is a feature request I filed
<AutomatedTester> and puppeteer supports it
<AutomatedTester> ... and I am currently leaning towards closing this issue
<AutomatedTester> ... and there is a way that we can implement it
<AutomatedTester> q+
<whimboo> q+
<AutomatedTester> automatedtester: from Selenium point of view we don't need this feature and are ahppy for you to close it
<AutomatedTester> ack next
<AutomatedTester> ack next
<AutomatedTester> whimboo: if your fine then great. we can always see about adding this in the future if there are clients that are porting from CDP and are struggling to amek it work
<AutomatedTester> q?
<AutomatedTester> s/amek/make
<MaksimSadym> present-

[OrKoN]

Closed in favor of initially supporting this feature client-side using preload scripts and request interception. Can revisit if more clients require that.

[whimboo]

From the Playwright team there was also the request to add support for emulating the user agent per user context. Maybe this should be more a general issue given that it affects other emulation features and events as well?

[OrKoN]

I think it would be great to file a separate issue to discuss (generic) per user context configuration for all commands, although we would probably need to specify it per command anyway. I will update the description to mention these details for the user agent emulation.

[whimboo]

I think it would be great to file a separate issue to discuss (generic) per user context configuration for all commands

I filed #775 for that wanted discussion.

[css-meeting-bot]

The Browser Testing and Tools Working Group just discussed Emulation - User Agent.

The full IRC log of that discussion

<simonstewart> Topic: Emulation - User Agent
<simonstewart> https://github.com//issues/448
<AutomatedTester> github: https://github.com//issues/448
<simonstewart> whimboo: the issue request is from quite a long time ago, since we decided to implement this sufficiently for puppeteer. Now we have more clients using bidi, they all want to have a way of changing the UA
<AutomatedTester> q+
<simonstewart> whimboo: this is why I requested a separate command to get and set the UA for a browsing context
<simonstewart> ack AutomatedTester
<jgraham> q+
<simonstewart> AutomatedTester: I guess this is possibly a question for the Googlers. Do we have any metrics for how widely this is used? I ask because the Selenium project always aims to test in the same browser that people use, rather than (eg) making Chrome act like Firefox.
<jgraham> q+
<simonstewart> orkon: We don't have any data. We know people do use it, but because we're an OSS project we don't know how many people are using it.
<AutomatedTester> ack jgraham
<simonstewart> jgraham: I think there are legitimate use-cases for this. We know that people try to do mobile emulation on desktop, even if they shouldn't be doing that.
<simonstewart> jgraham: Other people want to check what will happen when the UA string changes (eg. will that break my site?)
<simonstewart> jgraham: The technical question is what we want the scope of the issue to be. The obvious thing is about HTTP headers. Then there's navigator.userAgent, which you can use a preload script for. Then there are other features, which you may not want to override in an adhoc way.
<simonstewart> jgraham: This is a little bit of a thing you could implement in other ways. What do people actually want the command to do?
<AutomatedTester> q+
<orkon> q+
<simonstewart> AutomatedTester: there were concerns from Mozilla and WebKit about this before. It might have been around client hints, and perhaps UA strings.
<AutomatedTester> ack next
<simonstewart> AutomatedTester: do these concerns still exist? How will that affect how we go about creating the implementation?
<jgraham> q+\
<jgraham> q-\
<jgraham> q+
<sideshowbarker> i/new browser engine called Ladybird/https://github.com/LadybirdBrowser/ladybird/issues/1040 Ladybird WebDriver implementation: Missing endpoints
<AutomatedTester> ack orkon
<simonstewart> orkon: I recall the conversation from last year. Client hints can be considered out-of-scope, and not all browsers implement them anyway.
<sideshowbarker> RRSAgent, make minutes
<RRSAgent> I have made the request to generate https://www.w3.org/2024/09/26-webdriver-minutes.html sideshowbarker
<simonstewart> orkon: from the spec perspective, I think we need two commands. One for the HTTP headers, and one for the web APIs. From the testing perspective, only one command makes sense.
<AutomatedTester> q?
<AutomatedTester> ack jgraham
<simonstewart> jgraham: to be clear. Mozilla can't override client hints because we don't implement them.
<simonstewart> jgraham: in regards to what orkon says, a command that changes the http UA string and navigator value makes sense. I'm wary of allowing this command to make other changes over time, as that might mean introducing other changes
<simonstewart> q+
<AutomatedTester> ack next
<jgraham> scribe+
<jgraham> simonstewart: If someone is asking to change the UA string to emulate another browser, wouldn't you like to try to be as close as possible to that other browser e.g. client hints?
<simonstewart> scribe+
<AutomatedTester> q?
<gsnedders> q+
<simonstewart> jgraham: I think the answer is that we have a lot of commands that are orthogonal commands, rather than one "do everything" command.
<orkon> q+
<simonstewart> jgraham: so things that are specifically about defining the UA might be handled by additional parameters in the command
<simonstewart> simonstewart: so why not have separate commands at that point?
<simonstewart> jgraham: Let's assume we had a command to change http headers, and we had a preload script command. That would allow the UA string and then the navigator.userAgent string to be set. So do we need the single command to do those two things? I guess that's a question for the CDP folks to answer.
<AutomatedTester> ack gsnedders
<simonstewart> jgraham: I'm not against a small quality of life command to make things simpler. Without that, more burden is left to the clients to get things right
<simonstewart> gsnedders: my main take here is that there are a bunch of things that should always be in sync. There's no browser that gives different values in http headers and another in navigator.userAgent. It feels like there should be a way to keep things in sync, which implies a single command
<jgraham> q+
<simonstewart> gsnedders: one question is that the CDP command that changes these things, if you don't pass any of the optional values, does Chrome attempt to derive things like client hints. If we're trying to keep everything in sync, then should the single command change those? We should design things so that they _can_ stay in sync. We shouldn't rely on
<simonstewart> preload scripts
<AutomatedTester> ack orkon
<simonstewart> orkon: about changing other properties based on the UA. The playwright case is "I want something that looks like some specific mobile device". They collect all the properties they think is meaningful, and then they call all the different commands to change the browsing context. It's central to the way that they encourage people to write tests.
<simonstewart> orkon: I don't know how the UA emulation works in CDP, but I think client hints override UA strings.
<AutomatedTester> q?
<AutomatedTester> ack jgraham
<gsnedders> (Kinda as an aside, with CDP: https://chromedevtools.github.io/devtools-protocol/tot/Emulation/#method-setUserAgentOverride is kinda surprising insofar as it includes `acceptLanguage` to me? Because that doesn't affect UA or Client Hints at all.)
<orkon> q+
<simonstewart> jgraham: I'm sceptical of a command that's too "do what I mean", particularly if there's a change in API surface. Having a command that suddenly starts changing that part of the UA may be a bit unclear about how that should actually work. Will that break people's tests that depend on headers (etc) not being changed.
<simonstewart> jgraham: if you put in the primitive data, how would you know how to reassemble the header, and vice versa. You'd need to specify both things.
<simonstewart> jgraham: looking at the CDP command, you need to set the UA string, and then optional other things (such as platform). That allows the command to evolve, and means we don't need to define a mapping between UA and (eg) screen size
<AutomatedTester> q?
<AutomatedTester> ack orkon
<simonstewart> orkon: I wanted to mention about preload scripts. We implement this as request interception.
<simonstewart> orkon: I think for some scenarios and emulations, you want to apply things dynamically. That's an argument about relying on preload scripts for emulation
<jgraham> q+
<AutomatedTester> q?
<AutomatedTester> ack jgraham
<simonstewart> jgraham: it seems like people agree the command should exist. Is the disagreement that it should start with a UA string and (possibly) platform, and that override the http UA string, navigator.userAgent, and potentially the platform. Client hints could be an extension, or defined in the client hints spec.
<simonstewart> gsnedders. I think so????
<AutomatedTester> q?
<simonstewart> jgraham: This isn't a formal attempt to get consensus, just to find out whether you'd object to this API in general.
<simonstewart> gsnedders: that seems reasonable. I think my main concern is that we end up in some space where Chrome is doing something different such that UA client hints make you think you're looking at one browser, but the UA string defines it as another browser. That may be a chrome problem
<simonstewart> jgraham: that may be an author problem....
<simonstewart> q+
<simonstewart> simonstewart: people using libraries may not be able to consistently know whether the UA string or client hints are being used.
<simonstewart> ack simonstewart
<AutomatedTester> q?
<simonstewart> jgraham: it's a hard thing to solve without some kind of massive database of what each browser can do. Maybe that's a local-end issue.
<AutomatedTester> q?
<sideshowbarker> q?
<simonstewart> jgraham: From a slightly different perspective, we sometimes do this for web-compat stuff. Often you can get away with overriding specific things. You don't need to be 100% accurate. Would rather provide a command to do the low-level things we need to do
<simonstewart> q+
<AutomatedTester> ack simonstewart
<sideshowbarker> ack simonstewart
<simonstewart> simonstewart: that suggests the client hints changes should be in the client hints spec
<AutomatedTester> q?
<simonstewart> jgraham: If people wanted to add client hints as an optional parameter, I don't think we'd object to adding that to our spec
<whimboo> RRSAgent, make minutes
<RRSAgent> I have made the request to generate https://www.w3.org/2024/09/26-webdriver-minutes.html whimboo