appium-android-driver 7.8.3 → 8.0.1

package/lib/commands/device/utils.js

@@ -0,0 +1,285 @@
+import _ from 'lodash';
+import {util} from '@appium/support';
+import ADB from 'appium-adb';
+import {retryInterval} from 'asyncbox';
+import {
+  path as SETTINGS_APK_PATH,
+  SETTINGS_HELPER_ID,
+  UNICODE_IME,
+  EMPTY_IME,
+} from 'io.appium.settings';
+import B from 'bluebird';
+
+const HELPER_APP_INSTALL_RETRIES = 3;
+const HELPER_APP_INSTALL_RETRY_DELAY_MS = 5000;
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {string} errMsg
+ */
+export function requireEmulator(errMsg) {
+  if (!this.isEmulator()) {
+    this.log.errorAndThrow(errMsg);
+  }
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @returns {void}
+ */
+export function validatePackageActivityNames() {
+  for (const key of ['appPackage', 'appActivity', 'appWaitPackage', 'appWaitActivity']) {
+    const name = this.opts[key];
+    if (!name) {
+      continue;
+    }
+
+    const match = /([^\w.*,])+/.exec(String(name));
+    if (!match) {
+      continue;
+    }
+
+    this.log.warn(
+      `Capability '${key}' is expected to only include latin letters, digits, underscore, dot, comma and asterisk characters.`,
+    );
+    this.log.warn(
+      `Current value '${name}' has non-matching character at index ${match.index}: '${String(
+        name,
+      ).substring(0, match.index + 1)}'`,
+    );
+  }
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {string} networkSpeed
+ * @returns {string}
+ */
+export function ensureNetworkSpeed(networkSpeed) {
+  if (networkSpeed.toUpperCase() in this.adb.NETWORK_SPEED) {
+    return networkSpeed;
+  }
+  this.log.warn(
+    `Wrong network speed param '${networkSpeed}', using default: ${this.adb.NETWORK_SPEED.FULL}. ` +
+      `Supported values: ${_.values(this.adb.NETWORK_SPEED)}`,
+  );
+  return this.adb.NETWORK_SPEED.FULL;
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @returns {string[]}
+ */
+export function prepareAvdArgs() {
+  const {networkSpeed, isHeadless, avdArgs} = this.opts;
+  const result = [];
+  if (avdArgs) {
+    if (_.isArray(avdArgs)) {
+      result.push(...avdArgs);
+    } else {
+      result.push(...util.shellParse(`${avdArgs}`));
+    }
+  }
+  if (networkSpeed) {
+    result.push('-netspeed', ensureNetworkSpeed.bind(this)(networkSpeed));
+  }
+  if (isHeadless) {
+    result.push('-no-window');
+  }
+  return result;
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @returns {Promise<void>}
+ */
+export async function prepareEmulator() {
+  const {
+    avd,
+    avdEnv: env,
+    language,
+    locale: country,
+    avdLaunchTimeout: launchTimeout,
+    avdReadyTimeout: readyTimeout,
+  } = this.opts;
+  if (!avd) {
+    throw new Error('Cannot launch AVD without AVD name');
+  }
+
+  const avdName = avd.replace('@', '');
+  let isEmulatorRunning = true;
+  try {
+    await this.adb.getRunningAVDWithRetry(avdName, 5000);
+  } catch (e) {
+    this.log.debug(`Emulator '${avdName}' is not running: ${e.message}`);
+    isEmulatorRunning = false;
+  }
+  const args = prepareAvdArgs.bind(this)();
+  if (isEmulatorRunning) {
+    if (args.includes('-wipe-data')) {
+      this.log.debug(`Killing '${avdName}' because it needs to be wiped at start.`);
+      await this.adb.killEmulator(avdName);
+    } else {
+      this.log.debug('Not launching AVD because it is already running.');
+      return;
+    }
+  }
+  await this.adb.launchAVD(avd, {
+    args,
+    env,
+    language,
+    country,
+    launchTimeout,
+    readyTimeout,
+  });
+}
+
+/**
+ * @param {import('../../driver').AndroidDriverOpts?} [opts=null]
+ * @returns {Promise<ADB>}
+ */
+export async function createBaseADB(opts = null) {
+  // filter out any unwanted options sent in
+  // this list should be updated as ADB takes more arguments
+  const {
+    adbPort,
+    suppressKillServer,
+    remoteAdbHost,
+    clearDeviceLogsOnStart,
+    adbExecTimeout,
+    useKeystore,
+    keystorePath,
+    keystorePassword,
+    keyAlias,
+    keyPassword,
+    remoteAppsCacheLimit,
+    buildToolsVersion,
+    allowOfflineDevices,
+    allowDelayAdb,
+  } = opts ?? {};
+  return await ADB.createADB({
+    adbPort,
+    suppressKillServer,
+    remoteAdbHost,
+    clearDeviceLogsOnStart,
+    adbExecTimeout,
+    useKeystore,
+    keystorePath,
+    keystorePassword,
+    keyAlias,
+    keyPassword,
+    remoteAppsCacheLimit,
+    buildToolsVersion,
+    allowOfflineDevices,
+    allowDelayAdb,
+  });
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {boolean} throwIfError
+ * @returns {Promise<void>}
+ */
+export async function pushSettingsApp(throwIfError) {
+  this.log.debug('Pushing settings apk to the device...');
+
+  try {
+    // Sometimes adb push or adb instal take more time than expected to install an app
+    // e.g. https://github.com/appium/io.appium.settings/issues/40#issuecomment-476593174
+    await retryInterval(
+      HELPER_APP_INSTALL_RETRIES,
+      HELPER_APP_INSTALL_RETRY_DELAY_MS,
+      async () =>
+        await this.adb.installOrUpgrade(SETTINGS_APK_PATH, SETTINGS_HELPER_ID, {
+          grantPermissions: true,
+        }),
+    );
+  } catch (err) {
+    if (throwIfError) {
+      throw err;
+    }
+
+    this.log.warn(
+      `Ignored error while installing '${SETTINGS_APK_PATH}': ` +
+        `'${err.message}'. Features that rely on this helper ` +
+        'require the apk such as toggle WiFi and getting location ' +
+        'will raise an error if you try to use them.',
+    );
+  }
+
+  // Reinstall would stop the settings helper process anyway, so
+  // there is no need to continue if the application is still running
+  if (await this.settingsApp.isRunningInForeground()) {
+    this.log.debug(
+      `${SETTINGS_HELPER_ID} is already running. ` + `There is no need to reset its permissions.`,
+    );
+    return;
+  }
+
+  const fixSettingsAppPermissionsForLegacyApis = async () => {
+    if ((await this.adb.getApiLevel()) > 23) {
+      return;
+    }
+
+    // Android 6- devices should have granted permissions
+    // https://github.com/appium/appium/pull/11640#issuecomment-438260477
+    const perms = ['SET_ANIMATION_SCALE', 'CHANGE_CONFIGURATION', 'ACCESS_FINE_LOCATION'];
+    this.log.info(`Granting permissions ${perms} to '${SETTINGS_HELPER_ID}'`);
+    await this.adb.grantPermissions(
+      SETTINGS_HELPER_ID,
+      perms.map((x) => `android.permission.${x}`),
+    );
+  };
+
+  try {
+    await B.all([
+      this.settingsApp.adjustNotificationsPermissions(),
+      this.settingsApp.adjustMediaProjectionServicePermissions(),
+      fixSettingsAppPermissionsForLegacyApis(),
+    ]);
+  } catch (e) {
+    this.log.debug(e.stack);
+  }
+
+  // launch io.appium.settings app due to settings failing to be set
+  // if the app is not launched prior to start the session on android 7+
+  // see https://github.com/appium/appium/issues/8957
+  try {
+    await this.settingsApp.requireRunning({
+      timeout: this.isEmulator() ? 30000 : 5000,
+    });
+  } catch (err) {
+    this.log.debug(err.stack);
+    if (throwIfError) {
+      throw err;
+    }
+  }
+}
+
+/**
+ * @deprecated
+ * @this {import('../../driver').AndroidDriver}
+ * @returns {Promise<string?>}
+ */
+export async function initUnicodeKeyboard() {
+  this.log.debug('Enabling Unicode keyboard support');
+
+  // get the default IME so we can return back to it later if we want
+  const defaultIME = await this.adb.defaultIME();
+
+  this.log.debug(`Unsetting previous IME ${defaultIME}`);
+  this.log.debug(`Setting IME to '${UNICODE_IME}'`);
+  await this.adb.enableIME(UNICODE_IME);
+  await this.adb.setIME(UNICODE_IME);
+  return defaultIME;
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @returns {Promise<void>}
+ */
+export async function hideKeyboardCompletely() {
+  this.log.debug(`Hiding the on-screen keyboard by setting IME to '${EMPTY_IME}'`);
+  await this.adb.enableIME(EMPTY_IME);
+  await this.adb.setIME(EMPTY_IME);
+}

package/lib/commands/deviceidle.js

@@ -1,56 +1,43 @@
 import {errors} from 'appium/driver';
 import _ from 'lodash';
-import {mixin} from './mixins';
 
 const SUPPORTED_ACTIONS = ['whitelistAdd', 'whitelistRemove'];
 
 /**
- * @type {import('./mixins').DeviceidleMixin & ThisType<import('../driver').AndroidDriver>}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * This is a wrapper to 'adb shell dumpsys deviceidle' interface.
+ * Read https://www.protechtraining.com/blog/post/diving-into-android-m-doze-875
+ * for more details.
+ *
+ * @param {import('./types').DeviceidleOpts} opts
+ * @returns {Promise<void>}
  */
-const DeviceidleMixin = {
-  /**
-   * This is a wrapper to 'adb shell dumpsys deviceidle' interface.
-   * Read https://www.protechtraining.com/blog/post/diving-into-android-m-doze-875
-   * for more details.
-   *
-   * @param {import('./types').DeviceidleOpts} opts
-   */
-  async mobileDeviceidle(opts) {
-    const {
-      action,
-      packages,
-    } = opts;
+export async function mobileDeviceidle(opts) {
+  const {action, packages} = opts;
 
-    if (!(_.isString(packages) || _.isArray(packages))) {
-      throw new errors.InvalidArgumentError(`packages argument must be a string or an array`);
-    }
+  if (!(_.isString(packages) || _.isArray(packages))) {
+    throw new errors.InvalidArgumentError(`packages argument must be a string or an array`);
+  }
 
-    /** @type {string[]} */
-    const packagesArr = _.isArray(packages) ? packages : [packages];
-    /** @type {string[]} */
-    const commonArgs = ['dumpsys', 'deviceidle', 'whitelist'];
-    /** @type {(x: string) => string[]} */
-    let argsGenerator;
-    switch (action) {
-      case SUPPORTED_ACTIONS[0]:
-        argsGenerator = (pkg) => [...commonArgs, `+${pkg}`];
-        break;
-      case SUPPORTED_ACTIONS[1]:
-        argsGenerator = (pkg) => [...commonArgs, `-${pkg}`];
-        break;
-      default:
-        throw new errors.InvalidArgumentError(
-          `action must be one of ${JSON.stringify(SUPPORTED_ACTIONS)}. Got '${action}' instead`
-        );
-    }
-    await (this.adb).shellChunks(argsGenerator, packagesArr);
-  },
-};
-
-mixin(DeviceidleMixin);
-
-export default DeviceidleMixin;
+  /** @type {string[]} */
+  const packagesArr = _.isArray(packages) ? packages : [packages];
+  /** @type {string[]} */
+  const commonArgs = ['dumpsys', 'deviceidle', 'whitelist'];
+  /** @type {(x: string) => string[]} */
+  let argsGenerator;
+  switch (action) {
+    case SUPPORTED_ACTIONS[0]:
+      argsGenerator = (pkg) => [...commonArgs, `+${pkg}`];
+      break;
+    case SUPPORTED_ACTIONS[1]:
+      argsGenerator = (pkg) => [...commonArgs, `-${pkg}`];
+      break;
+    default:
+      throw new errors.InvalidArgumentError(
+        `action must be one of ${JSON.stringify(SUPPORTED_ACTIONS)}. Got '${action}' instead`,
+      );
+  }
+  await this.adb.shellChunks(argsGenerator, packagesArr);
+}
 
 /**
  * @typedef {import('appium-adb').ADB} ADB

package/lib/commands/element.js

@@ -1,151 +1,158 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 
-import {mixin} from './mixins';
-import {retryInterval} from 'asyncbox';
 import {errors} from 'appium/driver';
 
 /**
- * @type {import('./mixins').ElementMixin & ThisType<import('../driver').AndroidDriver>}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} attribute
+ * @param {string} elementId
+ * @returns {Promise<string?>}
  */
-const ElementMixin = {
-  async getAttribute(attribute, elementId) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  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) {
-    const text = keys instanceof Array ? keys.join('') : keys;
-    return await this.doSetElementValue({
-      elementId,
-      text: String(text),
-      replace,
-    });
-  },
-
-  /**
-   * 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) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  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('');
-    }
-
-    // first, make sure we are focused on the element
-    await this.click(elementId);
-
-    // then send through adb
-    await this.adb.inputText(/** @type {string} */ (text));
-  },
-
-  async getText(elementId) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  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 this.adb.clearTextField(lengthToSend);
-        remainingLength -= lengthToSend;
-      }
-    });
-  },
-
-  async click(elementId) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  async getLocation(elementId) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  async getLocationInView(elementId) {
-    return await this.getLocation(elementId);
-  },
-
-  async getSize(elementId) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  async getElementRect(elementId) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  async touchLongClick(elementId, x, y, duration) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  async touchDown(elementId, x, y) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  async touchUp(elementId, x, y) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  async touchMove(elementId, x, y) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  async complexTap(tapCount, touchCount, duration, x, y) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  async tap(elementId = null, x = null, y = null, count = 1) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-};
-
-mixin(ElementMixin);
-
-export default ElementMixin;
+export async function getAttribute(attribute, elementId) {
+  throw new errors.NotImplementedError('Not implemented');
+}
 
 /**
- * @typedef {import('appium-adb').ADB} ADB
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} elementId
+ * @returns {Promise<void>}
  */
