From 80aeb9fbe5634d0d5bece7478dd590814657eb03 Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Fri, 13 Nov 2026 12:33:04 -0500 Subject: [PATCH 1/4] adds locale override page --- .../emulation/setlocaleoverride/index.md | 140 ++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 files/en-us/web/webdriver/reference/bidi/modules/emulation/setlocaleoverride/index.md diff --git a/files/en-us/web/webdriver/reference/bidi/modules/emulation/setlocaleoverride/index.md b/files/en-us/web/webdriver/reference/bidi/modules/emulation/setlocaleoverride/index.md new file mode 100644 index 000000000000000..736d8e92a42c8c4 --- /dev/null +++ b/files/en-us/web/webdriver/reference/bidi/modules/emulation/setlocaleoverride/index.md @@ -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. + +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. + +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, + "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 formatter 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) From 1b77aedeeb6d7c148675c230d63e57507f30b5a4 Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Fri, 13 Nov 2026 13:41:39 -0500 Subject: [PATCH 2/4] adds timezone override page --- .../emulation/settimezoneoverride/index.md | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 files/en-us/web/webdriver/reference/bidi/modules/emulation/settimezoneoverride/index.md diff --git a/files/en-us/web/webdriver/reference/bidi/modules/emulation/settimezoneoverride/index.md b/files/en-us/web/webdriver/reference/bidi/modules/emulation/settimezoneoverride/index.md new file mode 100644 index 000000000000000..e78b4e813ac98ba --- /dev/null +++ b/files/en-us/web/webdriver/reference/bidi/modules/emulation/settimezoneoverride/index.md @@ -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"`. + 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. +- `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). + +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. + +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, + "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 +- [`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) From f5b79296fc6c96428acf725f146b44ee14c2bdc2 Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Fri, 13 Nov 2026 13:46:37 -0500 Subject: [PATCH 3/4] updates overview page --- .../web/webdriver/reference/bidi/modules/emulation/index.md | 5 +++++ .../bidi/modules/emulation/setlocaleoverride/index.md | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/files/en-us/web/webdriver/reference/bidi/modules/emulation/index.md b/files/en-us/web/webdriver/reference/bidi/modules/emulation/index.md index d757ad06d40990b..5bfe1718bc82d86 100644 --- a/files/en-us/web/webdriver/reference/bidi/modules/emulation/index.md +++ b/files/en-us/web/webdriver/reference/bidi/modules/emulation/index.md @@ -9,6 +9,11 @@ sidebar: webdriver The **`emulation`** module contains commands for overriding the behavior of certain Web APIs, such as the [Geolocation API](/en-US/docs/Web/API/Geolocation_API) and the [Screen Orientation API](/en-US/docs/Web/API/Screen_Orientation_API), to simulate different environments. +## Commands + +- [`emulation.setLocaleOverride`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/emulation/setLocaleOverride) +- [`emulation.setTimezoneOverride`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/emulation/setTimezoneOverride) + ## Specifications {{Specifications}} diff --git a/files/en-us/web/webdriver/reference/bidi/modules/emulation/setlocaleoverride/index.md b/files/en-us/web/webdriver/reference/bidi/modules/emulation/setlocaleoverride/index.md index 736d8e92a42c8c4..799c6f9c8b72652 100644 --- a/files/en-us/web/webdriver/reference/bidi/modules/emulation/setlocaleoverride/index.md +++ b/files/en-us/web/webdriver/reference/bidi/modules/emulation/setlocaleoverride/index.md @@ -117,7 +117,7 @@ The browser responds with an empty `result` object: ``` 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 formatter uses the overridden locale, `fr-FR`. +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. From 3451b35aec3b36b882514a91f60883cb02286fec Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Fri, 13 Nov 2026 13:50:35 -0500 Subject: [PATCH 4/4] updates sidebar --- files/sidebars/webdriver.yaml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/files/sidebars/webdriver.yaml b/files/sidebars/webdriver.yaml index 152025e198e6036..1d172c5ac322d6f 100644 --- a/files/sidebars/webdriver.yaml +++ b/files/sidebars/webdriver.yaml @@ -99,7 +99,15 @@ sidebar: - link: /Web/WebDriver/Reference/BiDi/Modules/browsingContext/userPromptOpened code: true - link: /Web/WebDriver/Reference/BiDi/Modules/emulation + details: closed code: true + children: + - type: listSubPages + path: /Web/WebDriver/Reference/BiDi/Modules/emulation + tags: webdriver-command + link: /Web/WebDriver/Reference/BiDi/Modules/emulation#commands + title: Commands + code: true - link: /Web/WebDriver/Reference/BiDi/Modules/input details: closed code: true