Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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}}
Expand Down
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).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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).
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 {{glossary("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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
The command changes the default locale used by internationalization APIs such as {{jsxref("Intl.DateTimeFormat")}}.
It also changes the language preferences exposed through {{domxref("Navigator.language", "navigator.language")}} and {{domxref("Navigator.languages", "navigator.languages")}}.
The command also sets the {{HTTPHeader("Accept-Language")}} request header to the overridden locale when the request does not already specify that header.

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Then load the page you're testing.
Then load the page you're testing using [`browsingContext.navigate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigate).

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"type": "success",
"id": 1,
"id": 1,
"type": "success",

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"`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- : 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"`.
- : 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`.

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `timezone` is neither `null` nor a valid time zone offset string nor an available named time zone identifier.
- `timezone` is not `null` and is neither a valid time zone offset string nor an available named time zone identifier.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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).
The command changes the default time zone used by date and time APIs such as {{jsxref("Intl.DateTimeFormat")}}.
It also changes the local time zone used by {{jsxref("Date")}} methods such as {{jsxref("Date.prototype.getHours()", "getHours()")}} and {{jsxref("Date.prototype.getTimezoneOffset()", "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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Then load the page you're testing.
Then load the page you're testing using [`browsingContext.navigate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigate).

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"type": "success",
"id": 1,
"id": 1,
"type": "success",

"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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree) command
- [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree) command
- [`emulation.setLocaleOverride`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/emulation/setLocaleOverride) command

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)
8 changes: 8 additions & 0 deletions files/sidebars/webdriver.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading