appium-uiautomator2-driver 6.7.5 → 6.7.6

package/lib/commands/element.js

@@ -1,261 +0,0 @@
-import B from 'bluebird';
-import _ from 'lodash';
-import {PROTOCOLS} from 'appium/driver';
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<import('@appium/types').Element>}
- */
-export async function active() {
-  return /** @type {import('@appium/types').Element} */ (
-    await this.uiautomator2.jwproxy.command(
-      '/element/active',
-      'GET'
-    )
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} attribute
- * @param {string} elementId
- * @returns {Promise<string?>}
- */
-export async function getAttribute(attribute, elementId) {
-  return String(
-    await this.uiautomator2.jwproxy.command(
-      `/element/${elementId}/attribute/${attribute}`,
-      'GET',
-      {}
-    )
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} elementId
- * @returns {Promise<boolean>}
- */
-export async function elementDisplayed(elementId) {
-  return toBool(await this.getAttribute('displayed', elementId));
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} elementId
- * @returns {Promise<boolean>}
- */
-export async function elementEnabled(elementId) {
-  return toBool(await this.getAttribute('enabled', elementId));
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} elementId
- * @returns {Promise<boolean>}
- */
-export async function elementSelected(elementId) {
-  return toBool(await this.getAttribute('selected', elementId));
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} elementId
- * @returns {Promise<string>}
- */
-export async function getName(elementId) {
-  return /** @type {string} */ (
-    await this.uiautomator2.jwproxy.command(
-      `/element/${elementId}/name`,
-      'GET',
-      {}
-    )
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} elementId
- * @returns {Promise<import('@appium/types').Position>}
- */
-export async function getLocation(elementId) {
-  return /** @type {import('@appium/types').Position} */ (
-    await this.uiautomator2.jwproxy.command(
-      `/element/${elementId}/location`,
-      'GET',
-      {}
-    )
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} elementId
- * @returns {Promise<import('@appium/types').Size>}
- */
-export async function getSize(elementId) {
-  return /** @type {import('@appium/types').Size} */ (
-    await this.uiautomator2.jwproxy.command(
-      `/element/${elementId}/size`,
-      'GET',
-      {}
-    )
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {import('appium-android-driver').DoSetElementValueOpts} params
- * @returns {Promise<void>}
- */
-export async function doSetElementValue(params) {
-  await this.uiautomator2.jwproxy.command(
-    `/element/${params.elementId}/value`,
-    'POST',
-    params
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string|string[]} keys
- * @param {string} elementId
- * @returns {Promise<void>}
- */
-export async function setValueImmediate(keys, elementId) {
-  await this.uiautomator2.jwproxy.command(
-    `/element/${elementId}/value`,
-    'POST',
-    {
-      elementId,
-      text: _.isArray(keys) ? keys.join('') : keys,
-      replace: false,
-    }
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} elementId
- * @returns {Promise<string>}
- */
-export async function getText(elementId) {
-  return String(
-    await this.uiautomator2.jwproxy.command(
-      `/element/${elementId}/text`,
-      'GET',
-      {}
-    )
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} element
- * @returns {Promise<void>}
- */
-export async function click(element) {
-  await this.uiautomator2.jwproxy.command(
-    `/element/${element}/click`,
-    'POST',
-    {element}
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} element
- * @returns {Promise<string>}
- */
-export async function getElementScreenshot(element) {
-  return String(
-    await this.uiautomator2.jwproxy.command(
-      `/element/${element}/screenshot`,
-      'GET',
-      {}
-    )
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} elementId
- * @returns {Promise<void>}
- */
-export async function clear(elementId) {
-  await this.uiautomator2.jwproxy.command(
-    `/element/${elementId}/clear`,
-    'POST',
-    {
-      elementId,
-    }
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} elementId
- * @returns {Promise<import('@appium/types').Rect>}
- */
-export async function getElementRect(elementId) {
-  const chromedriver = /** @type {import('appium-chromedriver').default} */ (this.chromedriver);
-  if (this.isWebContext()) {
-    this.log.debug(
-      `Detected downstream chromedriver protocol: ${chromedriver.jwproxy.downstreamProtocol}`
-    );
-    if (chromedriver.jwproxy.downstreamProtocol === PROTOCOLS.MJSONWP) {
-      const [{x, y}, {width, height}] =
-        /** @type {[import('@appium/types').Position, import('@appium/types').Size]} */ (
-          await B.all([
-            chromedriver.jwproxy.command(`/element/${elementId}/location`, 'GET'),
-            chromedriver.jwproxy.command(`/element/${elementId}/size`, 'GET'),
-          ])
-        );
-      return {x, y, width, height};
-    }
-    return /** @type {import('@appium/types').Rect} */ (
-      await chromedriver.jwproxy.command(`/element/${elementId}/rect`, 'GET')
-    );
-  }
-  return /** @type {import('@appium/types').Rect} */ (
-    await this.uiautomator2.jwproxy.command(
-      `/element/${elementId}/rect`,
-      'GET'
-    )
-  );
-}
-
-/**
- * Sends text to the given element by replacing its previous content
- * @this {AndroidUiautomator2Driver}
- * @param {string} elementId The id of the element whose content will be replaced.
- * @param {string} text The actual text to set.
- * @throws {Error} If there was a faulre while setting the text
- * @returns {Promise<void>}
- */
-export async function mobileReplaceElementValue(elementId, text) {
-  await this.uiautomator2.jwproxy.command(
-    `/element/${elementId}/value`,
-    'POST',
-    {
-      text,
-      replace: true,
-    }
-  );
-}
-
-// #region Internal Helpers
-
-/**
- * @param {any} s
- * @returns {boolean}
- */
-function toBool(s) {
-  return _.isString(s) ? s.toLowerCase() === 'true' : !!s;
-}
-
-// #endregion
-
-/**
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */

package/lib/commands/gestures.js

@@ -1,446 +0,0 @@
-import {util} from 'appium/support';
-import _ from 'lodash';
-import {errors} from 'appium/driver';
-
-/**
- * Performs a simple click/tap gesture
- *
- * @this {AndroidUiautomator2Driver}
- * @param {string} [elementId] The id of the element to be clicked.
- * If the element is missing then both click offset coordinates must be provided.
- * If both the element id and offset are provided then the coordinates are parsed
- * as relative offsets from the top left corner of the element.
- * @param {number} [x] The x coordinate to click on.
- * @param {number} [y] The y coordinate to click on.
- * @returns {Promise<void>}
- * @throws {Error} if provided options are not valid
- */
-export async function mobileClickGesture(elementId, x, y) {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/gestures/click',
-    'POST',
-    {
-      origin: toOrigin(elementId),
-      offset: toPoint(x, y),
-    }
-  );
-}
-
-/**
- * Performs a click that lasts for the given duration
- *
- * @this {AndroidUiautomator2Driver}
- * @param {string} [elementId] The id of the element to be clicked.
- * If the element is missing then both click offset coordinates must be provided.
- * If both the element id and offset are provided then the coordinates are parsed
- * as relative offsets from the top left corner of the element.
- * @param {number} [x] The x coordinate to click on.
- * @param {number} [y] The y coordinate to click on.
- * @param {number} [duration] Click duration in milliseconds. The value must not be negative.
- * Default is 500.
- * @returns {Promise<void>}
- * @throws {Error} if provided options are not valid
- */
-export async function mobileLongClickGesture(elementId, x, y, duration) {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/gestures/long_click',
-    'POST',
-    {
-      origin: toOrigin(elementId),
-      offset: toPoint(x, y),
-      duration,
-    }
-  );
-}
-
-/**
- * Performs a click that lasts for the given duration
- * @this {AndroidUiautomator2Driver}
- * @param {string} [elementId] The id of the element to be clicked.
- * If the element is missing then both click offset coordinates must be provided.
- * If both the element id and offset are provided then the coordinates are parsed
- * as relative offsets from the top left corner of the element.
- * @param {number} [x] The x coordinate to click on.
- * @param {number} [y] The y coordinate to click on.
- * @returns {Promise<void>}
- * @throws {Error} if provided options are not valid
- */
-export async function mobileDoubleClickGesture(elementId, x, y) {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/gestures/double_click',
-    'POST',
-    {
-      origin: toOrigin(elementId),
-      offset: toPoint(x, y),
-    }
-  );
-}
-
-/**
- * Drags this object to the specified location.
- * @this {AndroidUiautomator2Driver}
- * @param {string} [elementId] The id of the element to be dragged.
- * If the element id is missing then the start coordinates must be provided.
- * If both the element id and the start coordinates are provided then these
- * coordinates are considered as offsets from the top left element corner.
- * @param {number} [startX] The x coordinate where the dragging starts
- * @param {number} [startY] The y coordinate where the dragging starts
- * @param {number} [endX] The x coordinate where the dragging ends
- * @param {number} [endY] The y coordinate where the dragging ends
- * @param {number} [speed] The speed at which to perform this gesture in pixels per second.
- * The value must not be negative.
- * Default is 2500 * displayDensity.
- * @returns {Promise<void>}
- * @throws {Error} if provided options are not valid
- */
-export async function mobileDragGesture(
-  elementId,
-  startX,
-  startY,
-  endX,
-  endY,
-  speed,
-) {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/gestures/drag',
-    'POST',
-    {
-      origin: toOrigin(elementId),
-      start: toPoint(startX, startY),
-      end: toPoint(endX, endY),
-      speed,
-    }
-  );
-}
-
-/**
- * Drags to the specified location.
- *
- * @throws {Error} if provided options are not valid
- * @this {AndroidUiautomator2Driver}
- * @param {string} direction Direction of the fling.
- * Acceptable values are: `up`, `down`, `left` and `right` (case insensitive).
- * @param {string} [elementId] The id of the element to be flinged.
- * If the element id is missing then fling bounding area must be provided.
- * If both the element id and the fling bounding area are provided then this
- * area is effectively ignored.
- * @param {number} [left] The left coordinate of the fling bounding area.
- * @param {number} [top] The top coordinate of the fling bounding area.
- * @param {number} [width] The width of the fling bounding area.
- * @param {number} [height] The height of the fling bounding area.
- * @param {number} [speed] The speed at which to perform this gesture in pixels per second.
- * The value must be greater than the minimum fling velocity for the given view (50 by default).
- * Default is 7500 * displayDensity.
- * @returns {Promise<boolean>} True if the object can still scroll in the given direction.
- */
-export async function mobileFlingGesture(
-  direction,
-  elementId,
-  left,
-  top,
-  width,
-  height,
-  speed,
-) {
-  return /** @type {boolean} */ (
-    await this.uiautomator2.jwproxy.command(
-      '/appium/gestures/fling',
-      'POST',
-      {
-        origin: toOrigin(elementId),
-        area: toRect(left, top, width, height),
-        direction,
-        speed,
-      }
-    )
-  );
-}
-
-/**
- * Performs a pinch close gesture.
- * @this {AndroidUiautomator2Driver}
- * @param {number} percent The size of the pinch as a percentage of the pinch area size.
- * Valid values must be float numbers in range 0..1, where 1.0 is 100%
- * @param {string} [elementId] The id of the element to be pinched.
- * If the element id is missing then pinch bounding area must be provided.
- * If both the element id and the pinch bounding area are provided then the
- * area is effectively ignored.
- * @param {number} [left] The left coordinate of the pinch bounding area.
- * @param {number} [top] The top coordinate of the pinch bounding area.
- * @param {number} [width] The width of the pinch bounding area.
- * @param {number} [height] The height of the pinch bounding area.
- * @param {number} [speed] The speed at which to perform this gesture in pixels per second.
- * The value must not be negative.
- * Default is 2500 * displayDensity.
- * @returns {Promise<void>}
- * @throws {Error} if provided options are not valid
- */
-export async function mobilePinchCloseGesture(
-  percent,
-  elementId,
-  left,
-  top,
-  width,
-  height,
-  speed,
-) {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/gestures/pinch_close',
-    'POST',
-    {
-      origin: toOrigin(elementId),
-      area: toRect(left, top, width, height),
-      percent,
-      speed,
-    }
-  );
-}
-
-/**
- * Performs a pinch open gesture.
- * @this {AndroidUiautomator2Driver}
- * @param {number} percent The size of the pinch as a percentage of the pinch area size.
- * Valid values must be float numbers in range 0..1, where 1.0 is 100%
- * @param {string} [elementId] The id of the element to be pinched.
- * If the element id is missing then pinch bounding area must be provided.
- * If both the element id and the pinch bounding area are provided then the
- * area is effectively ignored.
- * @param {number} [left] The left coordinate of the pinch bounding area.
- * @param {number} [top] The top coordinate of the pinch bounding area.
- * @param {number} [width] The width of the pinch bounding area.
- * @param {number} [height] The height of the pinch bounding area.
- * @param {number} [speed] The speed at which to perform this gesture in pixels per second.
- * The value must not be negative.
- * Default is 2500 * displayDensity.
- * @returns {Promise<void>}
- * @throws {Error} if provided options are not valid
- */
-export async function mobilePinchOpenGesture(
-  percent,
-  elementId,
-  left,
-  top,
-  width,
-  height,
-  speed,
-) {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/gestures/pinch_open',
-    'POST',
-    {
-      origin: toOrigin(elementId),
-      area: toRect(left, top, width, height),
-      percent,
-      speed,
-    }
-  );
-}
-
-/**
- * Performs a swipe gesture.
- * @this {AndroidUiautomator2Driver}
- * @param {string} direction Direction of the swipe.
- * Acceptable values are: `up`, `down`, `left` and `right` (case insensitive).
- * @param {number} percent The size of the swipe as a percentage of the swipe area size.
- * Valid values must be float numbers in range 0..1, where 1.0 is 100%.
- * @param {string} [elementId] The id of the element to be swiped.
- * If the element id is missing then swipe bounding area must be provided.
- * If both the element id and the swipe bounding area are provided then the
- * area is effectively ignored.
- * @param {number} [left] The left coordinate of the swipe bounding area.
- * @param {number} [top] The top coordinate of the swipe bounding area.
- * @param {number} [width] The width of the swipe bounding area.
- * @param {number} [height] The height of the swipe bounding area.
- * @param {number} [speed] The speed at which to perform this gesture in pixels per second.
- * The value must not be negative.
- * Default is 5000 * displayDensity.
- * @returns {Promise<void>}
- * @throws {Error} if provided options are not valid
- */
-export async function mobileSwipeGesture(
-  direction,
-  percent,
-  elementId,
-  left,
-  top,
-  width,
-  height,
-  speed,
-) {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/gestures/swipe',
-    'POST',
-    {
-      origin: toOrigin(elementId),
-      area: toRect(left, top, width, height),
-      direction,
-      percent,
-      speed,
-    }
-  );
-}
-
-/**
- * Performs a scroll gesture.
- *
- * @throws {Error} if provided options are not valid
- * @this {AndroidUiautomator2Driver}
- * @param {string} direction Direction of the scroll.
- * Acceptable values are: `up`, `down`, `left` and `right` (case insensitive).
- * @param {number} percent The size of the scroll as a percentage of the scrolling area size.
- * Valid values must be float numbers greater than zero, where 1.0 is 100%.
- * @param {string} [elementId] The id of the element to be scrolled.
- * If the element id is missing then scroll bounding area must be provided.
- * If both the element id and the scroll bounding area are provided then this
- * area is effectively ignored.
- * @param {number} [left] The left coordinate of the scroll bounding area.
- * @param {number} [top] The top coordinate of the scroll bounding area.
- * @param {number} [width] The width of the scroll bounding area.
- * @param {number} [height] The height of the scroll bounding area.
- * @param {number} [speed] The speed at which to perform this gesture in pixels per second.
- * The value must not be negative.
- * Default is 5000 * displayDensity.
- * @returns {Promise<boolean>} True if the object can still scroll in the given direction.
- */
-export async function mobileScrollGesture(
-  direction,
-  percent,
-  elementId,
-  left,
-  top,
-  width,
-  height,
-  speed,
-) {
-  return /** @type {boolean} */ (
-    await this.uiautomator2.jwproxy.command(
-      '/appium/gestures/scroll',
-      'POST',
-      {
-        origin: toOrigin(elementId),
-        area: toRect(left, top, width, height),
-        direction,
-        percent,
-        speed,
-      }
-    )
-  );
-}
-
-/**
- * Scrolls the given scrollable element `elementId` until `elementToId`
- * becomes visible. This function returns immediately if the `elementToId`
- * is already visible in the view port. Otherwise it would scroll
- * to the very beginning of the scrollable control and tries to reach the destination element
- * by scrolling its parent to the end step by step. The scroll direction (vertical or horizontal)
- * is detected automatically.
- * @this {AndroidUiautomator2Driver}
- * @param {string} elementId The identifier of the scrollable element, which is going to be scrolled.
- * It is required this element is a valid scrollable container and it was located
- * by `-android uiautomator` strategy.
- * @param {string} elementToId The identifier of the item, which belongs to the scrollable element above,
- * and which should become visible after the scrolling operation is finished.
- * It is required this element was located by `-android uiautomator` strategy.
- * @returns {Promise<void>}
- * @throws {Error} if the scrolling operation cannot be performed
- */
-export async function mobileScrollBackTo(elementId, elementToId) {
-  if (!elementId || !elementToId) {
-    throw new errors.InvalidArgumentError(
-      `Both elementId and elementToId arguments must be provided`
-    );
-  }
-  await this.uiautomator2.jwproxy.command(
-    `/appium/element/${util.unwrapElement(elementId)}/scroll_to/${util.unwrapElement(
-      elementToId
-    )}`,
-    'POST',
-    {}
-  );
-}
-
-/**
- * Scrolls the given scrollable element until the element identified
- * by `strategy` and `selector` becomes visible. This function returns immediately if the
- * destination element is already visible in the view port. Otherwise it would scroll
- * to the very beginning of the scrollable control and tries to reach the destination element
- * by scrolling its parent to the end step by step. The scroll direction (vertical or horizontal)
- * is detected automatically.
- *
- * @this {AndroidUiautomator2Driver}
- * @param {string} strategy The following strategies are supported:
- * - `accessibility id` (UiSelector().description)
- * - `class name` (UiSelector().className)
- * - `-android uiautomator` (UiSelector)
- * @param {string} selector The corresponding lookup value for the given strategy.
- * @param {string} [elementId] The identifier of an element. It is required this element is a valid scrollable container
- * and it was located by `-android uiautomator` strategy.
- * If this property is not provided then the first currently available scrollable view
- * is selected for the interaction.
- * @param {number} [maxSwipes] The maximum number of swipes to perform on the target scrollable view in order to reach
- * the destination element. In case this value is unset then it would be retrieved from the
- * scrollable element itself (via `getMaxSearchSwipes()` property).
- * @returns {Promise<void>}
- * @throws {Error} if the scrolling operation cannot be performed
- */
-export async function mobileScroll(
-  strategy,
-  selector,
-  elementId,
-  maxSwipes,
-) {
-  if (!strategy || !selector) {
-    throw new errors.InvalidArgumentError(
-      `Both strategy and selector arguments must be provided`
-    );
-  }
-  await this.uiautomator2.jwproxy.command(
-    '/gestures/scroll_to',
-    'POST',
-    {
-      origin: toOrigin(elementId),
-      params: {strategy, selector, maxSwipes},
-    }
-  );
-}
-
-// #region Internal Helpers
-
-/**
- *
- * @param {import('@appium/types').Element|string} [element]
- * @returns {import('@appium/types').Element|undefined}
- */
-function toOrigin(element) {
-  return element ? util.wrapElement(util.unwrapElement(element)) : undefined;
-}
-
-/**
- *
- * @param {number} [x]
- * @param {number} [y]
- * @returns {Partial<import('@appium/types').Position>|undefined}
- */
-function toPoint(x, y) {
-  return _.isFinite(x) && _.isFinite(y) ? {x, y} : undefined;
-}
-
-/**
- *
- * @param {number} [left]
- * @param {number} [top]
- * @param {number} [width]
- * @param {number} [height]
- * @returns {Partial<import('./types').RelativeRect>|undefined}
- */
-function toRect(left, top, width, height) {
-  return [left, top, width, height].some((v) => !_.isFinite(v))
-    ? undefined
-    : {left, top, width, height};
-}
-
-// #endregion
-
-/**
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */