appium-adb 14.3.4 → 14.4.0

package/lib/utils/helpers/index.ts

@@ -0,0 +1,10 @@
+export {
+  APKS_EXTENSION,
+  APK_EXTENSION,
+  APK_INSTALL_TIMEOUT,
+  DEFAULT_ADB_EXEC_TIMEOUT,
+} from './constants';
+export {buildInstallArgs, type BuildInstallArgsOptions} from './install';
+export {readPackageManifest} from './manifest';
+export {getResourcePath, unzipFile} from './resource';
+export {getSdkRootFromEnv, requireSdkRoot, getJavaHome, getJavaForOs} from './sdk';

package/lib/utils/helpers/install.ts

@@ -0,0 +1,50 @@
+import {util} from '@appium/support';
+import {log} from '../../logger';
+
+export interface BuildInstallArgsOptions {
+  replace?: boolean;
+  allowTestPackages?: boolean;
+  useSdcard?: boolean;
+  grantPermissions?: boolean;
+  partialInstall?: boolean;
+}
+
+/**
+ * Builds command-line arguments for `adb install`.
+ *
+ * @param apiLevel - Android API level of the target device
+ * @param options - Install options mapped to adb flags
+ * @returns A list of install flags
+ */
+export function buildInstallArgs(
+  apiLevel: number,
+  options: BuildInstallArgsOptions = {},
+): string[] {
+  const result: string[] = [];
+
+  if (!util.hasValue(options.replace) || options.replace) {
+    result.push('-r');
+  }
+  if (options.allowTestPackages) {
+    result.push('-t');
+  }
+  if (options.useSdcard) {
+    result.push('-s');
+  }
+  if (options.grantPermissions) {
+    if (apiLevel < 23) {
+      log.debug(
+        `Skipping permissions grant option, since ` +
+          `the current API level ${apiLevel} does not support applications ` +
+          `permissions customization`,
+      );
+    } else {
+      result.push('-g');
+    }
+  }
+  if (options.partialInstall) {
+    result.push('-p');
+  }
+
+  return result;
+}

package/lib/utils/helpers/manifest.ts

@@ -0,0 +1,127 @@
+import {util} from '@appium/support';
+import {exec, type ExecError} from 'teen_process';
+import {log} from '../../logger';
+import type {ADB} from '../../adb';
+import type {ApkManifest} from '../../tools/types';
+
+/**
+ * Reads and parses Android manifest metadata from an APK via `aapt2`.
+ *
+ * @param apkPath - Local path to the APK file
+ * @returns Parsed manifest data
+ */
+export async function readPackageManifest(this: ADB, apkPath: string): Promise<ApkManifest> {
+  await this.initAapt2();
+  const aapt2Binary = this.binaries?.aapt2;
+  if (!aapt2Binary) {
+    throw new Error('aapt2 binary is not available');
+  }
+
+  const args = ['dump', 'badging', apkPath];
+  log.debug(`Reading package manifest: '${util.quote([aapt2Binary, ...args])}'`);
+  let stdout: string;
+  try {
+    ({stdout} = await exec(aapt2Binary, args));
+  } catch (e: unknown) {
+    const error = e as ExecError;
+    const prefix = `Cannot read the manifest from '${apkPath}'`;
+    const suffix = `Original error: ${error.stderr || error.message}`;
+    if (error.stderr && error.stderr.includes(`Unable to open 'badging'`)) {
+      throw new Error(`${prefix}. Update build tools to use a newer aapt2 version. ${suffix}`, {
+        cause: e,
+      });
+    }
+    throw new Error(`${prefix}. ${suffix}`, {cause: e});
+  }
+
+  const extractValue = (
+    line: string,
+    propPattern: RegExp,
+    valueTransformer: ((x: string) => any) | null,
+  ): any => {
+    const match = propPattern.exec(line);
+    if (match) {
+      return valueTransformer ? valueTransformer(match[1]) : match[1];
+    }
+    return undefined;
+  };
+  const extractArray = (
+    line: string,
+    propPattern: RegExp,
+    valueTransformer: ((x: string) => any) | null,
+  ): any[] => {
+    let match: RegExpExecArray | null;
+    const resultArray: any[] = [];
+    while ((match = propPattern.exec(line))) {
+      resultArray.push(valueTransformer ? valueTransformer(match[1]) : match[1]);
+    }
+    return resultArray;
+  };
+
+  const toInt = (x: string): number => parseInt(x, 10);
+
+  const result: ApkManifest = {
+    name: '',
+    versionCode: 0,
+    minSdkVersion: 0,
+    compileSdkVersion: 0,
+    usesPermissions: [],
+    launchableActivity: {
+      name: '',
+    },
+    architectures: [],
+    locales: [],
+    densities: [],
+  };
+  for (const line of stdout.split('\n')) {
+    if (line.startsWith('package:')) {
+      for (const [name, pattern, transformer] of [
+        ['name', /name='([^']+)'/, null],
+        ['versionCode', /versionCode='([^']+)'/, toInt],
+        ['versionName', /versionName='([^']+)'/, null],
+        ['platformBuildVersionName', /platformBuildVersionName='([^']+)'/, null],
+        ['platformBuildVersionCode', /platformBuildVersionCode='([^']+)'/, toInt],
+        ['compileSdkVersion', /compileSdkVersion='([^']+)'/, toInt],
+        ['compileSdkVersionCodename', /compileSdkVersionCodename='([^']+)'/, null],
+      ] as const) {
+        const value = extractValue(line, pattern, transformer);
+        if (value !== undefined) {
+          (result as Record<string, any>)[name] = value;
+        }
+      }
+    } else if (line.startsWith('sdkVersion:') || line.startsWith('minSdkVersion:')) {
+      const value = extractValue(line, /[sS]dkVersion:'([^']+)'/, toInt);
+      if (value) {
+        result.minSdkVersion = value;
+      }
+    } else if (line.startsWith('targetSdkVersion:')) {
+      const value = extractValue(line, /targetSdkVersion:'([^']+)'/, toInt);
+      if (value) {
+        result.targetSdkVersion = value;
+      }
+    } else if (line.startsWith('uses-permission:')) {
+      const value = extractValue(line, /name='([^']+)'/, null);
+      if (value) {
+        result.usesPermissions.push(value);
+      }
+    } else if (line.startsWith('launchable-activity:')) {
+      for (const [name, pattern] of [
+        ['name', /name='([^']+)'/],
+        ['label', /label='([^']+)'/],
+        ['icon', /icon='([^']+)'/],
+      ] as const) {
+        const value = extractValue(line, pattern, null);
+        if (value) {
+          (result.launchableActivity as Record<string, any>)[name] = value;
+        }
+      }
+    } else if (line.startsWith('locales:')) {
+      result.locales = extractArray(line, /'([^']+)'/g, null) as string[];
+    } else if (line.startsWith('native-code:')) {
+      result.architectures = extractArray(line, /'([^']+)'/g, null) as string[];
+    } else if (line.startsWith('densities:')) {
+      result.densities = extractArray(line, /'([^']+)'/g, toInt) as number[];
+    }
+  }
+  return result;
+}

package/lib/utils/helpers/resource.ts

@@ -0,0 +1,63 @@
+import path from 'node:path';
+import {fs, zip, util} from '@appium/support';
+import {log} from '../../logger';
+import {MODULE_NAME} from './constants';
+
+// Declare __filename for CommonJS compatibility
+declare const __filename: string;
+
+export const getResourcePath = util.memoize(async function getResourcePath(
+  relPath: string,
+): Promise<string> {
+  const moduleRoot = await getModuleRoot();
+  const resultPath = path.resolve(moduleRoot, relPath);
+  if (!(await fs.exists(resultPath))) {
+    throw new Error(
+      `Cannot find the resource '${relPath}' under the '${moduleRoot}' ` +
+        `folder of ${MODULE_NAME} Node.js module`,
+    );
+  }
+  return resultPath;
+});
+
+/**
+ * Unzips an archive into the target destination directory.
+ *
+ * @param zipPath - Source zip file path
+ * @param dstRoot - Destination directory. Defaults to zip parent directory
+ */
+export async function unzipFile(
+  zipPath: string,
+  dstRoot: string = path.dirname(zipPath),
+): Promise<void> {
+  log.debug(`Unzipping '${zipPath}' to '${dstRoot}'`);
+  await zip.assertValidZip(zipPath);
+  await zip.extractAllTo(zipPath, dstRoot);
+  log.debug('Unzip successful');
+}
+
+const getModuleRoot = util.memoize(async function getModuleRoot(): Promise<string> {
+  let moduleRoot = path.dirname(path.resolve(__filename));
+  let isAtFsRoot = false;
+  while (!isAtFsRoot) {
+    const manifestPath = path.join(moduleRoot, 'package.json');
+    try {
+      if (await fs.exists(manifestPath)) {
+        const manifestContent = await fs.readFile(manifestPath, 'utf8');
+        const manifest = JSON.parse(manifestContent) as {name?: string};
+        if (manifest.name === MODULE_NAME) {
+          return moduleRoot;
+        }
+      }
+    } catch {
+      // Ignore errors and continue searching
+    }
+    const parentDir = path.dirname(moduleRoot);
+    isAtFsRoot = moduleRoot.length <= parentDir.length;
+    moduleRoot = parentDir;
+  }
+  if (isAtFsRoot) {
+    throw new Error(`Cannot find the root folder of the ${MODULE_NAME} Node.js module`);
+  }
+  return moduleRoot;
+});

package/lib/utils/helpers/sdk.ts

@@ -0,0 +1,81 @@
+import {fs, system, util} from '@appium/support';
+import path from 'node:path';
+
+/**
+ * Gets Android SDK root from environment variables.
+ *
+ * @returns SDK root path if present
+ */
+export function getSdkRootFromEnv(): string | undefined {
+  return process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
+}
+
+/**
+ * Resolves and validates Android SDK root path.
+ *
+ * @param customRoot - Optional explicit SDK root path override
+ * @returns Absolute path to a valid SDK root directory
+ */
+export async function requireSdkRoot(customRoot: string | null = null): Promise<string> {
+  const sdkRoot = customRoot || getSdkRootFromEnv();
+  const docMsg =
+    'Read https://developer.android.com/studio/command-line/variables for more details';
+  if (!sdkRoot || util.isEmpty(sdkRoot)) {
+    throw new Error(
+      `Neither ANDROID_HOME nor ANDROID_SDK_ROOT environment variable was exported. ${docMsg}`,
+    );
+  }
+  if (!(await fs.exists(sdkRoot))) {
+    throw new Error(
+      `The Android SDK root folder '${sdkRoot}' does not exist on the local file system. ${docMsg}`,
+    );
+  }
+
+  const stats = await fs.stat(sdkRoot);
+  if (!stats.isDirectory()) {
+    throw new Error(`The Android SDK root '${sdkRoot}' must be a folder. ${docMsg}`);
+  }
+  return sdkRoot;
+}
+
+export const getJavaHome = util.memoize(async function getJavaHome(): Promise<string> {
+  const result = process.env.JAVA_HOME;
+  if (!result) {
+    throw new Error('The JAVA_HOME environment variable is not set for the current process');
+  }
+  if (!(await fs.exists(result))) {
+    throw new Error(`The JAVA_HOME location '${result}' must exist`);
+  }
+  const stats = await fs.stat(result);
+  if (!stats.isDirectory()) {
+    throw new Error(`The JAVA_HOME location '${result}' must be a valid folder`);
+  }
+  return result;
+});
+
+export const getJavaForOs = util.memoize(async function getJavaForOs(): Promise<string> {
+  let javaHome: string | undefined;
+  let errMsg: string | undefined;
+  try {
+    javaHome = await getJavaHome();
+  } catch (err: unknown) {
+    const error = err as Error;
+    errMsg = error.message;
+  }
+  const executableName = `java${system.isWindows() ? '.exe' : ''}`;
+  if (javaHome) {
+    const resultPath = path.resolve(javaHome, 'bin', executableName);
+    if (await fs.exists(resultPath)) {
+      return resultPath;
+    }
+  }
+  try {
+    return await fs.which(executableName);
+  } catch {
+    // Ignore and throw custom error below
+  }
+  throw new Error(
+    `The '${executableName}' binary could not be found ` +
+      `neither in PATH nor under JAVA_HOME (${javaHome ? path.resolve(javaHome, 'bin') : errMsg})`,
+  );
+});

