appium-adb 14.3.1 → 14.3.3

package/lib/tools/apks-utils.ts

@@ -1,14 +1,14 @@
 import {exec} from 'teen_process';
-import {log} from '../logger.js';
+import {log} from '../logger';
 import path from 'node:path';
 import _ from 'lodash';
 import {fs, tempDir, util} from '@appium/support';
 import {LRUCache} from 'lru-cache';
-import {getJavaForOs, unzipFile, buildInstallArgs, APK_INSTALL_TIMEOUT} from '../helpers.js';
+import {getJavaForOs, unzipFile, buildInstallArgs, APK_INSTALL_TIMEOUT} from '../helpers';
 import AsyncLock from 'async-lock';
 import B from 'bluebird';
-import type {ADB} from '../adb.js';
-import type {InstallMultipleApksOptions, InstallApksOptions, StringRecord} from './types.js';
+import type {ADB} from '../adb';
+import type {InstallMultipleApksOptions, InstallApksOptions, StringRecord} from './types';
 
 const BASE_APK = 'base-master.apk';
 const LANGUAGE_APK = (lang: string) => `base-${lang}.apk`;
@@ -39,55 +39,6 @@ process.on('exit', () => {
   }
 });
 
-/**
- * Extracts the particular apks package into a temporary folder,
- * finds and returns the full path to the file contained in this apk.
- * The resulting temporary path, where the .apks file has been extracted,
- * will be stored into the internal LRU cache for better performance.
- *
- * @param apks - The full path to the .apks file
- * @param dstPath - The relative path to the destination file,
- * which is going to be extracted, where each path component is an array item
- * @returns Full path to the extracted file
- * @throws {Error} If the requested item does not exist in the extracted archive or the provides
- * apks file is not a valid bundle
- */
-async function extractFromApks(apks: string, dstPath: string | string[]): Promise<string> {
-  const normalizedDstPath = _.isArray(dstPath) ? dstPath : [dstPath];
-
-  return await APKS_CACHE_GUARD.acquire(apks, async () => {
-    // It might be that the original file has been replaced,
-    // so we need to keep the hash sums instead of the actual file paths
-    // as caching keys
-    const apksHash = await fs.hash(apks);
-    log.debug(`Calculated '${apks}' hash: ${apksHash}`);
-
-    if (APKS_CACHE.has(apksHash)) {
-      const cachedRoot = APKS_CACHE.get(apksHash);
-      if (cachedRoot) {
-        const resultPath = path.resolve(cachedRoot, ...normalizedDstPath);
-        if (await fs.exists(resultPath)) {
-          return resultPath;
-        }
-      }
-      APKS_CACHE.delete(apksHash);
-    }
-
-    const tmpRoot = await tempDir.openDir();
-    log.debug(`Unpacking application bundle at '${apks}' to '${tmpRoot}'`);
-    await unzipFile(apks, tmpRoot);
-    const resultPath = path.resolve(tmpRoot, ...normalizedDstPath);
-    if (!(await fs.exists(resultPath))) {
-      throw new Error(
-        `${normalizedDstPath.join(path.sep)} cannot be found in '${apks}' bundle. ` +
-          `Does the archive contain a valid application bundle?`,
-      );
-    }
-    APKS_CACHE.set(apksHash, tmpRoot);
-    return resultPath;
-  });
-}
-
 /**
  * Executes bundletool utility with given arguments and returns the actual stdout
  *
@@ -275,3 +226,52 @@ export async function extractLanguageApk(
 export function isTestPackageOnlyError(output: string): boolean {
   return /\[INSTALL_FAILED_TEST_ONLY\]/.test(output);
 }
+
+/**
+ * Extracts the particular apks package into a temporary folder,
+ * finds and returns the full path to the file contained in this apk.
+ * The resulting temporary path, where the .apks file has been extracted,
+ * will be stored into the internal LRU cache for better performance.
+ *
+ * @param apks - The full path to the .apks file
+ * @param dstPath - The relative path to the destination file,
+ * which is going to be extracted, where each path component is an array item
+ * @returns Full path to the extracted file
+ * @throws {Error} If the requested item does not exist in the extracted archive or the provides
+ * apks file is not a valid bundle
+ */
+async function extractFromApks(apks: string, dstPath: string | string[]): Promise<string> {
+  const normalizedDstPath = _.isArray(dstPath) ? dstPath : [dstPath];
+
+  return await APKS_CACHE_GUARD.acquire(apks, async () => {
+    // It might be that the original file has been replaced,
+    // so we need to keep the hash sums instead of the actual file paths
+    // as caching keys
+    const apksHash = await fs.hash(apks);
+    log.debug(`Calculated '${apks}' hash: ${apksHash}`);
+
+    if (APKS_CACHE.has(apksHash)) {
+      const cachedRoot = APKS_CACHE.get(apksHash);
+      if (cachedRoot) {
+        const resultPath = path.resolve(cachedRoot, ...normalizedDstPath);
+        if (await fs.exists(resultPath)) {
+          return resultPath;
+        }
+      }
+      APKS_CACHE.delete(apksHash);
+    }
+
+    const tmpRoot = await tempDir.openDir();
+    log.debug(`Unpacking application bundle at '${apks}' to '${tmpRoot}'`);
+    await unzipFile(apks, tmpRoot);
+    const resultPath = path.resolve(tmpRoot, ...normalizedDstPath);
+    if (!(await fs.exists(resultPath))) {
+      throw new Error(
+        `${normalizedDstPath.join(path.sep)} cannot be found in '${apks}' bundle. ` +
+          `Does the archive contain a valid application bundle?`,
+      );
+    }
+    APKS_CACHE.set(apksHash, tmpRoot);
+    return resultPath;
+  });
+}

