appium-android-driver 7.8.2 → 8.0.0

package/lib/commands/geolocation.js

@@ -0,0 +1,179 @@
+import _ from 'lodash';
+import {fs, tempDir} from '@appium/support';
+import path from 'node:path';
+import B from 'bluebird';
+import {SETTINGS_HELPER_ID} from 'io.appium.settings';
+import {getThirdPartyPackages} from './app-management';
+
+// The value close to zero, but not zero, is needed
+// to trick JSON generation and send a float value instead of an integer,
+// This allows strictly-typed clients, like Java, to properly
+// parse it. Otherwise float 0.0 is always represented as integer 0 in JS.
+// The value must not be greater than DBL_EPSILON (https://opensource.apple.com/source/Libc/Libc-498/include/float.h)
+const GEO_EPSILON = Number.MIN_VALUE;
+const MOCK_APP_IDS_STORE = '/data/local/tmp/mock_apps.json';
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('@appium/types').Location} location
+ * @returns {Promise<import('@appium/types').Location>}
+ */
+export async function setGeoLocation(location) {
+  await this.settingsApp.setGeoLocation(location, this.isEmulator());
+  try {
+    return await this.getGeoLocation();
+  } catch (e) {
+    this.log.warn(
+      `Could not get the current geolocation info: ${/** @type {Error} */ (e).message}`,
+    );
+    this.log.warn(`Returning the default zero'ed values`);
+    return {
+      latitude: GEO_EPSILON,
+      longitude: GEO_EPSILON,
+      altitude: GEO_EPSILON,
+    };
+  }
+}
+
+/**
+ * Sends an async request to refresh the GPS cache.
+ *
+ * This feature only works if the device under test has Google Play Services
+ * installed. In case the vanilla LocationManager is used the device API level
+ * must be at version 30 (Android R) or higher.
+ *
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').GpsCacheRefreshOpts} [opts={}]
+ * @returns {Promise<void>}
+ */
+export async function mobileRefreshGpsCache(opts = {}) {
+  const {timeoutMs} = opts;
+  await this.settingsApp.refreshGeoLocationCache(timeoutMs);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<import('@appium/types').Location>}
+ */
+export async function getGeoLocation() {
+  const {latitude, longitude, altitude} = await this.settingsApp.getGeoLocation();
+  return {
+    latitude: parseFloat(String(latitude)) || GEO_EPSILON,
+    longitude: parseFloat(String(longitude)) || GEO_EPSILON,
+    altitude: parseFloat(String(altitude)) || GEO_EPSILON,
+  };
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<boolean>}
+ */
+export async function isLocationServicesEnabled() {
+  return (await this.adb.getLocationProviders()).includes('gps');
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<void>}
+ */
+export async function toggleLocationServices() {
+  this.log.info('Toggling location services');
+  const isGpsEnabled = await this.isLocationServicesEnabled();
+  this.log.debug(
+    `Current GPS state: ${isGpsEnabled}. ` +
+      `The service is going to be ${isGpsEnabled ? 'disabled' : 'enabled'}`,
+  );
+  await this.adb.toggleGPSLocationProvider(!isGpsEnabled);
+}
+
+// #region Internal helpers
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} appId
+ * @returns {Promise<void>}
+ */
+export async function setMockLocationApp(appId) {
+  try {
+    if ((await this.adb.getApiLevel()) < 23) {
+      await this.adb.shell(['settings', 'put', 'secure', 'mock_location', '1']);
+    } else {
+      await this.adb.shell(['appops', 'set', appId, 'android:mock_location', 'allow']);
+    }
+  } catch (err) {
+    this.log.warn(`Unable to set mock location for app '${appId}': ${err.message}`);
+    return;
+  }
+  try {
+    /** @type {string[]} */
+    let pkgIds = [];
+    if (await this.adb.fileExists(MOCK_APP_IDS_STORE)) {
+      try {
+        pkgIds = JSON.parse(await this.adb.shell(['cat', MOCK_APP_IDS_STORE]));
+      } catch (ign) {}
+    }
+    if (pkgIds.includes(appId)) {
+      return;
+    }
+    pkgIds.push(appId);
+    const tmpRoot = await tempDir.openDir();
+    const srcPath = path.posix.join(tmpRoot, path.posix.basename(MOCK_APP_IDS_STORE));
+    try {
+      await fs.writeFile(srcPath, JSON.stringify(pkgIds), 'utf8');
+      await this.adb.push(srcPath, MOCK_APP_IDS_STORE);
+    } finally {
+      await fs.rimraf(tmpRoot);
+    }
+  } catch (e) {
+    this.log.warn(`Unable to persist mock location app id '${appId}': ${e.message}`);
+  }
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<void>}
+ */
+export async function resetMockLocation() {
+  try {
+    if ((await this.adb.getApiLevel()) < 23) {
+      await this.adb.shell(['settings', 'put', 'secure', 'mock_location', '0']);
+      return;
+    }
+
+    const thirdPartyPkgIdsPromise = getThirdPartyPackages.bind(this)();
+    let pkgIds = [];
+    if (await this.adb.fileExists(MOCK_APP_IDS_STORE)) {
+      try {
+        pkgIds = JSON.parse(await this.adb.shell(['cat', MOCK_APP_IDS_STORE]));
+      } catch (ign) {}
+    }
+    const thirdPartyPkgIds = await thirdPartyPkgIdsPromise;
+    // Only include currently installed packages
+    const resultPkgs = _.intersection(pkgIds, thirdPartyPkgIds);
+    if (_.size(resultPkgs) <= 1) {
+      await this.adb.shell([
+        'appops',
+        'set',
+        resultPkgs[0] ?? SETTINGS_HELPER_ID,
+        'android:mock_location',
+        'deny',
+      ]);
+      return;
+    }
+
+    this.log.debug(`Resetting mock_location permission for the following apps: ${resultPkgs}`);
+    await B.all(
+      resultPkgs.map((pkgId) =>
+        (async () => {
+          try {
+            await this.adb.shell(['appops', 'set', pkgId, 'android:mock_location', 'deny']);
+          } catch (ign) {}
+        })(),
+      ),
+    );
+  } catch (err) {
+    this.log.warn(`Unable to reset mock location: ${err.message}`);
+  }
+}
+
+// #endregion Internal helpers

