appium-uiautomator2-driver 2.29.11 → 2.31.0

package/lib/commands/index.js

@@ -1,31 +1,11 @@
-import alertCmds from './alert';
-import findCmds from './find';
-import generalCmds from './general';
-import touchCmds from './touch';
-import elementCmds from './element';
-import actionsCmds from './actions';
-import viewportCmds from './viewport';
-import screenshotCmds from './screenshot';
-import batteryCmds from './battery';
-import gesturesCmds from './gestures';
-import appStringsCmds from './app-strings';
-
-let commands = {};
-Object.assign(
-  commands,
-  alertCmds,
-  findCmds,
-  generalCmds,
-  touchCmds,
-  actionsCmds,
-  elementCmds,
-  viewportCmds,
-  screenshotCmds,
-  batteryCmds,
-  gesturesCmds,
-  appStringsCmds,
-  // add other command types here
-);
-
-export default commands;
-
+import './alert';
+import './find';
+import './general';
+import './touch';
+import './element';
+import './actions';
+import './viewport';
+import './screenshot';
+import './battery';
+import './gestures';
+import './app-strings';

package/lib/commands/mixins.ts

@@ -0,0 +1,169 @@
+/**
+ * @module
+ * @privateRemarks These mixins are kind of a mishmash of stuff from `appium-android-driver`,
+ * @privateRemarks unique things, and stuff from `ExternalDriver`. Ideally, we should be pulling the method
+ * @privateRemarks definitions right out of `ExternalDriver` whenever possible.  Also note that the mixins
+ * @privateRemarks contain _more stuff than just commands or execute methods_.
+ */
+
+import type {Element, ExternalDriver, StringRecord} from '@appium/types';
+import type {
+  ActionsMixin,
+  AlertMixin,
+  ElementMixin,
+  ExecuteMixin,
+  FindMixin,
+  GeneralMixin,
+  NetworkMixin,
+  TouchMixin,
+} from 'appium-android-driver';
+import type {EmptyObject} from 'type-fest';
+import {AndroidUiautomator2Driver} from '../driver';
+import type * as types from './types';
+
+type UIA2Mixin<T = EmptyObject> = ThisType<import('../driver').AndroidUiautomator2Driver> & T;
+
+export type UIA2ActionsMixin = UIA2Mixin<
+  Pick<
+    ActionsMixin,
+    'pressKeyCode' | 'longPressKeyCode' | 'doSwipe' | 'doDrag' | 'getOrientation' | 'setOrientation'
+  >
+> & {
+  mobilePressKey(opts: types.PressKeyOptions): Promise<void>;
+  mobileScheduleAction(opts?: StringRecord): Promise<unknown>;
+  mobileGetActionHistory(opts?: types.ActionArgs): Promise<types.ActionResult>;
+  mobileUnscheduleAction(opts?: types.ActionArgs): Promise<unknown>;
+};
+
+export type UIA2AlertMixin = UIA2Mixin<
+  Pick<AlertMixin, 'getAlertText' | 'postAcceptAlert' | 'postDismissAlert'>
+> & {
+  mobileAcceptAlert(opts?: types.AcceptAlertOptions): Promise<void>;
+  mobileDismissAlert(opts?: types.DismissAlertOptions): Promise<void>;
+};
+
+export type UIA2AppStringsMixin = UIA2Mixin<Pick<GeneralMixin, 'getStrings'>> & {
+  mobileGetAppStrings(opts?: types.GetAppStringsOptions): Promise<StringRecord>;
+};
+
+export type UIA2BatteryMixin = UIA2Mixin & {
+  mobileGetBatteryInfo(): Promise<types.BatteryInfo>;
+};
+
+export type UIA2ElementMixin = UIA2Mixin<
+  Pick<
+    ElementMixin,
+    | 'getAttribute'
+    | 'elementDisplayed'
+    | 'elementEnabled'
+    | 'elementSelected'
+    | 'getName'
+    | 'getLocation'
+    | 'getSize'
+    | 'touchLongClick'
+    | 'touchDown'
+    | 'touchUp'
+    | 'touchMove'
+    | 'doSetElementValue'
+    | 'setValueImmediate'
+    | 'getText'
+    | 'click'
+    | 'tap'
+    | 'clear'
+    | 'getElementRect'
+  >
+> & {
+  active(): Promise<Element>;
+  mobileReplaceElementValue(opts: types.ReplaceValueOptions): Promise<void>;
+  getElementScreenshot(elementId: string): Promise<string>;
+};
+
+export type UIA2FindMixin = UIA2Mixin<Pick<FindMixin, 'doFindElementOrEls'>>;
+
+export type UIA2GeneralMixin = UIA2Mixin<
+  Pick<
+    GeneralMixin & NetworkMixin & ActionsMixin & ExecuteMixin,
+    | 'getPageSource'
+    | 'doSendKeys'
+    | 'back'
+    | 'getDisplayDensity'
+    | 'getWindowSize'
+    | 'getWindowRect'
+    | 'setUrl'
+    | 'keyevent'
+    | 'execute'
+    | 'executeMobile'
+  >
+> & {
+  getClipboard(): Promise<string>;
+  mobileViewportScreenshot(): Promise<string>;
+  mobileViewPortRect(): Promise<types.RelativeRect>;
+  mobileDeepLink(opts: types.DeepLinkOpts): Promise<void>;
+  openNotifications(): Promise<void>;
+  suspendChromedriverProxy(): void;
+  mobileGetDeviceInfo(): Promise<StringRecord>;
+  mobileType(opts: types.TypingOptions): Promise<boolean>;
+  mobileInstallMultipleApks(opts: types.InstallMultipleApksOptions): Promise<void>;
+  mobileBackgroundApp(opts?: types.BackgroundAppOptions): Promise<void>;
+};
+
+export type UIA2ViewportMixin = UIA2Mixin & {
+  getStatusBarHeight(): Promise<number>;
+  getDevicePixelRatio(): Promise<string>;
+  getViewportScreenshot(): Promise<string>;
+  getViewPortRect(): Promise<types.RelativeRect>;
+};
+
+export type UIA2GesturesMixin = UIA2Mixin & {
+  mobileClickGesture(opts?: types.ClickOptions): Promise<void>;
+  mobileDoubleClickGesture(opts?: types.ClickOptions): Promise<void>;
+  mobileDragGesture(opts: types.DragOptions): Promise<void>;
+  mobileFlingGesture(opts: types.FlingOptions): Promise<boolean>;
+  mobilePinchCloseGesture(opts: types.PinchOptions): Promise<void>;
+  mobilePinchOpenGesture(opts: types.PinchOptions): Promise<void>;
+  mobileSwipeGesture(opts: types.SwipeOptions): Promise<void>;
+  mobileScrollGesture(opts: types.ScrollGestureOptions): Promise<boolean>;
+  mobileScrollBackTo(opts: types.ScrollElementToElementOpts): Promise<void>;
+  mobileScroll(opts: types.ScrollOptions): Promise<void>;
+  mobileLongClickGesture(opts: types.LongClickOptions): Promise<void>;
+};
+
+export type UIA2ScreenshotMixin = UIA2Mixin<Pick<ActionsMixin, 'getScreenshot'>> & {
+  mobileScreenshots(opts: types.ScreenshotsOpts): Promise<StringRecord<types.Screenshot>>;
+};
+
+export type UIA2TouchMixin = UIA2Mixin<
+  // Required needed because ExternalDriver's methods are all optional
+  Required<
+    Pick<ExternalDriver & TouchMixin, 'performActions' | 'releaseActions' | 'doPerformMultiAction'>
+  >
+>;
+
+declare module '../driver' {
+  interface AndroidUiautomator2Driver
+    extends UIA2ActionsMixin,
+      UIA2AlertMixin,
+      UIA2AppStringsMixin,
+      UIA2BatteryMixin,
+      UIA2ElementMixin,
+      UIA2FindMixin,
+      UIA2GeneralMixin,
+      UIA2GesturesMixin,
+      UIA2ScreenshotMixin,
+      UIA2TouchMixin,
+      UIA2ViewportMixin {}
+}
+
+/**
+ * This function assigns a mixin `T` to the `AndroidUiautomator2Driver` class' prototype.
+ *
+ * While each mixin has its own interface which is (in isolation) unrelated to
+ * `AndroidUiautomator2Driver`, the constraint on this generic type `T` is that it must be a
+ * partial of `AndroidUiautomator2Driver`'s interface. This enforces that it does not
+ * conflict with the existing interface of `AndroidUiautomator2Driver`.  In that way, you
+ * can think of it as a type guard.
+ * @param mixin Mixin implementation
+ */
+export function mixin<T extends Partial<AndroidUiautomator2Driver>>(mixin: T): void {
+  Object.assign(AndroidUiautomator2Driver.prototype, mixin);
+}

