appium-xcuitest-driver 5.16.1 → 6.0.0

package/lib/commands/gesture.js

@@ -4,37 +4,6 @@ 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.
  *
@@ -43,7 +12,7 @@ async function toElementOrApplicationId(driver, elementId) {
  * @param {string} paramName
  * @returns {number}
  */
-function asFloat(value, paramName) {
+function requireFloat(value, paramName) {
   const num = parseFloat(String(value));
   if (Number.isNaN(num)) {
     throw new errors.InvalidArgumentError(
@@ -53,24 +22,6 @@ function asFloat(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
@@ -327,8 +278,8 @@ const helpers = {
     if (!_.isNil(distance)) {
       params.distance = distance;
     }
-    elementId = await toElementOrApplicationId(this, elementId);
-    return await this.proxyCommand(`/wda/element/${elementId}/scroll`, 'POST', params);
+    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/scroll` : '/wda/scroll';
+    return await this.proxyCommand(endpoint, 'POST', params);
   },
   /**
    * @param {import('./types').Direction} direction
@@ -346,8 +297,8 @@ const helpers = {
     if (!_.isNil(velocity)) {
       params.velocity = velocity;
     }
-    elementId = await toElementOrApplicationId(this, elementId);
-    return await this.proxyCommand(`/wda/element/${elementId}/swipe`, 'POST', params);
+    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/swipe` : '/wda/swipe';
+    await this.proxyCommand(endpoint, 'POST', params);
   },
   /**
    * Performs a pinch gesture on the given element or on the Application element.
@@ -366,18 +317,18 @@ const helpers = {
    */
   async mobilePinch(scale, velocity, elementId) {
     const params = {
-      scale: asFloat(scale, 'scale'),
-      velocity: asFloat(velocity, 'velocity'),
+      scale: requireFloat(scale, 'scale'),
+      velocity: requireFloat(velocity, 'velocity'),
     };
-    elementId = await toElementOrApplicationId(this, elementId);
-    return await this.proxyCommand(`/wda/element/${elementId}/pinch`, 'POST', params);
+    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/pinch` : '/wda/pinch';
+    await this.proxyCommand(endpoint, '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. 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.
+   * @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.
    * @returns {Promise<void>}
    * @this {XCUITestDriver}
    * @example
@@ -387,16 +338,8 @@ const helpers = {
    * ```
    */
   async mobileDoubleTap(elementId, 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);
+    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/doubleTap` : '/wda/doubleTap';
+    await this.proxyCommand(endpoint, 'POST', {x, y});
   },
   /**
    * Performs two finger tap gesture on the given element or on the application element.
@@ -413,16 +356,16 @@ const helpers = {
    * ```
    */
   async mobileTwoFingerTap(elementId) {
-    elementId = await toElementOrApplicationId(this, elementId);
-    return await this.proxyCommand(`/wda/element/${elementId}/twoFingerTap`, 'POST');
+    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/twoFingerTap` : '/wda/twoFingerTap';
+    await this.proxyCommand(endpoint, '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 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.
+   * @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.
    * @this {XCUITestDriver}
    * @see https://developer.apple.com/documentation/xctest/xcuielement/1618663-pressforduration?language=objc
    * @example
@@ -434,33 +377,24 @@ const helpers = {
    * ```
    */
   async mobileTouchAndHold(duration, x, y, elementId) {
-    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);
+    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/touchAndHold` : '/wda/touchAndHold';
+    await this.proxyCommand(endpoint, 'POST', {
+      duration: requireFloat(duration, 'duration'),
+      x, y,
+    });
   },
   /**
    * 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.
+   * @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.
    * @this {XCUITestDriver}
    * @returns {Promise<void>}
    */
-  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);
+  async mobileTap(x, y, elementId) {
+    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/tap` : '/wda/tap';
+    await this.proxyCommand(endpoint, 'POST', {x, y});
   },
   /**
    * Performs drag and drop gesture by coordinates on the given element or on the screen.
@@ -489,16 +423,15 @@ const helpers = {
    */
   async mobileDragFromToForDuration(duration, fromX, fromY, toX, toY, elementId) {
     const params = {
-      duration: asFloat(duration, 'duration'),
-      fromX: asFloat(fromX, 'fromX'),
-      fromY: asFloat(fromY, 'fromY'),
-      toX: asFloat(toX, 'toX'),
-      toY: asFloat(toY, 'toY'),
+      duration: requireFloat(duration, 'duration'),
+      fromX: requireFloat(fromX, 'fromX'),
+      fromY: requireFloat(fromY, 'fromY'),
+      toX: requireFloat(toX, 'toX'),
+      toY: requireFloat(toY, 'toY'),
     };
-    elementId = toElementId(elementId);
     return elementId
       ? // Drag element
-        await this.proxyCommand(`/wda/element/${elementId}/dragfromtoforduration`, 'POST', params)
+        await this.proxyCommand(`/wda/element/${util.unwrapElement(elementId)}/dragfromtoforduration`, 'POST', params)
       : // Drag coordinates
         await this.proxyCommand('/wda/dragfromtoforduration', 'POST', params);
   },
@@ -531,9 +464,9 @@ const helpers = {
     toY,
   ) {
     const params = {
-      pressDuration: asFloat(pressDuration, 'pressDuration'),
-      holdDuration: asFloat(holdDuration, 'holdDuration'),
-      velocity: asFloat(velocity, 'velocity'),
+      pressDuration: requireFloat(pressDuration, 'pressDuration'),
+      holdDuration: requireFloat(holdDuration, 'holdDuration'),
+      velocity: requireFloat(velocity, 'velocity'),
     };
     fromElementId = fromElementId ? util.unwrapElement(fromElementId) : undefined;
     if (fromElementId) {
@@ -550,19 +483,20 @@ const helpers = {
         params,
       );
     }
-    params.fromX = asFloat(fromX, 'fromX');
-    params.fromY = asFloat(fromY, 'fromY');
-    params.toX = asFloat(toX, 'toX');
-    params.toY = asFloat(toY, 'toY');
+    params.fromX = requireFloat(fromX, 'fromX');
+    params.fromY = requireFloat(fromY, 'fromY');
+    params.toX = requireFloat(toX, 'toX');
+    params.toY = requireFloat(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 {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.
+   * @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.
    * @returns {Promise<void>}
    * @this {XCUITestDriver}
    * @see https://developer.apple.com/documentation/xctest/xcuielement/1618671-tapwithnumberoftaps?language=objc
@@ -573,17 +507,14 @@ const helpers = {
    * @driver.execute_script 'mobile: tapWithNumberOfTaps', {element: e.ref, numberOfTaps: 2, numberOfTouches: 1}
    * ```
    */
-  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);
+  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,
+    });
   },
   /**
    * Performs a "force press" on the given element or coordinates.
@@ -593,13 +524,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. 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.
+   * @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.
    * @returns {Promise<void>}
    * @this {XCUITestDriver}
    */
   async mobileForcePress(x, y, duration, pressure, elementId) {
-    elementId = toElementId(elementId);
-    const endpoint = elementId ? `/wda/element/${elementId}/forceTouch` : `/wda/forceTouch`;
+    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/forceTouch` : `/wda/forceTouch`;
     return await this.proxyCommand(endpoint, 'POST', {x, y, duration, pressure});
   },
   /**
@@ -625,7 +556,6 @@ 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',
@@ -639,7 +569,7 @@ const helpers = {
     }
     const params = {order};
     if (offset) {
-      params.offset = asFloat(offset, 'offset');
+      params.offset = requireFloat(offset, 'offset');
     }
     if (!_.isNil(value)) {
       params.value = value;
@@ -647,15 +577,16 @@ const helpers = {
     if (!_.isNil(maxAttempts)) {
       params.maxAttempts = maxAttempts;
     }
-    return await this.proxyCommand(`/wda/pickerwheel/${elementId}/select`, 'POST', params);
+    return await this.proxyCommand(`/wda/pickerwheel/${util.unwrapElement(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
@@ -670,65 +601,13 @@ const helpers = {
    * ));
    * ```
    */
-  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',
-      );
-    }
+  async mobileRotateElement(rotation, velocity, elementId) {
     const params = {
-      rotation: asFloat(rotation, 'rotation'),
-      velocity: asFloat(velocity, 'velocity'),
+      rotation: requireFloat(rotation, 'rotation'),
+      velocity: requireFloat(velocity, 'velocity'),
     };
-    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;
+    const endpoint = elementId ? `/wda/element/${util.unwrapElement(elementId)}/rotate` : '/wda/rotate';
+    return await this.proxyCommand(endpoint, 'POST', params);
   },
 };
 

package/lib/driver.js

@@ -2018,7 +2018,6 @@ 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: {
-      required: ['elementId', 'numberOfTouches', 'numberOfTaps'],
+      optional: ['numberOfTouches', 'numberOfTaps', 'elementId'],
     },
   },
   // https://developer.apple.com/documentation/xctest/xcuielement/1618663-pressforduration?language=objc
@@ -84,7 +84,8 @@ export const executeMethodMap = {
   'mobile: rotateElement': {
     command: 'mobileRotateElement',
     params: {
-      required: ['elementId', 'rotation', 'velocity'],
+      required: ['rotation', 'velocity'],
+      optional: ['elementId'],
     },
   },
   // 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.1",
+  "version": "6.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-xcuitest-driver",
-      "version": "5.16.1",
+      "version": "6.0.0",
       "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": "~5.15.9",
+        "appium-webdriveragent": "^6.0.0",
         "appium-xcode": "^5.1.4",
         "async-lock": "^1.4.0",
         "asyncbox": "^3.0.0",
@@ -1064,9 +1064,9 @@
       }
     },
     "node_modules/appium-webdriveragent": {
-      "version": "5.15.9",
-      "resolved": "https://registry.npmjs.org/appium-webdriveragent/-/appium-webdriveragent-5.15.9.tgz",
-      "integrity": "sha512-03brYer2B68V+Jqjy8VVYNEeDftSzizZaXGazZsAq1ENDhvXgzIErKWjFAswTQWu/ciDmXASt8I96K6ks+Gy0A==",
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/appium-webdriveragent/-/appium-webdriveragent-6.0.0.tgz",
+      "integrity": "sha512-8uIm6MN3Kv+RBe/yOH2k8wdA5E2yQtoh+GG9Kgf9ZdTF3q5fR2WSmfBkCVVXk6T8/hYJkScBgSbC695Sh6zeIg==",
       "dependencies": {
         "@appium/base-driver": "^9.0.0",
         "@appium/strongbox": "^0.x",

package/package.json

@@ -8,7 +8,7 @@
     "xcuitest",
     "xctest"
   ],
-  "version": "5.16.1",
+  "version": "6.0.0",
   "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": "~5.15.9",
+    "appium-webdriveragent": "^6.0.0",
     "appium-xcode": "^5.1.4",
     "async-lock": "^1.4.0",
     "asyncbox": "^3.0.0",