appium-android-driver 5.14.7 → 6.0.0

package/lib/commands/element.js

@@ -1,168 +1,212 @@
-import androidHelpers from '../android-helpers';
-import { retryInterval } from 'asyncbox';
-import { util } from '@appium/support';
+// @ts-check
 
-
-let commands = {}, helpers = {}, extensions = {};
-
-commands.getAttribute = async function getAttribute (attribute, elementId) {
-  let p = {attribute, elementId};
-  return await this.bootstrap.sendAction('element:getAttribute', p);
-};
-
-commands.getName = async function getName (elementId) {
-  return await this.getAttribute('className', elementId);
-};
-
-commands.elementDisplayed = async function elementDisplayed (elementId) {
-  return await this.getAttribute('displayed', elementId) === 'true';
-};
-
-commands.elementEnabled = async function elementEnabled (elementId) {
-  return await this.getAttribute('enabled', elementId) === 'true';
-};
-
-commands.elementSelected = async function elementSelected (elementId) {
-  return await this.getAttribute('selected', elementId) === 'true';
-};
-
-helpers.setElementValue = async function setElementValue (keys, elementId, replace = false) {
-  let text = keys;
-  if (keys instanceof Array) {
-    text = keys.join('');
-  }
-
-  let params = {
-    elementId,
-    text,
-    replace,
-    unicodeKeyboard: this.opts.unicodeKeyboard
-  };
-
-  return await this.doSetElementValue(params);
-};
+import {AndroidHelpers as androidHelpers} from '../helpers';
+import {mixin} from './mixins';
+import {retryInterval} from 'asyncbox';
+import {util} from '@appium/support';
 
 /**
- * Reason for isolating doSetElementValue from setElementValue is for reusing setElementValue
- * across android-drivers (like appium-uiautomator2-driver) and to avoid code duplication.
- * Other android-drivers (like appium-uiautomator2-driver) need to override doSetElementValue
- * to facilitate setElementValue.
+ * @type {import('./mixins').ElementMixin & ThisType<import('../driver').AndroidDriver>}
+ * @satisfies {import('@appium/types').ExternalDriver}
  */