package/lib/tools/app-commands.ts

@@ -1,9 +1,9 @@
 import _ from 'lodash';
 import {fs, tempDir, util, system} from '@appium/support';
-import {log} from '../logger.js';
+import {log} from '../logger';
 import {waitForCondition} from 'asyncbox';
 import path from 'node:path';
-import type {ADB} from '../adb.js';
+import type {ADB} from '../adb';
 import type {ExecError} from 'teen_process';
 import type {
   StringRecord,
@@ -16,7 +16,7 @@ import type {
   PackageActivityInfo,
   ListInstalledPackagesOptions,
   ListInstalledPackagesResult,
-} from './types.js';
+} from './types';
 
 // Constants
 export const APP_INSTALL_STATE: StringRecord<InstallState> = {
@@ -35,6 +35,18 @@ const LAUNCHER_CATEGORY = 'android.intent.category.LAUNCHER';
 
 // Public methods
 
+export interface StartCmdOptions {
+  user?: number | string;
+  waitForLaunch?: boolean;
+  pkg?: string;
+  activity?: string;
+  action?: string;
+  category?: string;
+  stopApp?: boolean;
+  flags?: string;
+  optionalIntentArguments?: string;
+}
+
 /**
  * Verify whether the given argument is a
  * valid class name.
@@ -1159,8 +1171,6 @@ export async function isAppRunning(this: ADB, pkg: string): Promise<boolean> {
   return !_.isEmpty(await this.listAppProcessIds(pkg));
 }
 
-// Private methods
-
 /**
  * Parses optional intent arguments from a string.
  *
@@ -1235,17 +1245,3 @@ function escapeShellArg(arg: string): string {
   }
   return arg.replace(/&/g, '\\&');
 }
-
-// Type definitions
-
-export interface StartCmdOptions {
-  user?: number | string;
-  waitForLaunch?: boolean;
-  pkg?: string;
-  activity?: string;
-  action?: string;
-  category?: string;
-  stopApp?: boolean;
-  flags?: string;
-  optionalIntentArguments?: string;
-}

package/lib/tools/device-settings.ts

@@ -1,10 +1,10 @@
-import {log} from '../logger.js';
+import {log} from '../logger';
 import _ from 'lodash';
 import {retryInterval} from 'asyncbox';
 import {util} from '@appium/support';
 import B from 'bluebird';
-import type {ADB} from '../adb.js';
-import type {SetPropOpts} from './types.js';
+import type {ADB} from '../adb';
+import type {SetPropOpts} from './types';
 import type {ExecError} from 'teen_process';
 
 const ANIMATION_SCALE_KEYS = [
@@ -288,19 +288,6 @@ export async function toggleGPSLocationProvider(this: ADB, enabled: boolean): Pr
   await this.shell(['cmd', 'location', 'set-location-enabled', enabled ? 'true' : 'false']);
 }
 
-/**
- * Decorates an exception message with a solution link
- *
- * @param e The error object to be decorated
- * @returns Either the same error or the decorated one
- */
-function decorateWriteSecureSettingsException(e: Error): Error {
-  if (_.includes(e.message, 'requires:android.permission.WRITE_SECURE_SETTINGS')) {
-    e.message = `Check https://github.com/appium/appium/issues/13802 for throubleshooting. ${e.message}`;
-  }
-  return e;
-}
-
 /**
  * Set hidden api policy to manage access to non-SDK APIs.
  * https://developer.android.com/preview/restrictions-non-sdk-interfaces
@@ -715,6 +702,19 @@ export async function getScreenOrientation(this: ADB): Promise<number | null> {
 
 // #region Private functions
 
+/**
+ * Decorates an exception message with a solution link
+ *
+ * @param e The error object to be decorated
+ * @returns Either the same error or the decorated one
+ */
+function decorateWriteSecureSettingsException(e: Error): Error {
+  if (_.includes(e.message, 'requires:android.permission.WRITE_SECURE_SETTINGS')) {
+    e.message = `Check https://github.com/appium/appium/issues/13802 for throubleshooting. ${e.message}`;
+  }
+  return e;
+}
+
 /**
  * Reads SurfaceOrientation in dumpsys output
  *

package/lib/tools/emulator-commands.ts

@@ -1,11 +1,11 @@
-import {log} from '../logger.js';
+import {log} from '../logger';
 import _ from 'lodash';
 import net from 'node:net';
 import {util, fs} from '@appium/support';
 import B from 'bluebird';
 import path from 'node:path';
 import * as ini from 'ini';
-import type {ADB} from '../adb.js';
+import type {ADB} from '../adb';
 import type {
   EmuInfo,
   EmuVersionInfo,
@@ -17,57 +17,7 @@ import type {
   GsmVoiceStates,
   NetworkSpeed,
   ExecTelnetOptions,
-} from './types.js';
-
-/**
- * Retrieves the list of available Android emulators
- *
- * @returns
- */
-async function listEmulators(): Promise<EmuInfo[]> {
-  let avdsRoot = process.env.ANDROID_AVD_HOME;
-  if (await dirExists(avdsRoot ?? '')) {
-    return await getAvdConfigPaths(avdsRoot as string);
-  }
-
-  if (avdsRoot) {
-    log.warn(
-      `The value of the ANDROID_AVD_HOME environment variable '${avdsRoot}' is not an existing directory`,
-    );
-  }
-
-  const prefsRoot = await getAndroidPrefsRoot();
-  if (!prefsRoot) {
-    return [];
-  }
-
-  avdsRoot = path.resolve(prefsRoot, 'avd');
-  if (!(await dirExists(avdsRoot))) {
-    log.debug(`Virtual devices config root '${avdsRoot}' is not an existing directory`);
-    return [];
-  }
-
-  return await getAvdConfigPaths(avdsRoot);
-}
-
-/**
- * Get configuration paths of all virtual devices
- *
- * @param avdsRoot Path to the directory that contains the AVD .ini files
- * @returns
- */
-async function getAvdConfigPaths(avdsRoot: string): Promise<EmuInfo[]> {
-  const configs = await fs.glob('*.ini', {
-    cwd: avdsRoot,
-    absolute: true,
-  });
-  return configs
-    .map((confPath) => {
-      const avdName = path.basename(confPath).split('.').slice(0, -1).join('.');
-      return {name: avdName, config: confPath};
-    })
-    .filter(({name}) => _.trim(name));
-}
+} from './types';
 
 /**
  * Check the emulator state.
@@ -480,6 +430,56 @@ export async function sendTelnetCommand(this: ADB, command: string): Promise<str
 
 // #region Private functions
 
+/**
+ * Retrieves the list of available Android emulators
+ *
+ * @returns
+ */
+async function listEmulators(): Promise<EmuInfo[]> {
+  let avdsRoot = process.env.ANDROID_AVD_HOME;
+  if (await dirExists(avdsRoot ?? '')) {
+    return await getAvdConfigPaths(avdsRoot as string);
+  }
+
+  if (avdsRoot) {
+    log.warn(
+      `The value of the ANDROID_AVD_HOME environment variable '${avdsRoot}' is not an existing directory`,
+    );
+  }
+
+  const prefsRoot = await getAndroidPrefsRoot();
+  if (!prefsRoot) {
+    return [];
+  }
+
+  avdsRoot = path.resolve(prefsRoot, 'avd');
+  if (!(await dirExists(avdsRoot))) {
+    log.debug(`Virtual devices config root '${avdsRoot}' is not an existing directory`);
+    return [];
+  }
+
+  return await getAvdConfigPaths(avdsRoot);
+}
+
+/**
+ * Get configuration paths of all virtual devices
+ *
+ * @param avdsRoot Path to the directory that contains the AVD .ini files
+ * @returns
+ */
+async function getAvdConfigPaths(avdsRoot: string): Promise<EmuInfo[]> {
+  const configs = await fs.glob('*.ini', {
+    cwd: avdsRoot,
+    absolute: true,
+  });
+  return configs
+    .map((confPath) => {
+      const avdName = path.basename(confPath).split('.').slice(0, -1).join('.');
+      return {name: avdName, config: confPath};
+    })
+    .filter(({name}) => _.trim(name));
+}
+
 /**
  * Retrieves the full path to the Android preferences root
  *

package/lib/tools/fs-commands.ts

@@ -1,12 +1,8 @@
 import _ from 'lodash';
 import path from 'node:path';
-import type {ADB} from '../adb.js';
+import type {ADB} from '../adb';
 import type {TeenProcessExecOptions} from 'teen_process';
 
-function shellEscapeSingleQuotes(str: string): string {
-  return str.replace(/'/g, "'\\''");
-}
-
 /**
  * Verify whether a remote path exists on the device under test.
  *
@@ -132,3 +128,7 @@ export async function pull(
 export async function mkdir(this: ADB, remotePath: string): Promise<string> {
   return await this.shell([`mkdir -p -- '${shellEscapeSingleQuotes(remotePath)}'`]);
 }
+
+function shellEscapeSingleQuotes(str: string): string {
+  return str.replace(/'/g, "'\\''");
+}

package/lib/tools/general-commands.ts

@@ -1,9 +1,9 @@
-import {log} from '../logger.js';
+import {log} from '../logger';
 import _ from 'lodash';
 import {fs, util} from '@appium/support';
 import {SubProcess, exec, type ExecError} from 'teen_process';
-import type {ADB} from '../adb.js';
-import type {ScreenrecordOptions, StringRecord} from './types.js';
+import type {ADB} from '../adb';
+import type {ScreenrecordOptions, StringRecord} from './types';
 
 /**
  * Get the path to adb executable amd assign it

package/lib/tools/keyboard-commands.ts

@@ -1,8 +1,8 @@
-import {log} from '../logger.js';
+import {log} from '../logger';
 import {waitForCondition} from 'asyncbox';
 import B from 'bluebird';
-import type {ADB} from '../adb.js';
-import type {KeyboardState} from './types.js';
+import type {ADB} from '../adb';
+import type {KeyboardState} from './types';
 
 const KEYCODE_ESC = 111;
 const KEYCODE_BACK = 4;

package/lib/tools/lockmgmt.ts

@@ -1,8 +1,8 @@
-import {log} from '../logger.js';
+import {log} from '../logger';
 import _ from 'lodash';
 import B from 'bluebird';
 import {waitForCondition} from 'asyncbox';
-import type {ADB} from '../adb.js';
+import type {ADB} from '../adb';
 
 const CREDENTIAL_CANNOT_BE_NULL_OR_EMPTY_ERROR = `Credential can't be null or empty`;
 const CREDENTIAL_DID_NOT_MATCH_ERROR = `didn't match`;
@@ -11,51 +11,6 @@ const KEYCODE_POWER = 26;
 const KEYCODE_WAKEUP = 224; // works over API Level 20
 const HIDE_KEYBOARD_WAIT_TIME = 100;
 
-/**
- * @param verb
- * @param oldCredential
- * @param args
- */
-function buildCommand(
-  verb: string,
-  oldCredential: string | null = null,
-  ...args: string[]
-): string[] {
-  const cmd = ['locksettings', verb];
-  if (oldCredential && !_.isEmpty(oldCredential)) {
-    cmd.push('--old', oldCredential);
-  }
-  if (!_.isEmpty(args)) {
-    cmd.push(...args);
-  }
-  return cmd;
-}
-
-/**
- * Performs swipe up gesture on the screen
- *
- * @param windowDumpsys The output of `adb shell dumpsys window` command
- * @throws {Error} If the display size cannot be retrieved
- */
-async function swipeUp(this: ADB, windowDumpsys: string): Promise<void> {
-  const dimensionsMatch = /init=(\d+)x(\d+)/.exec(windowDumpsys);
-  if (!dimensionsMatch) {
-    throw new Error('Cannot retrieve the display size');
-  }
-  const displayWidth = parseInt(dimensionsMatch[1], 10);
-  const displayHeight = parseInt(dimensionsMatch[2], 10);
-  const x0 = displayWidth / 2;
-  const y0 = (displayHeight / 5) * 4;
-  const x1 = x0;
-  const y1 = displayHeight / 5;
-  await this.shell([
-    'input',
-    'touchscreen',
-    'swipe',
-    ...[x0, y0, x1, y1].map((c) => `${Math.trunc(c)}`),
-  ]);
-}
-
 /**
  * Check whether the device supports lock settings management with `locksettings`
  * command line tool. This tool has been added to Android toolset since  API 27 Oreo
@@ -323,8 +278,90 @@ export async function lock(this: ADB): Promise<void> {
   }
 }
 
+/**
+ * Checks mShowingLockscreen or mDreamingLockscreen in dumpsys output to determine
+ * if lock screen is showing
+ *
+ * A note: `adb shell dumpsys trust` performs better while detecting the locked screen state
+ * in comparison to `adb dumpsys window` output parsing.
+ * But the trust command does not work for `Swipe` unlock pattern.
+ *
+ * In some Android devices (Probably around Android 10+), `mShowingLockscreen` and `mDreamingLockscreen`
+ * do not work to detect lock status. Instead, keyguard preferences helps to detect the lock condition.
+ * Some devices such as Android TV do not have keyguard, so we should keep
+ * screen condition as this primary method.
+ *
+ * @param dumpsys - The output of dumpsys window command.
+ * @return True if lock screen is showing.
+ */
+export function isShowingLockscreen(dumpsys: string): boolean {
+  return (
+    _.some(['mShowingLockscreen=true', 'mDreamingLockscreen=true'], (x) => dumpsys.includes(x)) ||
+    // `mIsShowing` and `mInputRestricted` are `true` in lock condition. `false` is unlock condition.
+    _.every([/KeyguardStateMonitor[\n\s]+mIsShowing=true/, /\s+mInputRestricted=true/], (x) =>
+      x.test(dumpsys),
+    )
+  );
+}
+
+/**
+ * Checks screenState has SCREEN_STATE_OFF in dumpsys output to determine
+ * possible lock screen.
+ *
+ * @param dumpsys - The output of dumpsys window command.
+ * @return True if lock screen is showing.
+ */
+export function isScreenStateOff(dumpsys: string): boolean {
+  return /\s+screenState=SCREEN_STATE_OFF/i.test(dumpsys);
+}
+
 // #region Private functions
 
