appium-uiautomator2-driver 2.42.2 → 2.43.1

package/lib/commands/misc.js

@@ -0,0 +1,106 @@
+/**
+ * @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<string>}
+ */
+export async function getClipboard() {
+  return String(
+    (await this.adb.getApiLevel()) < 29
+      ? await this.uiautomator2.jwproxy.command(
+          '/appium/device/get_clipboard',
+          'POST',
+          {}
+        )
+      : await this.settingsApp.getClipboard()
+  );
+}
+
+/**
+ * @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() {
+  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'
+    )
+  );
+}
+
+/**
+ * @template [T=any]
+ * @typedef {import('@appium/types').StringRecord<T>} StringRecord
+ * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
+ */

package/lib/commands/navigation.js

@@ -0,0 +1,31 @@
+/**
+ * @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 {import('./types').DeepLinkOpts} opts
+ * @returns {Promise<void>}
+ */
+export async function mobileDeepLink(opts) {
+  const {url, package: pkg, waitForLaunch} = opts;
+  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
+ */

package/lib/commands/screenshot.js

@@ -1,95 +1,114 @@
-// @ts-check
-
-import {mixin} from './mixins';
 import _ from 'lodash';
 import B from 'bluebird';
+import {imageUtil} from 'appium/support';
 
 // Display 4619827259835644672 (HWC display 0): port=0 pnpId=GGL displayName="EMU_display_0"
 const DISPLAY_PATTERN = /^Display\s+(\d+)\s+\(.+display\s+(\d+)\).+displayName="([^"]*)/gm;
 
 /**
- * @type {import('./mixins').UIA2ScreenshotMixin}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * @this {AndroidUiautomator2Driver}
+ * @returns {Promise<string>}
  */
