feat: Add simulated geolocation extensions (#1503)

docs/execute-methods.md

@@ -1176,3 +1176,41 @@ Name | Type | Required | Description | Example
 --- | --- | --- | --- | ---
 url | string | yes | The URL to be opened. This parameter is manadatory. | https://apple.com, myscheme:yolo
 bundleId | string | no | The bundle identifier of an application to open the given url with. If not provided then the default application for the given url scheme is going to be used. | com.myapp.yolo
+
+### mobile: getSimulatedLocation
+
+Retrieves simulated geolocation value.
+This functionality is only available since xcuitest driver version 4.18.
+Xcode must be at version 14.3+ and iOS must be at version 16.4+.
+
+#### Returned Result
+
+This API returns a map with the following entries:
+
+Name | Type | Description | Example
+--- | --- | --- | ---
+latitude | number | Measurement of distance north or south of the Equator. `null` if [mobile: setSimulatedLocation](#mobile-setsimulatedlocation) has not been called before or the simulated geolocation has been reset by [mobile: resetSimulatedLocation](#mobile-resetsimulatedlocation). | 50.08546
+longitude | number | Measurement of distance east or west of the prime meridian. `null` if [mobile: setSimulatedLocation](#mobile-setsimulatedlocation) has not been called before or the simulated geolocation has been reset by [mobile: resetSimulatedLocation](#mobile-resetsimulatedlocation).  | -20.12345
+
+### mobile: setSimulatedLocation
+
+Sets simulated geolocation value.
+This functionality is only available since xcuitest driver version 4.18.
+Xcode must be at version 14.3+ and iOS must be at version 16.4+.
+
+#### Arguments
+
+Name | Type | Required | Description | Example
+--- | --- | --- | --- | ---
+latitude | number | yes | Measurement of distance north or south of the Equator. | 50.08546
+longitude | number | yes | Measurement of distance east or west of the prime meridian. | -20.12345
+
+### mobile: resetSimulatedLocation
+
+Resets the previously set simulated geolocation value.
+This functionality is only available since xcuitest driver version 4.18.
+Xcode must be at version 14.3+ and iOS must be at version 16.4+.
+
+> **Warning**
+> Do not forget to reset the simulated geolocation value after your automated test is finished.
+> If the value is not reset explcitly then the simulated one will remain until the next device restart.

lib/commands/execute.js

@@ -170,6 +170,10 @@ extensions.executeMobile = async function executeMobile (mobileCommand, opts = {
     updateSafariPreferences: 'mobileUpdateSafariPreferences',
 
     deepLink: 'mobileDeepLink',
+
+    setSimulatedLocation: 'mobileSetSimulatedLocation',
+    getSimulatedLocation: 'mobileGetSimulatedLocation',
+    resetSimulatedLocation: 'mobileResetSimulatedLocation',
   };
 
   if (!_.has(commandMap, mobileCommand)) {

lib/commands/geolocation.js

@@ -0,0 +1,48 @@
+import { requireArgs } from '../utils';
+
+const commands = {};
+
+/**
+ * @typedef {Object} GeolocationInfo
+ * @property {number} latitude Measurement of distance north or south of the Equator.
+ * @property {number} longitude Measurement of distance east or west of the prime meridian.
+ */
+
+/**
+ * Retrieves simulated geolocation value.
+ * Only works since Xcode 14.3/iOS 16.4
+ *
+ * @returns {GeolocationInfo} All entry values are set to null if no simulated location has
+ * been set prior to calling this API.
+ * @throws {Error} If the device under test does not support gelolocation simulation.
+ */
+commands.mobileGetSimulatedLocation = async function mobileGetSimulatedLocation () {
+  return await this.proxyCommand('/wda/simulatedLocation', 'GET');
+};
+
+/**
+ * Sets simulated geolocation value.
+ * Only works since Xcode 14.3/iOS 16.4
+ *
+ * @param {GeolocationInfo} opts
+ * @throws {Error} If the device under test does not support gelolocation simulation.
+ */
+commands.mobileSetSimulatedLocation = async function mobileGetSimulatedLocation (opts = {}) {
+  const {latitude, longitude} = requireArgs(['latitude', 'longitude'], opts);
+  return await this.proxyCommand('/wda/simulatedLocation', 'POST', {latitude, longitude});
+};
+
+/**
+ * Resets simulated geolocation value.
+ * Only works since Xcode 14.3/iOS 16.4.
+ * ! Do not forget to reset the simulated geolocation value after your automated test is finished.
+ * ! If the value is not reset explcitly then the simulated one will remain until the next device restart.
+ *
+ * @throws {Error} If the device under test does not support gelolocation simulation.
+ */
+commands.mobileResetSimulatedLocation = async function mobileGetSimulatedLocation () {
+  return await this.proxyCommand('/wda/simulatedLocation', 'DELETE');
+};
+
+export { commands };
+export default commands;

lib/commands/index.js

@@ -36,6 +36,7 @@ import iohidExtensions from './iohid';
 import localizationExtensions from './localization';
 import pcapExtensions from './pcap';
 import conditionExtensions from './condition';
+import geolocationExtensions from './geolocation';
 
 const commands = {};
 
@@ -49,7 +50,7 @@ Object.assign(commands, contextCommands, executeExtensions,
   biometricExtensions, keychainsExtensions, permissionsExtensions, deviceInfoExtensions,
   activeAppInfoExtensions, recordAudioExtensions, appearanceExtensions, xctestExtensions,
   notificationsExtensions, iohidExtensions, localizationExtensions, pcapExtensions,
-  conditionExtensions,
+  conditionExtensions, geolocationExtensions,
 );
 
 export default commands;

package.json

@@ -73,7 +73,7 @@
     "appium-ios-device": "^2.4.0",
     "appium-ios-simulator": "^5.0.5",
     "appium-remote-debugger": "^9.1.1",
-    "appium-webdriveragent": "^4.12.0",
+    "appium-webdriveragent": "^4.12.1",
     "appium-xcode": "^5.0.0",
     "async-lock": "^1.0.0",
     "asyncbox": "^2.3.1",