emulation.setTimezoneOverride command
The emulation.setTimezoneOverride command of the emulation module overrides the time zone for the specified top-level contexts or user contexts.
Syntax
/* 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:
contextsOptional-
An array of one or more strings that contains the IDs of the top-level contexts to affect. Context IDs are returned by commands such as
browsingContext.getTree. This field cannot be used ifuserContextsis also specified, but it is required ifuserContextsis not specified. timezone-
A string that specifies an available named time zone identifier or time zone offset string, such as
"Asia/Tokyo"or"+09:00". It can benullto remove the time zone override at the specified scope. userContextsOptional-
An array of one or more strings that contains the IDs of the user contexts to affect. User context IDs are returned by commands such as
browser.createUserContextorbrowser.getUserContexts. This field cannot be used ifcontextsis also specified, but it is required ifcontextsis not specified.
Return value
The result field in the response is an empty object ({}).
Errors
invalid argument-
Thrown in any of the following cases:
- A required parameter is missing, or a parameter has an invalid type or value.
- Both
contextsanduserContextsare specified. - Neither
contextsnoruserContextsis specified. contextsoruserContextsis an empty array.- A context specified in
contextsis not a top-level context. timezoneis neithernullnor a valid time zone offset string nor an available named time zone identifier.
no such frame-
No context with an ID specified in
contextsis found. no such user context-
No user context with an ID specified in
userContextsis 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.
It also changes the local time zone used by Date methods such as getHours() and 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 and an active session.
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, 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:
{
"id": 1,
"method": "emulation.setTimezoneOverride",
"params": {
"contexts": ["5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"],
"timezone": "Asia/Tokyo"
}
}
The browser responds with an empty result object:
{
"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 object without specifying a 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
| Specification |
|---|
| WebDriver BiDi> # command-emulation-setTimezoneOverride> |
Browser compatibility
See also
browser.getUserContextscommandbrowsingContext.createcommandbrowsingContext.getTreecommandIntl.DateTimeFormatDate- Time zones and offsets