package/lib/utils/index.ts

@@ -0,0 +1,25 @@
+import * as helpers from './helpers';
+import * as lodash from './lodash';
+import {util} from '@appium/support';
+
+export const APKS_EXTENSION = helpers.APKS_EXTENSION;
+export const APK_INSTALL_TIMEOUT = helpers.APK_INSTALL_TIMEOUT;
+export const DEFAULT_ADB_EXEC_TIMEOUT = helpers.DEFAULT_ADB_EXEC_TIMEOUT;
+export const buildInstallArgs = helpers.buildInstallArgs;
+export const readPackageManifest = helpers.readPackageManifest;
+export const getResourcePath = helpers.getResourcePath;
+export const unzipFile = helpers.unzipFile;
+export const getSdkRootFromEnv = helpers.getSdkRootFromEnv;
+export const requireSdkRoot = helpers.requireSdkRoot;
+export const getJavaHome = helpers.getJavaHome;
+export const getJavaForOs = helpers.getJavaForOs;
+
+export const memoize = util.memoize;
+export const cloneDeep = lodash.cloneDeep;
+export const defaults = lodash.defaults;
+export const intersectionWith = lodash.intersectionWith;
+export const zip = lodash.zip;
+export const pick = lodash.pick;
+export const defaultsDeep = lodash.defaultsDeep;
+
+export type {BuildInstallArgsOptions} from './helpers';

package/lib/utils/lodash/core.ts

@@ -0,0 +1,65 @@
+import {util} from '@appium/support';
+
+type AnyObject = Record<string, any>;
+
+export const cloneDeep = <T>(value: T): T => {
+  if (typeof globalThis.structuredClone === 'function') {
+    return globalThis.structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value)) as T;
+};
+
+export const defaults = (target: AnyObject, ...sources: AnyObject[]): AnyObject => {
+  for (const source of sources) {
+    if (!source) {
+      continue;
+    }
+    for (const [key, value] of Object.entries(source)) {
+      if (target[key] === undefined) {
+        target[key] = value;
+      }
+    }
+  }
+  return target;
+};
+
+const _defaultsDeep = (target: AnyObject, ...sources: AnyObject[]): AnyObject => {
+  for (const source of sources) {
+    if (!source) {
+      continue;
+    }
+    for (const [key, value] of Object.entries(source)) {
+      const current = target[key];
+      if (current === undefined) {
+        target[key] = util.isPlainObject(value) || Array.isArray(value) ? cloneDeep(value) : value;
+        continue;
+      }
+      if (util.isPlainObject(current) && util.isPlainObject(value)) {
+        _defaultsDeep(current, value);
+      }
+    }
+  }
+  return target;
+};
+
+export const intersectionWith = <T>(
+  first: T[],
+  second: T[],
+  comparator: (left: T, right: T) => boolean,
+): T[] => first.filter((item) => second.some((other) => comparator(item, other)));
+export const zip = <A, B>(
+  arrA: readonly A[],
+  arrB: readonly B[],
+): Array<[A | undefined, B | undefined]> => {
+  const length = Math.max(arrA.length, arrB.length);
+  return Array.from({length}, (_, idx) => [arrA[idx], arrB[idx]]);
+};
+export const pick = <T extends AnyObject>(obj: T, keysArg: string[]) =>
+  keysArg.reduce((acc, key) => {
+    if (key in obj) {
+      acc[key] = obj[key];
+    }
+    return acc;
+  }, {} as AnyObject) as Partial<T>;
+export const defaultsDeep = <T extends AnyObject>(target: T, ...sources: AnyObject[]): T =>
+  _defaultsDeep(target, ...sources) as T;

package/lib/utils/lodash/index.ts

