appium-uiautomator2-driver 2.42.2 → 2.43.1

package/lib/commands/actions.js

@@ -1,124 +1,47 @@
-// @ts-check
-
-import {mixin} from './mixins';
-
 /**
- * @type {import('./mixins').UIA2ActionsMixin}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * See https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/scheduled-actions.md#mobile-scheduleaction
+ * @this {AndroidUiautomator2Driver}
+ * @param {Record<string, any>} [opts={}]
+ * @returns {Promise<any>}
  */
-const ActionsMixin = {
-  async pressKeyCode(keycode, metastate, flags) {
-    await this.uiautomator2.jwproxy.command(
-      '/appium/device/press_keycode',
-      'POST',
-      {
-        keycode,
-        metastate,
-        flags,
-      }
-    );
-  },
-
-  async longPressKeyCode(keycode, metastate, flags) {
-    await this.uiautomator2.jwproxy.command(
-      '/appium/device/long_press_keycode',
-      'POST',
-      {
-        keycode,
-        metastate,
-        flags,
-      }
-    );
-  },
-
-  async doSwipe(swipeOpts) {
-    await this.uiautomator2.jwproxy.command(
-      `/touch/perform`,
-      'POST',
-      swipeOpts
-    );
-  },
-
-  async doDrag(dragOpts) {
-    await this.uiautomator2.jwproxy.command(
-      `/touch/drag`,
-      'POST',
-      dragOpts
-    );
-  },
-
-  async getOrientation() {
-    return /** @type {import('@appium/types').Orientation} */ (
-      await this.uiautomator2.jwproxy.command(
-        `/orientation`,
-        'GET',
-        {}
-      )
-    );
-  },
-
-  async setOrientation(orientation) {
-    orientation = /** @type {import('@appium/types').Orientation} */ (orientation.toUpperCase());
-    await this.uiautomator2.jwproxy.command(
-      `/orientation`,
-      'POST',
-      {orientation}
-    );
-  },
-
-  async mobilePressKey(opts) {
-    const {keycode, metastate, flags, isLongPress = false} = opts;
+export async function mobileScheduleAction(opts = {}) {
+  return await 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
+ * @this {AndroidUiautomator2Driver}
+ * @param {import('./types').ActionArgs} [opts={}]
+ * @returns {Promise<import('./types').ActionResult>}
+ */
+export async function mobileGetActionHistory(opts) {
+  return /** @type {import('./types').ActionResult} */ (
     await 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 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 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 this.uiautomator2.jwproxy.command(
-      '/appium/unschedule_action',
+      '/appium/action_history',
       'POST',
       opts ?? {}
-    );
-  },
-};
+    )
+  );
+}
 
-mixin(ActionsMixin);
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @see https://github.com/appium/appium-uiautomator2-driver/blob/master/docs/scheduled-actions.md#mobile-unscheduleaction
+ * @param {import('./types').ActionArgs} [opts={}]
+ * @returns {Promise<any>}
+ */
+export async function mobileUnscheduleAction(opts) {
+  return await this.uiautomator2.jwproxy.command(
+    '/appium/unschedule_action',
+    'POST',
+    opts ?? {}
+  );
+}
 
 /**
- * @typedef {import('../uiautomator2').UiAutomator2Server} UiAutomator2Server
+ * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
  */

package/lib/commands/alert.js

@@ -1,45 +1,59 @@
-// @ts-check
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @returns {Promise<string>}
+ */
+export async function getAlertText() {
+  return String(
+    await this.uiautomator2.jwproxy.command(
+      '/alert/text',
+      'GET',
+      {}
+    )
+  );
+}
 
-import {mixin} from './mixins';
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {import('./types').AcceptAlertOptions} [opts={}]
+ * @returns {Promise<void>}
+ */
+export async function mobileAcceptAlert(opts = {}) {
+  await this.uiautomator2.jwproxy.command(
+    '/alert/accept',
+    'POST',
+    opts
+  );
+}
 
 /**
- * @type {import('./mixins').UIA2AlertMixin}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * @this {AndroidUiautomator2Driver}
+ * @returns {Promise<void>}
  */