+export async function click(elementId) {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} elementId
+ * @returns {Promise<string>}
+ */
+export async function getText(elementId) {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} elementId
+ * @returns {Promise<import('@appium/types').Position>}
+ */
+export async function getLocation(elementId) {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} elementId
+ * @returns {Promise<import('@appium/types').Size>}
+ */
+export async function getSize(elementId) {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} elementId
+ * @returns {Promise<string>}
+ */
+export async function getName(elementId) {
+  return /** @type {string} */ (await this.getAttribute('className', elementId));
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} elementId
+ * @returns {Promise<boolean>}
+ */
+export async function elementDisplayed(elementId) {
+  return (await this.getAttribute('displayed', elementId)) === 'true';
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} elementId
+ * @returns {Promise<boolean>}
+ */
+export async function elementEnabled(elementId) {
+  return (await this.getAttribute('enabled', elementId)) === 'true';
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} elementId
+ * @returns {Promise<boolean>}
+ */
+export async function elementSelected(elementId) {
+  return (await this.getAttribute('selected', elementId)) === 'true';
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string|string[]} keys
+ * @param {string} elementId
+ * @param {boolean} [replace=false]
+ * @returns {Promise<void>}
+ */
+export async function setElementValue(keys, elementId, replace = false) {
+  const text = keys instanceof Array ? keys.join('') : keys;
+  return await this.doSetElementValue({
+    elementId,
+    text: String(text),
+    replace,
+  });
+}
+
+/**
+ * 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.
+ *
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').DoSetElementValueOpts} params
+ * @returns {Promise<void>}
+ */
+export async function doSetElementValue(params) {
+  throw new errors.NotImplementedError('Not implemented');
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string|string[]} keys
+ * @param {string} elementId
+ * @returns {Promise<void>}
+ */
+export async function setValue(keys, elementId) {
+  return await this.setElementValue(keys, elementId, false);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string|string[]} keys
+ * @param {string} elementId
+ * @returns {Promise<void>}
+ */
+export async function replaceValue(keys, elementId) {
+  return await this.setElementValue(keys, elementId, true);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string|string[]} keys
+ * @param {string} elementId
+ * @returns {Promise<void>}
+ */
+export async function setValueImmediate(keys, elementId) {
+  const text = Array.isArray(keys) ? keys.join('') : keys;
+  // first, make sure we are focused on the element
+  await this.click(elementId);
+  // then send through adb
+  await this.adb.inputText(/** @type {string} */ (text));
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} elementId
+ * @returns {Promise<import('@appium/types').Position>}
+ */
+export async function getLocationInView(elementId) {
+  return await this.getLocation(elementId);
+}