emulation.setGeolocationOverride command
The emulation.setGeolocationOverride command of the emulation module overrides geolocation characteristics exposed through the Geolocation API for the specified top-level contexts or user contexts.
Syntax
/* 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:
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. coordinates-
An object that specifies the simulated geographic position. It can be
nullto remove the override at the specified scope. This field cannot be used iferroris also specified, but it is required iferroris not specified. It contains the following fields:accuracyOptional-
A non-negative number that specifies the accuracy of the
latitudeandlongitudevalues in meters. The default value is1. altitudeOptional-
A number that specifies the altitude in meters, relative to nominal sea level. It can be
nullto simulate unavailable altitude data. The default value isnull. altitudeAccuracyOptional-
A non-negative number that specifies the accuracy of the
altitudevalue in meters. It can benullto simulate unavailable altitude accuracy data. Specifyaltitudewhen specifying this field. The default value isnull. headingOptional-
A number that specifies the direction of travel in degrees clockwise from true north. It can be
nullto simulate unavailable heading data. The value must be greater than or equal to0and less than360. The default value isnull. latitude-
A number that specifies the latitude in decimal degrees. The value must be between
-90and90. longitude-
A number that specifies the longitude in decimal degrees. The value must be between
-180and180. speedOptional-
A non-negative number that specifies the speed in meters per second. It can be
nullto simulate unavailable speed data. The default value isnull.
error-
An object that specifies a simulated failure to obtain a position. This field cannot be used if
coordinatesis also specified, but it is required ifcoordinatesis not specified.type-
A string that specifies the simulated error. The only supported value is
positionUnavailable.
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.
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-
Thrown in any of the following cases:
- A required parameter is missing, or a parameter has an invalid type or value.
- Both
contextsanduserContextsare specified. contextsoruserContextsis an empty array.- A context specified in
contextsis not a top-level context. - Both
coordinatesanderrorare specified. - Neither
coordinatesnorerroris specified. altitudeAccuracyis specified withoutaltitude.
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.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, 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 command.
Examples
>Overriding a tab's location with Toronto coordinates
Assume you have a WebDriver BiDi connection and an active session.
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, which returns its context ID.
Then load the page over HTTPS or from localhost, since the Geolocation API requires a secure context.
Additionally, grant geolocation permission for the page's origin using permissions.setPermission.
Send the following message to override the tab's location with Toronto's coordinates:
{
"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:
{
"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
| Specification |
|---|
| WebDriver BiDi> # command-emulation-setGeolocationOverride> |
Browser compatibility
See also
browser.getUserContextscommandbrowsingContext.createcommandbrowsingContext.getTreecommandpermissions.setPermissioncommand- Geolocation API