appium-android-driver 7.8.3 → 8.0.0

package/lib/commands/device/common.js

@@ -0,0 +1,264 @@
+import semver from 'semver';
+import _ from 'lodash';
+import {resetMockLocation, setMockLocationApp} from '../geolocation';
+import {SETTINGS_HELPER_ID} from 'io.appium.settings';
+import {hideKeyboardCompletely, initUnicodeKeyboard} from '../keyboard';
+import {
+  createBaseADB,
+  prepareEmulator,
+  validatePackageActivityNames,
+  pushSettingsApp,
+} from './utils';
+
+/**
+ * @this {AndroidDriver}
+ * @returns {Promise<import('../types').ADBDeviceInfo>}
+ */
+export async function getDeviceInfoFromCaps() {
+  // we can create a throwaway ADB instance here, so there is no dependency
+  // on instantiating on earlier (at this point, we have no udid)
+  // we can only use this ADB object for commands that would not be confused
+  // if multiple devices are connected
+  /** @type {import('appium-adb').ADB} */
+  const adb = this.adb ?? (await createBaseADB(this.opts));
+  let udid = this.opts.udid;
+  let emPort;
+
+  // a specific avd name was given. try to initialize with that
+  if (this.opts?.avd) {
+    await prepareEmulator.bind(this)();
+    udid = adb.curDeviceId;
+    emPort = adb.emulatorPort;
+  } else {
+    // no avd given. lets try whatever's plugged in devices/emulators
+    this.log.info('Retrieving device list');
+    const devices = await adb.getDevicesWithRetry();
+
+    // udid was given, lets try to init with that device
+    if (udid) {
+      if (!_.includes(_.map(devices, 'udid'), udid)) {
+        throw this.log.errorAndThrow(`Device ${udid} was not in the list of connected devices`);
+      }
+      emPort = adb.getPortFromEmulatorString(udid);
+    } else if (this.opts.platformVersion) {
+      this.opts.platformVersion = `${this.opts.platformVersion}`.trim();
+
+      // a platform version was given. lets try to find a device with the same os
+      const platformVersion = semver.coerce(this.opts.platformVersion) || this.opts.platformVersion;
+      this.log.info(`Looking for a device with Android '${platformVersion}'`);
+
+      // in case we fail to find something, give the user a useful log that has
+      // the device udids and os versions so they know what's available
+      const availDevices = [];
+      let partialMatchCandidate;
+      // first try started devices/emulators
+      for (const device of devices) {
+        // direct adb calls to the specific device
+        adb.setDeviceId(device.udid);
+        /** @type {string} */
+        const rawDeviceOS = await adb.getPlatformVersion();
+        // The device OS could either be a number, like `6.0`
+        // or an abbreviation, like `R`
+        availDevices.push(`${device.udid} (${rawDeviceOS})`);
+        const deviceOS = semver.coerce(rawDeviceOS) || rawDeviceOS;
+        if (!deviceOS) {
+          continue;
+        }
+
+        const semverPV = platformVersion;
+        const semverDO = deviceOS;
+
+        const bothVersionsCanBeCoerced = semver.valid(deviceOS) && semver.valid(platformVersion);
+        const bothVersionsAreStrings = _.isString(deviceOS) && _.isString(platformVersion);
+        if (
+          (bothVersionsCanBeCoerced &&
+            /** @type {semver.SemVer} */ (semverDO).version ===
+              /** @type {semver.SemVer} */ (semverPV).version) ||
+          (bothVersionsAreStrings && _.toLower(deviceOS) === _.toLower(platformVersion))
+        ) {
+          // Got an exact match - proceed immediately
+          udid = device.udid;
+          break;
+        } else if (!bothVersionsCanBeCoerced) {
+          // There is no point to check for partial match if either of version numbers is not coercible
+          continue;
+        }
+
+        if (
+          ((!_.includes(this.opts.platformVersion, '.') &&
+            /** @type {semver.SemVer} */ (semverPV).major ===
+              /** @type {semver.SemVer} */ (semverDO).major) ||
+            (/** @type {semver.SemVer} */ (semverPV).major ===
+              /** @type {semver.SemVer} */ (semverDO).major &&
+              /** @type {semver.SemVer} */ (semverPV).minor ===
+                /** @type {semver.SemVer} */ (semverDO).minor)) &&
+          // Got a partial match - make sure we consider the most recent
+          // device version available on the host system
+          ((partialMatchCandidate && semver.gt(deviceOS, _.values(partialMatchCandidate)[0])) ||
+            !partialMatchCandidate)
+        ) {
+          partialMatchCandidate = {[device.udid]: deviceOS};
+        }
+      }
+      if (!udid && partialMatchCandidate) {
+        udid = _.keys(partialMatchCandidate)[0];
+        adb.setDeviceId(udid);
+      }
+
+      if (!udid) {
+        // we couldn't find anything! quit
+        throw this.log.errorAndThrow(
+          `Unable to find an active device or emulator ` +
+            `with OS ${this.opts.platformVersion}. The following are available: ` +
+            availDevices.join(', '),
+        );
+      }
+
+      emPort = adb.getPortFromEmulatorString(udid);
+    } else {
+      // a udid was not given, grab the first device we see
+      udid = devices[0].udid;
+      emPort = adb.getPortFromEmulatorString(udid);
+    }
+  }
+
+  this.log.info(`Using device: ${udid}`);
+  return {udid: String(udid), emPort: emPort ?? false};
+}
+
+/**
+ * @this {AndroidDriver}
+ * @property {(AndroidDriverOpts & {emPort?: number})?} [opts=null]
+ * @returns {Promise<import('appium-adb').ADB>}
+ */
+export async function createADB(opts = null) {
+  // @ts-expect-error do not put arbitrary properties on opts
+  const {udid, emPort} = opts ?? {};
+  const adb = await createBaseADB(opts);
+  adb.setDeviceId(udid ?? '');
+  if (emPort) {
+    adb.setEmulatorPort(emPort);
+  }
+  return adb;
+}
+
+/**
+ * @this {AndroidDriver}
+ * @returns {Promise<import('../types').ADBLaunchInfo | undefined>}
+ */
+export async function getLaunchInfo() {
+  if (!this.opts.app) {
+    this.log.warn('No app sent in, not parsing package/activity');
+    return;
+  }
+  let {appPackage, appActivity, appWaitPackage, appWaitActivity} = this.opts;
+  const {app} = this.opts;
+
+  validatePackageActivityNames.bind(this)();
+
+  if (appPackage && appActivity) {
+    return;
+  }
+
+  this.log.debug('Parsing package and activity from app manifest');
+  const {apkPackage, apkActivity} = await this.adb.packageAndLaunchActivityFromManifest(app);
+  if (apkPackage && !appPackage) {
+    appPackage = apkPackage;
+  }
+  if (!appWaitPackage) {
+    appWaitPackage = appPackage;
+  }
+  if (apkActivity && !appActivity) {
+    appActivity = apkActivity;
+  }
+  if (!appWaitActivity) {
+    appWaitActivity = appActivity;
+  }
+  this.log.debug(`Parsed package and activity are: ${apkPackage}/${apkActivity}`);
+  return {appPackage, appWaitPackage, appActivity, appWaitActivity};
+}
+
+/**
+ * @this {AndroidDriver}
+ * @returns
+ */
+export async function initDevice() {
+  const {
+    skipDeviceInitialization,
+    locale,
+    language,
+    localeScript,
+    unicodeKeyboard,
+    hideKeyboard,
+    disableWindowAnimation,
+    skipUnlock,
+    mockLocationApp,
+    skipLogcatCapture,
+    logcatFormat,
+    logcatFilterSpecs,
+  } = this.opts;
+
+  if (skipDeviceInitialization) {
+    this.log.info(`'skipDeviceInitialization' is set. Skipping device initialization.`);
+  } else {
+    if (this.isEmulator()) {
+      // Check if the device wake up only for an emulator.
+      // It takes 1 second or so even when the device is already awake in a real device.
+      await this.adb.waitForDevice();
+    }
+    // pushSettingsApp required before calling ensureDeviceLocale for API Level 24+
+
+    // Some feature such as location/wifi are not necessary for all users,
+    // but they require the settings app. So, try to configure it while Appium
+    // does not throw error even if they fail.
+    const shouldThrowError = Boolean(
+      language ||
+        locale ||
+        localeScript ||
+        unicodeKeyboard ||
+        hideKeyboard ||
+        disableWindowAnimation ||
+        !skipUnlock,
+    );
+    await pushSettingsApp.bind(this)(shouldThrowError);
+  }
+
+  if (!this.isEmulator()) {
+    if (mockLocationApp || _.isUndefined(mockLocationApp)) {
+      await setMockLocationApp.bind(this)(mockLocationApp || SETTINGS_HELPER_ID);
+    } else {
+      await resetMockLocation.bind(this)();
+    }
+  }
+
+  if (language && locale) {
+    await this.ensureDeviceLocale(language, locale, localeScript);
+  }
+
+  if (skipLogcatCapture) {
+    this.log.info(`'skipLogcatCapture' is set. Skipping starting logcat capture.`);
+  } else {
+    await this.adb.startLogcat({
+      format: logcatFormat,
+      filterSpecs: logcatFilterSpecs,
+    });
+  }
+
+  if (hideKeyboard) {
+    await hideKeyboardCompletely.bind(this)();
+  } else if (hideKeyboard === false) {
+    await this.adb.shell(['ime', 'reset']);
+  }
+
+  if (unicodeKeyboard) {
+    this.log.warn(
+      `The 'unicodeKeyboard' capability has been deprecated and will be removed. ` +
+        `Set the 'hideKeyboard' capability to 'true' in order to make the on-screen keyboard invisible.`,
+    );
+    return await initUnicodeKeyboard.bind(this)();
+  }
+}
+
+/**
+ * @typedef {import('../../driver').AndroidDriver} AndroidDriver
+ */

