appium-xcuitest-driver 5.16.0 → 5.16.1

package/lib/commands/gesture.js

@@ -4,6 +4,37 @@ import _ from 'lodash';
 
 const SUPPORTED_GESTURE_DIRECTIONS = ['up', 'down', 'left', 'right'];
 
+/**
+ * @param {any} [opts]
+ * @returns {string|undefined}
+ */
+function toElementId(opts) {
+  if (_.isUndefined(opts)) {
+    return;
+  }
+  if (_.isString(opts) || _.isNumber(opts)) {
+    return String(opts);
+  }
+  if ('elementId' in opts || 'element' in opts) {
+    return util.unwrapElement(opts);
+  }
+}
+
+/**
+ *
+ * @param {XCUITestDriver} driver
+ * @param {Element|string} [elementId]
+ * @returns {Promise<string>}
+ */
+async function toElementOrApplicationId(driver, elementId) {
+  if (!_.isUndefined(elementId)) {
+    return util.unwrapElement(elementId);
+  }
+  return util.unwrapElement(
+    await driver.findNativeElementOrElements(`class name`, `XCUIElementTypeApplication`, false),
+  );
+}
+
 /**
  * Converts the given value to a float number.
  *
@@ -12,7 +43,7 @@ const SUPPORTED_GESTURE_DIRECTIONS = ['up', 'down', 'left', 'right'];
  * @param {string} paramName
  * @returns {number}
  */