package/lib/commands/ime.js

@@ -1,56 +1,64 @@
-// @ts-check
-
-import {mixin} from './mixins';
 import {errors} from 'appium/driver';
 
 /**
- * @type {import('./mixins').IMEMixin & ThisType<import('../driver').AndroidDriver>}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<boolean>}
  */
-const IMEMixin = {
-  async isIMEActivated() {
-    // eslint-disable-line require-await
-    // IME is always activated on Android devices
-    return true;
-  },
-
-  async availableIMEEngines() {
-    this.log.debug('Retrieving available IMEs');
-    let engines = await this.adb.availableIMEs();
-    this.log.debug(`Engines: ${JSON.stringify(engines)}`);
-    return engines;
-  },
-
-  async getActiveIMEEngine() {
-    this.log.debug('Retrieving current default IME');
-    return String(await this.adb.defaultIME());
-  },
+export async function isIMEActivated() {
+  // eslint-disable-line require-await
+  // IME is always activated on Android devices
+  return true;
+}
 
-  async activateIMEEngine(imeId) {
-    this.log.debug(`Attempting to activate IME ${imeId}`);
-    let availableEngines = await this.adb.availableIMEs();
-    if (availableEngines.indexOf(imeId) === -1) {
-      this.log.debug('IME not found, failing');
-      throw new errors.IMENotAvailableError();
-    }
-    this.log.debug('Found installed IME, attempting to activate');
-    await this.adb.enableIME(imeId);
-    await this.adb.setIME(imeId);
-  },
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<string[]>}
+ */
+export async function availableIMEEngines() {
+  this.log.debug('Retrieving available IMEs');
+  let engines = await this.adb.availableIMEs();
+  this.log.debug(`Engines: ${JSON.stringify(engines)}`);
+  return engines;
+}
 
