Repository navigation
[Editorial review] BiDi emulation module - setLocaleOverride and setTimezoneOverride commands
#46517
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
[Editorial review] BiDi emulation module - setLocaleOverride and setTimezoneOverride commands
#46517
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,140 @@ | ||||||||||||||||||
| --- | ||||||||||||||||||
| title: "`emulation.setLocaleOverride` command" | ||||||||||||||||||
| short-title: setLocaleOverride | ||||||||||||||||||
| slug: Web/WebDriver/Reference/BiDi/Modules/emulation/setLocaleOverride | ||||||||||||||||||
| page-type: webdriver-command | ||||||||||||||||||
| browser-compat: webdriver.bidi.emulation.setLocaleOverride | ||||||||||||||||||
| sidebar: webdriver | ||||||||||||||||||
| --- | ||||||||||||||||||
|
|
||||||||||||||||||
| The `emulation.setLocaleOverride` [command](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#commands) of the [`emulation`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/emulation) module overrides the locale for the specified [top-level contexts](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext#top-level_context) or [user contexts](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browser#user_contexts). | ||||||||||||||||||
|
|
||||||||||||||||||
| ## Syntax | ||||||||||||||||||
|
|
||||||||||||||||||
| ```json-nolint | ||||||||||||||||||
| /* With required parameters and `contexts` */ | ||||||||||||||||||
| { | ||||||||||||||||||
| "method": "emulation.setLocaleOverride", | ||||||||||||||||||
| "params": { | ||||||||||||||||||
| "contexts": [ | ||||||||||||||||||
| "5e5e96e8-5247-4f22-9b35-a4a2d841cbaa" | ||||||||||||||||||
| ], | ||||||||||||||||||
| "locale": "fr-FR" | ||||||||||||||||||
| } | ||||||||||||||||||
| } | ||||||||||||||||||
|
|
||||||||||||||||||
| /* With required parameters and `userContexts` */ | ||||||||||||||||||
| { | ||||||||||||||||||
| "method": "emulation.setLocaleOverride", | ||||||||||||||||||
| "params": { | ||||||||||||||||||
| "locale": "fr-FR", | ||||||||||||||||||
| "userContexts": [ | ||||||||||||||||||
| "a812d4d0-8c8f-4c78-9de1-3e5c5b3b3c3c" | ||||||||||||||||||
| ] | ||||||||||||||||||
| } | ||||||||||||||||||
| } | ||||||||||||||||||
| ``` | ||||||||||||||||||
|
|
||||||||||||||||||
| ### Parameters | ||||||||||||||||||
|
|
||||||||||||||||||
| The `params` field contains: | ||||||||||||||||||
|
|
||||||||||||||||||
| - `contexts` {{optional_inline}} | ||||||||||||||||||
| - : An array of one or more strings that contains the IDs of the [top-level contexts](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext#top-level_context) to affect. | ||||||||||||||||||
| Context IDs are returned by commands such as [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree). | ||||||||||||||||||
| This field cannot be used if [`userContexts`](#usercontexts) is also specified, but it is required if `userContexts` is not specified. | ||||||||||||||||||
| - `locale` | ||||||||||||||||||
| - : A string that specifies a structurally valid {{glossary("BCP 47 language tag", "language tag")}}, such as `fr-FR`. | ||||||||||||||||||
| It can be `null` to remove the locale override at the specified scope. | ||||||||||||||||||
| - `userContexts` {{optional_inline}} | ||||||||||||||||||
| - : An array of one or more strings that contains the IDs of the [user contexts](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browser#user_contexts) to affect. | ||||||||||||||||||
| User context IDs are returned by commands such as [`browser.createUserContext`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browser/createUserContext) or [`browser.getUserContexts`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browser/getUserContexts). | ||||||||||||||||||
| This field cannot be used if [`contexts`](#contexts) is also specified, but it is required if `contexts` is not specified. | ||||||||||||||||||
|
|
||||||||||||||||||
| ### Return value | ||||||||||||||||||
|
|
||||||||||||||||||
| The `result` field in the response is an empty object (`{}`). | ||||||||||||||||||
|
|
||||||||||||||||||
| ### Errors | ||||||||||||||||||
|
|
||||||||||||||||||
| - [`invalid argument`](/en-US/docs/Web/WebDriver/Reference/Errors/InvalidArgument) | ||||||||||||||||||
| - : Thrown in any of the following cases: | ||||||||||||||||||
| - A required parameter is missing, or a parameter has an invalid type or value. | ||||||||||||||||||
| - Both `contexts` and `userContexts` are specified. | ||||||||||||||||||
| - Neither `contexts` nor `userContexts` is specified. | ||||||||||||||||||
| - `contexts` or `userContexts` is an empty array. | ||||||||||||||||||
| - A context specified in `contexts` is not a top-level context. | ||||||||||||||||||
| - `locale` is not `null` and is not a structurally valid language tag. | ||||||||||||||||||
| - `no such frame` | ||||||||||||||||||
| - : No context with an ID specified in `contexts` is found. | ||||||||||||||||||
| - `no such user context` | ||||||||||||||||||
| - : No user context with an ID specified in `userContexts` is found. | ||||||||||||||||||
|
|
||||||||||||||||||
| ## Description | ||||||||||||||||||
|
|
||||||||||||||||||
| The `emulation.setLocaleOverride` command allows you to simulate a locale for the selected top-level contexts or user contexts. | ||||||||||||||||||
|
|
||||||||||||||||||
| The command changes the default locale used by internationalization APIs such as [`Intl.DateTimeFormat`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). | ||||||||||||||||||
| It also changes the language preferences exposed through [`navigator.language`](/en-US/docs/Web/API/Navigator/language) and [`navigator.languages`](/en-US/docs/Web/API/Navigator/languages). | ||||||||||||||||||
|
|
||||||||||||||||||
| The command also sets the [`Accept-Language`](/en-US/docs/Web/HTTP/Reference/Headers/Accept-Language) request header to the overridden locale when the request does not already specify that header. | ||||||||||||||||||
|
Comment on lines
+77
to
+80
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Using macros |
||||||||||||||||||
|
|
||||||||||||||||||
| To remove an override, set `locale` to `null` for the affected contexts or user contexts. | ||||||||||||||||||
| If you remove an override for a top-level context, an override configured for its user context still applies. | ||||||||||||||||||
|
|
||||||||||||||||||
| ## Examples | ||||||||||||||||||
|
|
||||||||||||||||||
| ### Overriding a tab's locale with French | ||||||||||||||||||
|
|
||||||||||||||||||
| Assume you have a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and an [active session](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new). | ||||||||||||||||||
|
|
||||||||||||||||||
| Suppose you have a web page that formats dates using the browser's default locale, and you want to verify that it displays dates in French when the locale is `fr-FR`. | ||||||||||||||||||
|
|
||||||||||||||||||
| First, open a tab using [`browsingContext.create`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/create), which returns its context ID. | ||||||||||||||||||
| Then load the page you're testing. | ||||||||||||||||||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Maybe linking this one, too? |
||||||||||||||||||
|
|
||||||||||||||||||
| Send the following message to set the tab's locale to French: | ||||||||||||||||||
|
|
||||||||||||||||||
| ```json | ||||||||||||||||||
| { | ||||||||||||||||||
| "id": 1, | ||||||||||||||||||
| "method": "emulation.setLocaleOverride", | ||||||||||||||||||
| "params": { | ||||||||||||||||||
| "contexts": ["5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"], | ||||||||||||||||||
| "locale": "fr-FR" | ||||||||||||||||||
| } | ||||||||||||||||||
| } | ||||||||||||||||||
| ``` | ||||||||||||||||||
|
|
||||||||||||||||||
| The browser responds with an empty `result` object: | ||||||||||||||||||
|
|
||||||||||||||||||
| ```json | ||||||||||||||||||
| { | ||||||||||||||||||
| "type": "success", | ||||||||||||||||||
| "id": 1, | ||||||||||||||||||
|
Comment on lines
+113
to
+114
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Just for consistency with other pages. |
||||||||||||||||||
| "result": {} | ||||||||||||||||||
| } | ||||||||||||||||||
| ``` | ||||||||||||||||||
|
|
||||||||||||||||||
| After the command succeeds, trigger the page's date formatting. | ||||||||||||||||||
| When the page creates a new [`Intl.DateTimeFormat`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) object without specifying a locale, the object uses the overridden locale, `fr-FR`. | ||||||||||||||||||
| Check that the page displays dates using French formatting conventions, such as "14 mars 2026" for March 14, 2026, when using the [`dateStyle: "long"`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#datestyle) option. | ||||||||||||||||||
|
|
||||||||||||||||||
| To remove the override, send the same command with `locale` set to `null` and the same `contexts` array. | ||||||||||||||||||
|
|
||||||||||||||||||
| ## Specifications | ||||||||||||||||||
|
|
||||||||||||||||||
| {{Specifications}} | ||||||||||||||||||
|
|
||||||||||||||||||
| ## Browser compatibility | ||||||||||||||||||
|
|
||||||||||||||||||
| {{Compat}} | ||||||||||||||||||
|
|
||||||||||||||||||
| ## See also | ||||||||||||||||||
|
|
||||||||||||||||||
| - [`browser.getUserContexts`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browser/getUserContexts) command | ||||||||||||||||||
| - [`browsingContext.create`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/create) command | ||||||||||||||||||
| - [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree) command | ||||||||||||||||||
| - [`Intl.DateTimeFormat`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) | ||||||||||||||||||
| - [`Navigator.language`](/en-US/docs/Web/API/Navigator/language) | ||||||||||||||||||
| - [`Navigator.languages`](/en-US/docs/Web/API/Navigator/languages) | ||||||||||||||||||
| Original file line number | Diff line number | Diff line change | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,138 @@ | ||||||||||
| --- | ||||||||||
| title: "`emulation.setTimezoneOverride` command" | ||||||||||
| short-title: setTimezoneOverride | ||||||||||
| slug: Web/WebDriver/Reference/BiDi/Modules/emulation/setTimezoneOverride | ||||||||||
| page-type: webdriver-command | ||||||||||
| browser-compat: webdriver.bidi.emulation.setTimezoneOverride | ||||||||||
| sidebar: webdriver | ||||||||||
| --- | ||||||||||
|
|
||||||||||
| The `emulation.setTimezoneOverride` [command](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#commands) of the [`emulation`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/emulation) module overrides the time zone for the specified [top-level contexts](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext#top-level_context) or [user contexts](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browser#user_contexts). | ||||||||||
|
|
||||||||||
| ## Syntax | ||||||||||
|
|
||||||||||
| ```json-nolint | ||||||||||
| /* With required parameters and `contexts` */ | ||||||||||
| { | ||||||||||
| "method": "emulation.setTimezoneOverride", | ||||||||||
| "params": { | ||||||||||
| "contexts": [ | ||||||||||
| "5e5e96e8-5247-4f22-9b35-a4a2d841cbaa" | ||||||||||
| ], | ||||||||||
| "timezone": "Asia/Tokyo" | ||||||||||
| } | ||||||||||
| } | ||||||||||
|
|
||||||||||
| /* With required parameters and `userContexts` */ | ||||||||||
| { | ||||||||||
| "method": "emulation.setTimezoneOverride", | ||||||||||
| "params": { | ||||||||||
| "timezone": "Asia/Tokyo", | ||||||||||
| "userContexts": [ | ||||||||||
| "a812d4d0-8c8f-4c78-9de1-3e5c5b3b3c3c" | ||||||||||
| ] | ||||||||||
| } | ||||||||||
| } | ||||||||||
| ``` | ||||||||||
|
|
||||||||||
| ### Parameters | ||||||||||
|
|
||||||||||
| The `params` field contains: | ||||||||||
|
|
||||||||||
| - `contexts` {{optional_inline}} | ||||||||||
| - : An array of one or more strings that contains the IDs of the [top-level contexts](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext#top-level_context) to affect. | ||||||||||
| Context IDs are returned by commands such as [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree). | ||||||||||
| This field cannot be used if [`userContexts`](#usercontexts) is also specified, but it is required if `userContexts` is not specified. | ||||||||||
| - `timezone` | ||||||||||
| - : A string that specifies an available [named time zone identifier or time zone offset string](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#time_zones_and_offsets), such as `"Asia/Tokyo"` or `"+09:00"`. | ||||||||||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
For consistency with other pages. |
||||||||||
| It can be `null` to remove the time zone override at the specified scope. | ||||||||||
| - `userContexts` {{optional_inline}} | ||||||||||
| - : An array of one or more strings that contains the IDs of the [user contexts](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browser#user_contexts) to affect. | ||||||||||
| User context IDs are returned by commands such as [`browser.createUserContext`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browser/createUserContext) or [`browser.getUserContexts`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browser/getUserContexts). | ||||||||||
| This field cannot be used if [`contexts`](#contexts) is also specified, but it is required if `contexts` is not specified. | ||||||||||
|
|
||||||||||
| ### Return value | ||||||||||
|
|
||||||||||
| The `result` field in the response is an empty object (`{}`). | ||||||||||
|
|
||||||||||
| ### Errors | ||||||||||
|
|
||||||||||
| - [`invalid argument`](/en-US/docs/Web/WebDriver/Reference/Errors/InvalidArgument) | ||||||||||
| - : Thrown in any of the following cases: | ||||||||||
| - A required parameter is missing, or a parameter has an invalid type or value. | ||||||||||
| - Both `contexts` and `userContexts` are specified. | ||||||||||
| - Neither `contexts` nor `userContexts` is specified. | ||||||||||
| - `contexts` or `userContexts` is an empty array. | ||||||||||
| - A context specified in `contexts` is not a top-level context. | ||||||||||
| - `timezone` is neither `null` nor a valid time zone offset string nor an available named time zone identifier. | ||||||||||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
It would be easier to read. |
||||||||||
| - `no such frame` | ||||||||||
| - : No context with an ID specified in `contexts` is found. | ||||||||||
| - `no such user context` | ||||||||||
| - : No user context with an ID specified in `userContexts` is found. | ||||||||||
|
|
||||||||||
| ## Description | ||||||||||
|
|
||||||||||
| The `emulation.setTimezoneOverride` command allows you to simulate a time zone for the selected top-level contexts or user contexts. | ||||||||||
|
|
||||||||||
| The command changes the default time zone used by date and time APIs such as [`Intl.DateTimeFormat`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). | ||||||||||
| It also changes the local time zone used by [`Date`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) methods such as [`getHours()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getHours) and [`getTimezoneOffset()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTimezoneOffset). | ||||||||||
|
Comment on lines
+77
to
+78
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
|
|
||||||||||
| To remove an override, set `timezone` to `null` for the affected contexts or user contexts. | ||||||||||
| If you remove an override for a top-level context, an override configured for its user context still applies. | ||||||||||
|
|
||||||||||
| ## Examples | ||||||||||
|
|
||||||||||
| ### Overriding a tab's time zone with Asia/Tokyo | ||||||||||
|
|
||||||||||
| Assume you have a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and an [active session](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new). | ||||||||||
|
|
||||||||||
| Suppose you have a web page that displays event times in the browser's default time zone, and you want to verify that it displays them in Tokyo's time zone when the override is `Asia/Tokyo`. | ||||||||||
|
|
||||||||||
| First, open a tab using [`browsingContext.create`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/create), which returns its context ID. | ||||||||||
| Then load the page you're testing. | ||||||||||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Same as above. |
||||||||||
|
|
||||||||||
| Send the following message to set the tab's time zone to `Asia/Tokyo`: | ||||||||||
|
|
||||||||||
| ```json | ||||||||||
| { | ||||||||||
| "id": 1, | ||||||||||
| "method": "emulation.setTimezoneOverride", | ||||||||||
| "params": { | ||||||||||
| "contexts": ["5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"], | ||||||||||
| "timezone": "Asia/Tokyo" | ||||||||||
| } | ||||||||||
| } | ||||||||||
| ``` | ||||||||||
|
|
||||||||||
| The browser responds with an empty `result` object: | ||||||||||
|
|
||||||||||
| ```json | ||||||||||
| { | ||||||||||
| "type": "success", | ||||||||||
| "id": 1, | ||||||||||
|
Comment on lines
+111
to
+112
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
| "result": {} | ||||||||||
| } | ||||||||||
| ``` | ||||||||||
|
|
||||||||||
| After the command succeeds, trigger the page's date and time formatting. | ||||||||||
| When the page creates a new [`Intl.DateTimeFormat`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) object without specifying a [`timeZone`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#timezone) option, the object uses the overridden time zone, `Asia/Tokyo`. | ||||||||||
| Check that the page displays event times in Tokyo's time zone, for example, 18:00 for an event at 09:00 UTC. | ||||||||||
|
|
||||||||||
| To remove the override, send the same command with `timezone` set to `null` and the same `contexts` array. | ||||||||||
|
|
||||||||||
| ## Specifications | ||||||||||
|
|
||||||||||
| {{Specifications}} | ||||||||||
|
|
||||||||||
| ## Browser compatibility | ||||||||||
|
|
||||||||||
| {{Compat}} | ||||||||||
|
|
||||||||||
| ## See also | ||||||||||
|
|
||||||||||
| - [`browser.getUserContexts`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browser/getUserContexts) command | ||||||||||
| - [`browsingContext.create`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/create) command | ||||||||||
| - [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree) command | ||||||||||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Would be relevant here too. |
||||||||||
| - [`Intl.DateTimeFormat`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) | ||||||||||
| - [`Date`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | ||||||||||
| - [Time zones and offsets](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#time_zones_and_offsets) | ||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.