appium-uiautomator2-driver 2.29.11 → 2.31.0

package/lib/commands/actions.js

@@ -1,110 +1,124 @@
+// @ts-check
 
-
-let commands = {}, helpers = {}, extensions = {};
-
-commands.pressKeyCode = async function (keycode, metastate = null, flags = null) {
-  return await this.uiautomator2.jwproxy.command('/appium/device/press_keycode', 'POST', {
-    keycode,
-    metastate,
-    flags,
-  });
-};
-
-commands.longPressKeyCode = async function (keycode, metastate = null, flags = null) {
-  return await this.uiautomator2.jwproxy.command('/appium/device/long_press_keycode', 'POST', {
-    keycode,
-    metastate,
-    flags
-  });
-};
-
-commands.doSwipe = async function (swipeOpts) {
-  return await this.uiautomator2.jwproxy.command(`/touch/perform`, 'POST', swipeOpts);
-};
-
-commands.doDrag = async function (dragOpts) {
-  return await this.uiautomator2.jwproxy.command(`/touch/drag`, 'POST', dragOpts);
-};
-
-commands.getOrientation = async function () {
-  return await this.uiautomator2.jwproxy.command(`/orientation`, 'GET', {});
-};
-
-commands.setOrientation = async function (orientation) {
-  orientation = orientation.toUpperCase();
-  return await this.uiautomator2.jwproxy.command(`/orientation`, 'POST', {orientation});
-};
-
-/**
- * @typedef {Object} PressKeyOptions
- * @property {number} keycode A valid Android key code. See https://developer.android.com/reference/android/view/KeyEvent
- * for the list of available key codes
- * @property {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.
- * @property {string?} flags Flags for the particular key event. See
- * https://developer.android.com/reference/android/view/KeyEvent for more details.
- * @property {boolean} isLongPress [false] Whether to emulate long key press
-*/
+import {mixin} from './mixins';
 
 /**
- * Emulates single key press of the key with the given code.
- *
- * @param {PressKeyOptions} opts
+ * @type {import('./mixins').UIA2ActionsMixin}
+ * @satisfies {import('@appium/types').ExternalDriver}
  */