-const ScreenshotMixin = {
-  async getScreenshot() {
-    if (this.mjpegStream) {
-      const data = await this.mjpegStream.lastChunkPNGBase64();
-      if (data) {
-        return data;
-      }
-      this.log.warn(
-        'Tried to get screenshot from active MJPEG stream, but there ' +
-          'was no data yet. Falling back to regular screenshot methods.'
-      );
+export async function mobileViewportScreenshot() {
+  return await this.getViewportScreenshot();
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @returns {Promise<string>}
+ */
+export async function getViewportScreenshot() {
+  const screenshot = await this.getScreenshot();
+  const rect = await this.getViewPortRect();
+  return await imageUtil.cropBase64Image(screenshot, rect);
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @returns {Promise<string>}
+ */
+export async function getScreenshot() {
+  if (this.mjpegStream) {
+    const data = await this.mjpegStream.lastChunkPNGBase64();
+    if (data) {
+      return data;
     }
-    return String(
-      await /** @type {import('../uiautomator2').UiAutomator2Server} */ (
-        this.uiautomator2
-      ).jwproxy.command('/screenshot', 'GET')
+    this.log.warn(
+      'Tried to get screenshot from active MJPEG stream, but there ' +
+        'was no data yet. Falling back to regular screenshot methods.'
     );
-  },
+  }
+  return String(
+    await /** @type {import('../uiautomator2').UiAutomator2Server} */ (
+      this.uiautomator2
+    ).jwproxy.command('/screenshot', 'GET')
+  );
+}
+
+/**
+ * Retrieves screenshots of each display available to Android.
+ * This functionality is only supported since Android 10.
+ * @this {AndroidUiautomator2Driver}
+ * @param {import('./types').ScreenshotsOpts} [opts={}]
+ * @returns {Promise<import('@appium/types').StringRecord<import('./types').Screenshot>>}
+ */
+export async function mobileScreenshots(opts = {}) {
+  const displaysInfo = await /** @type {import('appium-adb').ADB} */ (this.adb).shell([
+    'dumpsys',
+    'SurfaceFlinger',
+    '--display-id',
+  ]);
+  /** @type {import('@appium/types').StringRecord<import('./types').Screenshot>} */
+  const infos = {};
+  let match;
+  while ((match = DISPLAY_PATTERN.exec(displaysInfo))) {
+    infos[match[1]] = /** @type {any} */ ({
+      id: match[1],
+      isDefault: match[2] === '0',
+      name: match[3],
+    });
+  }
+  if (_.isEmpty(infos)) {
+    this.log.debug(displaysInfo);
+    throw new Error('Cannot determine the information about connected Android displays');
+  }
+  this.log.info(`Parsed Android display infos: ${JSON.stringify(infos)}`);
 
   /**
-   * Retrieves screenshots of each display available to Android.
-   * This functionality is only supported since Android 10.
+   * @param {string} dispId
    */
-  async mobileScreenshots(opts = {}) {
-    const displaysInfo = await /** @type {import('appium-adb').ADB} */ (this.adb).shell([
-      'dumpsys',
-      'SurfaceFlinger',
-      '--display-id',
-    ]);
-    /** @type {import('@appium/types').StringRecord<import('./types').Screenshot>} */
-    const infos = {};
-    let match;
-    while ((match = DISPLAY_PATTERN.exec(displaysInfo))) {
-      infos[match[1]] = /** @type {any} */ ({
-        id: match[1],
-        isDefault: match[2] === '0',
-        name: match[3],
-      });
-    }
-    if (_.isEmpty(infos)) {
-      this.log.debug(displaysInfo);
-      throw new Error('Cannot determine the information about connected Android displays');
-    }
-    this.log.info(`Parsed Android display infos: ${JSON.stringify(infos)}`);
+  const toB64Screenshot = async (dispId) =>
+    (await /** @type {import('appium-adb').ADB} */ (this.adb).takeScreenshot(dispId)).toString(
+      'base64'
+    );
 
-    /**
-     * @param {string} dispId
-     */
-    const toB64Screenshot = async (dispId) =>
-      (await /** @type {import('appium-adb').ADB} */ (this.adb).takeScreenshot(dispId)).toString(
-        'base64'
+  const {displayId} = opts;
+  const displayIdStr = _.isNaN(displayId) ? null : `${displayId}`;
+  if (displayIdStr) {
+    if (!infos[displayIdStr]) {
+      throw new Error(
+        `The provided display identifier '${displayId}' is not known. ` +
+          `Only the following displays have been detected: ${JSON.stringify(infos)}`
       );
-
-    const {displayId} = opts;
-    const displayIdStr = _.isNaN(displayId) ? null : `${displayId}`;
-    if (displayIdStr) {
-      if (!infos[displayIdStr]) {
-        throw new Error(
-          `The provided display identifier '${displayId}' is not known. ` +
-            `Only the following displays have been detected: ${JSON.stringify(infos)}`
-        );
-      }
-      return {
-        [displayIdStr]: {
-          ...infos[displayIdStr],
-          payload: await toB64Screenshot(displayIdStr),
-        },
-      };
     }
+    return {
+      [displayIdStr]: {
+        ...infos[displayIdStr],
+        payload: await toB64Screenshot(displayIdStr),
+      },
+    };
+  }
 
-    const allInfos = _.values(infos);
-    const screenshots = await B.all(allInfos.map(({id}) => toB64Screenshot(id)));
-    for (const [info, payload] of /** @type {[import('./types').Screenshot, string][]} */ (
-      _.zip(allInfos, screenshots)
-    )) {
-      info.payload = payload;
-    }
-    return infos;
-  },
-};
+  const allInfos = _.values(infos);
+  const screenshots = await B.all(allInfos.map(({id}) => toB64Screenshot(id)));
+  for (const [info, payload] of /** @type {[import('./types').Screenshot, string][]} */ (
+    _.zip(allInfos, screenshots)
+  )) {
+    info.payload = payload;
+  }
+  return infos;
+}
 
-mixin(ScreenshotMixin);
+/**
+ * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
+ */

package/lib/commands/touch.js

@@ -1,71 +1,213 @@
-// @ts-check
+import { util } from 'appium/support';
+import { W3C_ELEMENT_KEY } from 'appium/driver';
 
-import {mixin} from './mixins';
+/**
+ * @deprecated
+ * @this {AndroidUiautomator2Driver}
+ * @param {import('appium-android-driver').SwipeOpts} swipeOpts
+ * @returns {Promise<void>}
+ */
+export async function doSwipe(swipeOpts) {
+  await this.uiautomator2.jwproxy.command(
+    `/touch/perform`,
+    'POST',
+    swipeOpts
+  );
+}
+
+/**
+ * @deprecated
+ * @this {AndroidUiautomator2Driver}
+ * @param {import('appium-android-driver').DragOpts} dragOpts
+ * @returns {Promise<void>}
+ */
+export async function doDrag(dragOpts) {
+  await this.uiautomator2.jwproxy.command(
+    `/touch/drag`,
+    'POST',
+    dragOpts
+  );
+}
+
+/**
+ * @deprecated
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} element
+ * @param {number} x
+ * @param {number} y
+ * @param {number} duration
+ * @returns {Promise<void>}
+ */
+export async function touchLongClick(element, x, y, duration) {
+  let params = {element, x, y, duration};
+  await this.uiautomator2.jwproxy.command(
+    `/touch/longclick`,
+    'POST',
+    {params}
+  );
+}
+
+/**
+ * @deprecated
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} element
+ * @param {number} x
+ * @param {number} y
+ * @returns {Promise<void>}
+ */
+export async function touchDown(element, x, y) {
+  let params = {element, x, y};
+  await this.uiautomator2.jwproxy.command(
+    `/touch/down`,
+    'POST',
+    {params}
+  );
+}
+
+/**
+ * @deprecated
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} element
+ * @param {number} x
+ * @param {number} y
+ * @returns {Promise<void>}
+ */
+export async function touchUp(element, x, y) {
+  let params = {element, x, y};
+  await this.uiautomator2.jwproxy.command(
+    `/touch/up`,
+    'POST',
+    {params}
+  );
+}
 
 /**
- * @type {import('./mixins').UIA2TouchMixin}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * @deprecated
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} element
+ * @param {number} x
+ * @param {number} y
+ * @returns {Promise<void>}
  */
-const TouchMixin = {
-  async doPerformMultiAction(elementId, states) {
-    let opts;
-    if (elementId) {
-      opts = {
-        elementId,
-        actions: states,
-      };
+export async function touchMove(element, x, y) {
+  let params = {element, x, y};
+  await this.uiautomator2.jwproxy.command(
+    `/touch/move`,
+    'POST',
+    {params}
+  );
+}
 
+/**
+ * @deprecated
+ * @this {AndroidUiautomator2Driver}
+ * @param {string?} [elementId=null]
+ * @param {number?} [x=null]
+ * @param {number?} [y=null]
+ * @param {number} [count=1]
+ * @returns {Promise<void>}
+ */
+export async function tap(elementId = null, x = null, y = null, count = 1) {
+  const areCoordinatesDefined = util.hasValue(x) && util.hasValue(y);
+  if (!util.hasValue(elementId) && !areCoordinatesDefined) {
+    throw new Error(`Either element id to tap or both absolute coordinates should be defined`);
+  }
+
+  for (let i = 0; i < count; i++) {
+    if (util.hasValue(elementId) && !areCoordinatesDefined) {
+      // we are either tapping on the default location of the element
+      // or an offset from the top left corner
       await this.uiautomator2.jwproxy.command(
-        '/touch/multi/perform',
-        'POST',
-        opts
+        `/element/${elementId}/click`,
+        'POST'
       );
     } else {
-      opts = {
-        actions: states,
-      };
       await this.uiautomator2.jwproxy.command(
-        '/touch/multi/perform',
+        `/appium/tap`,
         'POST',
-        opts
+        {
+          x,
+          y,
+          [W3C_ELEMENT_KEY]: elementId,
+        }
       );
     }
-  },
+  }
+}
+
+/**
+ * @deprecated
+ * @this {AndroidUiautomator2Driver}
+ * @param {string} elementId
+ * @param {import('appium-android-driver').TouchState[]} states
+ * @returns {Promise<void>}
+ */
+export async function doPerformMultiAction(elementId, states) {
+  let opts;
+  if (elementId) {
+    opts = {
+      elementId,
+      actions: states,
+    };
 
-  async performActions(actions) {
-    this.log.debug(`Received the following W3C actions: ${JSON.stringify(actions, null, '  ')}`);
-    // This is mandatory, since Selenium API uses MOUSE as the default pointer type
-    const preprocessedActions = actions.map((action) =>
-      Object.assign(
-        {},
-        action,
-        action.type === 'pointer'
-          ? {
-              parameters: {
-                pointerType: 'touch',
-              },
-            }
-          : {}
-      )
+    await this.uiautomator2.jwproxy.command(
+      '/touch/multi/perform',
+      'POST',
+      opts
     );
-    this.log.debug(`Preprocessed actions: ${JSON.stringify(preprocessedActions, null, '  ')}`);
+  } else {
+    opts = {
+      actions: states,
+    };
     await this.uiautomator2.jwproxy.command(
-      '/actions',
+      '/touch/multi/perform',
       'POST',
-      {
-        actions: preprocessedActions,
-      }
+      opts
     );
-  },
+  }
+}
 
-  // eslint-disable-next-line require-await
-  async releaseActions() {
-    this.log.info('On this platform, releaseActions is a no-op');
-  },
-};
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {import('@appium/types').StringRecord} actions
+ * @returns {Promise<void>}
+ */
+export async function performActions(actions) {
+  this.log.debug(`Received the following W3C actions: ${JSON.stringify(actions, null, '  ')}`);
+  // This is mandatory, since Selenium API uses MOUSE as the default pointer type
+  const preprocessedActions = actions.map((action) =>
+    Object.assign(
+      {},
+      action,
+      action.type === 'pointer'
+        ? {
+            parameters: {
+              pointerType: 'touch',
+            },
+          }
+        : {}
+    )
+  );
+  this.log.debug(`Preprocessed actions: ${JSON.stringify(preprocessedActions, null, '  ')}`);
+  await this.uiautomator2.jwproxy.command(
+    '/actions',
+    'POST',
+    {
+      actions: preprocessedActions,
+    }
+  );
+}
 
-mixin(TouchMixin);
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @returns {Promise<void>}
+ */
+// eslint-disable-next-line require-await
+export async function releaseActions() {
+  this.log.info('On this platform, releaseActions is a no-op');
+}
 
 /**
  * @typedef {import('../uiautomator2').UiAutomator2Server} UiAutomator2Server
+ * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
  */