appium-adb 14.3.2 → 14.3.3

package/lib/logcat.ts

@@ -36,6 +36,8 @@ export interface LogcatOptions {
   maxBufferSize?: number;
 }
 
+type LogFormat = (typeof SUPPORTED_FORMATS)[number];
+
 export class Logcat extends EventEmitter {
   private readonly adb: ADBExecutable;
   private readonly clearLogs: boolean;
@@ -187,12 +189,6 @@ export class Logcat extends EventEmitter {
   }
 }
 
-export default Logcat;
-
-// Private entities
-
-type LogFormat = (typeof SUPPORTED_FORMATS)[number];
-
 function requireFormat(format: string): LogFormat {
   if (!SUPPORTED_FORMATS.includes(format as LogFormat)) {
     log.info(`The format value '${format}' is unknown. Supported values are: ${SUPPORTED_FORMATS}`);
@@ -242,3 +238,5 @@ function formatFilterSpecs(filterSpecs: string | string[]): string[] {
     .filter((spec) => spec && _.isString(spec) && !spec.startsWith('-'))
     .map((spec) => (spec.includes(':') ? requireSpec(spec) : spec));
 }
+
+export default Logcat;

package/lib/tools/apk-utils.ts

@@ -583,43 +583,6 @@ export async function getApkInfo(this: ADB, appPath: string): Promise<AppInfo |
 
 // #region Private functions
 
-/**
- * Formats the config marker, which is then passed to parse.. methods
- * to make it compatible with resource formats generated by aapt(2) tool
- *
- * @param configsGetter The function whose result is a list
- * of apk configs
- * @param desiredMarker The desired config marker value
- * @param defaultMarker The default config marker value
- * @returns The formatted config marker
- */
-async function formatConfigMarker(
-  configsGetter: () => Promise<string[]>,
-  desiredMarker: string | null,
-  defaultMarker: string,
-): Promise<string> {
-  let configMarker = desiredMarker || defaultMarker;
-  if (configMarker.includes('-') && !configMarker.includes('-r')) {
-    configMarker = configMarker.replace('-', '-r');
-  }
-  const configs = await configsGetter();
-  log.debug(`Resource configurations: ${JSON.stringify(configs)}`);
-  // Assume the 'en' configuration is the default one
-  if (
-    configMarker.toLowerCase().startsWith('en') &&
-    !configs.some((x) => x.trim() === configMarker)
-  ) {
-    log.debug(
-      `Resource configuration name '${configMarker}' is unknown. ` +
-        `Replacing it with '${defaultMarker}'`,
-    );
-    configMarker = defaultMarker;
-  } else {
-    log.debug(`Selected configuration: '${configMarker}'`);
-  }
-  return configMarker;
-}
-
 /**
  * Parses apk strings from aapt2 tool output
  *
@@ -812,4 +775,41 @@ export function parseAaptStrings(rawOutput: string, configMarker: string): Strin
   return apkStrings;
 }
 
+/**
+ * Formats the config marker, which is then passed to parse.. methods
+ * to make it compatible with resource formats generated by aapt(2) tool
+ *
+ * @param configsGetter The function whose result is a list
+ * of apk configs
+ * @param desiredMarker The desired config marker value
+ * @param defaultMarker The default config marker value
+ * @returns The formatted config marker
+ */
+async function formatConfigMarker(
+  configsGetter: () => Promise<string[]>,
+  desiredMarker: string | null,
+  defaultMarker: string,
+): Promise<string> {
+  let configMarker = desiredMarker || defaultMarker;
+  if (configMarker.includes('-') && !configMarker.includes('-r')) {
+    configMarker = configMarker.replace('-', '-r');
+  }
+  const configs = await configsGetter();
+  log.debug(`Resource configurations: ${JSON.stringify(configs)}`);
+  // Assume the 'en' configuration is the default one
+  if (
+    configMarker.toLowerCase().startsWith('en') &&
+    !configs.some((x) => x.trim() === configMarker)
+  ) {
+    log.debug(
+      `Resource configuration name '${configMarker}' is unknown. ` +
+        `Replacing it with '${defaultMarker}'`,
+    );
+    configMarker = defaultMarker;
+  } else {
+    log.debug(`Selected configuration: '${configMarker}'`);
+  }
+  return configMarker;
+}
+
 // #endregion

package/lib/tools/apks-utils.ts

@@ -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

@@ -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

@@ -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

@@ -19,56 +19,6 @@ import type {
   ExecTelnetOptions,
 } from './types';
 
-/**
- * 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));
-}
-
 /**
  * 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

@@ -3,10 +3,6 @@ import path from 'node:path';
 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/lockmgmt.ts

@@ -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/system-calls.ts

@@ -43,7 +43,15 @@ const MIN_DELAY_ADB_API_LEVEL = 28;
 const REQUIRED_SERVICES = ['activity', 'package', 'window'] as const;
 const MAX_SHELL_BUFFER_LENGTH = 1000;
 
-// Private methods (defined early as they're used by public methods)
+/**
+ * Retrieve full path to the given binary.
+ *
+ * @param binaryName - The name of the binary
+ * @returns The full path to the binary
+ */
+export async function getSdkBinaryPath(this: ADB, binaryName: string): Promise<string> {
+  return await this.getBinaryFromSdkRoot(binaryName);
+}
 
 /**
  * Retrieve full binary name for the current operating system.
@@ -93,18 +101,6 @@ async function getOpenSslForOs(): Promise<string> {
   }
 }
 
-// Public methods
-
-/**
- * Retrieve full path to the given binary.
- *
- * @param binaryName - The name of the binary
- * @returns The full path to the binary
- */
-export async function getSdkBinaryPath(this: ADB, binaryName: string): Promise<string> {
-  return await this.getBinaryFromSdkRoot(binaryName);
-}
-
 export const getBinaryNameForOS = _.memoize(_getBinaryNameForOS);
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-adb",
-  "version": "14.3.2",
+  "version": "14.3.3",
   "description": "Android Debug Bridge interface",
   "main": "./build/lib/index.js",
   "scripts": {