-  async deactivateIMEEngine() {
-    let currentEngine = await this.getActiveIMEEngine();
-    // XXX: this allowed 'null' to be passed into `adb.shell`
-    if (currentEngine) {
-      this.log.debug(`Attempting to deactivate ${currentEngine}`);
-      await this.adb.disableIME(currentEngine);
-    }
-  },
-};
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<string>}
+ */
+export async function getActiveIMEEngine() {
+  this.log.debug('Retrieving current default IME');
+  return String(await this.adb.defaultIME());
+}
 
-export default IMEMixin;
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} imeId
+ * @returns {Promise<void>}
+ */
+export async function activateIMEEngine(imeId) {
+  this.log.debug(`Attempting to activate IME ${imeId}`);
+  let availableEngines = await this.adb.availableIMEs();
+  if (availableEngines.indexOf(imeId) === -1) {
+    this.log.debug('IME not found, failing');
+    throw new errors.IMENotAvailableError();
+  }
+  this.log.debug('Found installed IME, attempting to activate');
+  await this.adb.enableIME(imeId);
+  await this.adb.setIME(imeId);
+}
 
-mixin(IMEMixin);
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @returns {Promise<void>}
+ */
+export async function deactivateIMEEngine() {
+  let currentEngine = await this.getActiveIMEEngine();
+  // XXX: this allowed 'null' to be passed into `adb.shell`
+  if (currentEngine) {
+    this.log.debug(`Attempting to deactivate ${currentEngine}`);
+    await this.adb.disableIME(currentEngine);
+  }
+}
 
 /**
  * @typedef {import('appium-adb').ADB} ADB

package/lib/commands/intent.js

@@ -1,8 +1,6 @@
-// @ts-check
-
-import {mixin} from './mixins';
 import _ from 'lodash';
 import {errors} from 'appium/driver';
+import {util} from '@appium/support';
 
 const NO_VALUE_ARG_TYPE = 'sn';
 const SUPPORTED_EXTRA_TYPES = [
@@ -25,6 +23,150 @@ const SUPPORTED_EXTRA_TYPES = [
 ];
 const API_LEVEL_ANDROID_8 = 26;
 
+/**
+ * @deprecated
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} appPackage
+ * @param {string} appActivity
+ * @param {string} [appWaitPackage]
+ * @param {string} [appWaitActivity]
+ * @param {string} [intentAction]
+ * @param {string} [intentCategory]
+ * @param {string} [intentFlags]
+ * @param {string} [optionalIntentArguments]
+ * @param {boolean} [dontStopAppOnReset]
+ * @returns {Promise<void>}
+ */
+export async function startActivity(
+  appPackage,
+  appActivity,
+  appWaitPackage,
+  appWaitActivity,
+  intentAction,
+  intentCategory,
+  intentFlags,
+  optionalIntentArguments,
+  dontStopAppOnReset,
+) {
+  this.log.debug(`Starting package '${appPackage}' and activity '${appActivity}'`);
+
+  // dontStopAppOnReset is both an argument here, and a desired capability
+  // if the argument is set, use it, otherwise use the cap
+  if (!util.hasValue(dontStopAppOnReset)) {
+    dontStopAppOnReset = !!this.opts.dontStopAppOnReset;
+  }
+
+  /** @type {import('appium-adb').StartAppOptions} */
+  let args = {
+    pkg: appPackage,
+    activity: appActivity,
+    waitPkg: appWaitPackage || appPackage,
+    waitActivity: appWaitActivity || appActivity,
+    action: intentAction,
+    category: intentCategory,
+    flags: intentFlags,
+    optionalIntentArguments,
+    stopApp: !dontStopAppOnReset,
+  };
+  this._cachedActivityArgs = this._cachedActivityArgs || {};
+  this._cachedActivityArgs[`${args.waitPkg}/${args.waitActivity}`] = args;
+  await this.adb.startApp(args);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').StartActivityOpts} [opts={}]
+ * @returns {Promise<string>}
+ */
+export async function mobileStartActivity(opts = {}) {
+  const {user, wait, stop, windowingMode, activityType, display} = opts;
+  const cmd = [
+    'am',
+    (await this.adb.getApiLevel()) < API_LEVEL_ANDROID_8 ? 'start' : 'start-activity',
+  ];
+  if (!_.isNil(user)) {
+    cmd.push('--user', String(user));
+  }
+  if (wait) {
+    cmd.push('-W');
+  }
+  if (stop) {
+    cmd.push('-S');
+  }
+  if (!_.isNil(windowingMode)) {
+    cmd.push('--windowingMode', String(windowingMode));
+  }
+  if (!_.isNil(activityType)) {
+    cmd.push('--activityType', String(activityType));
+  }
+  if (!_.isNil(display)) {
+    cmd.push('--display', String(display));
+  }
+  cmd.push(...parseIntentSpec(opts));
+  return await this.adb.shell(cmd);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').BroadcastOpts} [opts={}]
+ * @returns {Promise<string>}
+ */
+export async function mobileBroadcast(opts = {}) {
+  const {user, receiverPermission, allowBackgroundActivityStarts} = opts;
+  const cmd = ['am', 'broadcast'];
+  if (!_.isNil(user)) {
+    cmd.push('--user', String(user));
+  }
+  if (receiverPermission) {
+    cmd.push('--receiver-permission', receiverPermission);
+  }
+  if (allowBackgroundActivityStarts) {
+    cmd.push('--allow-background-activity-starts');
+  }
+  cmd.push(...parseIntentSpec(opts));
+  return await this.adb.shell(cmd);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').StartServiceOpts} [opts={}]
+ * @returns {Promise<string>}
+ */
+export async function mobileStartService(opts = {}) {
+  const {user, foreground} = opts;
+  const cmd = ['am'];
+  if ((await this.adb.getApiLevel()) < API_LEVEL_ANDROID_8) {
+    cmd.push('startservice');
+  } else {
+    cmd.push(foreground ? 'start-foreground-service' : 'start-service');
+  }
+  if (!_.isNil(user)) {
+    cmd.push('--user', String(user));
+  }
+  cmd.push(...parseIntentSpec(opts));
+  return await this.adb.shell(cmd);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').StopServiceOpts} [opts={}]
+ * @returns {Promise<string>}
+ */
+export async function mobileStopService(opts = {}) {
+  const {user} = opts;
+  const cmd = [
+    'am',
+    (await this.adb.getApiLevel()) < API_LEVEL_ANDROID_8 ? 'stopservice' : 'stop-service',
+  ];
+  if (!_.isNil(user)) {
+    cmd.push('--user', String(user));
+  }
+  cmd.push(...parseIntentSpec(opts));
+  return await this.adb.shell(cmd);
+}
+
+// #region Internal helpers
+
 /**
  *
  * @param {import('./types').IntentOpts} opts
@@ -73,12 +215,12 @@ function parseIntentSpec(opts = {}) {
       if (!_.includes(SUPPORTED_EXTRA_TYPES, type)) {
         throw new errors.InvalidArgumentError(
           `Extra argument type '${type}' is not known. ` +
-            `Supported intent argument types are: ${SUPPORTED_EXTRA_TYPES}`
+            `Supported intent argument types are: ${SUPPORTED_EXTRA_TYPES}`,
         );
       }
       if (_.isEmpty(key) || (_.isString(key) && _.trim(key) === '')) {
         throw new errors.InvalidArgumentError(
-          `Extra argument's key in '${JSON.stringify(item)}' must be a valid string identifier`
+          `Extra argument's key in '${JSON.stringify(item)}' must be a valid string identifier`,
         );
       }
       if (type === NO_VALUE_ARG_TYPE) {
@@ -86,7 +228,7 @@ function parseIntentSpec(opts = {}) {
       } else if (_.isUndefined(value)) {
         throw new errors.InvalidArgumentError(
           `Intent argument type '${type}' in '${JSON.stringify(item)}' requires a ` +
-            `valid value to be provided`
+            `valid value to be provided`,
         );
       } else {
         resultArgs.push(`--e${type}`, key, value);
@@ -99,91 +241,7 @@ function parseIntentSpec(opts = {}) {
   return resultArgs;
 }
 
-/**
- * @type {import('./mixins').ActivityMixin & ThisType<import('../driver').AndroidDriver>}
- * @satisfies {import('@appium/types').ExternalDriver}
- */
-const ActivityMixin = {
-  async mobileStartActivity(opts = {}) {
-    const {user, wait, stop, windowingMode, activityType, display} = opts;
-    const cmd = [
-      'am',
-      (await this.adb.getApiLevel()) < API_LEVEL_ANDROID_8
-        ? 'start'
-        : 'start-activity',
-    ];
-    if (!_.isNil(user)) {
-      cmd.push('--user', String(user));
-    }
-    if (wait) {
-      cmd.push('-W');
-    }
-    if (stop) {
-      cmd.push('-S');
-    }
-    if (!_.isNil(windowingMode)) {
-      cmd.push('--windowingMode', String(windowingMode));
-    }
-    if (!_.isNil(activityType)) {
-      cmd.push('--activityType', String(activityType));
-    }
-    if (!_.isNil(display)) {
-      cmd.push('--display', String(display));
-    }
-    cmd.push(...parseIntentSpec(opts));
-    return await this.adb.shell(cmd);
-  },
-
-  async mobileBroadcast(opts = {}) {
-    const {user, receiverPermission, allowBackgroundActivityStarts} = opts;
-    const cmd = ['am', 'broadcast'];
-    if (!_.isNil(user)) {
-      cmd.push('--user', String(user));
-    }
-    if (receiverPermission) {
-      cmd.push('--receiver-permission', receiverPermission);
-    }
-    if (allowBackgroundActivityStarts) {
-      cmd.push('--allow-background-activity-starts');
-    }
-    cmd.push(...parseIntentSpec(opts));
-    return await this.adb.shell(cmd);
-  },
-
-  async mobileStartService(opts = {}) {
-    const {user, foreground} = opts;
-    const cmd = ['am'];
-    if ((await this.adb.getApiLevel()) < API_LEVEL_ANDROID_8) {
-      cmd.push('startservice');
-    } else {
-      cmd.push(foreground ? 'start-foreground-service' : 'start-service');
-    }
-    if (!_.isNil(user)) {
-      cmd.push('--user', String(user));
-    }
-    cmd.push(...parseIntentSpec(opts));
-    return await this.adb.shell(cmd);
-  },
-
-  async mobileStopService(opts = {}) {
-    const {user} = opts;
-    const cmd = [
-      'am',
-      (await this.adb.getApiLevel()) < API_LEVEL_ANDROID_8
-        ? 'stopservice'
-        : 'stop-service',
-    ];
-    if (!_.isNil(user)) {
-      cmd.push('--user', String(user));
-    }
-    cmd.push(...parseIntentSpec(opts));
-    return await this.adb.shell(cmd);
-  },
-};
-
-mixin(ActivityMixin);
-
-export default ActivityMixin;
+// #endregion
 
 /**
  * @typedef {import('appium-adb').ADB} ADB