appium-uiautomator2-driver 6.7.5 → 6.7.7

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
- */

package/lib/commands/keyboard.js

@@ -1,108 +0,0 @@
-import { errors } from 'appium/driver';
-import _ from 'lodash';
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string|number} keycode
- * @param {number} [metastate]
- * @param {number} [flags]
- * @returns {Promise<void>}
- */
-export async function pressKeyCode(keycode, metastate, flags) {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/device/press_keycode',
-    'POST',
-    {
-      keycode,
-      metastate,
-      flags,
-    }
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string|number} keycode
- * @param {number} metastate
- * @param {number} [flags]
- * @returns {Promise<void>}
- */
-export async function longPressKeyCode(keycode, metastate, flags) {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/device/long_press_keycode',
-    'POST',
-    {
-      keycode,
-      metastate,
-      flags,
-    }
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {number} keycode A valid Android key code. See https://developer.android.com/reference/android/view/KeyEvent
- * for the list of available key codes.
- * @param {number} [metastate] An integer in which each bit set to 1 represents a pressed meta key. See
- * https://developer.android.com/reference/android/view/KeyEvent for more details.
- * @param {string} [flags] Flags for the particular key event. See
- * https://developer.android.com/reference/android/view/KeyEvent for more details.
- * @param {boolean} [isLongPress=false] Whether to emulate long key press
- * @returns {Promise<void>}
- */
-export async function mobilePressKey(keycode, metastate, flags, isLongPress = false) {
-  await this.uiautomator2.jwproxy.command(
-    `/appium/device/${isLongPress ? 'long_' : ''}press_keycode`,
-    'POST',
-    {
-      keycode,
-      metastate,
-      flags,
-    }
-  );
-}
-
-/**
- * Types the given Unicode string.
- * It is expected that the focus is already put
- * to the destination input field before this method is called.
- *
- * @this {AndroidUiautomator2Driver}
- * @param {string | number | boolean} text The text to type. Can be a string, number or boolean.
- * @returns {Promise<boolean>} `true` if the input text has been successfully sent to adb
- * @throws {Error} if `text` property has not been provided
- */
-export async function mobileType(text) {
-  if (_.isUndefined(text)) {
-    throw new errors.InvalidArgumentError(`The 'text' argument is mandatory`);
-  }
-  return await this.settingsApp.typeUnicode(String(text));
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {import('appium-android-driver').SendKeysOpts} params
- * @returns {Promise<void>}
- */
-export async function doSendKeys(params) {
-  await this.uiautomator2.jwproxy.command(
-    '/keys',
-    'POST',
-    params
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string|number} keycode
- * @param {number} [metastate]
- * @returns {Promise<void>}
- */
-export async function keyevent(keycode, metastate) {
-  this.log.debug(`Ignoring metastate ${metastate}`);
-  await this.adb.keyevent(keycode);
-}
-
-/**
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */

package/lib/commands/misc.js

@@ -1,109 +0,0 @@
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<string>}
- */
-export async function getPageSource() {
-  return String(
-    await this.uiautomator2.jwproxy.command(
-      '/source',
-      'GET',
-      {}
-    )
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<import('@appium/types').Orientation>}
- */
-export async function getOrientation() {
-  return /** @type {import('@appium/types').Orientation} */ (
-    await this.uiautomator2.jwproxy.command(
-      `/orientation`,
-      'GET',
-      {}
-    )
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {import('@appium/types').Orientation} orientation
- * @returns {Promise<void>}
- */
-export async function setOrientation(orientation) {
-  orientation = /** @type {import('@appium/types').Orientation} */ (orientation.toUpperCase());
-  await this.uiautomator2.jwproxy.command(
-    `/orientation`,
-    'POST',
-    {orientation}
-  );
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<void>}
- */
-export async function openNotifications() {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/device/open_notifications',
-    'POST',
-    {}
-  );
-}
-
-/**
- * Stop proxying to any Chromedriver and redirect to uiautomator2
- * @this {AndroidUiautomator2Driver}
- * @returns {void}
- */
-export function suspendChromedriverProxy() {
-  if (!this.uiautomator2?.proxyReqRes || !this.uiautomator2?.proxyCommand) {
-    return;
-  }
-
-  this.chromedriver = undefined;
-  this.proxyReqRes = this.uiautomator2.proxyReqRes.bind(
-    this.uiautomator2
-  );
-  this.proxyCommand = /** @type {typeof this.proxyCommand} */ (
-    this.uiautomator2.proxyCommand.bind(this.uiautomator2)
-  );
-  this.jwpProxyActive = true;
-}
-
-/**
- * The list of available info entries can be found at
- * https://github.com/appium/appium-uiautomator2-server/blob/master/app/src/main/java/io/appium/uiautomator2/handler/GetDeviceInfo.java
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<StringRecord>}
- */
-export async function mobileGetDeviceInfo() {
-  return /** @type {StringRecord} */ (
-    await this.uiautomator2.jwproxy.command(
-      '/appium/device/info',
-      'GET'
-    )
-  );
-}
-
-/**
- * Resets the accessibility cache on the device.
- * This can be useful when the accessibility service cache becomes stale
- * and needs to be refreshed to reflect the current UI state.
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<void>}
- */
-export async function mobileResetAccessibilityCache() {
-  await this.uiautomator2.jwproxy.command(
-    '/appium/reset_ax_cache',
-    'POST',
-    {}
-  );
-}
-
-/**
- * @template [T=any]
- * @typedef {import('@appium/types').StringRecord<T>} StringRecord
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */

package/lib/commands/navigation.js

@@ -1,33 +0,0 @@
-/**
- * @this {AndroidUiautomator2Driver}
- * @param {string} url
- * @returns {Promise<void>}
- */
-export async function setUrl(url) {
-  await this.adb.startUri(url, /** @type {string} */ (this.opts.appPackage));
-}
-
-/**
- * Start URL that take users directly to specific content in the app
- * @this {AndroidUiautomator2Driver}
- * @param {string} url The name of URL to start.
- * @param {string} [pkg] The name of the package to start the URI with.
- * @param {boolean} [waitForLaunch=true] If `false` then adb won't wait for
- * the started activity to return the control.
- * @returns {Promise<void>}
- */
-export async function mobileDeepLink(url, pkg, waitForLaunch) {
-  return await this.adb.startUri(url, pkg, {waitForLaunch});
-}
-
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<void>}
- */
-export async function back() {
-  await this.adb.keyevent(4);
-}
-
-/**
- * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
- */