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

json
/* 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

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 if 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, such as "Asia/Tokyo" or "+09:00". It can be null to remove the time zone override at the specified scope.

userContexts Optional

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.createUserContext or browser.getUserContexts. This field cannot be used if 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

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. 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:

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 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