package/lib/commands/device/emulator-actions.js

@@ -0,0 +1,194 @@
+import {util} from '@appium/support';
+import {requireArgs} from '../../utils';
+import {requireEmulator} from './utils';
+
+/**
+ * @deprecated Use mobile: extension
+ * @this {import('../../driver').AndroidDriver}
+ * @param {string|number} fingerprintId
+ * @returns {Promise<void>}
+ */
+export async function fingerprint(fingerprintId) {
+  requireEmulator.bind(this)('fingerprint is only available for emulators');
+  await this.adb.fingerprint(String(fingerprintId));
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').FingerprintOpts} opts
+ * @returns {Promise<void>}
+ */
+export async function mobileFingerprint(opts) {
+  const {fingerprintId} = requireArgs('fingerprintId', opts);
+  await this.fingerprint(fingerprintId);
+}
+
+/**
+ * @deprecated Use mobile: extension
+ * @this {import('../../driver').AndroidDriver}
+ * @param {string} phoneNumber
+ * @param {string} message
+ * @returns {Promise<void>}
+ */
+export async function sendSMS(phoneNumber, message) {
+  requireEmulator.bind(this)('sendSMS is only available for emulators');
+  await this.adb.sendSMS(phoneNumber, message);
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').SendSMSOpts} opts
+ * @returns {Promise<void>}
+ */
+export async function mobileSendSms(opts) {
+  const {phoneNumber, message} = requireArgs(['phoneNumber', 'message'], opts);
+  await this.sendSMS(phoneNumber, message);
+}
+
+/**
+ * @deprecated Use mobile: extension
+ * @this {import('../../driver').AndroidDriver}
+ * @param {string} phoneNumber
+ * @param {string} action
+ * @returns {Promise<void>}
+ */
+export async function gsmCall(phoneNumber, action) {
+  requireEmulator.bind(this)('gsmCall is only available for emulators');
+  await this.adb.gsmCall(phoneNumber, /** @type {any} */ (action));
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').GsmCallOpts} opts
+ * @returns {Promise<void>}
+ */
+export async function mobileGsmCall(opts) {
+  const {phoneNumber, action} = requireArgs(['phoneNumber', 'action'], opts);
+  await this.gsmCall(phoneNumber, action);
+}
+
+/**
+ * @deprecated Use mobile: extension
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').GsmSignalStrength} signalStrengh
+ * @returns {Promise<void>}
+ */
+export async function gsmSignal(signalStrengh) {
+  requireEmulator.bind(this)('gsmSignal is only available for emulators');
+  await this.adb.gsmSignal(signalStrengh);
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').GsmSignalStrengthOpts} opts
+ * @returns {Promise<void>}
+ */
+export async function mobileGsmSignal(opts) {
+  const {strength} = requireArgs('strength', opts);
+  await this.gsmSignal(strength);
+}
+
+/**
+ * @deprecated Use mobile: extension
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').GsmVoiceState} state
+ * @returns {Promise<void>}
+ */
+export async function gsmVoice(state) {
+  requireEmulator.bind(this)('gsmVoice is only available for emulators');
+  await this.adb.gsmVoice(state);
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').GsmVoiceOpts} opts
+ * @returns {Promise<void>}
+ */
+export async function mobileGsmVoice(opts) {
+  const {state} = requireArgs('state', opts);
+  await this.gsmVoice(state);
+}
+
+/**
+ * @deprecated Use mobile: extension
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').PowerACState} state
+ * @returns {Promise<void>}
+ */
+export async function powerAC(state) {
+  requireEmulator.bind(this)('powerAC is only available for emulators');
+  await this.adb.powerAC(state);
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').PowerACOpts} opts
+ * @returns {Promise<void>}
+ */
+export async function mobilePowerAc(opts) {
+  const {state} = requireArgs('state', opts);
+  await this.powerAC(state);
+}
+
+/**
+ * @deprecated Use mobile: extension
+ * @this {import('../../driver').AndroidDriver}
+ * @param {number} batteryPercent
+ * @returns {Promise<void>}
+ */
+export async function powerCapacity(batteryPercent) {
+  requireEmulator.bind(this)('powerCapacity is only available for emulators');
+  await this.adb.powerCapacity(batteryPercent);
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').PowerCapacityOpts} opts
+ * @return {Promise<void>}
+ */
+export async function mobilePowerCapacity(opts) {
+  const {percent} = requireArgs('percent', opts);
+  await this.powerCapacity(percent);
+}
+
+/**
+ * @deprecated Use mobile: extension
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').NetworkSpeed} networkSpeed
+ * @returns {Promise<void>}
+ */
+export async function networkSpeed(networkSpeed) {
+  requireEmulator.bind(this)('networkSpeed is only available for emulators');
+  await this.adb.networkSpeed(networkSpeed);
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').NetworkSpeedOpts} opts
+ * @returns {Promise<void>}
+ */
+export async function mobileNetworkSpeed(opts) {
+  const {speed} = requireArgs('speed', opts);
+  await this.networkSpeed(speed);
+}
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').SensorSetOpts} opts
+ * @returns {Promise<void>}
+ */
+export async function sensorSet(opts) {
+  requireEmulator.bind(this)('sensorSet is only available for emulators');
+  const {sensorType, value} = opts;
+  if (!util.hasValue(sensorType)) {
+    this.log.errorAndThrow(`'sensorType' argument is required`);
+  }
+  if (!util.hasValue(value)) {
+    this.log.errorAndThrow(`'value' argument is required`);
+  }
+  await this.adb.sensorSet(sensorType, /** @type {any} */ (value));
+}
+
+/**
+ * @typedef {import('appium-adb').ADB} ADB
+ */

package/lib/commands/device/emulator-console.js

@@ -0,0 +1,24 @@
+import {errors} from 'appium/driver';
+
+const EMU_CONSOLE_FEATURE = 'emulator_console';
+
+/**
+ * @this {import('../../driver').AndroidDriver}
+ * @param {import('../types').ExecOptions} opts
+ * @returns {Promise<string>}
+ */
+export 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 /** @type {import('appium-adb').ADB} */ (this.adb).execEmuConsoleCommand(command, {
+    execTimeout,
+    connTimeout,
+    initTimeout,
+  });
+}