-helpers.doSetElementValue = async function doSetElementValue (params) {
-  return await this.bootstrap.sendAction('element:setText', params);
-};
-
-commands.setValue = async function setValue (keys, elementId) {
-  return await this.setElementValue(keys, elementId, false);
-};
-
-commands.replaceValue = async function replaceValue (keys, elementId) {
-  return await this.setElementValue(keys, elementId, true);
-};
-
-commands.setValueImmediate = async function setValueImmediate (keys, elementId) {
-  let text = keys;
-  if (keys instanceof Array) {
-    text = keys.join('');
-  }
-
-  // first, make sure we are focused on the element
-  await this.click(elementId);
-
-  // then send through adb
-  await this.adb.inputText(text);
-};
-
-commands.getText = async function getText (elementId) {
-  return await this.bootstrap.sendAction('element:getText', {elementId});
-};
-
-commands.clear = async function clear (elementId) {
-  let text = (await this.getText(elementId)) || '';
-  let length = text.length;
-  if (length === 0) {
-    // if length is zero there are two possibilities:
-    //   1. there is nothing in the text field
-    //   2. it is a password field
-    // since there is little overhead to the adb call, delete 100 elements
-    // if we get zero, just in case it is #2
-    length = 100;
-  }
-  await this.click(elementId);
-  this.log.debug(`Sending up to ${length} clear characters to device`);
-  return await retryInterval(5, 500, async () => {
-    let remainingLength = length;
-    while (remainingLength > 0) {
-      let lengthToSend = remainingLength < 50 ? remainingLength : 50;
-      this.log.debug(`Sending ${lengthToSend} clear characters to device`);
-      await this.adb.clearTextField(lengthToSend);
-      remainingLength -= lengthToSend;
+const ElementMixin = {
+  async getAttribute(attribute, elementId) {
+    let p = {attribute, elementId};
+    return await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction(
+      'element:getAttribute',
+      p
+    );
+  },
+
+  async getName(elementId) {
+    return await this.getAttribute('className', elementId);
+  },
+
+  async elementDisplayed(elementId) {
+    return (await this.getAttribute('displayed', elementId)) === 'true';
+  },
+
+  async elementEnabled(elementId) {
+    return (await this.getAttribute('enabled', elementId)) === 'true';
+  },
+
+  async elementSelected(elementId) {
+    return (await this.getAttribute('selected', elementId)) === 'true';
+  },
+
+  async setElementValue(keys, elementId, replace = false) {
+    let text = keys;
+    if (keys instanceof Array) {
+      text = keys.join('');
     }
-  });
-};
-
-commands.click = async function click (elementId) {
-  return await this.bootstrap.sendAction('element:click', {elementId});
-};
-
-commands.getLocation = async function getLocation (elementId) {
-  return await this.bootstrap.sendAction('element:getLocation', {elementId});
-};
-
-commands.getLocationInView = async function getLocationInView (elementId) {
-  return await this.getLocation(elementId);
-};
-
-commands.getSize = async function getSize (elementId) {
-  return await this.bootstrap.sendAction('element:getSize', {elementId});
-};
-
-commands.getElementRect = async function getElementRect (elementId) {
-  return await this.bootstrap.sendAction('element:getRect', {elementId});
-};
-
-commands.touchLongClick = async function touchLongClick (elementId, x, y, duration) {
-  let params = {elementId, x, y, duration};
-  androidHelpers.removeNullProperties(params);
-  return await this.bootstrap.sendAction('element:touchLongClick', params);
-};
-
-commands.touchDown = async function touchDown (elementId, x, y) {
-  let params = {elementId, x, y};
-  androidHelpers.removeNullProperties(params);
-  return await this.bootstrap.sendAction('element:touchDown', params);
-};
 
-commands.touchUp = async function touchUp (elementId, x, y) {
-  let params = {elementId, x, y};
-  androidHelpers.removeNullProperties(params);
-  return await this.bootstrap.sendAction('element:touchUp', params);
-};
+    let params = {
+      elementId,
+      text: String(text),
+      replace,
+      unicodeKeyboard: this.opts.unicodeKeyboard,
+    };
+
+    return await this.doSetElementValue(params);
+  },
+
+  /**
+   * Reason for isolating doSetElementValue from setElementValue is for reusing setElementValue
+   * across android-drivers (like appium-uiautomator2-driver) and to avoid code duplication.
+   * Other android-drivers (like appium-uiautomator2-driver) need to override doSetElementValue
+   * to facilitate setElementValue.
+   */
+  async doSetElementValue(params) {
+    return await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction(
+      'element:setText',
+      params
+    );
+  },
+
+  async setValue(keys, elementId) {
+    return await this.setElementValue(keys, elementId, false);
+  },
+
+  async replaceValue(keys, elementId) {
+    return await this.setElementValue(keys, elementId, true);
+  },
+
+  async setValueImmediate(keys, elementId) {
+    let text = keys;
+    if (keys instanceof Array) {
+      text = keys.join('');
+    }
 
-commands.touchMove = async function touchMove (elementId, x, y) {
-  let params = {elementId, x, y};
-  androidHelpers.removeNullProperties(params);
-  return await this.bootstrap.sendAction('element:touchMove', params);
+    // first, make sure we are focused on the element
+    await this.click(elementId);
+
+    // then send through adb
+    await /** @type {ADB} */ (this.adb).inputText(/** @type {string} */ (text));
+  },
+
+  async getText(elementId) {
+    return await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction('element:getText', {
+      elementId,
+    });
+  },
+
+  async clear(elementId) {
+    let text = (await this.getText(elementId)) || '';
+    let length = text.length;
+    if (length === 0) {
+      // if length is zero there are two possibilities:
+      //   1. there is nothing in the text field
+      //   2. it is a password field
+      // since there is little overhead to the adb call, delete 100 elements
+      // if we get zero, just in case it is #2
+      length = 100;
+    }
+    await this.click(elementId);
+    this.log.debug(`Sending up to ${length} clear characters to device`);
+    await retryInterval(5, 500, async () => {
+      let remainingLength = length;
+      while (remainingLength > 0) {
+        let lengthToSend = remainingLength < 50 ? remainingLength : 50;
+        this.log.debug(`Sending ${lengthToSend} clear characters to device`);
+        await /** @type {ADB} */ (this.adb).clearTextField(lengthToSend);
+        remainingLength -= lengthToSend;
+      }
+    });
+  },
+
+  async click(elementId) {
+    return await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction('element:click', {
+      elementId,
+    });
+  },
+
+  async getLocation(elementId) {
+    return await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction(
+      'element:getLocation',
+      {elementId}
+    );
+  },
+
+  async getLocationInView(elementId) {
+    return await this.getLocation(elementId);
+  },
+
+  async getSize(elementId) {
+    return await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction('element:getSize', {
+      elementId,
+    });
+  },
+
+  async getElementRect(elementId) {
+    return await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction('element:getRect', {
+      elementId,
+    });
+  },
+
+  async touchLongClick(elementId, x, y, duration) {
+    let params = {elementId, x, y, duration};
+    androidHelpers.removeNullProperties(params);
+    return await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction(
+      'element:touchLongClick',
+      params
+    );
+  },
+
+  async touchDown(elementId, x, y) {
+    let params = {elementId, x, y};
+    androidHelpers.removeNullProperties(params);
+    return await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction(
+      'element:touchDown',
+      params
+    );
+  },
+
+  async touchUp(elementId, x, y) {
+    let params = {elementId, x, y};
+    androidHelpers.removeNullProperties(params);
+    return await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction(
+      'element:touchUp',
+      params
+    );
+  },
+
+  async touchMove(elementId, x, y) {
+    let params = {elementId, x, y};
+    androidHelpers.removeNullProperties(params);
+    return await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction(
+      'element:touchMove',
+      params
+    );
+  },
+
+  async complexTap(tapCount, touchCount, duration, x, y) {
+    return await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction('click', {x, y});
+  },
+
+  async tap(elementId = null, x = null, y = null, count = 1) {
+    if (!util.hasValue(elementId) && !util.hasValue(x) && !util.hasValue(y)) {
+      throw new Error(`Either element to tap or both absolute coordinates should be defined`);
+    }
+    for (let i = 0; i < count; i++) {
+      if (util.hasValue(elementId)) {
+        // FIXME: bootstrap ignores relative coordinates
+        await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction('element:click', {
+          elementId,
+          x,
+          y,
+        });
+      } else {
+        await /** @type {AndroidBootstrap} */ (this.bootstrap).sendAction('click', {x, y});
+      }
+    }
+  },
 };
 
-commands.complexTap = async function complexTap (tapCount, touchCount, duration, x, y) {
-  return await this.bootstrap.sendAction('click', {x, y});
-};
+mixin(ElementMixin);
 
-commands.tap = async function (elementId = null, x = null, y = null, count = 1) {
-  if (!util.hasValue(elementId) && !util.hasValue(x) && !util.hasValue(y)) {
-    throw new Error(`Either element to tap or both absolute coordinates should be defined`);
-  }
-  for (let i = 0; i < count; i++) {
-    if (util.hasValue(elementId)) {
-      // FIXME: bootstrap ignores relative coordinates
-      await this.bootstrap.sendAction('element:click', {elementId, x, y});
-    } else {
-      await this.bootstrap.sendAction('click', {x, y});
-    }
-  }
-};
+export default ElementMixin;
 
-Object.assign(extensions, commands, helpers);
-export { commands, helpers };
-export default extensions;
+/**
+ * @typedef {import('../bootstrap').AndroidBootstrap} AndroidBootstrap
+ * @typedef {import('appium-adb').ADB} ADB
+ */

package/lib/commands/emu-console.js

@@ -1,51 +1,31 @@
-import { errors } from 'appium/driver';
+// @ts-check
 
-const EMU_CONSOLE_FEATURE = 'emulator_console';
-
-const commands = {};
-
-/**
- * @typedef {Object} ExecOptions
- * @property {!Array<string>|string} command - The actual command to execute. See
- * https://developer.android.com/studio/run/emulator-console for more details
- * on available commands
- * @property {number} execTimeout [60000] A timeout used to wait for a server
- * reply to the given command in milliseconds
- * @property {number} connTimeout [5000] Console connection timeout in milliseconds
- * @property {number} initTimeout [5000] Telnet console initialization timeout
- * in milliseconds (the time between the connection happens and the command prompt
- * is available)
- */
+import {mixin} from './mixins';
+import {errors} from 'appium/driver';
 
+const EMU_CONSOLE_FEATURE = 'emulator_console';
 /**
- * Executes a command through emulator telnet console interface and returns its output.
- * The `emulator_console` server feature must be enabled in order to use this method.
- *
- * @param {ExecOptions} opts
- * @returns {string} The command output
- * @throws {Error} If there was an error while connecting to the Telnet console
- * or if the given command returned non-OK response
+ * @type {import('./mixins').EmulatorConsoleMixin & ThisType<import('../driver').AndroidDriver>}
+ * @satisfies {import('@appium/types').ExternalDriver}
  */
-commands.mobileExecEmuConsoleCommand = async function mobileExecEmuConsoleCommand (opts = {}) {
-  this.ensureFeatureEnabled(EMU_CONSOLE_FEATURE);
-
-  const {
-    command,
-    execTimeout,
-    connTimeout,
-    initTimeout,
-  } = opts;
-
-  if (!command) {
-    throw new errors.InvalidArgumentError(`The 'command' argument is mandatory`);
-  }
-
-  return await this.adb.execEmuConsoleCommand(command, {
-    execTimeout,
-    connTimeout,
-    initTimeout,
-  });
+const EmulatorConsoleMixin = {
+  async mobileExecEmuConsoleCommand(opts) {
+    this.ensureFeatureEnabled(EMU_CONSOLE_FEATURE);
+
+    const {command, execTimeout, connTimeout, initTimeout} = opts;
+
+    if (!command) {
+      throw new errors.InvalidArgumentError(`The 'command' argument is mandatory`);
+    }
+
+    return await /** @type {import('appium-adb').ADB} */ (this.adb).execEmuConsoleCommand(command, {
+      execTimeout,
+      connTimeout,
+      initTimeout,
+    });
+  },
 };
 
-export { commands };
-export default commands;
+mixin(EmulatorConsoleMixin);
+
+export default EmulatorConsoleMixin;

package/lib/commands/execute.js

@@ -1,95 +1,111 @@
+// @ts-check
+
 import _ from 'lodash';
 import {errors, PROTOCOLS} from 'appium/driver';
-
-const extensions = {};
-
-extensions.execute = async function execute(script, args) {
-  if (script.match(/^mobile:/)) {
-    this.log.info(`Executing native command '${script}'`);
-    script = script.replace(/^mobile:/, '').trim();
-    return await this.executeMobile(script, _.isArray(args) ? args[0] : args);
-  }
-  if (!this.isWebContext()) {
-    throw new errors.NotImplementedError();
-  }
-  const endpoint =
-    this.chromedriver.jwproxy.downstreamProtocol === PROTOCOLS.MJSONWP
-      ? '/execute'
-      : '/execute/sync';
-  return await this.chromedriver.jwproxy.command(endpoint, 'POST', {
-    script,
-    args,
-  });
+import {mixin} from './mixins';
+
+/**
+ * @type {import('./mixins').ExecuteMixin & ThisType<import('../driver').AndroidDriver>}
+ * @satisfies {import('@appium/types').ExternalDriver}
+ */
+const ExecuteMixin = {
+  async execute(script, args) {
+    if (script.match(/^mobile:/)) {
+      this.log.info(`Executing native command '${script}'`);
+      script = script.replace(/^mobile:/, '').trim();
+      return await this.executeMobile(
+        script,
+        _.isArray(args) ? /** @type {import('@appium/types').StringRecord} */ (args[0]) : args
+      );
+    }
+    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,
+    });
+  },
+
+  async executeMobile(mobileCommand, opts = {}) {
+    const mobileCommandsMapping = {
+      shell: 'mobileShell',
+
+      execEmuConsoleCommand: 'mobileExecEmuConsoleCommand',
+
+      startLogsBroadcast: 'mobileStartLogsBroadcast',
+      stopLogsBroadcast: 'mobileStopLogsBroadcast',
+
+      changePermissions: 'mobileChangePermissions',
+      getPermissions: 'mobileGetPermissions',
+
+      performEditorAction: 'mobilePerformEditorAction',
+
+      sensorSet: 'sensorSet',
+
+      getDeviceTime: 'mobileGetDeviceTime',
+
+      startScreenStreaming: 'mobileStartScreenStreaming',
+      stopScreenStreaming: 'mobileStopScreenStreaming',
+
+      getNotifications: 'mobileGetNotifications',
+
+      listSms: 'mobileListSms',
+
+      pushFile: 'mobilePushFile',
+      pullFile: 'mobilePullFile',
+      pullFolder: 'mobilePullFolder',
+      deleteFile: 'mobileDeleteFile',
+
+      isAppInstalled: 'mobileIsAppInstalled',
+      queryAppState: 'mobileQueryAppState',
+      activateApp: 'mobileActivateApp',
+      removeApp: 'mobileRemoveApp',
+      terminateApp: 'mobileTerminateApp',
+      installApp: 'mobileInstallApp',
+      clearApp: 'mobileClearApp',
+
+      startService: 'mobileStartService',
+      stopService: 'mobileStopService',
+      startActivity: 'mobileStartActivity',
+      broadcast: 'mobileBroadcast',
+
+      getContexts: 'mobileGetContexts',
+
+      lock: 'mobileLock',
+      unlock: 'mobileUnlock',
+
+      refreshGpsCache: 'mobileRefreshGpsCache',
+
+      startMediaProjectionRecording: 'mobileStartMediaProjectionRecording',
+      isMediaProjectionRecordingRunning: 'mobileIsMediaProjectionRecordingRunning',
+      stopMediaProjectionRecording: 'mobileStopMediaProjectionRecording',
+
+      getConnectivity: 'mobileGetConnectivity',
+      setConnectivity: 'mobileSetConnectivity',
+
+      hideKeyboard: 'hideKeyboard',
+      isKeyboardShown: 'isKeyboardShown',
+    };
+
+    if (!_.has(mobileCommandsMapping, mobileCommand)) {
+      throw new errors.UnknownCommandError(
+        `Unknown mobile command "${mobileCommand}". ` +
+          `Only ${_.keys(mobileCommandsMapping)} commands are supported.`
+      );
+    }
+    // @ts-expect-error fine for now until we replace with execute methods
+    return await this[mobileCommandsMapping[mobileCommand]](opts);
+  },
 };
 
-extensions.executeMobile = async function executeMobile(mobileCommand, opts = {}) {
-  const mobileCommandsMapping = {
-    shell: 'mobileShell',
-
-    execEmuConsoleCommand: 'mobileExecEmuConsoleCommand',
-
-    startLogsBroadcast: 'mobileStartLogsBroadcast',
-    stopLogsBroadcast: 'mobileStopLogsBroadcast',
-
-    changePermissions: 'mobileChangePermissions',
-    getPermissions: 'mobileGetPermissions',
-
-    performEditorAction: 'mobilePerformEditorAction',
-
-    sensorSet: 'sensorSet',
-
-    getDeviceTime: 'mobileGetDeviceTime',
-
-    startScreenStreaming: 'mobileStartScreenStreaming',
-    stopScreenStreaming: 'mobileStopScreenStreaming',
-
-    getNotifications: 'mobileGetNotifications',
-
-    listSms: 'mobileListSms',
-
-    pushFile: 'mobilePushFile',
-    pullFile: 'mobilePullFile',
-    pullFolder: 'mobilePullFolder',
-    deleteFile: 'mobileDeleteFile',
-
-    isAppInstalled: 'mobileIsAppInstalled',
-    queryAppState: 'mobileQueryAppState',
-    activateApp: 'mobileActivateApp',
-    removeApp: 'mobileRemoveApp',
-    terminateApp: 'mobileTerminateApp',
-    installApp: 'mobileInstallApp',
-    clearApp: 'mobileClearApp',
-
-    startService: 'mobileStartService',
-    stopService: 'mobileStopService',
-    startActivity: 'mobileStartActivity',
-    broadcast: 'mobileBroadcast',
-
-    getContexts: 'mobileGetContexts',
-
-    lock: 'mobileLock',
-    unlock: 'mobileUnlock',
-
-    refreshGpsCache: 'mobileRefreshGpsCache',
-
-    startMediaProjectionRecording: 'mobileStartMediaProjectionRecording',
-    isMediaProjectionRecordingRunning: 'mobileIsMediaProjectionRecordingRunning',
-    stopMediaProjectionRecording: 'mobileStopMediaProjectionRecording',
-
-    getConnectivity: 'mobileGetConnectivity',
-    setConnectivity: 'mobileSetConnectivity',
-
-    hideKeyboard: 'hideKeyboard',
-    isKeyboardShown: 'isKeyboardShown',
-  };
-
-  if (!_.has(mobileCommandsMapping, mobileCommand)) {
-    throw new errors.UnknownCommandError(
-      `Unknown mobile command "${mobileCommand}". ` +
-        `Only ${_.keys(mobileCommandsMapping)} commands are supported.`
-    );
-  }
-  return await this[mobileCommandsMapping[mobileCommand]](opts);
-};
+mixin(ExecuteMixin);
 
-export default extensions;
+export default ExecuteMixin;