package/lib/commands/screenshot.js

@@ -1,91 +1,95 @@
+// @ts-check
+
+import {mixin} from './mixins';
 import _ from 'lodash';
 import B from 'bluebird';
 
-const commands = {};
-
 // 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;
 
-commands.getScreenshot = async function () {
-  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.');
-  }
-  return await this.uiautomator2.jwproxy.command('/screenshot', 'GET');
-};
-
-/**
- * @typedef {Object} ScreenshotsInfo
- *
- * A dictionary where each key contains a unique display identifier
- * and values are dictionaries with following items:
- * - id: Display identifier
- * - name: Display name, could be empty
- * - isDefault: Whether this display is the default one
- * - payload: The actual PNG screenshot data encoded to base64 string
- */
-
-/**
- * @typedef {Object} ScreenshotsOpts
- * @property {number|string?} displayId Android display identifier to take a screenshot for.
- * If not provided then screenshots of all displays are going to be returned.
- * If no matches were found then an error is thrown.
- */
-
 /**
- * Retrieves screenshots of each display available to Android.
- * This functionality is only supported since Android 10.
- *
- * @param {ScreenshotsOpts} opts
- * @returns {Promise<ScreenshotsInfo>}
+ * @type {import('./mixins').UIA2ScreenshotMixin}
+ * @satisfies {import('@appium/types').ExternalDriver}
  */