-commands.mobilePressKey = async function mobilePressKey(opts = {}) {
-  const {
-    keycode,
-    metastate,
-    flags,
-    isLongPress = false,
-  } = opts;
-
-  return await this.uiautomator2.jwproxy.command(
-    `/appium/device/${isLongPress ? 'long_' : ''}press_keycode`,
-    'POST', {
-      keycode,
-      metastate,
-      flags
-    }
-  );
+const ActionsMixin = {
+  async pressKeyCode(keycode, metastate, flags) {
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      '/appium/device/press_keycode',
+      'POST',
+      {
+        keycode,
+        metastate,
+        flags,
+      }
+    );
+  },
+
+  async longPressKeyCode(keycode, metastate, flags) {
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      '/appium/device/long_press_keycode',
+      'POST',
+      {
+        keycode,
+        metastate,
+        flags,
+      }
+    );
+  },
+
+  async doSwipe(swipeOpts) {
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/touch/perform`,
+      'POST',
+      swipeOpts
+    );
+  },
+
+  async doDrag(dragOpts) {
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/touch/drag`,
+      'POST',
+      dragOpts
+    );
+  },
+
+  async getOrientation() {
+    return /** @type {import('@appium/types').Orientation} */ (
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        `/orientation`,
+        'GET',
+        {}
+      )
+    );
+  },
+
+  async setOrientation(orientation) {
+    orientation = /** @type {import('@appium/types').Orientation} */ (orientation.toUpperCase());
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/orientation`,
+      'POST',
+      {orientation}
+    );
+  },
+
+  async mobilePressKey(opts) {
+    const {keycode, metastate, flags, isLongPress = false} = opts;
+
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      `/appium/device/${isLongPress ? 'long_' : ''}press_keycode`,
+      'POST',
+      {
+        keycode,
+        metastate,
+        flags,
+      }
+    );
+  },
+
+  /**
+   * See https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/scheduled-actions.md#mobile-scheduleaction
+   * @param {Record<string, any>} opts
+   */
+  async mobileScheduleAction(opts = {}) {
+    return await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      '/appium/schedule_action',
+      'POST',
+      opts
+    );
+  },
+
+  /**
+   * @see https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/scheduled-actions.md#mobile-getactionhistory
+   */
+  async mobileGetActionHistory(opts) {
+    return /** @type {import('./types').ActionResult} */ (
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        '/appium/action_history',
+        'POST',
+        opts ?? {}
+      )
+    );
+  },
+
+  /**
+   * @see https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/scheduled-actions.md#mobile-unscheduleaction
+   */
+  async mobileUnscheduleAction(opts) {
+    return await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      '/appium/unschedule_action',
+      'POST',
+      opts ?? {}
+    );
+  },
 };
 
-/**
- * See https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/scheduled-actions.md#mobile-scheduleaction
- * @param {Record<string, any>} opts
- */
-commands.mobileScheduleAction = async function mobileScheduleAction (opts = {}) {
-  return await this.uiautomator2.jwproxy.command('/appium/schedule_action', 'POST', opts);
-};
-
-/**
- * @typedef {Object} ActionResult
- * @property {number} repeats
- * @property {Record<string, any>[][]}
- */
+mixin(ActionsMixin);
 
 /**
- * @typedef {Object} ActionArgs
- * @property {string} name
+ * @typedef {import('../uiautomator2').UiAutomator2Server} UiAutomator2Server
  */
-
-/**
- * See https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/scheduled-actions.md#mobile-getactionhistory
- * @param {ActionArgs} opts
- * @returns {Promise<ActionResult>}
- */
-commands.mobileGetActionHistory = async function mobileGetActionHistory (opts) {
-  return await this.uiautomator2.jwproxy.command('/appium/action_history', 'POST', opts ?? {});
-};
-
-/**
- * See https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/scheduled-actions.md#mobile-unscheduleaction
- * @param {ActionArgs} opts
- */
-commands.mobileUnscheduleAction = async function mobileUnscheduleAction (opts) {
-  return await this.uiautomator2.jwproxy.command('/appium/unschedule_action', 'POST', opts ?? {});
-};
-
-Object.assign(extensions, commands, helpers);
-export { commands, helpers };
-export default extensions;

package/lib/commands/alert.js

@@ -1,53 +1,45 @@
-let commands = {}, helpers = {}, extensions = {};
+// @ts-check
 
-commands.getAlertText = async function () {
-  return await this.uiautomator2.jwproxy.command('/alert/text', 'GET', {});
-};
-
-/**
- * @typedef {Object} AcceptAlertOptions
- * @property {?string} buttonLabel - The name of the button to click in order to
- *                                   accept the alert. If the name is not provided
- *                                   then the script will try to detect the button
- *                                   automatically.
- */
+import {mixin} from './mixins';
 
 /**
- * @param {AcceptAlertOptions} opts
- * @throws {InvalidElementStateError} If no matching button, that can accept the alert,
- *                                    can be found
- * @throws {NoAlertOpenError} If no alert is present
+ * @type {import('./mixins').UIA2AlertMixin}
+ * @satisfies {import('@appium/types').ExternalDriver}
  */
-commands.mobileAcceptAlert = async function (opts = {}) {
-  return await this.uiautomator2.jwproxy.command('/alert/accept', 'POST', opts);
-};
-
-commands.postAcceptAlert = async function () {
-  return await this.mobileAcceptAlert();
+const AlertMixin = {
+  async getAlertText() {
+    return String(
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        '/alert/text',
+        'GET',
+        {}
+      )
+    );
+  },
+  async mobileAcceptAlert(opts = {}) {
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      '/alert/accept',
+      'POST',
+      opts
+    );
+  },
+  async postAcceptAlert() {
+    await this.mobileAcceptAlert();
+  },
+  async mobileDismissAlert(opts = {}) {
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      '/alert/dismiss',
+      'POST',
+      opts
+    );
+  },
+  async postDismissAlert() {
+    await this.mobileDismissAlert();
+  },
 };
 
-/**
- * @typedef {Object} DismissAlertOptions
- * @property {?string} buttonLabel - The name of the button to click in order to
- *                                   dismiss the alert. If the name is not provided
- *                                   then the script will try to detect the button
- *                                   automatically.
- */
+mixin(AlertMixin);
 
 /**
- * @param {DismissAlertOptions} opts
- * @throws {InvalidElementStateError} If no matching button, that can dismiss the alert,
- *                                    can be found
- * @throws {NoAlertOpenError} If no alert is present
+ * @typedef {import('../uiautomator2').UiAutomator2Server} UiAutomator2Server
  */
-commands.mobileDismissAlert = async function (opts = {}) {
-  return await this.uiautomator2.jwproxy.command('/alert/dismiss', 'POST', opts);
-};
-
-commands.postDismissAlert = async function () {
-  return await this.mobileDismissAlert();
-};
-
-Object.assign(extensions, commands, helpers);
-export { commands, helpers };
-export default extensions;

package/lib/commands/app-strings.js

@@ -1,76 +1,97 @@
+// @ts-check
+
+import {mixin} from './mixins';
 import _ from 'lodash';
-import { fs, tempDir } from 'appium/support';
+import {fs, tempDir} from 'appium/support';
 
-const commands = {};
+/**
+ * @type {import('./mixins').UIA2AppStringsMixin}
+ * @satisfies {import('@appium/types').ExternalDriver}
+ */
+const AppStringsMixin = {
+  async getStrings(language) {
+    const adb = /** @type {ADB} */ (this.adb);
+    if (!language) {
+      language = await adb.getDeviceLanguage();
+      this.log.info(`No language specified, returning strings for: ${language}`);
+    }
 
-commands.getStrings = async function (language) {
-  if (!language) {
-    language = await this.adb.getDeviceLanguage();
-    this.log.info(`No language specified, returning strings for: ${language}`);
-  }
+    /**
+     * Clients require the resulting mapping to have both keys
+     * and values of type string
+     * @param {StringRecord} mapping
+     */
+    const preprocessStringsMap = function (mapping) {
+      /** @type {StringRecord} */
+      const result = {};
+      for (const [key, value] of _.toPairs(mapping)) {
+        result[key] = _.isString(value) ? value : JSON.stringify(value);
+      }
+      return result;
+    };
 
-  // Clients require the resulting mapping to have both keys
-  // and values of type string
-  const preprocessStringsMap = function (mapping) {
-    const result = {};
-    for (const [key, value] of _.toPairs(mapping)) {
-      result[key] = _.isString(value) ? value : JSON.stringify(value);
+    if (this.apkStrings[language]) {
+      // Return cached strings
+      return preprocessStringsMap(this.apkStrings[language]);
     }
-    return result;
-  };
 
-  if (this.apkStrings[language]) {
-    // Return cached strings
-    return preprocessStringsMap(this.apkStrings[language]);
-  }
+    if (!this.opts.app && !this.opts.appPackage) {
+      this.log.errorAndThrow("One of 'app' or 'appPackage' capabilities should must be specified");
+      throw new Error(); // unreachable
+    }
+
+    let app = this.opts.app;
+    const tmpRoot = await tempDir.openDir();
+    try {
+      if (!app) {
+        try {
+          app = await adb.pullApk(/** @type {string} */ (this.opts.appPackage), tmpRoot);
+        } catch (err) {
+          this.log.errorAndThrow(
+            `Failed to pull an apk from '${this.opts.appPackage}'. Original error: ${
+              /** @type {Error} */ (err).message
+            }`
+          );
+          throw new Error(); // unreachable
+        }
+      }
 
-  if (!this.opts.app && !this.opts.appPackage) {
-    this.log.errorAndThrow("One of 'app' or 'appPackage' capabilities should must be specified");
-  }
+      if (!(await fs.exists(app))) {
+        this.log.errorAndThrow(`The app at '${app}' does not exist`);
+        throw new Error(); // unreachable
+      }
 
-  let app = this.opts.app;
-  const tmpRoot = await tempDir.openDir();
-  try {
-    if (!app) {
       try {
-        app = await this.adb.pullApk(this.opts.appPackage, tmpRoot);
+        const {apkStrings} = await adb.extractStringsFromApk(app, language, tmpRoot);
+        this.apkStrings[language] = apkStrings;
+        return preprocessStringsMap(apkStrings);
       } catch (err) {
-        this.log.errorAndThrow(`Failed to pull an apk from '${this.opts.appPackage}'. Original error: ${err.message}`);
+        this.log.errorAndThrow(
+          `Cannot extract strings from '${app}'. Original error: ${
+            /** @type {Error} */ (err).message
+          }`
+        );
+        throw new Error(); // unreachable
       }
+    } finally {
+      await fs.rimraf(tmpRoot);
     }
+  },
 
-    if (!await fs.exists(app)) {
-      this.log.errorAndThrow(`The app at '${app}' does not exist`);
-    }
-
-    try {
-      const {apkStrings} = await this.adb.extractStringsFromApk(app, language, tmpRoot);
-      this.apkStrings[language] = apkStrings;
-      return preprocessStringsMap(apkStrings);
-    } catch (err) {
-      this.log.errorAndThrow(`Cannot extract strings from '${app}'. Original error: ${err.message}`);
-    }
-  } finally {
-    await fs.rimraf(tmpRoot);
-  }
+  /**
+   * Retrives app strings from its resources for the given language
+   * or the default device language.
+   *
+   * @returns App strings map
+   */
+  async mobileGetAppStrings(opts) {
+    return await this.getStrings(opts?.language);
+  },
 };
 
-/**
- * @typedef {Object} GetAppStringsOptions
- * @property {string?} language The language abbreviation to fetch app strings mapping for. If no
- * language is provided then strings for the default language on the device under test
- * would be returned. Examples: en, fr
- */
+mixin(AppStringsMixin);
 
 /**
- * Retrives app strings from its resources for the given language
- * or the default device language.
- *
- * @param {GetAppStringsOptions} opts
- * @returns {Promise<object>} App strings map
+ * @typedef {import('appium-adb').ADB} ADB
+ * @typedef {import('@appium/types').StringRecord} StringRecord
  */
-commands.mobileGetAppStrings = async function mobileGetAppStrings (opts = {}) {
-  return await this.getStrings(opts.language);
-};
-
-export default commands;

package/lib/commands/battery.js

@@ -1,34 +1,33 @@
-let extensions = {}, commands = {};
+// @ts-check
 
-/**
- * @typedef {Object} BatteryInfo
- *
- * @property {number} level - Battery level in range [0.0, 1.0], where
- *                            1.0 means 100% charge.
- *                             -1 is returned if the actual value cannot be
- *                            retrieved from the system.
- * @property {number} state - Battery state. The following values are possible:
- *   BATTERY_STATUS_UNKNOWN = 1
- *   BATTERY_STATUS_CHARGING = 2
- *   BATTERY_STATUS_DISCHARGING = 3
- *   BATTERY_STATUS_NOT_CHARGING = 4
- *   BATTERY_STATUS_FULL = 5
- *   -1 is returned if the actual value cannot be retrieved from the system.
- */
+import {mixin} from './mixins';
 
 /**
- * Reads the battery information from the device under test.
- *
- * @returns {BatteryInfo} The actual battery info
+ * @type {import('./mixins').UIA2BatteryMixin}
+ * @satisfies {import('@appium/types').ExternalDriver}
  */
-commands.mobileGetBatteryInfo = async function () {
-  const result = await this.uiautomator2.jwproxy.command('/appium/device/battery_info', 'GET', {});
-  // Give it the same name as in iOS
-  result.state = result.status;
-  delete result.status;
-  return result;
+const BatteryMixin = {
+  /**
+   * Reads the battery information from the device under test.
+   *
+   * @returns The actual battery info
+   */
+  async mobileGetBatteryInfo() {
+    const result = /** @type {import('./types').MapKey<BatteryInfo, 'state', 'status'>} */ (
+      await /** @type {import('../uiautomator2').UiAutomator2Server} */ (
+        this.uiautomator2
+      ).jwproxy.command('/appium/device/battery_info', 'GET', {})
+    );
+    const batteryInfo = /** @type {any} */ (result);
+    // Give it the same name as in iOS
+    batteryInfo.state = result.status;
+    delete batteryInfo.status;
+    return /** @type {BatteryInfo} */ (batteryInfo);
+  },
 };
 
-Object.assign(extensions, commands);
-export { commands };
-export default extensions;
+mixin(BatteryMixin);
+
+/**
+ * @typedef {import('./types').BatteryInfo} BatteryInfo
+ */