-const AlertMixin = {
-  async getAlertText() {
-    return String(
-      await this.uiautomator2.jwproxy.command(
-        '/alert/text',
-        'GET',
-        {}
-      )
-    );
-  },
-  async mobileAcceptAlert(opts = {}) {
-    await this.uiautomator2.jwproxy.command(
-      '/alert/accept',
-      'POST',
-      opts
-    );
-  },
-  async postAcceptAlert() {
-    await this.mobileAcceptAlert();
-  },
-  async mobileDismissAlert(opts = {}) {
-    await this.uiautomator2.jwproxy.command(
-      '/alert/dismiss',
-      'POST',
-      opts
-    );
-  },
-  async postDismissAlert() {
-    await this.mobileDismissAlert();
-  },
-};
+export async function postAcceptAlert() {
+  await this.mobileAcceptAlert();
+}
+
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @param {import('./types').DismissAlertOptions} [opts={}]
+ * @returns {Promise<void>}
+ */
+export async function mobileDismissAlert(opts = {}) {
+  await this.uiautomator2.jwproxy.command(
+    '/alert/dismiss',
+    'POST',
+    opts
+  );
+}
 
-mixin(AlertMixin);
+/**
+ * @this {AndroidUiautomator2Driver}
+ * @returns {Promise<void>}
+ */
+export async function postDismissAlert() {
+  await this.mobileDismissAlert();
+}
 
 /**
- * @typedef {import('../uiautomator2').UiAutomator2Server} UiAutomator2Server
+ * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
  */

package/lib/commands/app-management.js

@@ -0,0 +1,42 @@
+import _ from 'lodash';
+import B from 'bluebird';
+import {errors} from 'appium/driver';
+import {APK_EXTENSION} from '../extensions';
+
+/**
+ * Install multiple APKs with `install-multiple` option.
+ * @this {AndroidUiautomator2Driver}=
+ * @param {import('./types').InstallMultipleApksOptions} opts
+ * @throws {Error} if an error occured while installing the given APKs.
+ * @returns {Promise<void>}
+ */
+export async function mobileInstallMultipleApks(opts) {
+  if (!_.isArray(opts.apks) || _.isEmpty(opts.apks)) {
+    throw new errors.InvalidArgumentError('No apks are given to install');
+  }
+  const apks = await B.all(
+    opts.apks.map((app) => this.helpers.configureApp(app, [APK_EXTENSION]))
+  );
+  await this.adb.installMultipleApks(apks, opts.options);
+}
+
+/**
+ * Puts the app to background and waits the given number of seconds Then restores the app
+ * if necessary. The call is blocking.
+ * @this {AndroidUiautomator2Driver}=
+ * @param {import('./types').BackgroundAppOptions} [opts={}]
+ * @returns {Promise<void>}
+ */
+export async function mobileBackgroundApp(opts = {}) {
+  const {seconds = -1} = opts;
+  await this.background(seconds);
+}
+
+/**
+ * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
+ */
+
+/**
+ * @template [T=any]
+ * @typedef {import('@appium/types').StringRecord<T>} StringRecord
+ */

package/lib/commands/app-strings.js

@@ -1,96 +1,16 @@
-// @ts-check
-
-import {mixin} from './mixins';
-import _ from 'lodash';
-import {fs, tempDir} from 'appium/support';
-
 /**
- * @type {import('./mixins').UIA2AppStringsMixin}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * Retrives app strings from its resources for the given language
+ * or the default device language.
+ * @this {AndroidUiautomator2Driver}
+ * @param {import('./types').GetAppStringsOptions} [opts={}]
+ * @returns {Promise<StringRecord>}
  */
-const AppStringsMixin = {
-  async getStrings(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;
-    };
-
-    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 this.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 (!(await fs.exists(app))) {
-        this.log.errorAndThrow(`The app at '${app}' does not exist`);
-        throw new Error(); // unreachable
-      }
-
-      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: ${
-            /** @type {Error} */ (err).message
-          }`
-        );
-        throw new Error(); // unreachable
-      }
-    } 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);
-  },
-};
-
-mixin(AppStringsMixin);
+export async function mobileGetAppStrings(opts) {
+  return await this.getStrings(opts?.language);
+}
 
 /**
  * @typedef {import('appium-adb').ADB} ADB
  * @typedef {import('@appium/types').StringRecord} StringRecord
+ * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
  */

package/lib/commands/battery.js

@@ -1,33 +1,23 @@
-// @ts-check
-
-import {mixin} from './mixins';
 
 /**
- * @type {import('./mixins').UIA2BatteryMixin}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * Reads the battery information from the device under test.
+ * @this {AndroidUiautomator2Driver}
+ * @returns {Promise<import('./types').BatteryInfo>} The actual battery info
  */
-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);
-  },
-};
-
-mixin(BatteryMixin);
+export async function 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);
+}
 
 /**
  * @typedef {import('./types').BatteryInfo} BatteryInfo
+ * @typedef {import('../driver').AndroidUiautomator2Driver} AndroidUiautomator2Driver
  */