-commands.mobileScreenshots = async function mobileScreenshots (opts = {}) {
-  const displaysInfo = await this.adb.shell(['dumpsys', 'SurfaceFlinger', '--display-id']);
-  const infos = {};
-  let match;
-  while ((match = DISPLAY_PATTERN.exec(displaysInfo))) {
-    infos[match[1]] = {
-      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 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.'
+      );
+    }
+    return String(
+      await /** @type {import('../uiautomator2').UiAutomator2Server} */ (
+        this.uiautomator2
+      ).jwproxy.command('/screenshot', 'GET')
+    );
+  },
 
-  const toB64Screenshot = async (dispId) => (await this.adb.takeScreenshot(dispId))
-    .toString('base64');
+  /**
+   * Retrieves screenshots of each display available to Android.
+   * This functionality is only supported since Android 10.
+   */
+  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 {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)}`
+    /**
+     * @param {string} dispId
+     */
+    const toB64Screenshot = async (dispId) =>
+      (await /** @type {import('appium-adb').ADB} */ (this.adb).takeScreenshot(dispId)).toString(
+        'base64'
       );
-    }
-    return {
-      [displayIdStr]: {
-        ...infos[displayIdStr],
-        payload: await toB64Screenshot(displayIdStr),
+
+    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),
+        },
+      };
+    }
 
-  const allInfos = _.values(infos);
-  const screenshots = await B.all(allInfos.map(({id}) => toB64Screenshot(id)));
-  for (const [info, payload] of _.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;
+  },
 };
 
-export default commands;
+mixin(ScreenshotMixin);

package/lib/commands/touch.js

@@ -1,38 +1,71 @@
-const commands = {};
+// @ts-check
 
-commands.doPerformMultiAction = async function (elementId, states) {
-  let opts;
-  if (elementId) {
-    opts = {
-      elementId,
-      actions: states
-    };
+import {mixin} from './mixins';
 
-    return await this.uiautomator2.jwproxy.command('/touch/multi/perform', 'POST', opts);
-  } else {
-    opts = {
-      actions: states
-    };
-    return await this.uiautomator2.jwproxy.command('/touch/multi/perform', 'POST', opts);
-  }
-};
+/**
+ * @type {import('./mixins').UIA2TouchMixin}
+ * @satisfies {import('@appium/types').ExternalDriver}
+ */
+const TouchMixin = {
+  async doPerformMultiAction(elementId, states) {
+    let opts;
+    if (elementId) {
+      opts = {
+        elementId,
+        actions: states,
+      };
+
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        '/touch/multi/perform',
+        'POST',
+        opts
+      );
+    } else {
+      opts = {
+        actions: states,
+      };
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        '/touch/multi/perform',
+        'POST',
+        opts
+      );
+    }
+  },
 
-commands.performActions = async function (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'
+  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',
+              },
+            }
+          : {}
+      )
+    );
+    this.log.debug(`Preprocessed actions: ${JSON.stringify(preprocessedActions, null, '  ')}`);
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      '/actions',
+      'POST',
+      {
+        actions: preprocessedActions,
       }
-    } : {}));
-  this.log.debug(`Preprocessed actions: ${JSON.stringify(preprocessedActions, null, '  ')}`);
-  return await this.uiautomator2.jwproxy.command('/actions', 'POST', {actions: preprocessedActions});
-};
+    );
+  },
 
-// eslint-disable-next-line require-await
-commands.releaseActions = async function releaseActions () {
-  this.log.info('On this platform, releaseActions is a no-op');
+  // eslint-disable-next-line require-await
+  async releaseActions() {
+    this.log.info('On this platform, releaseActions is a no-op');
+  },
 };
 
-export default commands;
+mixin(TouchMixin);
+
+/**
+ * @typedef {import('../uiautomator2').UiAutomator2Server} UiAutomator2Server
+ */