@@ -0,0 +1 @@
+export * from './core';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-adb",
-  "version": "14.3.4",
+  "version": "14.4.0",
   "description": "Android Debug Bridge interface",
   "main": "./build/lib/index.js",
   "scripts": {
@@ -46,11 +46,10 @@
   ],
   "homepage": "https://github.com/appium/appium-adb",
   "dependencies": {
-    "@appium/support": "^7.0.0-rc.1",
+    "@appium/support": "^7.2.2",
     "async-lock": "^1.0.0",
     "asyncbox": "^6.0.1",
     "ini": "^6.0.0",
-    "lodash": "^4.0.0",
     "lru-cache": "^11.1.0",
     "semver": "^7.0.0",
     "teen_process": "^4.0.4"
@@ -63,7 +62,6 @@
     "@semantic-release/git": "^10.0.1",
     "@types/async-lock": "^1.4.0",
     "@types/ini": "^4.1.0",
-    "@types/lodash": "^4.14.195",
     "@types/mocha": "^10.0.1",
     "@types/node": "^25.0.0",
     "@types/semver": "^7.5.0",
@@ -74,7 +72,7 @@
     "mocha": "^11.0.1",
     "prettier": "^3.0.0",
     "semantic-release": "^25.0.2",
-    "sinon": "^21.0.0",
+    "sinon": "^22.0.0",
     "ts-node": "^10.9.1",
     "typescript": "^6.0.2"
   },

package/build/lib/helpers.d.ts

@@ -1,47 +0,0 @@
-import _ from 'lodash';
-import type { ADB } from './adb';
-import type { ApkManifest } from './tools/types';
-export declare const APKS_EXTENSION = ".apks";
-export declare const APK_EXTENSION = ".apk";
-export declare const APK_INSTALL_TIMEOUT = 60000;
-export declare const DEFAULT_ADB_EXEC_TIMEOUT = 20000;
-/**
- * Calculates the absolute path to the given resource
- */
-export declare const getResourcePath: ((relPath: string) => Promise<string>) & _.MemoizedFunction;
-/**
- * Retrieves the actual path to SDK root folder from the system environment
- */
-export declare function getSdkRootFromEnv(): string | undefined;
-/**
- * Retrieves the actual path to SDK root folder
- */
-export declare function requireSdkRoot(customRoot?: string | null): Promise<string>;
-/**
- * @param zipPath
- * @param dstRoot
- */
-export declare function unzipFile(zipPath: string, dstRoot?: string): Promise<void>;
-export declare const getJavaHome: (() => Promise<string>) & _.MemoizedFunction;
-export declare const getJavaForOs: (() => Promise<string>) & _.MemoizedFunction;
-/**
- * Transforms given options into the list of `adb install.install-multiple` command arguments
- */
-export declare function buildInstallArgs(apiLevel: number, options?: BuildInstallArgsOptions): string[];
-/**
- * Extracts various package manifest details
- * from the given application file.
- */
-export declare function readPackageManifest(this: ADB, apkPath: string): Promise<ApkManifest>;
-/**
- * Options for building install arguments
- */
-interface BuildInstallArgsOptions {
-    replace?: boolean;
-    allowTestPackages?: boolean;
-    useSdcard?: boolean;
-    grantPermissions?: boolean;
-    partialInstall?: boolean;
-}
-export {};
-//# sourceMappingURL=helpers.d.ts.map

package/build/lib/helpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../lib/helpers.ts"],"names":[],"mappings":"AAGA,OAAO,CAAC,MAAM,QAAQ,CAAC;AAEvB,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,eAAe,CAAC;AAM/C,eAAO,MAAM,cAAc,UAAU,CAAC;AACtC,eAAO,MAAM,aAAa,SAAS,CAAC;AACpC,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AACzC,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAK9C;;GAEG;AACH,eAAO,MAAM,eAAe,aACjB,MAAM,KACd,OAAO,CAAC,MAAM,CAAC,sBAUhB,CAAC;AAEH;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,UAAU,GAAE,MAAM,GAAG,IAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBtF;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,eAAO,MAAM,WAAW,SAA2C,OAAO,CAAC,MAAM,CAAC,sBAahF,CAAC;AAEH,eAAO,MAAM,YAAY,SAA4C,OAAO,CAAC,MAAM,CAAC,sBAyBlF,CAAC;AAEH;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,GACpC,MAAM,EAAE,CA6BV;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAgH1F;AAmCD;;GAEG;AACH,UAAU,uBAAuB;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B"}