Skip to content

[Technical review] BiDi emulation module - setGeolocationOverride command - #46498

Merged
dipikabh merged 4 commits into
mdn:mainfrom
dipikabh:bidi-emulation-geo
Nov 22, 2026
Merged

dipikabh merged 4 commits into
mdn:mainfrom
dipikabh:bidi-emulation-geo

Conversation

@dipikabh

Copy link
Copy Markdown
Contributor

Description

This PR adds the page for emulation.setGeolocationOverride command, with corresponding updates to the module overview page and the sidebar.

Note

The Firefox note in BCD explicitly states that the global configuration is not yet supported.
My testing in Chrome shows the same limitation: omitting both scope selectors returns invalid argument: “Either user contexts or browsing contexts must be provided”. However, there's no such note for Chrome in BCD.

The current version of the page aligns with the spec to say that session-wide overrides are applied when neither contexts nor userContexts is specified. Let me know if this needs to be changed to the implemented behaviour instead.

Spec link

Related issues and pull requests

Project tracker: mdn/mdn#851

@dipikabh
dipikabh requested a review from a team November 12, 2026 17:32
@dipikabh
dipikabh requested review from a team as code owners November 12, 2026 17:32
@dipikabh
dipikabh requested review from chrisdavidmills and pepelsbey and removed request for a team November 12, 2026 17:32
@github-actions github-actions Bot added the Content:WebDriver WebDriver docs label Nov 12, 2026
@github-actions github-actions Bot added the size/m [PR only] 51-500 LoC changed label Nov 12, 2026
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Preview URLs (2 pages)

Flaws (3)

Note! 1 document with no flaws that don't need to be listed. 🎉

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Web/WebDriver/Reference/BiDi/Modules/emulation/setGeolocationOverride
Title: emulation.setGeolocationOverride command
Flaw count: 3

  • broken_links:
    • Link /en-US/docs/Web/WebDriver/Reference/BiDi/Modules/permissions/setPermission doesn't resolve
    • Link /en-US/docs/Web/WebDriver/Reference/BiDi/Modules/permissions/setPermission doesn't resolve
    • Link /en-US/docs/Web/WebDriver/Reference/BiDi/Modules/permissions/setPermission doesn't resolve

(comment last updated: 2026-11-22 06:07:16)

@chrisdavidmills chrisdavidmills left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Looks great, @dipikabh. Just a couple of small comments.

@dipikabh

Copy link
Copy Markdown
Contributor Author

Thanks for reviewing, @chrisdavidmills!
I’ll also wait for a technical review from the Webdriver team before merging this.