+/**
+ * @param verb
+ * @param oldCredential
+ * @param args
+ */
+function buildCommand(
+  verb: string,
+  oldCredential: string | null = null,
+  ...args: string[]
+): string[] {
+  const cmd = ['locksettings', verb];
+  if (oldCredential && !_.isEmpty(oldCredential)) {
+    cmd.push('--old', oldCredential);
+  }
+  if (!_.isEmpty(args)) {
+    cmd.push(...args);
+  }
+  return cmd;
+}
+
+/**
+ * Performs swipe up gesture on the screen
+ *
+ * @param windowDumpsys The output of `adb shell dumpsys window` command
+ * @throws {Error} If the display size cannot be retrieved
+ */
+async function swipeUp(this: ADB, windowDumpsys: string): Promise<void> {
+  const dimensionsMatch = /init=(\d+)x(\d+)/.exec(windowDumpsys);
+  if (!dimensionsMatch) {
+    throw new Error('Cannot retrieve the display size');
+  }
+  const displayWidth = parseInt(dimensionsMatch[1], 10);
+  const displayHeight = parseInt(dimensionsMatch[2], 10);
+  const x0 = displayWidth / 2;
+  const y0 = (displayHeight / 5) * 4;
+  const x1 = x0;
+  const y1 = displayHeight / 5;
+  await this.shell([
+    'input',
+    'touchscreen',
+    'swipe',
+    ...[x0, y0, x1, y1].map((c) => `${Math.trunc(c)}`),
+  ]);
+}
+
 /**
  * Checks mScreenOnFully in dumpsys output to determine if screen is showing
  * Default is true.
@@ -365,41 +402,4 @@ function isInDozingMode(dumpsys: string): boolean {
   return /^[\s\w]+wakefulness[^=]*=Dozing$/im.test(dumpsys);
 }
 
-/**
- * Checks mShowingLockscreen or mDreamingLockscreen in dumpsys output to determine
- * if lock screen is showing
- *
- * A note: `adb shell dumpsys trust` performs better while detecting the locked screen state
- * in comparison to `adb dumpsys window` output parsing.
- * But the trust command does not work for `Swipe` unlock pattern.
- *
- * In some Android devices (Probably around Android 10+), `mShowingLockscreen` and `mDreamingLockscreen`
- * do not work to detect lock status. Instead, keyguard preferences helps to detect the lock condition.
- * Some devices such as Android TV do not have keyguard, so we should keep
- * screen condition as this primary method.
- *
- * @param dumpsys - The output of dumpsys window command.
- * @return True if lock screen is showing.
- */
-export function isShowingLockscreen(dumpsys: string): boolean {
-  return (
-    _.some(['mShowingLockscreen=true', 'mDreamingLockscreen=true'], (x) => dumpsys.includes(x)) ||
-    // `mIsShowing` and `mInputRestricted` are `true` in lock condition. `false` is unlock condition.
-    _.every([/KeyguardStateMonitor[\n\s]+mIsShowing=true/, /\s+mInputRestricted=true/], (x) =>
-      x.test(dumpsys),
-    )
-  );
-}
-
-/**
- * Checks screenState has SCREEN_STATE_OFF in dumpsys output to determine
- * possible lock screen.
- *
- * @param dumpsys - The output of dumpsys window command.
- * @return True if lock screen is showing.
- */
-export function isScreenStateOff(dumpsys: string): boolean {
-  return /\s+screenState=SCREEN_STATE_OFF/i.test(dumpsys);
-}
-
 // #endregion

