appium-android-driver 9.15.0 → 10.0.0

package/lib/commands/context/exports.js

@@ -73,16 +73,16 @@ export async function setContext(name) {
 
 /**
  * @this {AndroidDriver}
- * @param {any} [opts={}]
+ * @param {number} [waitForWebviewMs]
  * @returns {Promise<import('../types').WebviewsMapping[]>}
  */
-export async function mobileGetContexts(opts = {}) {
+export async function mobileGetContexts(waitForWebviewMs) {
   const _opts = {
     androidDeviceSocket: this.opts.androidDeviceSocket,
     ensureWebviewsHavePages: true,
     webviewDevtoolsPort: this.opts.webviewDevtoolsPort,
     enableWebviewDetailsCollection: true,
-    waitForWebviewMs: opts.waitForWebviewMs || 0,
+    waitForWebviewMs: waitForWebviewMs || 0,
   };
   return await getWebViewsMapping.bind(this)(_opts);
 }

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

@@ -1,6 +1,6 @@
 import {util} from '@appium/support';
-import {requireArgs} from '../../utils';
 import {requireEmulator} from './utils';
+import { errors } from 'appium/driver';
 
 /**
  * @deprecated Use mobile: extension
@@ -15,11 +15,14 @@ export async function fingerprint(fingerprintId) {
 
 /**
  * @this {import('../../driver').AndroidDriver}
- * @param {import('../types').FingerprintOpts} opts
+ * @param {string | number} fingerprintId The value is the `finger_id` for the finger that was "scanned". It is a
+ * unique integer that you assign for each virtual fingerprint. When the app
+ * is running you can run this same command each time the emulator prompts you
+ * for a fingerprint, you can run the adb command and pass it the `finger_id`
+ * to simulate the fingerprint scan.
  * @returns {Promise<void>}
  */
-export async function mobileFingerprint(opts) {
-  const {fingerprintId} = requireArgs('fingerprintId', opts);
+export async function mobileFingerprint(fingerprintId) {
   await this.fingerprint(fingerprintId);
 }
 
@@ -37,11 +40,11 @@ export async function sendSMS(phoneNumber, message) {
 
 /**
  * @this {import('../../driver').AndroidDriver}
- * @param {import('../types').SendSMSOpts} opts
+ * @param {string} phoneNumber The phone number to send SMS to
+ * @param {string} message The message payload
  * @returns {Promise<void>}
  */
-export async function mobileSendSms(opts) {
-  const {phoneNumber, message} = requireArgs(['phoneNumber', 'message'], opts);
+export async function mobileSendSms(phoneNumber, message) {
   await this.sendSMS(phoneNumber, message);
 }
 
@@ -59,11 +62,11 @@ export async function gsmCall(phoneNumber, action) {
 
 /**
  * @this {import('../../driver').AndroidDriver}
- * @param {import('../types').GsmCallOpts} opts
+ * @param {string} phoneNumber The phone number to call to
+ * @param {import('../types').GsmAction} action  Action to take
  * @returns {Promise<void>}
  */
-export async function mobileGsmCall(opts) {
-  const {phoneNumber, action} = requireArgs(['phoneNumber', 'action'], opts);
+export async function mobileGsmCall(phoneNumber, action) {
   await this.gsmCall(phoneNumber, action);
 }
 
@@ -80,11 +83,10 @@ export async function gsmSignal(signalStrengh) {
 
 /**
  * @this {import('../../driver').AndroidDriver}
- * @param {import('../types').GsmSignalStrengthOpts} opts
+ * @param {import('../types').GsmSignalStrength} strength The signal strength value
  * @returns {Promise<void>}
  */
-export async function mobileGsmSignal(opts) {
-  const {strength} = requireArgs('strength', opts);
+export async function mobileGsmSignal(strength) {
   await this.gsmSignal(strength);
 }
 
@@ -101,11 +103,10 @@ export async function gsmVoice(state) {
 
 /**
  * @this {import('../../driver').AndroidDriver}
- * @param {import('../types').GsmVoiceOpts} opts
+ * @param {import('../types').GsmVoiceState} state
  * @returns {Promise<void>}
  */
-export async function mobileGsmVoice(opts) {
-  const {state} = requireArgs('state', opts);
+export async function mobileGsmVoice(state) {
   await this.gsmVoice(state);
 }
 
@@ -122,11 +123,10 @@ export async function powerAC(state) {
 
 /**
  * @this {import('../../driver').AndroidDriver}
- * @param {import('../types').PowerACOpts} opts
+ * @param {import('../types').PowerACState} state
  * @returns {Promise<void>}
  */
-export async function mobilePowerAc(opts) {
-  const {state} = requireArgs('state', opts);
+export async function mobilePowerAc(state) {
   await this.powerAC(state);
 }
 
@@ -143,11 +143,10 @@ export async function powerCapacity(batteryPercent) {
 
 /**
  * @this {import('../../driver').AndroidDriver}
- * @param {import('../types').PowerCapacityOpts} opts
+ * @param {number} percent Percentage value in range `[0, 100]`
  * @return {Promise<void>}
  */
-export async function mobilePowerCapacity(opts) {
-  const {percent} = requireArgs('percent', opts);
+export async function mobilePowerCapacity(percent) {
   await this.powerCapacity(percent);
 }
 
@@ -164,27 +163,26 @@ export async function networkSpeed(networkSpeed) {
 
 /**
  * @this {import('../../driver').AndroidDriver}
- * @param {import('../types').NetworkSpeedOpts} opts
+ * @param {import('../types').NetworkSpeed} speed
  * @returns {Promise<void>}
  */
-export async function mobileNetworkSpeed(opts) {
-  const {speed} = requireArgs('speed', opts);
+export async function mobileNetworkSpeed(speed) {
   await this.networkSpeed(speed);
 }
 
 /**
  * @this {import('../../driver').AndroidDriver}
- * @param {import('../types').SensorSetOpts} opts
+ * @param {string} sensorType Sensor type as declared in `adb.SENSORS`
+ * @param {string} value Value to set to the sensor
  * @returns {Promise<void>}
  */
-export async function sensorSet(opts) {
+export async function sensorSet(sensorType, value) {
   requireEmulator.bind(this)('sensorSet is only available for emulators');
-  const {sensorType, value} = opts;
   if (!util.hasValue(sensorType)) {
-    throw this.log.errorWithException(`'sensorType' argument is required`);
+    throw new errors.InvalidArgumentError(`'sensorType' argument is required`);
   }
   if (!util.hasValue(value)) {
-    throw this.log.errorWithException(`'value' argument is required`);
+    throw new errors.InvalidArgumentError(`'value' argument is required`);
   }
   await this.adb.sensorSet(sensorType, /** @type {any} */ (value));
 }

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

@@ -4,14 +4,19 @@ const EMU_CONSOLE_FEATURE = 'emulator_console';
 
 /**
  * @this {import('../../driver').AndroidDriver}
- * @param {import('../types').ExecOptions} opts
  * @returns {Promise<string>}
+ * @param {string | string[]} command The actual command to execute.
+ * @see {@link https://developer.android.com/studio/run/emulator-console}
+ * @param {number} [execTimeout] A timeout used to wait for a server reply to the given command in
+ * milliseconds. 60000ms by default
+ * @param {number} [connTimeout] Console connection timeout in milliseconds.
+ * 5000ms by default.
+ * @param {number} [initTimeout] Telnet console initialization timeout in milliseconds (the time between the
+ * connection happens and the command prompt is available)
  */
-export async function mobileExecEmuConsoleCommand(opts) {
+export async function mobileExecEmuConsoleCommand(command, execTimeout, connTimeout, initTimeout) {
   this.assertFeatureEnabled(EMU_CONSOLE_FEATURE);
 
-  const {command, execTimeout, connTimeout, initTimeout} = opts;
-
   if (!command) {
     throw new errors.InvalidArgumentError(`The 'command' argument is mandatory`);
   }

package/lib/commands/deviceidle.js

@@ -8,12 +8,11 @@ const SUPPORTED_ACTIONS = ['whitelistAdd', 'whitelistRemove'];
  * Read https://www.protechtraining.com/blog/post/diving-into-android-m-doze-875
  * for more details.
  *
- * @param {import('./types').DeviceidleOpts} opts
+ * @param {'whitelistAdd' | 'whitelistRemove'} action The action name to execute
+ * @param {string} [packages] Either a single package or multiple packages to add or remove from the idle whitelist
  * @returns {Promise<void>}
  */
-export async function mobileDeviceidle(opts) {
-  const {action, packages} = opts;
-
+export async function mobileDeviceidle(action, packages) {
   if (!(_.isString(packages) || _.isArray(packages))) {
     throw new errors.InvalidArgumentError(`packages argument must be a string or an array`);
   }

package/lib/commands/execute.js

@@ -1,125 +1,20 @@
 import _ from 'lodash';
 import {errors, PROTOCOLS} from 'appium/driver';
+import { util } from '@appium/support';
 
-/**
- * @this {import('../driver').AndroidDriver}
- * @returns {import('@appium/types').StringRecord<string>}
- */
-export function mobileCommandsMapping() {
-  return {
-    shell: 'mobileShell',
-
-    execEmuConsoleCommand: 'mobileExecEmuConsoleCommand',
-
-    startLogsBroadcast: 'mobileStartLogsBroadcast',
-    stopLogsBroadcast: 'mobileStopLogsBroadcast',
-
-    changePermissions: 'mobileChangePermissions',
-    getPermissions: 'mobileGetPermissions',
-
-    performEditorAction: 'mobilePerformEditorAction',
-
-    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',
-    isLocked: 'isLocked',
-
-    refreshGpsCache: 'mobileRefreshGpsCache',
-
-    startMediaProjectionRecording: 'mobileStartMediaProjectionRecording',
-    isMediaProjectionRecordingRunning: 'mobileIsMediaProjectionRecordingRunning',
-    stopMediaProjectionRecording: 'mobileStopMediaProjectionRecording',
-
-    getConnectivity: 'mobileGetConnectivity',
-    setConnectivity: 'mobileSetConnectivity',
-
-    hideKeyboard: 'hideKeyboard',
-    isKeyboardShown: 'isKeyboardShown',
-
-    deviceidle: 'mobileDeviceidle',
-
-    bluetooth: 'mobileBluetooth',
-
-    nfc: 'mobileNfc',
-
-    setUiMode: 'mobileSetUiMode',
-    getUiMode: 'mobileGetUiMode',
-
-    injectEmulatorCameraImage: 'mobileInjectEmulatorCameraImage',
-
-    sendTrimMemory: 'mobileSendTrimMemory',
-
-    getPerformanceData: 'mobileGetPerformanceData',
-    getPerformanceDataTypes: 'getPerformanceDataTypes',
-
-    toggleGps: 'toggleLocationServices',
-    isGpsEnabled: 'isLocationServicesEnabled',
-
-    getDisplayDensity: 'getDisplayDensity',
-    getSystemBars: 'getSystemBars',
-    statusBar: 'mobilePerformStatusBarCommand',
-
-    fingerprint: 'mobileFingerprint',
-    sendSms: 'mobileSendSms',
-    gsmCall: 'mobileGsmCall',
-    gsmSignal: 'mobileGsmSignal',
-    gsmVoice: 'mobileGsmVoice',
-    powerAc: 'mobilePowerAc',
-    powerCapacity: 'mobilePowerCapacity',
-    networkSpeed: 'mobileNetworkSpeed',
-    sensorSet: 'sensorSet',
-
-    getCurrentActivity: 'getCurrentActivity',
-    getCurrentPackage: 'getCurrentPackage',
-
-    setGeolocation: 'mobileSetGeolocation',
-    getGeolocation: 'mobileGetGeolocation',
-    resetGeolocation: 'mobileResetGeolocation',
-  };
-}
+const EXECUTE_SCRIPT_PREFIX = 'mobile:';
 
 /**
- * @this {import('../driver').AndroidDriver}
+ * @this {AndroidDriver}
  * @param {string} script
- * @param {import('@appium/types').StringRecord[]|import('@appium/types').StringRecord} [args]
+ * @param {ExecuteMethodArgs} [args]
  * @returns {Promise<any>}
  */
 export 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,
-      Array.isArray(args) ? (args[0]) : args,
-    );
+  if (_.startsWith(script, EXECUTE_SCRIPT_PREFIX)) {
+    const formattedScript = script.trim().replace(/^mobile:\s*/, `${EXECUTE_SCRIPT_PREFIX} `);
+    const executeMethodArgs = preprocessExecuteMethodArgs(args);
+    return await this.executeMethod(formattedScript, [executeMethodArgs]);
   }
   if (!this.isWebContext()) {
     throw new errors.NotImplementedError();
@@ -137,19 +32,42 @@ export async function execute(script, args) {
   });
 }
 
+// #region Internal Helpers
+
 /**
- * @this {import('../driver').AndroidDriver}
- * @param {string} mobileCommand
- * @param {import('@appium/types').StringRecord} [opts={}]
- * @returns {Promise<any>}
+ * Massages the arguments going into an execute method.
+ *
+ * @param {ExecuteMethodArgs} [args]
+ * @returns {StringRecord}
  */
-export async function executeMobile(mobileCommand, opts = {}) {
-  const mobileCommandsMapping = this.mobileCommandsMapping();
-  if (!(mobileCommand in mobileCommandsMapping)) {
-    throw new errors.UnknownCommandError(
-      `Unknown mobile command "${mobileCommand}". ` +
-      `Only ${_.keys(mobileCommandsMapping)} commands are supported.`,
+function preprocessExecuteMethodArgs(args) {
+  const executeMethodArgs = /** @type {StringRecord} */ ((_.isArray(args) ? _.first(args) : 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;
+  }
+
+  /**
+   * Automatically unwraps the `elementId` prop _if and only if_ the execute method expects it.
+   */
+  if ('elementId' in executeMethodArgs) {
+    executeMethodArgs.elementId = util.unwrapElement(
+      /** @type {import('@appium/types').Element|string} */ (executeMethodArgs.elementId),
     );
   }
-  return await this[mobileCommandsMapping[mobileCommand]](opts);
+
+  return executeMethodArgs;
 }
+
+// #endregion
+
+/**
+ * @typedef {import('../driver').AndroidDriver} AndroidDriver
+ * @typedef {import('@appium/types').StringRecord} StringRecord
+ * @typedef {readonly any[] | readonly [StringRecord] | Readonly<StringRecord>} ExecuteMethodArgs
+ */

package/lib/commands/file-actions.js

@@ -2,7 +2,6 @@ import _ from 'lodash';
 import {fs, util, zip, tempDir} from '@appium/support';
 import path from 'path';
 import {errors} from 'appium/driver';
-import {requireArgs} from '../utils';
 
 const CONTAINER_PATH_MARKER = '@';
 // https://regex101.com/r/PLdB0G/2
@@ -11,7 +10,10 @@ const ANDROID_MEDIA_RESCAN_INTENT = 'android.intent.action.MEDIA_SCANNER_SCAN_FI
 
 /**
  * @this {import('../driver').AndroidDriver}
- * @param {string} remotePath
+ * @param {string} remotePath The full path to the remote file or a specially formatted path, which
+ * points to an item inside an app bundle, for example `@my.app.id/my/path`.
+ * It is mandatory for the app bundle to have debugging enabled in order to
+ * use the latter `remotePath` format.
  * @returns {Promise<string>}
  */
 export async function pullFile(remotePath) {
@@ -59,18 +61,11 @@ export async function pullFile(remotePath) {
 
 /**
  * @this {import('../driver').AndroidDriver}
- * @param {import('./types').PullFileOpts} opts
- * @returns {Promise<string>}
- */
-export async function mobilePullFile(opts) {
-  const {remotePath} = requireArgs('remotePath', opts);
-  return await this.pullFile(remotePath);
-}
-
-/**
- * @this {import('../driver').AndroidDriver}
- * @param {string} remotePath
- * @param {string} base64Data
+ * @param {string} remotePath The full path to the remote file or a specially formatted path, which
+ * points to an item inside an app bundle, for example `@my.app.id/my/path`.
+ * It is mandatory for the app bundle to have debugging enabled in order to
+ * use the latter `remotePath` format.
+ * @param {string} base64Data Base64-encoded content of the file to be pushed.
  * @returns {Promise<void>}
  */
 export async function pushFile(remotePath, base64Data) {
@@ -138,17 +133,7 @@ export async function pushFile(remotePath, base64Data) {
 
 /**
  * @this {import('../driver').AndroidDriver}
- * @param {import('./types').PushFileOpts} opts
- * @returns {Promise<void>}
- */
-export async function mobilePushFile(opts) {
-  const {remotePath, payload} = requireArgs(['remotePath', 'payload'], opts);
-  return await this.pushFile(remotePath, payload);
-}
-
-/**
- * @this {import('../driver').AndroidDriver}
- * @param {string} remotePath
+ * @param {string} remotePath The full path to the remote folder
  * @returns {Promise<string>}
  */
 export async function pullFolder(remotePath) {
@@ -167,21 +152,11 @@ export async function pullFolder(remotePath) {
 
 /**
  * @this {import('../driver').AndroidDriver}
- * @param {import('./types').PullFolderOpts} opts
- * @returns {Promise<string>}
- */
-export async function mobilePullFolder(opts) {
-  const {remotePath} = requireArgs('remotePath', opts);
-  return await this.pullFolder(remotePath);
-}
-
-/**
- * @this {import('../driver').AndroidDriver}
- * @param {import('./types').DeleteFileOpts} opts
+ * @param {string} remotePath The full path to the remote file or a file inside an application bundle
+ * (for example `@my.app.id/path/in/bundle`)
  * @returns {Promise<boolean>}
  */
-export async function mobileDeleteFile(opts) {
-  const {remotePath} = requireArgs('remotePath', opts);
+export async function mobileDeleteFile(remotePath) {
   if (remotePath.endsWith('/')) {
     throw new errors.InvalidArgumentError(
       `It is expected that remote path points to a folder and not to a file. ` +

package/lib/commands/geolocation.js

@@ -37,10 +37,16 @@ export async function setGeoLocation(location) {
 
 /**
  * @this {import('../driver').AndroidDriver}
- * @param {import('@appium/types').Location} opts
+ * @param {number} latitude
+ * @param {number} longitude
+ * @param {number} [altitude]
  */
-export async function mobileSetGeolocation(opts) {
-  await this.settingsApp.setGeoLocation(opts, this.isEmulator());
+export async function mobileSetGeolocation(latitude, longitude, altitude) {
+  await this.settingsApp.setGeoLocation({
+    latitude,
+    longitude,
+    altitude,
+  }, this.isEmulator());
 }
 
 /**
@@ -51,11 +57,13 @@ export async function mobileSetGeolocation(opts) {
  * must be at version 30 (Android R) or higher.
  *
  * @this {import('../driver').AndroidDriver}
- * @param {import('./types').GpsCacheRefreshOpts} [opts={}]
+ * @param {number} [timeoutMs] The maximum number of milliseconds
+ * to block until GPS cache is refreshed. Providing zero or a negative
+ * value to it skips waiting completely.
+ * 20000ms by default.
  * @returns {Promise<void>}
  */
-export async function mobileRefreshGpsCache(opts = {}) {
-  const {timeoutMs} = opts;
+export async function mobileRefreshGpsCache(timeoutMs) {
   await this.settingsApp.refreshGeoLocationCache(timeoutMs);
 }
 

package/lib/commands/image-injection.js

@@ -75,15 +75,14 @@ export async function prepareEmulatorForImageInjection(sdkRoot) {
  * `injectedImageProperties` capability.
  *
  * @this {AndroidDriver}
- * @param {import('./types').ImageInjectionOpts} opts
+ * @param {string} payload Base64-encoded payload of a .png image to be injected
  * @returns {Promise<void>}
  */
-export async function mobileInjectEmulatorCameraImage(opts) {
+export async function mobileInjectEmulatorCameraImage(payload) {
   if (!this.isEmulator()) {
     throw new Error('The image injection feature is only available on emulators');
   }
 
-  const {payload} = opts;
   if (!_.isString(payload) || _.size(payload) <= PNG_MAGIC_LENGTH) {
     throw new errors.InvalidArgumentError(
       `You must provide a valid base64-encoded .PNG data as the 'payload' argument`