appium-uiautomator2-driver 2.29.10 → 2.30.0

package/lib/commands/general.js

@@ -1,356 +1,291 @@
+// @ts-check
+
 import _ from 'lodash';
 import B from 'bluebird';
-import { errors } from 'appium/driver';
-import { APK_EXTENSION } from '../extensions';
-
-let extensions = {},
-    commands = {},
-    helpers = {};
-
-commands.getPageSource = async function () {
-  return await this.uiautomator2.jwproxy.command('/source', 'GET', {});
-};
-
-commands.getClipboard = async function () {
-  return (await this.adb.getApiLevel() < 29)
-    ? (await this.uiautomator2.jwproxy.command('/appium/device/get_clipboard', 'POST', {}))
-    : (await this.adb.getClipboard());
-};
-
-// Need to override this for correct unicode support
-commands.doSendKeys = async function (params) {
-  await this.uiautomator2.jwproxy.command('/keys', 'POST', params);
-};
-
-// uiautomator2 doesn't support metastate for keyevents
-commands.keyevent = async function (keycode, metastate) {
-  this.log.debug(`Ignoring metastate ${metastate}`);
-  await this.adb.keyevent(keycode);
-};
-
-// Use ADB since we don't have UiAutomator
-commands.back = async function () {
-  await this.adb.keyevent(4);
-};
-
-commands.getDisplayDensity = async function getDisplayDensity () {
-  return await this.uiautomator2.jwproxy.command('/appium/device/display_density', 'GET', {});
-};
-
-// memoized in constructor
-commands.getWindowSize = async function () {
-  return await this.uiautomator2.jwproxy.command('/window/current/size', 'GET', {});
-};
-
-// For W3C
-commands.getWindowRect = async function () {
-  const {width, height} = await this.getWindowSize();
-  return {
-    width,
-    height,
-    x: 0,
-    y: 0,
-  };
-};
-
-extensions.executeMobile = async function (mobileCommand, opts = {}) {
-  const mobileCommandsMapping = {
-    shell: 'mobileShell',
-
-    execEmuConsoleCommand: 'mobileExecEmuConsoleCommand',
-
-    dragGesture: 'mobileDragGesture',
-    flingGesture: 'mobileFlingGesture',
-    doubleClickGesture: 'mobileDoubleClickGesture',
-    clickGesture: 'mobileClickGesture',
-    longClickGesture: 'mobileLongClickGesture',
-    pinchCloseGesture: 'mobilePinchCloseGesture',
-    pinchOpenGesture: 'mobilePinchOpenGesture',
-    swipeGesture: 'mobileSwipeGesture',
-    scrollGesture: 'mobileScrollGesture',
-    scrollBackTo: 'mobileScrollBackTo',
-    scroll: 'mobileScroll',
-    viewportScreenshot: 'mobileViewportScreenshot',
-    viewportRect: 'mobileViewPortRect',
-
-    deepLink: 'mobileDeepLink',
-
-    startLogsBroadcast: 'mobileStartLogsBroadcast',
-    stopLogsBroadcast: 'mobileStopLogsBroadcast',
-
-    acceptAlert: 'mobileAcceptAlert',
-    dismissAlert: 'mobileDismissAlert',
-
-    batteryInfo: 'mobileGetBatteryInfo',
-
-    deviceInfo: 'mobileGetDeviceInfo',
-
-    getDeviceTime: 'mobileGetDeviceTime',
-
-    changePermissions: 'mobileChangePermissions',
-    getPermissions: 'mobileGetPermissions',
-
-    performEditorAction: 'mobilePerformEditorAction',
-
-    startScreenStreaming: 'mobileStartScreenStreaming',
-    stopScreenStreaming: 'mobileStopScreenStreaming',
-
-    getNotifications: 'mobileGetNotifications',
-    openNotifications: 'openNotifications',
-
-    listSms: 'mobileListSms',
-
-    type: 'mobileType',
-    replaceElementValue: 'mobileReplaceElementValue',
-
-    pushFile: 'mobilePushFile',
-    pullFile: 'mobilePullFile',
-    pullFolder: 'mobilePullFolder',
-    deleteFile: 'mobileDeleteFile',
-
-    isAppInstalled: 'mobileIsAppInstalled',
-    queryAppState: 'mobileQueryAppState',
-    activateApp: 'mobileActivateApp',
-    removeApp: 'mobileRemoveApp',
-    terminateApp: 'mobileTerminateApp',
-    installApp: 'mobileInstallApp',
-    clearApp: 'mobileClearApp',
-    backgroundApp: 'mobileBackgroundApp',
-    getCurrentActivity: 'getCurrentActivity',
-    getCurrentPackage: 'getCurrentPackage',
-
-    startActivity: 'mobileStartActivity',
-    startService: 'mobileStartService',
-    stopService: 'mobileStopService',
-    broadcast: 'mobileBroadcast',
-
-    getContexts: 'mobileGetContexts',
-
-    getAppStrings: 'mobileGetAppStrings',
-
-    installMultipleApks: 'mobileInstallMultipleApks',
-
-    lock: 'mobileLock',
-    unlock: 'mobileUnlock',
-    isLocked: 'isLocked',
-
-    refreshGpsCache: 'mobileRefreshGpsCache',
-
-    startMediaProjectionRecording: 'mobileStartMediaProjectionRecording',
-    isMediaProjectionRecordingRunning: 'mobileIsMediaProjectionRecordingRunning',
-    stopMediaProjectionRecording: 'mobileStopMediaProjectionRecording',
-
-    getConnectivity: 'mobileGetConnectivity',
-    setConnectivity: 'mobileSetConnectivity',
-    toggleGps: 'toggleLocationServices',
-    isGpsEnables: 'isLocationServicesEnabled',
-
-    hideKeyboard: 'hideKeyboard',
-    isKeyboardShown: 'isKeyboardShown',
-
-    pressKey: 'mobilePressKey',
-
-    getDisplayDensity: 'getDisplayDensity',
-    getSystemBars: 'getSystemBars',
-
-    fingerprint: 'mobileFingerprint',
-    sendSms: 'mobileSendSms',
-    gsmCall: 'mobileGsmCall',
-    gsmSignal: 'mobileGsmSignal',
-    gsmVoice: 'mobileGsmVoice',
-    powerAc: 'mobilePowerAC',
-    powerCapacity: 'mobilePowerCapacity',
-    networkSpeed: 'mobileNetworkSpeed',
-    sensorSet: 'sensorSet',
-
-    getPerformanceData: 'mobileGetPerformanceData',
-    getPerformanceDataTypes: 'getPerformanceDataTypes',
-
-    statusBar: 'mobilePerformStatusBarCommand',
-
-    screenshots: 'mobileScreenshots',
-
-    scheduleAction: 'mobileScheduleAction',
-    getActionHistory: 'mobileGetActionHistory',
-    unscheduleAction: 'mobileUnscheduleAction',
-  };
-
-  if (!_.has(mobileCommandsMapping, mobileCommand)) {
-    throw new errors.UnknownCommandError(`Unknown mobile command "${mobileCommand}". ` +
-      `Only ${_.keys(mobileCommandsMapping)} commands are supported.`);
-  }
-  return await this[mobileCommandsMapping[mobileCommand]](opts);
-};
-
-commands.mobileViewportScreenshot = async function () {
-  return await this.getViewportScreenshot();
-};
-
-/**
- * @typedef {object} Rectangle
- * @property {number} left - The left coordinate of the Rectangle.
- * @property {number} top - The top coordinate of the Rectangle.
- * @property {number} width - The width of Rectangle.
- * @property {number} height - The height of Rectangle.
- */
-
-/**
- * Returns the viewport coordinates.
- * @returns {Rectangle} The viewport coordinates.
- */
-commands.mobileViewPortRect = async function mobileViewPortRect () {
-  return await this.getViewPortRect();
-};
-
-commands.setUrl = async function (url) {
-  await this.adb.startUri(url, this.opts.appPackage);
-};
-
-/**
- * @typedef {object} DeepLinkOpts
- * @property {!string} url - The name of URL to start.
- * @property {!string} package - The name of the package to start the URI with.
- * @property {?boolean} waitForLaunch [true] - if `false` then adb won't wait
- * for the started activity to return the control
- */
-
-/**
- * Start URL that take users directly to specific content in the app
- * @param {DeepLinkOpts} opts
- */
-commands.mobileDeepLink = async function (opts = {}) {
-  const {
-    url,
-    package: pkg,
-    waitForLaunch,
-  } = opts;
-  return await this.adb.startUri(url, pkg, { waitForLaunch });
-};
-
-commands.openNotifications = async function () {
-  return await this.uiautomator2.jwproxy.command('/appium/device/open_notifications', 'POST', {});
-};
-
-commands.updateSettings = async function (settings) {
-  await this.settings.update(settings);
-  await this.uiautomator2.jwproxy.command('/appium/settings', 'POST', {settings});
-};
-
-commands.getSettings = async function () {
-  const driverSettings = this.settings.getSettings();
-  const serverSettings = await this.uiautomator2.jwproxy.command('/appium/settings', 'GET');
-  return {...driverSettings, ...serverSettings};
-};
+import {errors, PROTOCOLS} from 'appium/driver';
+import {APK_EXTENSION} from '../extensions';
+import {mixin} from './mixins';
+import {AndroidUiautomator2Driver} from '../driver';
 
 /**
- * Overriding appium-android-driver's wrapBootstrapDisconnect,
- * unlike in appium-android-driver avoiding adb restarting as it intern
- * kills UiAutomator2 server running in the device.
- **/
-helpers.wrapBootstrapDisconnect = async function (wrapped) {
-  await wrapped();
-};
-
-// Stop proxying to any Chromedriver and redirect to uiautomator2
-helpers.suspendChromedriverProxy = function () {
-  this.chromedriver = null;
-  this.proxyReqRes = this.uiautomator2.proxyReqRes.bind(this.uiautomator2);
-  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
- */
-commands.mobileGetDeviceInfo = async function () {
-  return await this.uiautomator2.jwproxy.command('/appium/device/info', 'GET');
-};
-
-/**
- * @typedef {Object} TypingOptions
- * @property {!string|number|boolean} text - The text to type
+ * Massages the arguments going into an execute method.
+ * @remarks A similar method is implemented in `appium-xcuitest-driver`, but it
+ * appears the methods in here handle unwrapping of `Element` objects, so we do
+ * not do that here.
+ * @param {readonly any[] | readonly [StringRecord] | Readonly<StringRecord>} [args]
+ * @internal
+ * @returns {StringRecord<unknown>}
  */
-
-/**
- * Types the given Unicode string.
- * It is expected that the focus is already put
- * to the destination input field before this method is called.
- *
- * @param {TypingOptions} opts
- * @returns {boolean} `true` if the input text has been successfully sent to adb
- * @throws {Error} if `text` property has not been provided
- */
-commands.mobileType = async function mobileType (opts = {}) {
-  const {
-    text,
-  } = opts;
-  if (_.isUndefined(text)) {
-    this.log.errorAndThrow(`The 'text' argument is mandatory`);
+function preprocessExecuteMethodArgs(args) {
+  if (_.isArray(args)) {
+    args = _.first(args);
+  }
+  const executeMethodArgs = /** @type {StringRecord<unknown>} */ (args ?? {});
+  /**
+   * Renames the deprecated `element` key to `elementId`.  Historically,
+   * all of the pre-Execute-Method-Map execute methods accepted an `element` _or_ and `elementId` param.
+   * This assigns the `element` value to `elementId` if `elementId` is not already present.
+   */
+  if (!('elementId' in executeMethodArgs) && 'element' in executeMethodArgs) {
+    executeMethodArgs.elementId = executeMethodArgs.element;
+    delete executeMethodArgs.element;
   }
-  return await this.adb.typeUnicode(text);
-};
-
 
-/**
- * @typedef {Object} InstallOptions
- * @property {boolean} allowTestPackages [false] - Set to true in order to allow test
- *                                                 packages installation.
- * @property {boolean} useSdcard [false] - Set to true to install the app on sdcard
- *                                         instead of the device memory.
- * @property {boolean} grantPermissions [false] - Set to true in order to grant all the
- *                                                permissions requested in the application's manifest
- *                                                automatically after the installation is completed
- *                                                under Android 6+.
- * @property {boolean} replace [true] - Set it to false if you don't want
- *                                      the application to be upgraded/reinstalled
- *                                      if it is already present on the device.
- * @property {boolean} partialInstall [false] - Install apks partially. It is used for 'install-multiple'.
- *                                             https://android.stackexchange.com/questions/111064/what-is-a-partial-application-install-via-adb
- */
+  return executeMethodArgs;
+}
 
 /**
- * @typedef {Object} InstallMultipleApksOptions
- * @property {Array<string>} apks - The list of APKs to install. Each APK should be a path to a apk
- *                                  or downloadable URL as HTTP/HTTPS.
- * @property {InstallOptions} options
+ * Type guard to check if a script is an execute method.
+ * @param {any} script
+ * @internal
+ * @returns {script is keyof import('../execute-method-map').Uiautomator2ExecuteMethodMap}
  */
+function isExecuteMethod(script) {
+  return script in AndroidUiautomator2Driver.executeMethodMap;
+}
 
 /**
- * Install multiple APKs with `install-multiple` option.
- *
- * @param {InstallMultipleApksOptions} opts
- * @throws {Error} if an error occured while installing the given APKs.
+ * @type {import('./mixins').UIA2GeneralMixin}
+ * @satisfies {import('@appium/types').ExternalDriver}
  */
-commands.mobileInstallMultipleApks = async function (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);
+const GeneralMixin = {
+  async getPageSource() {
+    return String(
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        '/source',
+        'GET',
+        {}
+      )
+    );
+  },
+
+  async getClipboard() {
+    const adb = /** @type {ADB} */ (this.adb);
+    return String(
+      (await adb.getApiLevel()) < 29
+        ? await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+            '/appium/device/get_clipboard',
+            'POST',
+            {}
+          )
+        : await adb.getClipboard()
+    );
+  },
+
+  async doSendKeys(params) {
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      '/keys',
+      'POST',
+      params
+    );
+  },
+
+  async keyevent(keycode, metastate) {
+    this.log.debug(`Ignoring metastate ${metastate}`);
+    await /** @type {ADB} */ (this.adb).keyevent(keycode);
+  },
+
+  async back() {
+    await /** @type {ADB} */ (this.adb).keyevent(4);
+  },
+
+  async getDisplayDensity() {
+    return /** @type {number} */ (
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        '/appium/device/display_density',
+        'GET',
+        {}
+      )
+    );
+  },
+
+  async getWindowSize() {
+    return /** @type {import('@appium/types').Size} */ (
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        '/window/current/size',
+        'GET',
+        {}
+      )
+    );
+  },
+
+  // For W3C
+  async getWindowRect() {
+    const {width, height} = await this.getWindowSize();
+    return {
+      width,
+      height,
+      x: 0,
+      y: 0,
+    };
+  },
+
+  /**
+   * @override
+   * @privateRemarks Because the "mobile" commands (execute methods) in this
+   * driver universally accept an options object, this method will _not_ call
+   * into `BaseDriver.executeMethod`.
+   */
+  async execute(script, args) {
+    if (isExecuteMethod(script)) {
+      const executeMethodArgs = preprocessExecuteMethodArgs(args);
+      this.log.info(`Executing native command '${script}'`);
+      return await this.executeMobile(script, executeMethodArgs);
+    }
+    if (!this.isWebContext()) {
+      throw new errors.NotImplementedError();
+    }
+    const endpoint =
+      /** @type {import('appium-chromedriver').Chromedriver} */ (this.chromedriver).jwproxy
+        .downstreamProtocol === PROTOCOLS.MJSONWP
+        ? '/execute'
+        : '/execute/sync';
+    return await /** @type {import('appium-chromedriver').Chromedriver} */ (
+      this.chromedriver
+    ).jwproxy.command(endpoint, 'POST', {
+      script,
+      args,
+    });
+  },
+
+  /**
+   * @param script Must be of the form `mobile: <something>`, which differs from its parent class implementation.
+   * @override
+   */
+  async executeMobile(script, opts = {}) {
+    if (!isExecuteMethod(script)) {
+      const commandNames = _.map(_.keys(AndroidUiautomator2Driver.executeMethodMap), (value) =>
+        value.slice(8)
+      );
+      throw new errors.UnknownCommandError(
+        `Unknown mobile command "${script}". ` +
+          `Only ${commandNames.join(', ')} commands are supported.`
+      );
+    }
+    const methodName =
+      AndroidUiautomator2Driver.executeMethodMap[
+        /** @type {keyof import('../execute-method-map').Uiautomator2ExecuteMethodMap} */ (script)
+      ].command;
+
+    return await /** @type {(opts?: any) => Promise<unknown>} */ (this[methodName])(opts);
+  },
+
+  async mobileViewportScreenshot() {
+    return await this.getViewportScreenshot();
+  },
+
+  /**
+   * Returns the viewport coordinates.
+   * @returns The viewport coordinates.
+   */
+  async mobileViewPortRect() {
+    return await this.getViewPortRect();
+  },
+
+  async setUrl(url) {
+    await /** @type {ADB} */ (this.adb).startUri(url, /** @type {string} */ (this.opts.appPackage));
+  },
+
+  /**
+   * Start URL that take users directly to specific content in the app
+   */
+  async mobileDeepLink(opts) {
+    const {url, package: pkg, waitForLaunch} = opts;
+    return await /** @type {ADB} */ (this.adb).startUri(url, pkg, {waitForLaunch});
+  },
+
+  async openNotifications() {
+    await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+      '/appium/device/open_notifications',
+      'POST',
+      {}
+    );
+  },
+
+  /**
+   * Overriding appium-android-driver's wrapBootstrapDisconnect,
+   * unlike in appium-android-driver avoiding adb restarting as it intern
+   * kills UiAutomator2 server running in the device.
+   **/
+  async wrapBootstrapDisconnect(wrapped) {
+    await wrapped();
+  },
+
+  // Stop proxying to any Chromedriver and redirect to uiautomator2
+  suspendChromedriverProxy() {
+    this.chromedriver = undefined;
+    this.proxyReqRes = /** @type {UiAutomator2Server} */ (this.uiautomator2).proxyReqRes.bind(
+      this.uiautomator2
+    );
+    this.proxyCommand = /** @type {typeof this.proxyCommand} */ (
+      /** @type {UiAutomator2Server} */ (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
+   */
+  async mobileGetDeviceInfo() {
+    return /** @type {StringRecord} */ (
+      await /** @type {UiAutomator2Server} */ (this.uiautomator2).jwproxy.command(
+        '/appium/device/info',
+        'GET'
+      )
+    );
+  },
+
+  /**
+   * Types the given Unicode string.
+   * It is expected that the focus is already put
+   * to the destination input field before this method is called.
+   *
+   * @returns `true` if the input text has been successfully sent to adb
+   * @throws {Error} if `text` property has not been provided
+   */
+  async mobileType(opts) {
+    const {text} = opts;
+    if (_.isUndefined(text)) {
+      this.log.errorAndThrow(`The 'text' argument is mandatory`);
+      throw new Error(); // unreachable
+    }
+    return await /** @type {ADB} */ (this.adb).typeUnicode(String(text));
+  },
+
+  /**
+   * Install multiple APKs with `install-multiple` option.
+   *
+   * @throws {Error} if an error occured while installing the given APKs.
+   */
+  async 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 /** @type {ADB} */ (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.
+   */
+  async mobileBackgroundApp(opts = {}) {
+    const {seconds = -1} = opts;
+    await this.background(seconds);
+  },
 };
 
+mixin(GeneralMixin);
+
 /**
- * @typedef {Object} BackgroundAppOptions
- * @property {number} seconds The amount of seconds to wait between
- * putting the app to background and restoring it. Any negative value
- * means to not restore the app after putting it to background.
+ * @typedef {import('../uiautomator2').UiAutomator2Server} UiAutomator2Server
+ * @typedef {import('appium-adb').ADB} ADB
  */
 
 /**
- * Puts the app to background and waits the given number of seconds Then restores the app
- * if necessary. The call is blocking.
- *
- * @param {BackgroundAppOptions} opts
+ * @template [T=any]
+ * @typedef {import('@appium/types').StringRecord<T>} StringRecord
  */
-commands.mobileBackgroundApp = async function mobileBackgroundApp (opts = {}) {
-  const {
-    seconds = -1,
-  } = opts;
-  return await this.background(seconds);
-};
-
-Object.assign(extensions, commands, helpers);
-
-export default extensions;