(sorry for the initial ping, can't avoid it - GH automatically adds a reviewer from mdn/web when I open the PR)

@whimboo whimboo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This looks fine to me. Nothing else to comment on. Thank you @dipikabh!

dipikabh and others added 2 commits November 20, 2026 20:51
Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Comment on lines +1 to +212
---
title: "`emulation.setGeolocationOverride` command"
short-title: setGeolocationOverride
slug: Web/WebDriver/Reference/BiDi/Modules/emulation/setGeolocationOverride
page-type: webdriver-command
browser-compat: webdriver.bidi.emulation.setGeolocationOverride
sidebar: webdriver
---

The `emulation.setGeolocationOverride` [command](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#commands) of the [`emulation`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/emulation) module overrides geolocation characteristics exposed through the [Geolocation API](/en-US/docs/Web/API/Geolocation_API) 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.setGeolocationOverride",
"params": {
"contexts": [
"5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"
],
"coordinates": {
"latitude": 51.5074,
"longitude": -0.1278
}
}
}

/* With required parameters and `userContexts` */
{
"method": "emulation.setGeolocationOverride",
"params": {
"coordinates": {
"latitude": 51.5074,
"longitude": -0.1278
},
"userContexts": [
"a812d4d0-8c8f-4c78-9de1-3e5c5b3b3c3c"
]
}
}

/* With required and optional parameters */
{
"method": "emulation.setGeolocationOverride",
"params": {
"contexts": [
"5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"
],
"coordinates": {
"accuracy": 10,
"altitude": 35,
"altitudeAccuracy": 5,
"heading": 90,
"latitude": 51.5074,
"longitude": -0.1278,
"speed": 1.5
}
}
}
```

### 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.
- `coordinates`
- : An object that specifies the simulated geographic position.
It can be `null` to remove the override at the specified scope.
This field cannot be used if `error` is also specified, but it is required if `error` is not specified.
It contains the following fields:
- `accuracy` {{optional_inline}}
- : A non-negative number that specifies the accuracy of the `latitude` and `longitude` values in meters.
The default value is `1`.
- `altitude` {{optional_inline}}
- : A number that specifies the altitude in meters, relative to nominal sea level.
It can be `null` to simulate unavailable altitude data.
The default value is `null`.
- `altitudeAccuracy` {{optional_inline}}
- : A non-negative number that specifies the accuracy of the `altitude` value in meters.
It can be `null` to simulate unavailable altitude accuracy data.
Specify `altitude` when specifying this field.
The default value is `null`.
- `heading` {{optional_inline}}
- : A number that specifies the direction of travel in degrees clockwise from true north.
It can be `null` to simulate unavailable heading data.
The value must be greater than or equal to `0` and less than `360`.
The default value is `null`.
- `latitude`
- : A number that specifies the latitude in decimal degrees.
The value must be between `-90` and `90`.
- `longitude`
- : A number that specifies the longitude in decimal degrees.
The value must be between `-180` and `180`.
- `speed` {{optional_inline}}
- : A non-negative number that specifies the speed in meters per second.
It can be `null` to simulate unavailable speed data.
The default value is `null`.
- `error`
- : An object that specifies a simulated failure to obtain a position.
This field cannot be used if `coordinates` is also specified, but it is required if `coordinates` is not specified.
- `type`
- : A string that specifies the simulated error.
The only supported value is `positionUnavailable`.
- `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.

If neither `contexts` nor `userContexts` is specified, the command applies to the entire session.

### 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.
- `contexts` or `userContexts` is an empty array.
- A context specified in `contexts` is not a top-level context.
- Both `coordinates` and `error` are specified.
- Neither `coordinates` nor `error` is specified.
- [`altitudeAccuracy`](#altitudeaccuracy) is specified without [`altitude`](#altitude).
- `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.setGeolocationOverride` command allows you to simulate a geographic location for the selected top-level contexts or user contexts; if neither scope is specified, the override applies to the entire session.
The command overrides the position reported by the [Geolocation API](/en-US/docs/Web/API/Geolocation_API), so you can test location-aware features such as geofencing for local recommendations.

The `coordinates` parameter supplies a simulated position, while `error` simulates a failure to obtain one.
You cannot use these fields together, but you must specify one of them.
Setting an individual coordinate field, such as `altitude`, to `null` simulates unavailable data for that field.

An override set for a specific context takes precedence over an override set for its user context.
An override set for a user context takes precedence over an override set for the entire session.

To remove an override, set `coordinates` to `null` for the affected contexts or user contexts.
For example, if you set Paris for a user context and London for a tab within it, removing the tab's override makes the tab report Paris.

Overriding the position does not automatically grant geolocation permission.
To configure geolocation permission for your test, use the [`permissions.setPermission`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/permissions/setPermission) command.

## Examples

### Overriding a tab's location with Toronto coordinates

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 recommends nearby restaurants based on the user's location, and you want to check that it shows recommendations for Toronto.

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 over HTTPS or from localhost, since the [Geolocation API](/en-US/docs/Web/API/Geolocation_API) requires a secure context.
Additionally, grant geolocation permission for the page's origin using [`permissions.setPermission`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/permissions/setPermission).

Send the following message to override the tab's location with Toronto's coordinates:

```json
{
"id": 1,
"method": "emulation.setGeolocationOverride",
"params": {
"contexts": ["5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"],
"coordinates": {
"latitude": 43.6532,
"longitude": -79.3832
}
}
}
```

The browser responds with an empty `result` object:

```json
{
"type": "success",
"id": 1,
"result": {}
}
```

After the command succeeds, trigger the page's location lookup.
When the page requests the user's position, the browser returns the overridden coordinates.
Check that the page displays restaurant recommendations for Toronto.

To remove the override, send the same command with `coordinates` 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
- [`permissions.setPermission`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/permissions/setPermission) command
- [Geolocation API](/en-US/docs/Web/API/Geolocation_API)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[mdn-linter] reported by reviewdog 🐶

Suggested change
---
title: "`emulation.setGeolocationOverride` command"
short-title: setGeolocationOverride
slug: Web/WebDriver/Reference/BiDi/Modules/emulation/setGeolocationOverride
page-type: webdriver-command
browser-compat: webdriver.bidi.emulation.setGeolocationOverride
sidebar: webdriver
---
The `emulation.setGeolocationOverride` [command](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#commands) of the [`emulation`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/emulation) module overrides geolocation characteristics exposed through the [Geolocation API](/en-US/docs/Web/API/Geolocation_API) 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.setGeolocationOverride",
"params": {
"contexts": [
"5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"
],
"coordinates": {
"latitude": 51.5074,
"longitude": -0.1278
}
}
}
/* With required parameters and `userContexts` */
{
"method": "emulation.setGeolocationOverride",
"params": {
"coordinates": {
"latitude": 51.5074,
"longitude": -0.1278
},
"userContexts": [
"a812d4d0-8c8f-4c78-9de1-3e5c5b3b3c3c"
]
}
}
/* With required and optional parameters */
{
"method": "emulation.setGeolocationOverride",
"params": {
"contexts": [
"5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"
],
"coordinates": {
"accuracy": 10,
"altitude": 35,
"altitudeAccuracy": 5,
"heading": 90,
"latitude": 51.5074,
"longitude": -0.1278,
"speed": 1.5
}
}
}
```
### 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.
- `coordinates`
- : An object that specifies the simulated geographic position.
It can be `null` to remove the override at the specified scope.
This field cannot be used if `error` is also specified, but it is required if `error` is not specified.
It contains the following fields:
- `accuracy` {{optional_inline}}
- : A non-negative number that specifies the accuracy of the `latitude` and `longitude` values in meters.
The default value is `1`.
- `altitude` {{optional_inline}}
- : A number that specifies the altitude in meters, relative to nominal sea level.
It can be `null` to simulate unavailable altitude data.
The default value is `null`.
- `altitudeAccuracy` {{optional_inline}}
- : A non-negative number that specifies the accuracy of the `altitude` value in meters.
It can be `null` to simulate unavailable altitude accuracy data.
Specify `altitude` when specifying this field.
The default value is `null`.
- `heading` {{optional_inline}}
- : A number that specifies the direction of travel in degrees clockwise from true north.
It can be `null` to simulate unavailable heading data.
The value must be greater than or equal to `0` and less than `360`.
The default value is `null`.
- `latitude`
- : A number that specifies the latitude in decimal degrees.
The value must be between `-90` and `90`.
- `longitude`
- : A number that specifies the longitude in decimal degrees.
The value must be between `-180` and `180`.
- `speed` {{optional_inline}}
- : A non-negative number that specifies the speed in meters per second.
It can be `null` to simulate unavailable speed data.
The default value is `null`.
- `error`
- : An object that specifies a simulated failure to obtain a position.
This field cannot be used if `coordinates` is also specified, but it is required if `coordinates` is not specified.
- `type`
- : A string that specifies the simulated error.
The only supported value is `positionUnavailable`.
- `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.
If neither `contexts` nor `userContexts` is specified, the command applies to the entire session.
### 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.
- `contexts` or `userContexts` is an empty array.
- A context specified in `contexts` is not a top-level context.
- Both `coordinates` and `error` are specified.
- Neither `coordinates` nor `error` is specified.
- [`altitudeAccuracy`](#altitudeaccuracy) is specified without [`altitude`](#altitude).
- `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.setGeolocationOverride` command allows you to simulate a geographic location for the selected top-level contexts or user contexts; if neither scope is specified, the override applies to the entire session.
The command overrides the position reported by the [Geolocation API](/en-US/docs/Web/API/Geolocation_API), so you can test location-aware features such as geofencing for local recommendations.
The `coordinates` parameter supplies a simulated position, while `error` simulates a failure to obtain one.
You cannot use these fields together, but you must specify one of them.
Setting an individual coordinate field, such as `altitude`, to `null` simulates unavailable data for that field.
An override set for a specific context takes precedence over an override set for its user context.
An override set for a user context takes precedence over an override set for the entire session.
To remove an override, set `coordinates` to `null` for the affected contexts or user contexts.
For example, if you set Paris for a user context and London for a tab within it, removing the tab's override makes the tab report Paris.
Overriding the position does not automatically grant geolocation permission.
To configure geolocation permission for your test, use the [`permissions.setPermission`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/permissions/setPermission) command.
## Examples
### Overriding a tab's location with Toronto coordinates
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 recommends nearby restaurants based on the user's location, and you want to check that it shows recommendations for Toronto.
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 over HTTPS or from localhost, since the [Geolocation API](/en-US/docs/Web/API/Geolocation_API) requires a secure context.
Additionally, grant geolocation permission for the page's origin using [`permissions.setPermission`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/permissions/setPermission).
Send the following message to override the tab's location with Toronto's coordinates:
```json
{
"id": 1,
"method": "emulation.setGeolocationOverride",
"params": {
"contexts": ["5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"],
"coordinates": {
"latitude": 43.6532,
"longitude": -79.3832
}
}
}
```
The browser responds with an empty `result` object:
```json
{
"type": "success",
"id": 1,
"result": {}
}
```
After the command succeeds, trigger the page's location lookup.
When the page requests the user's position, the browser returns the overridden coordinates.
Check that the page displays restaurant recommendations for Toronto.
To remove the override, send the same command with `coordinates` 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
- [`permissions.setPermission`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/permissions/setPermission) command
- [Geolocation API](/en-US/docs/Web/API/Geolocation_API)
---
title: "`emulation.setGeolocationOverride` command"
short-title: setGeolocationOverride
slug: Web/WebDriver/Reference/BiDi/Modules/emulation/setGeolocationOverride
page-type: webdriver-command
browser-compat: webdriver.bidi.emulation.setGeolocationOverride
sidebar: webdriver
---
The `emulation.setGeolocationOverride` [command](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#commands) of the [`emulation`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/emulation) module overrides geolocation characteristics exposed through the [Geolocation API](/en-US/docs/Web/API/Geolocation_API) 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.setGeolocationOverride",
"params": {
"contexts": [
"5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"
],
"coordinates": {
"latitude": 51.5074,
"longitude": -0.1278
}
}
}
/* With required parameters and `userContexts` */
{
"method": "emulation.setGeolocationOverride",
"params": {
"coordinates": {
"latitude": 51.5074,
"longitude": -0.1278
},
"userContexts": [
"a812d4d0-8c8f-4c78-9de1-3e5c5b3b3c3c"
]
}
}
/* With required and optional parameters */
{
"method": "emulation.setGeolocationOverride",
"params": {
"contexts": [
"5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"
],
"coordinates": {
"accuracy": 10,
"altitude": 35,
"altitudeAccuracy": 5,
"heading": 90,
"latitude": 51.5074,
"longitude": -0.1278,
"speed": 1.5
}
}
}
```
### 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.
- `coordinates`
- : An object that specifies the simulated geographic position.
It can be `null` to remove the override at the specified scope.
This field cannot be used if `error` is also specified, but it is required if `error` is not specified.
It contains the following fields:
- `accuracy` {{optional_inline}}
- : A non-negative number that specifies the accuracy of the `latitude` and `longitude` values in meters.
The default value is `1`.
- `altitude` {{optional_inline}}
- : A number that specifies the altitude in meters, relative to nominal sea level.
It can be `null` to simulate unavailable altitude data.
The default value is `null`.
- `altitudeAccuracy` {{optional_inline}}
- : A non-negative number that specifies the accuracy of the `altitude` value in meters.
It can be `null` to simulate unavailable altitude accuracy data.
Specify `altitude` when specifying this field.
The default value is `null`.
- `heading` {{optional_inline}}
- : A number that specifies the direction of travel in degrees clockwise from true north.
It can be `null` to simulate unavailable heading data.
The value must be greater than or equal to `0` and less than `360`.
The default value is `null`.
- `latitude`
- : A number that specifies the latitude in decimal degrees.
The value must be between `-90` and `90`.
- `longitude`
- : A number that specifies the longitude in decimal degrees.
The value must be between `-180` and `180`.
- `speed` {{optional_inline}}
- : A non-negative number that specifies the speed in meters per second.
It can be `null` to simulate unavailable speed data.
The default value is `null`.
- `error`
- : An object that specifies a simulated failure to obtain a position.
This field cannot be used if `coordinates` is also specified, but it is required if `coordinates` is not specified.
- `type`
- : A string that specifies the simulated error.
The only supported value is `positionUnavailable`.
- `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.
If neither `contexts` nor `userContexts` is specified, the command applies to the entire session.
### 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.
- `contexts` or `userContexts` is an empty array.
- A context specified in `contexts` is not a top-level context.
- Both `coordinates` and `error` are specified.
- Neither `coordinates` nor `error` is specified.
- [`altitudeAccuracy`](#altitudeaccuracy) is specified without [`altitude`](#altitude).
- `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.setGeolocationOverride` command allows you to simulate a geographic location for the selected top-level contexts or user contexts; if neither scope is specified, the override applies to the entire session.
The command overrides the position reported by the [Geolocation API](/en-US/docs/Web/API/Geolocation_API), so you can test location-aware features such as geofencing for local recommendations.
The `coordinates` parameter supplies a simulated position, while `error` simulates a failure to obtain one.
You cannot use these fields together, but you must specify one of them.
Setting an individual coordinate field, such as `altitude`, to `null` simulates unavailable data for that field.
An override set for a specific context takes precedence over an override set for its user context.
An override set for a user context takes precedence over an override set for the entire session.
To remove an override, set `coordinates` to `null` for the affected contexts or user contexts.
For example, if you set Paris for a user context and London for a tab within it, removing the tab's override makes the tab report Paris.
Overriding the position does not automatically grant geolocation permission.
To configure geolocation permission for your test, use the [`permissions.setPermission`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/permissions/setPermission) command.
## Examples
### Overriding a tab's location with Toronto coordinates
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 recommends nearby restaurants based on the user's location, and you want to check that it shows recommendations for Toronto.
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 over HTTPS or from localhost, since the [Geolocation API](/en-US/docs/Web/API/Geolocation_API) requires a secure context.
Additionally, grant geolocation permission for the page's origin using [`permissions.setPermission`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/permissions/setPermission).
Send the following message to override the tab's location with Toronto's coordinates:
```json
{
"id": 1,
"method": "emulation.setGeolocationOverride",
"params": {
"contexts": ["5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"],
"coordinates": {
"latitude": 43.6532,
"longitude": -79.3832
}
}
}
```
The browser responds with an empty `result` object:
```json
{
"type": "success",
"id": 1,
"result": {}
}
```
After the command succeeds, trigger the page's location lookup.
When the page requests the user's position, the browser returns the overridden coordinates.
Check that the page displays restaurant recommendations for Toronto.
To remove the override, send the same command with `coordinates` 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
- [`permissions.setPermission`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/permissions/setPermission) command
- [Geolocation API](/en-US/docs/Web/API/Geolocation_API)

@dipikabh
dipikabh merged commit fbe036d into mdn:main Nov 22, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Content:WebDriver WebDriver docs size/m [PR only] 51-500 LoC changed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants