appium-android-driver 12.4.7 → 12.4.9

package/lib/commands/{file-actions.js → file-actions.ts}

@@ -2,6 +2,8 @@ import _ from 'lodash';
 import {fs, util, zip, tempDir} from '@appium/support';
 import path from 'path';
 import {errors} from 'appium/driver';
+import type {AndroidDriver} from '../driver';
+import type {ADB} from 'appium-adb';
 
 const CONTAINER_PATH_MARKER = '@';
 // https://regex101.com/r/PLdB0G/2
@@ -9,21 +11,31 @@ const CONTAINER_PATH_PATTERN = new RegExp(`^${CONTAINER_PATH_MARKER}([^/]+)/(.+)
 const ANDROID_MEDIA_RESCAN_INTENT = 'android.intent.action.MEDIA_SCANNER_SCAN_FILE';
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @param {string} remotePath The full path to the remote file or a specially formatted path, which
+ * Pulls a file from the remote device.
+ *
+ * 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 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>}
+ * @returns Promise that resolves to the file content as a base64-encoded string.
+ * @throws {errors.InvalidArgumentError} If the remote path points to a folder instead of a file.
  */
-export async function pullFile(remotePath) {
+export async function pullFile(
+  this: AndroidDriver,
+  remotePath: string,
+): Promise<string> {
   if (remotePath.endsWith('/')) {
     throw new errors.InvalidArgumentError(
       `It is expected that remote path points to a file and not to a folder. ` +
         `'${remotePath}' is given instead`,
     );
   }
-  let tmpDestination = null;
+  let tmpDestination: string | null = null;
   if (remotePath.startsWith(CONTAINER_PATH_MARKER)) {
     const [packageId, pathInContainer] = parseContainerPath(remotePath);
     this.log.debug(
@@ -41,7 +53,7 @@ export async function pullFile(remotePath) {
       throw this.log.errorWithException(
         `Cannot access the container of '${packageId}' application. ` +
           `Is the application installed and has 'debuggable' build option set to true? ` +
-          `Original error: ${/** @type {Error} */ (e).message}`,
+          `Original error: ${(e as Error).message}`,
       );
     }
   }
@@ -60,15 +72,27 @@ export async function pullFile(remotePath) {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @param {string} remotePath The full path to the remote file or a specially formatted path, which
+ * Pushes a file to the remote device.
+ *
+ * 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>}
+ *
+ * @param 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 base64Data Base64-encoded content of the file to be pushed.
+ * Can be a string or an array of numbers (for Java clients that send byte arrays).
+ * @returns Promise that resolves when the file is pushed.
+ * @throws {errors.InvalidArgumentError} If the remote path points to a folder instead of a file.
  */
-export async function pushFile(remotePath, base64Data) {
+export async function pushFile(
+  this: AndroidDriver,
+  remotePath: string,
+  base64Data: string | number[],
+): Promise<void> {
   if (remotePath.endsWith('/')) {
     throw new errors.InvalidArgumentError(
       `It is expected that remote path points to a file and not to a folder. ` +
@@ -76,13 +100,16 @@ export async function pushFile(remotePath, base64Data) {
     );
   }
   const localFile = await tempDir.path({prefix: 'appium', suffix: '.tmp'});
+  let base64String: string;
   if (_.isArray(base64Data)) {
     // some clients (ahem) java, send a byte array encoding utf8 characters
     // instead of a string, which would be infinitely better!
-    base64Data = Buffer.from(base64Data).toString('utf8');
+    base64String = Buffer.from(base64Data).toString('utf8');
+  } else {
+    base64String = base64Data;
   }
-  const content = Buffer.from(base64Data, 'base64');
-  let tmpDestination = null;
+  const content = Buffer.from(base64String, 'base64');
+  let tmpDestination: string | null = null;
   try {
     await fs.writeFile(localFile, content.toString('binary'), 'binary');
     if (remotePath.startsWith(CONTAINER_PATH_MARKER)) {
@@ -110,7 +137,7 @@ export async function pushFile(remotePath, base64Data) {
         throw this.log.errorWithException(
           `Cannot access the container of '${packageId}' application. ` +
             `Is the application installed and has 'debuggable' build option set to true? ` +
-            `Original error: ${/** @type {Error} */ (e).message}`,
+            `Original error: ${(e as Error).message}`,
         );
       }
     } else {
@@ -132,11 +159,15 @@ export async function pushFile(remotePath, base64Data) {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @param {string} remotePath The full path to the remote folder
- * @returns {Promise<string>}
+ * Pulls a folder from the remote device.
+ *
+ * @param remotePath The full path to the remote folder.
+ * @returns Promise that resolves to the folder content as a base64-encoded zip file string.
  */
-export async function pullFolder(remotePath) {
+export async function pullFolder(
+  this: AndroidDriver,
+  remotePath: string,
+): Promise<string> {
   const tmpRoot = await tempDir.openDir();
   try {
     await this.adb.pull(remotePath, tmpRoot);
@@ -151,12 +182,17 @@ export async function pullFolder(remotePath) {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @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>}
+ * Deletes a file from the remote device.
+ *
+ * @param 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 that resolves to `true` if the file was successfully deleted, `false` if it doesn't exist.
+ * @throws {errors.InvalidArgumentError} If the remote path points to a folder instead of a file.
  */
-export async function mobileDeleteFile(remotePath) {
+export async function mobileDeleteFile(
+  this: AndroidDriver,
+  remotePath: string,
+): Promise<boolean> {
   if (remotePath.endsWith('/')) {
     throw new errors.InvalidArgumentError(
       `It is expected that remote path points to a folder and not to a file. ` +
@@ -169,21 +205,20 @@ export async function mobileDeleteFile(remotePath) {
 /**
  * Deletes the given folder or file from the remote device
  *
- * @param {ADB} adb
- * @param {string} remotePath The full path to the remote folder
- * or file (folder names must end with a single slash)
  * @throws {Error} If the provided remote path is invalid or
  * the package content cannot be accessed
- * @returns {Promise<boolean>} `true` if the remote item has been successfully deleted.
+ * @returns `true` if the remote item has been successfully deleted.
  * If the remote path is valid, but the remote path does not exist
  * this function return `false`.
- * @this {import('../driver').AndroidDriver}
  */
-async function deleteFileOrFolder(adb, remotePath) {
+async function deleteFileOrFolder(
+  this: AndroidDriver,
+  adb: ADB,
+  remotePath: string,
+): Promise<boolean> {
   const {isDir, isPresent, isFile} = createFSTests(adb);
   let dstPath = remotePath;
-  /** @type {string|undefined} */
-  let pkgId;
+  let pkgId: string | undefined;
   if (remotePath.startsWith(CONTAINER_PATH_MARKER)) {
     const [packageId, pathInContainer] = parseContainerPath(remotePath);
     this.log.debug(`Parsed package identifier '${packageId}' from '${remotePath}'`);
@@ -198,7 +233,7 @@ async function deleteFileOrFolder(adb, remotePath) {
       throw this.log.errorWithException(
         `Cannot access the container of '${pkgId}' application. ` +
           `Is the application installed and has 'debuggable' build option set to true? ` +
-          `Original error: ${/** @type {Error} */ (e).message}`,
+          `Original error: ${(e as Error).message}`,
       );
     }
   }
@@ -233,13 +268,11 @@ async function deleteFileOrFolder(adb, remotePath) {
 /**
  * Parses the actual destination path from the given value
  *
- * @param {string} remotePath The preformatted remote path, which looks like
- * `@my.app.id/my/path`
- * @returns {Array<string>} An array, where the first item is the parsed package
+ * @returns An array, where the first item is the parsed package
  * identifier and the second one is the actual destination path inside the package.
  * @throws {Error} If the given string cannot be parsed
  */
-function parseContainerPath(remotePath) {
+function parseContainerPath(remotePath: string): [string, string] {
   const match = CONTAINER_PATH_PATTERN.exec(remotePath);
   if (!match) {
     throw new Error(
@@ -254,11 +287,11 @@ function parseContainerPath(remotePath) {
  * Scans the given file/folder on the remote device
  * and adds matching items to the device's media library.
  * Exceptions are ignored and written into the log.
- *
- * @this {import('../driver').AndroidDriver}
- * @param {string} remotePath The file/folder path on the remote device
  */
-async function scanMedia(remotePath) {
+async function scanMedia(
+  this: AndroidDriver,
+  remotePath: string,
+): Promise<void> {
   this.log.debug(`Performing media scan of '${remotePath}'`);
   try {
     // https://github.com/appium/appium/issues/16184
@@ -275,7 +308,7 @@ async function scanMedia(remotePath) {
       ]);
     }
   } catch (e) {
-    const err = /** @type {any} */ (e);
+    const err = e as {stderr?: string; message?: string};
     // FIXME: what has a `stderr` prop?
     this.log.warn(
       `Ignoring an unexpected error upon media scanning of '${remotePath}': ${
@@ -288,27 +321,20 @@ async function scanMedia(remotePath) {
 /**
  * A small helper, which escapes single quotes in paths,
  * so they are safe to be passed as arguments of shell commands
- *
- * @param {string} p The initial remote path
- * @returns {string} The escaped path value
  */
-function escapePath(p) {
+function escapePath(p: string): string {
   return p.replace(/'/g, `\\'`);
 }
 
 /**
  * Factory providing filesystem test functions using ADB
- * @param {ADB} adb
  */
-function createFSTests(adb) {
-  /**
-   *
-   * @param {string} p
-   * @param {'d'|'f'|'e'} op
-   * @param {string} [runAs]
-   * @returns
-   */
-  const performRemoteFsCheck = async (p, op, runAs) => {
+function createFSTests(adb: ADB) {
+  const performRemoteFsCheck = async (
+    p: string,
+    op: 'd' | 'f' | 'e',
+    runAs?: string,
+  ): Promise<boolean> => {
     const passFlag = '__PASS__';
     const checkCmd = `[ -${op} '${escapePath(p)}' ] && echo ${passFlag}`;
     const fullCmd = runAs ? `run-as ${runAs} ${checkCmd}` : checkCmd;
@@ -319,27 +345,15 @@ function createFSTests(adb) {
     }
   };
 
-  /**
-   * @param {string} p
-   * @param {string} [runAs]
-   */
-  const isFile = async (p, runAs) => await performRemoteFsCheck(p, 'f', runAs);
-  /**
-   * @param {string} p
-   * @param {string} [runAs]
-   */
-  const isDir = async (p, runAs) => await performRemoteFsCheck(p, 'd', runAs);
-  /**
-   * @param {string} p
-   * @param {string} [runAs]
-   */
-  const isPresent = async (p, runAs) => await performRemoteFsCheck(p, 'e', runAs);
+  const isFile = async (p: string, runAs?: string): Promise<boolean> =>
+    await performRemoteFsCheck(p, 'f', runAs);
+  const isDir = async (p: string, runAs?: string): Promise<boolean> =>
+    await performRemoteFsCheck(p, 'd', runAs);
+  const isPresent = async (p: string, runAs?: string): Promise<boolean> =>
+    await performRemoteFsCheck(p, 'e', runAs);
 
   return {isFile, isDir, isPresent};
 }
 
 // #endregion
 
-/**
- * @typedef {import('appium-adb').ADB} ADB
- */

package/lib/commands/{geolocation.js → geolocation.ts}

@@ -2,8 +2,10 @@ import _ from 'lodash';
 import {fs, tempDir} from '@appium/support';
 import path from 'node:path';
 import B from 'bluebird';
+import type {Location} from '@appium/types';
 import {SETTINGS_HELPER_ID} from 'io.appium.settings';
 import {getThirdPartyPackages} from './app-management';
+import type {AndroidDriver} from '../driver';
 
 // The value close to zero, but not zero, is needed
 // to trick JSON generation and send a float value instead of an integer,
@@ -14,17 +16,21 @@ 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>}
+ * Sets the device geolocation.
+ *
+ * @param location The geolocation object containing latitude, longitude, and altitude.
+ * @returns Promise that resolves to the current geolocation after setting it.
  */
-export async function setGeoLocation(location) {
+export async function setGeoLocation(
+  this: AndroidDriver,
+  location: Location,
+): Promise<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}`,
+      `Could not get the current geolocation info: ${(e as Error).message}`,
     );
     this.log.warn(`Returning the default zero'ed values`);
     return {
@@ -38,28 +44,28 @@ export async function setGeoLocation(location) {
 /**
  * Set the device geolocation.
  *
- * @this {import('../driver').AndroidDriver}
- * @param {number} latitude Valid latitude value.
- * @param {number} longitude Valid longitude value.
- * @param {number} [altitude] Valid altitude value.
- * @param {number} [satellites] Number of satellites being tracked (1-12). Available for emulators.
- * @param {number} [speed] Valid speed value.
+ * @param latitude Valid latitude value.
+ * @param longitude Valid longitude value.
+ * @param altitude Valid altitude value.
+ * @param satellites Number of satellites being tracked (1-12). Available for emulators.
+ * @param speed Valid speed value.
  * https://developer.android.com/reference/android/location/Location#setSpeed(float)
- * @param {number} [bearing] Valid bearing value. Available for real devices.
+ * @param bearing Valid bearing value. Available for real devices.
  * https://developer.android.com/reference/android/location/Location#setBearing(float)
- * @param {number} [accuracy] Valid accuracy value. Available for real devices.
+ * @param accuracy Valid accuracy value. Available for real devices.
  * https://developer.android.com/reference/android/location/Location#setAccuracy(float),
  * https://developer.android.com/reference/android/location/Criteria
  */
 export async function mobileSetGeolocation(
-  latitude,
-  longitude,
-  altitude,
-  satellites,
-  speed,
-  bearing,
-  accuracy
-) {
+  this: AndroidDriver,
+  latitude: number,
+  longitude: number,
+  altitude?: number,
+  satellites?: number,
+  speed?: number,
+  bearing?: number,
+  accuracy?: number,
+): Promise<void> {
   await this.settingsApp.setGeoLocation({
     latitude,
     longitude,
@@ -67,7 +73,7 @@ export async function mobileSetGeolocation(
     satellites,
     speed,
     bearing,
-    accuracy
+    accuracy,
   }, this.isEmulator());
 }
 
@@ -78,22 +84,27 @@ export async function mobileSetGeolocation(
  * 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 {number} [timeoutMs] The maximum number of milliseconds
+ * @param 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>}
+ * @returns Promise that resolves when the GPS cache refresh is initiated.
  */
-export async function mobileRefreshGpsCache(timeoutMs) {
+export async function mobileRefreshGpsCache(
+  this: AndroidDriver,
+  timeoutMs?: number,
+): Promise<void> {
   await this.settingsApp.refreshGeoLocationCache(timeoutMs);
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<import('@appium/types').Location>}
+ * Gets the current device geolocation.
+ *
+ * @returns Promise that resolves to the current geolocation object.
  */
-export async function getGeoLocation() {
+export async function getGeoLocation(
+  this: AndroidDriver,
+): Promise<Location> {
   const {latitude, longitude, altitude} = await this.settingsApp.getGeoLocation();
   return {
     latitude: parseFloat(String(latitude)) || GEO_EPSILON,
@@ -103,26 +114,35 @@ export async function getGeoLocation() {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<import('@appium/types').Location>}
+ * Gets the current device geolocation.
+ *
+ * @returns Promise that resolves to the current geolocation object.
  */
-export async function mobileGetGeolocation() {
+export async function mobileGetGeolocation(
+  this: AndroidDriver,
+): Promise<Location> {
   return await this.getGeoLocation();
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<boolean>}
+ * Checks if location services are enabled.
+ *
+ * @returns Promise that resolves to `true` if location services are enabled, `false` otherwise.
  */
-export async function isLocationServicesEnabled() {
+export async function isLocationServicesEnabled(
+  this: AndroidDriver,
+): Promise<boolean> {
   return (await this.adb.getLocationProviders()).includes('gps');
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * Toggles the location services state.
+ *
+ * @returns Promise that resolves when the location services state is toggled.
  */
-export async function toggleLocationServices() {
+export async function toggleLocationServices(
+  this: AndroidDriver,
+): Promise<void> {
   this.log.info('Toggling location services');
   const isGpsEnabled = await this.isLocationServicesEnabled();
   this.log.debug(
@@ -133,10 +153,14 @@ export async function toggleLocationServices() {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * Resets the geolocation to the default state.
+ *
+ * @returns Promise that resolves when the geolocation is reset.
+ * @throws {Error} If called on an emulator (geolocation reset does not work on emulators).
  */
-export async function mobileResetGeolocation() {
+export async function mobileResetGeolocation(
+  this: AndroidDriver,
+): Promise<void> {
   if (this.isEmulator()) {
     throw new Error('Geolocation reset does not work on emulators');
   }
@@ -146,20 +170,23 @@ export async function mobileResetGeolocation() {
 // #region Internal helpers
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @param {string} appId
- * @returns {Promise<void>}
+ * Sets the mock location permission for a specific app.
+ *
+ * @param appId The application package identifier.
+ * @returns Promise that resolves when the mock location permission is set.
  */
-export async function setMockLocationApp(appId) {
+export async function setMockLocationApp(
+  this: AndroidDriver,
+  appId: string,
+): Promise<void> {
   try {
     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}`);
+    this.log.warn(`Unable to set mock location for app '${appId}': ${(err as Error).message}`);
     return;
   }
   try {
-    /** @type {string[]} */
-    let pkgIds = [];
+    let pkgIds: string[] = [];
     if (await this.adb.fileExists(MOCK_APP_IDS_STORE)) {
       try {
         pkgIds = JSON.parse(await this.adb.shell(['cat', MOCK_APP_IDS_STORE]));
@@ -178,18 +205,21 @@ export async function setMockLocationApp(appId) {
       await fs.rimraf(tmpRoot);
     }
   } catch (e) {
-    this.log.warn(`Unable to persist mock location app id '${appId}': ${e.message}`);
+    this.log.warn(`Unable to persist mock location app id '${appId}': ${(e as Error).message}`);
   }
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * Resets the mock location permissions for all apps.
+ *
+ * @returns Promise that resolves when the mock location permissions are reset.
  */
-async function resetMockLocation() {
+async function resetMockLocation(
+  this: AndroidDriver,
+): Promise<void> {
   try {
     const thirdPartyPkgIdsPromise = getThirdPartyPackages.bind(this)();
-    let pkgIds = [];
+    let pkgIds: string[] = [];
     if (await this.adb.fileExists(MOCK_APP_IDS_STORE)) {
       try {
         pkgIds = JSON.parse(await this.adb.shell(['cat', MOCK_APP_IDS_STORE]));
@@ -220,8 +250,9 @@ async function resetMockLocation() {
       ),
     );
   } catch (err) {
-    this.log.warn(`Unable to reset mock location: ${err.message}`);
+    this.log.warn(`Unable to reset mock location: ${(err as Error).message}`);
   }
 }
 
 // #endregion Internal helpers
+