package/lib/tools/logcat-commands.ts

@@ -1,7 +1,7 @@
 import _ from 'lodash';
 import {Logcat} from '../logcat';
-import type {ADB} from '../adb.js';
-import type {LogcatOpts, LogEntry, LogcatListener} from './types.js';
+import type {ADB} from '../adb';
+import type {LogcatOpts, LogEntry, LogcatListener} from './types';
 
 /**
  * Start the logcat process to gather logs.

package/lib/tools/network-commands.ts

@@ -1,8 +1,8 @@
 import {EOL} from 'node:os';
 import _ from 'lodash';
-import {log} from '../logger.js';
-import type {ADB} from '../adb.js';
-import type {PortFamily, PortInfo} from './types.js';
+import {log} from '../logger';
+import type {ADB} from '../adb';
+import type {PortFamily, PortInfo} from './types';
 
 /**
  * Get TCP port forwarding with adb on the device under test.

package/lib/tools/process-commands.ts

@@ -1,8 +1,8 @@
 import _ from 'lodash';
-import {log} from '../logger.js';
+import {log} from '../logger';
 import B from 'bluebird';
 import type {ExecError} from 'teen_process';
-import type {ADB} from '../adb.js';
+import type {ADB} from '../adb';
 
 const PID_COLUMN_TITLE: string = 'PID';
 const PROCESS_NAME_COLUMN_TITLE: string = 'NAME';