-function requireFloat(value, paramName) {
+function asFloat(value, paramName) {
   const num = parseFloat(String(value));
   if (Number.isNaN(num)) {
     throw new errors.InvalidArgumentError(
@@ -22,6 +53,24 @@ function requireFloat(value, paramName) {
   return num;
 }
 
+/**
+ * Converts the given value to an integer number.
+ *
+ * @throws If `value` is `NaN`
+ * @param {any} value
+ * @param {string} paramName
+ * @returns {number}
+ */
+function asInt(value, paramName) {
+  const num = parseInt(String(value), 10);
+  if (Number.isNaN(num)) {
+    throw new errors.InvalidArgumentError(
+      `"${paramName}" parameter should be a valid integer. "${value}" is given instead`,
+    );
+  }
+  return num;
+}
+
 /**
  *
  * @param {any[]} gestures
@@ -278,8 +327,8 @@ const helpers = {
     if (!_.isNil(distance)) {
       params.distance = distance;
     }
-    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/scroll` : '/wda/scroll';
-    return await this.proxyCommand(endpoint, 'POST', params);
+    elementId = await toElementOrApplicationId(this, elementId);
+    return await this.proxyCommand(`/wda/element/${elementId}/scroll`, 'POST', params);
   },
   /**
    * @param {import('./types').Direction} direction
@@ -297,8 +346,8 @@ const helpers = {
     if (!_.isNil(velocity)) {
       params.velocity = velocity;
     }
-    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/swipe` : '/wda/swipe';
-    await this.proxyCommand(endpoint, 'POST', params);
+    elementId = await toElementOrApplicationId(this, elementId);
+    return await this.proxyCommand(`/wda/element/${elementId}/swipe`, 'POST', params);
   },
   /**
    * Performs a pinch gesture on the given element or on the Application element.
@@ -317,18 +366,18 @@ const helpers = {
    */
   async mobilePinch(scale, velocity, elementId) {
     const params = {
-      scale: requireFloat(scale, 'scale'),
-      velocity: requireFloat(velocity, 'velocity'),
+      scale: asFloat(scale, 'scale'),
+      velocity: asFloat(velocity, 'velocity'),
     };
-    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/pinch` : '/wda/pinch';
-    await this.proxyCommand(endpoint, 'POST', params);
+    elementId = await toElementOrApplicationId(this, elementId);
+    return await this.proxyCommand(`/wda/element/${elementId}/pinch`, 'POST', params);
   },
   /**
    * Performs double tap gesture on the given element or on the screen.
    *
-   * @param {Element|string} [elementId] - The internal element identifier (as hexadecimal hash string) to double tap on. The Application element will be used if this parameter is not provided.
-   * @param {number} [x] - The _x_ coordinate (float value) to double tap on.
-   * @param {number} [y] - The _y_ coordinate (float value) to double tap on.
+   * @param {Element|string} [elementId] - The internal element identifier (as hexadecimal hash string) to double tap on. This is required if `x` and `y` are not provided.
+   * @param {number} [x] - The _x_ coordinate (float value) to double tap on. This is required if `elementId` is not provided.
+   * @param {number} [y] - The _y_ coordinate (float value) to double tap on. This is required if `elementId` is not provided.
    * @returns {Promise<void>}
    * @this {XCUITestDriver}
    * @example
@@ -338,8 +387,16 @@ const helpers = {
    * ```
    */
   async mobileDoubleTap(elementId, x, y) {
-    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/doubleTap` : '/wda/doubleTap';
-    await this.proxyCommand(endpoint, 'POST', {x, y});
+    if (elementId) {
+      // Double tap element
+      return await this.proxyCommand(`/wda/element/${elementId}/doubleTap`, 'POST');
+    }
+    // Double tap coordinates
+    const params = {
+      x: asFloat(x, 'x'),
+      y: asFloat(y, 'y'),
+    };
+    return await this.proxyCommand('/wda/doubleTap', 'POST', params);
   },
   /**
    * Performs two finger tap gesture on the given element or on the application element.
@@ -356,16 +413,16 @@ const helpers = {
    * ```
    */
   async mobileTwoFingerTap(elementId) {
-    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/twoFingerTap` : '/wda/twoFingerTap';
-    await this.proxyCommand(endpoint, 'POST');
+    elementId = await toElementOrApplicationId(this, elementId);
+    return await this.proxyCommand(`/wda/element/${elementId}/twoFingerTap`, 'POST');
   },
   /**
    * Performs a "long press" gesture on the given element or on the screen.
    *
    * @param {number} duration - The duration (in seconds) of the gesture.
-   * @param {number} [y] - The _y_ coordinate (float value) to hold on.
-   * @param {number} [x] - The _x_ coordinate (float value) to hold on.
-   * @param {Element|string} [elementId] - The internal element identifier (as hexadecimal hash string) to double tap on.  The Application element will be used if this parameter is not provided.
+   * @param {number} [y] - The _y_ coordinate (float value) to double tap on. This is required if `elementId` is not provided.
+   * @param {number} [x] - The _x_ coordinate (float value) to double tap on. This is required if `elementId` is not provided.
+   * @param {Element|string} [elementId] - The internal element identifier (as hexadecimal hash string) to double tap on. This is required if `x` and `y` are not provided.
    * @this {XCUITestDriver}
    * @see https://developer.apple.com/documentation/xctest/xcuielement/1618663-pressforduration?language=objc
    * @example
@@ -377,24 +434,33 @@ const helpers = {
    * ```
    */
   async mobileTouchAndHold(duration, x, y, elementId) {
-    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/touchAndHold` : '/wda/touchAndHold';
-    await this.proxyCommand(endpoint, 'POST', {
-      duration: requireFloat(duration, 'duration'),
-      x, y,
-    });
+    const params = {
+      duration: asFloat(duration, 'duration'),
+    };
+    if (elementId) {
+      // Long tap element
+      return await this.proxyCommand(`/wda/element/${elementId}/touchAndHold`, 'POST', params);
+    }
+    // Long tap coordinates
+    params.x = asFloat(x, 'x');
+    params.y = asFloat(y, 'y');
+    return await this.proxyCommand('/wda/touchAndHold', 'POST', params);
   },
   /**
    * Performs tap gesture by coordinates on the given element or on the screen.
    *
    * @param {number} x - The _x_ coordinate (float value) to tap on. If `elementId` is provided, this is computed relative to the element; otherwise it is computed relative to the active Application element.
    * @param {number} y - The _y_ coordinate (float value) to tap on. If `elementId` is provided, this is computed relative to the element; otherwise it is computed relative to the active Application element.
-   * @param {string|Element} [elementId] - The internal element identifier (as hexadecimal hash string) to tap on.  The Application element will be used if this parameter is not provided.
+   * @param {string|Element} [elementId] - The internal element identifier (as hexadecimal hash string) to tap on.
    * @this {XCUITestDriver}
    * @returns {Promise<void>}
    */
-  async mobileTap(x, y, elementId) {
-    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/tap` : '/wda/tap';
-    await this.proxyCommand(endpoint, 'POST', {x, y});
+  async mobileTap(x, y, elementId = '0') {
+    const params = {
+      x: asFloat(x, 'x'),
+      y: asFloat(y, 'y'),
+    };
+    return await this.proxyCommand(`/wda/tap/${elementId}`, 'POST', params);
   },
   /**
    * Performs drag and drop gesture by coordinates on the given element or on the screen.
@@ -423,15 +489,16 @@ const helpers = {
    */
   async mobileDragFromToForDuration(duration, fromX, fromY, toX, toY, elementId) {
     const params = {
-      duration: requireFloat(duration, 'duration'),
-      fromX: requireFloat(fromX, 'fromX'),
-      fromY: requireFloat(fromY, 'fromY'),
-      toX: requireFloat(toX, 'toX'),
-      toY: requireFloat(toY, 'toY'),
+      duration: asFloat(duration, 'duration'),
+      fromX: asFloat(fromX, 'fromX'),
+      fromY: asFloat(fromY, 'fromY'),
+      toX: asFloat(toX, 'toX'),
+      toY: asFloat(toY, 'toY'),
     };
+    elementId = toElementId(elementId);
     return elementId
       ? // Drag element
-        await this.proxyCommand(`/wda/element/${util.unwrapElement(elementId)}/dragfromtoforduration`, 'POST', params)
+        await this.proxyCommand(`/wda/element/${elementId}/dragfromtoforduration`, 'POST', params)
       : // Drag coordinates
         await this.proxyCommand('/wda/dragfromtoforduration', 'POST', params);
   },
@@ -464,9 +531,9 @@ const helpers = {
     toY,
   ) {
     const params = {
-      pressDuration: requireFloat(pressDuration, 'pressDuration'),
-      holdDuration: requireFloat(holdDuration, 'holdDuration'),
-      velocity: requireFloat(velocity, 'velocity'),
+      pressDuration: asFloat(pressDuration, 'pressDuration'),
+      holdDuration: asFloat(holdDuration, 'holdDuration'),
+      velocity: asFloat(velocity, 'velocity'),
     };
     fromElementId = fromElementId ? util.unwrapElement(fromElementId) : undefined;
     if (fromElementId) {
@@ -483,20 +550,19 @@ const helpers = {
         params,
       );
     }
-    params.fromX = requireFloat(fromX, 'fromX');
-    params.fromY = requireFloat(fromY, 'fromY');
-    params.toX = requireFloat(toX, 'toX');
-    params.toY = requireFloat(toY, 'toY');
+    params.fromX = asFloat(fromX, 'fromX');
+    params.fromY = asFloat(fromY, 'fromY');
+    params.toX = asFloat(toX, 'toX');
+    params.toY = asFloat(toY, 'toY');
     return await this.proxyCommand('/wda/pressAndDragWithVelocity', 'POST', params);
   },
   /**
    * Sends one or more taps with one or more touch points.
    *
    * @since 1.17.1
-   * @param {number} [numberOfTaps=1] - Number of taps to perform.
-   * @param {number} [numberOfTouches=1] - Number of touch points to use.
-   * @param {string|Element} [elementId] - The internal element identifier (as hexadecimal hash string) to perform one or more taps.
-   * The Application element will be used if this parameter is not provided.
+   * @param {string|Element} elementId - The internal element identifier (as hexadecimal hash string) to perform one or more taps.
+   * @param {number} numberOfTaps - Number of taps to perform.
+   * @param {number} numberOfTouches - Number of touch points to use.
    * @returns {Promise<void>}
    * @this {XCUITestDriver}
    * @see https://developer.apple.com/documentation/xctest/xcuielement/1618671-tapwithnumberoftaps?language=objc
@@ -507,14 +573,17 @@ const helpers = {
    * @driver.execute_script 'mobile: tapWithNumberOfTaps', {element: e.ref, numberOfTaps: 2, numberOfTouches: 1}
    * ```
    */
-  async mobileTapWithNumberOfTaps(numberOfTouches = 1, numberOfTaps = 1, elementId = undefined) {
-    const endpoint = elementId
-      ? `/wda/element/${util.unwrapElement(elementId)}/tapWithNumberOfTaps`
-      : '/wda/tapWithNumberOfTaps';
-    return await this.proxyCommand(endpoint, 'POST', {
-      numberOfTaps,
-      numberOfTouches,
-    });
+  async mobileTapWithNumberOfTaps(elementId, numberOfTouches, numberOfTaps) {
+    if (!elementId) {
+      throw new errors.InvalidArgumentError(
+        'Element id is expected to be set for tapWithNumberOfTaps method',
+      );
+    }
+    const params = {
+      numberOfTaps: asInt(numberOfTaps, 'numberOfTaps'),
+      numberOfTouches: asInt(numberOfTouches, 'numberOfTouches'),
+    };
+    return await this.proxyCommand(`/wda/element/${elementId}/tapWithNumberOfTaps`, 'POST', params);
   },
   /**
    * Performs a "force press" on the given element or coordinates.
@@ -524,13 +593,13 @@ const helpers = {
    * @param {number} [y] - The _y_ coordinate of the gesture. If `elementId` is set, this is calculated relative to its position; otherwise it's calculated relative to the active Application.
    * @param {number} [duration] - The duraiton (in seconds) of the force press. If this is provided, `pressure` must also be provided.
    * @param {number} [pressure] - A float value defining the pressure of the force press. If this is provided, `duration` must also be provided.
-   * @param {string|Element} [elementId] - The internal element identifier (as hexadecimal hash string) to perform one or more taps.
-   * The Application element will be used if this parameter is not provided.
+   * @param {string|Element} [elementId] - The internal element identifier (as hexadecimal hash string) to perform one or more taps. If this is _not_ provided, both `x` and `y` must be provided. If this is provided _and_ `x` and `y` are not provided, the actual touch point will be calculated internally.
    * @returns {Promise<void>}
    * @this {XCUITestDriver}
    */
   async mobileForcePress(x, y, duration, pressure, elementId) {
-    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/forceTouch` : `/wda/forceTouch`;
+    elementId = toElementId(elementId);
+    const endpoint = elementId ? `/wda/element/${elementId}/forceTouch` : `/wda/forceTouch`;
     return await this.proxyCommand(endpoint, 'POST', {x, y, duration, pressure});
   },
   /**
@@ -556,6 +625,7 @@ const helpers = {
    * ```
    */
   async mobileSelectPickerWheelValue(elementId, order, offset, value, maxAttempts) {
+    elementId = /** @type {string} */ (toElementId(elementId));
     if (!elementId) {
       throw new errors.InvalidArgumentError(
         'elementId is expected to be set for selectPickerWheelValue method',
@@ -569,7 +639,7 @@ const helpers = {
     }
     const params = {order};
     if (offset) {
-      params.offset = requireFloat(offset, 'offset');
+      params.offset = asFloat(offset, 'offset');
     }
     if (!_.isNil(value)) {
       params.value = value;
@@ -577,16 +647,15 @@ const helpers = {
     if (!_.isNil(maxAttempts)) {
       params.maxAttempts = maxAttempts;
     }
-    return await this.proxyCommand(`/wda/pickerwheel/${util.unwrapElement(elementId)}/select`, 'POST', params);
+    return await this.proxyCommand(`/wda/pickerwheel/${elementId}/select`, 'POST', params);
   },
   /**
    * Performs a rotate gesture on the given element.
    *
    * @see https://developer.apple.com/documentation/xctest/xcuielement/1618665-rotate?language=objc
+   * @param {string|Element} elementId - The internal element identifier (as hexadecimal hash string) to perform the gesture on.
    * @param {number} rotation - The rotation gesture (in radians)
    * @param {number} velocity - The velocity (in radians-per-second) of the gesture.
-   * @param {string|Element} [elementId] - The internal element identifier (as hexadecimal hash string) to perform the gesture on.
-   * The Application element will be used if this parameter is not provided.
    * @returns {Promise<void>}
    * @this {XCUITestDriver}
    * @example
@@ -601,13 +670,65 @@ const helpers = {
    * ));
    * ```
    */
-  async mobileRotateElement(rotation, velocity, elementId) {
+  async mobileRotateElement(elementId, rotation, velocity) {
+    elementId = /** @type {string} */ (toElementId(elementId));
+    if (!elementId) {
+      throw new errors.InvalidArgumentError(
+        'Element id is expected to be set for rotateElement method',
+      );
+    }
     const params = {
-      rotation: requireFloat(rotation, 'rotation'),
-      velocity: requireFloat(velocity, 'velocity'),
+      rotation: asFloat(rotation, 'rotation'),
+      velocity: asFloat(velocity, 'velocity'),
     };
-    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/rotate` : '/wda/rotate';
-    return await this.proxyCommand(endpoint, 'POST', params);
+    return await this.proxyCommand(`/wda/element/${elementId}/rotate`, 'POST', params);
+  },
+  /**
+   * @this {XCUITestDriver}
+   */
+  async getCoordinates(gesture) {
+    // defaults
+    let coordinates = {x: 0, y: 0, areOffsets: false};
+
+    let optionX = null;
+    if (gesture.options.x) {
+      optionX = asFloat(gesture.options.x, 'x');
+    }
+    let optionY = null;
+    if (gesture.options.y) {
+      optionY = asFloat(gesture.options.y, 'y');
+    }
+
+    // figure out the element coordinates.
+    const elementId = toElementId(gesture.options);
+    if (elementId) {
+      let rect = await this.getElementRect(elementId);
+      let pos = {x: rect.x, y: rect.y};
+      let size = {w: rect.width, h: rect.height};
+
+      // defaults
+      let offsetX = 0;
+      let offsetY = 0;
+
+      // get the real offsets
+      if (optionX || optionY) {
+        offsetX = optionX || 0;
+        offsetY = optionY || 0;
+      } else {
+        offsetX = size.w / 2;
+        offsetY = size.h / 2;
+      }
+
+      // apply the offsets
+      coordinates.x = pos.x + offsetX;
+      coordinates.y = pos.y + offsetY;
+    } else {
+      // moveTo coordinates are passed in as offsets
+      coordinates.areOffsets = gesture.action === 'moveTo';
+      coordinates.x = optionX || 0;
+      coordinates.y = optionY || 0;
+    }
+    return coordinates;
   },
 };
 

package/lib/driver.js

@@ -2018,6 +2018,7 @@ class XCUITestDriver extends BaseDriver {
   mobileForcePress = commands.gestureExtensions.mobileForcePress;
   mobileSelectPickerWheelValue = commands.gestureExtensions.mobileSelectPickerWheelValue;
   mobileRotateElement = commands.gestureExtensions.mobileRotateElement;
+  getCoordinates = commands.gestureExtensions.getCoordinates;
 
   /*-------+
    | IOHID |

package/lib/execute-method-map.ts

@@ -61,7 +61,7 @@ export const executeMethodMap = {
   'mobile: tapWithNumberOfTaps': {
     command: 'mobileTapWithNumberOfTaps',
     params: {
-      optional: ['numberOfTouches', 'numberOfTaps', 'elementId'],
+      required: ['elementId', 'numberOfTouches', 'numberOfTaps'],
     },
   },
   // https://developer.apple.com/documentation/xctest/xcuielement/1618663-pressforduration?language=objc
@@ -84,8 +84,7 @@ export const executeMethodMap = {
   'mobile: rotateElement': {
     command: 'mobileRotateElement',
     params: {
-      required: ['rotation', 'velocity'],
-      optional: ['elementId'],
+      required: ['elementId', 'rotation', 'velocity'],
     },
   },
   // https://developer.apple.com/documentation/xctest/xcuicoordinate/3551692-pressforduration?language=objc

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-xcuitest-driver",
-  "version": "5.16.0",
+  "version": "5.16.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-xcuitest-driver",
-      "version": "5.16.0",
+      "version": "5.16.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@colors/colors": "^1.6.0",
@@ -14,7 +14,7 @@
         "appium-ios-device": "^2.5.4",
         "appium-ios-simulator": "^5.5.1",
         "appium-remote-debugger": "^10.0.0",
-        "appium-webdriveragent": "^6.0.0",
+        "appium-webdriveragent": "~5.15.9",
         "appium-xcode": "^5.1.4",
         "async-lock": "^1.4.0",
         "asyncbox": "^3.0.0",
@@ -1064,9 +1064,9 @@
       }
     },
     "node_modules/appium-webdriveragent": {
-      "version": "6.0.0",
-      "resolved": "https://registry.npmjs.org/appium-webdriveragent/-/appium-webdriveragent-6.0.0.tgz",
-      "integrity": "sha512-8uIm6MN3Kv+RBe/yOH2k8wdA5E2yQtoh+GG9Kgf9ZdTF3q5fR2WSmfBkCVVXk6T8/hYJkScBgSbC695Sh6zeIg==",
+      "version": "5.15.9",
+      "resolved": "https://registry.npmjs.org/appium-webdriveragent/-/appium-webdriveragent-5.15.9.tgz",
+      "integrity": "sha512-03brYer2B68V+Jqjy8VVYNEeDftSzizZaXGazZsAq1ENDhvXgzIErKWjFAswTQWu/ciDmXASt8I96K6ks+Gy0A==",
       "dependencies": {
         "@appium/base-driver": "^9.0.0",
         "@appium/strongbox": "^0.x",

package/package.json

@@ -8,7 +8,7 @@
     "xcuitest",
     "xctest"
   ],
-  "version": "5.16.0",
+  "version": "5.16.1",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -81,7 +81,7 @@
     "appium-ios-device": "^2.5.4",
     "appium-ios-simulator": "^5.5.1",
     "appium-remote-debugger": "^10.0.0",
-    "appium-webdriveragent": "^6.0.0",
+    "appium-webdriveragent": "~5.15.9",
     "appium-xcode": "^5.1.4",
     "async-lock": "^1.4.0",
     "asyncbox": "^3.0.0",