appium-adb 14.1.2 → 14.1.3

package/lib/tools/{android-manifest.js → android-manifest.ts}

@@ -4,17 +4,21 @@ import {log} from '../logger.js';
 import {unzipFile, APKS_EXTENSION, readPackageManifest} from '../helpers.js';
 import {fs, zip, tempDir, util} from '@appium/support';
 import path from 'path';
+import type {ADB} from '../adb.js';
+import type {APKInfo, PlatformInfo, StringRecord} from './types.js';
 
 /**
  * Extract package and main activity name from application manifest.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} appPath - The full path to application .apk(s) package
- * @return {Promise<import('./types').APKInfo>} The parsed application info.
+ * @param appPath - The full path to application .apk(s) package
+ * @return The parsed application info.
  * @throws {error} If there was an error while getting the data from the given
  *                 application package.
  */
-export async function packageAndLaunchActivityFromManifest(appPath) {
+export async function packageAndLaunchActivityFromManifest(
+  this: ADB,
+  appPath: string,
+): Promise<APKInfo> {
   if (appPath.endsWith(APKS_EXTENSION)) {
     appPath = await this.extractBaseApk(appPath);
   }
@@ -31,13 +35,12 @@ export async function packageAndLaunchActivityFromManifest(appPath) {
 /**
  * Extract target SDK version from application manifest.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} appPath - The full path to .apk(s) package.
- * @return {Promise<number>} The version of the target SDK.
+ * @param appPath - The full path to .apk(s) package.
+ * @return The version of the target SDK.
  * @throws {error} If there was an error while getting the data from the given
  *                 application package.
  */
-export async function targetSdkVersionFromManifest(appPath) {
+export async function targetSdkVersionFromManifest(this: ADB, appPath: string): Promise<number> {
   log.debug(`Extracting target SDK version of '${appPath}'`);
   const originalAppPath = appPath;
   if (appPath.endsWith(APKS_EXTENSION)) {
@@ -57,13 +60,16 @@ export async function targetSdkVersionFromManifest(appPath) {
 /**
  * Extract target SDK version from package information.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} pkg - The class name of the package installed on the device under test.
- * @param {string?} [cmdOutput=null] - Optional parameter containing the output of
+ * @param pkg - The class name of the package installed on the device under test.
+ * @param cmdOutput - Optional parameter containing the output of
  * _dumpsys package_ command. It may speed up the method execution.
- * @return {Promise<number>} The version of the target SDK.
+ * @return The version of the target SDK.
  */
-export async function targetSdkVersionUsingPKG(pkg, cmdOutput = null) {
+export async function targetSdkVersionUsingPKG(
+  this: ADB,
+  pkg: string,
+  cmdOutput: string | null = null,
+): Promise<number> {
   const stdout = cmdOutput || (await this.shell(['dumpsys', 'package', pkg]));
   const targetSdkVersionMatch = new RegExp(/targetSdk=([^\s\s]+)/g).exec(stdout);
   return targetSdkVersionMatch && targetSdkVersionMatch.length >= 2
@@ -76,14 +82,18 @@ export async function targetSdkVersionUsingPKG(pkg, cmdOutput = null) {
  * `${manifest}.apk` file will be created as the result of this method
  * containing the compiled manifest.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} manifest - Full path to the initial manifest template
- * @param {string} manifestPackage - The name of the manifest package
- * @param {string} targetPackage - The name of the destination package
+ * @param manifest - Full path to the initial manifest template
+ * @param manifestPackage - The name of the manifest package
+ * @param targetPackage - The name of the destination package
  */
-export async function compileManifest(manifest, manifestPackage, targetPackage) {
+export async function compileManifest(
+  this: ADB,
+  manifest: string,
+  manifestPackage: string,
+  targetPackage: string,
+): Promise<void> {
   const {platform, platformPath} = await getAndroidPlatformAndPath(
-    /** @type {string} */ (this.sdkRoot),
+    this.sdkRoot as string,
   );
   if (!platform || !platformPath) {
     throw new Error(
@@ -98,6 +108,7 @@ export async function compileManifest(manifest, manifestPackage, targetPackage)
   try {
     await this.initAapt2();
     // https://developer.android.com/studio/command-line/aapt2
+    const binaries = this.binaries as StringRecord;
     const args = [
       'link',
       '-o',
@@ -113,18 +124,16 @@ export async function compileManifest(manifest, manifestPackage, targetPackage)
       '-v',
     ];
     log.debug(
-      `Compiling the manifest using '${util.quote([
-        /** @type {import('./types').StringRecord} */ (this.binaries).aapt2,
-        ...args,
-      ])}'`,
+      `Compiling the manifest using '${util.quote([binaries.aapt2, ...args])}'`,
     );
-    await exec(/** @type {import('./types').StringRecord} */ (this.binaries).aapt2, args);
+    await exec(binaries.aapt2, args);
   } catch (e) {
     log.debug(
       'Cannot compile the manifest using aapt2. Defaulting to aapt. ' +
-        `Original error: ${e.stderr || e.message}`,
+        `Original error: ${(e as Error).message || (e as {stderr?: string}).stderr}`,
     );
     await this.initAapt();
+    const binaries = this.binaries as StringRecord;
     const args = [
       'package',
       '-M',
@@ -140,15 +149,14 @@ export async function compileManifest(manifest, manifestPackage, targetPackage)
       '-f',
     ];
     log.debug(
-      `Compiling the manifest using '${util.quote([
-        /** @type {import('./types').StringRecord} */ (this.binaries).aapt,
-        ...args,
-      ])}'`,
+      `Compiling the manifest using '${util.quote([binaries.aapt, ...args])}'`,
     );
     try {
-      await exec(/** @type {import('./types').StringRecord} */ (this.binaries).aapt, args);
+      await exec(binaries.aapt, args);
     } catch (e1) {
-      throw new Error(`Cannot compile the manifest. Original error: ${e1.stderr || e1.message}`);
+      throw new Error(
+        `Cannot compile the manifest. Original error: ${(e1 as Error).message || (e1 as {stderr?: string}).stderr}`,
+      );
     }
   }
   log.debug(`Compiled the manifest at '${resultPath}'`);
@@ -158,41 +166,40 @@ export async function compileManifest(manifest, manifestPackage, targetPackage)
  * Replace/insert the specially precompiled manifest file into the
  * particular package.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} manifest - Full path to the precompiled manifest
+ * @param manifest - Full path to the precompiled manifest
  *                            created by `compileManifest` method call
  *                            without .apk extension
- * @param {string} srcApk - Full path to the existing valid application package, where
+ * @param srcApk - Full path to the existing valid application package, where
  *                          this manifest has to be insetred to. This package
  *                          will NOT be modified.
- * @param {string} dstApk - Full path to the resulting package.
+ * @param dstApk - Full path to the resulting package.
  *                          The file will be overridden if it already exists.
  */
-export async function insertManifest(manifest, srcApk, dstApk) {
+export async function insertManifest(
+  this: ADB,
+  manifest: string,
+  srcApk: string,
+  dstApk: string,
+): Promise<void> {
   log.debug(`Inserting manifest '${manifest}', src: '${srcApk}', dst: '${dstApk}'`);
   await zip.assertValidZip(srcApk);
   await unzipFile(`${manifest}.apk`);
   const manifestName = path.basename(manifest);
   try {
     await this.initAapt();
+    const binaries = this.binaries as StringRecord;
     await fs.copyFile(srcApk, dstApk);
     log.debug('Moving manifest');
     try {
-      await exec(/** @type {import('./types').StringRecord} */ (this.binaries).aapt, [
-        'remove',
-        dstApk,
-        manifestName,
-      ]);
+      await exec(binaries.aapt, ['remove', dstApk, manifestName]);
     } catch {}
-    await exec(
-      /** @type {import('./types').StringRecord} */ (this.binaries).aapt,
-      ['add', dstApk, manifestName],
-      {cwd: path.dirname(manifest)},
-    );
+    await exec(binaries.aapt, ['add', dstApk, manifestName], {
+      cwd: path.dirname(manifest),
+    });
   } catch (e) {
     log.debug(
       'Cannot insert manifest using aapt. Defaulting to zip. ' +
-        `Original error: ${e.stderr || e.message}`,
+        `Original error: ${(e as Error).message || (e as {stderr?: string}).stderr}`,
     );
     const tmpRoot = await tempDir.openDir();
     try {
@@ -217,20 +224,20 @@ export async function insertManifest(manifest, srcApk, dstApk) {
 /**
  * Check whether package manifest contains Internet permissions.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} appPath - The full path to .apk(s) package.
- * @return {Promise<boolean>} True if the manifest requires Internet access permission.
+ * @param appPath - The full path to .apk(s) package.
+ * @return True if the manifest requires Internet access permission.
  */
-export async function hasInternetPermissionFromManifest(appPath) {
+export async function hasInternetPermissionFromManifest(
+  this: ADB,
+  appPath: string,
+): Promise<boolean> {
   log.debug(`Checking if '${appPath}' requires internet access permission in the manifest`);
   if (appPath.endsWith(APKS_EXTENSION)) {
     appPath = await this.extractBaseApk(appPath);
   }
 
   const {usesPermissions} = await readPackageManifest.bind(this)(appPath);
-  return usesPermissions.some(
-    (/** @type {string} */ name) => name === 'android.permission.INTERNET',
-  );
+  return usesPermissions.some((name: string) => name === 'android.permission.INTERNET');
 }
 
 // #region Private functions
@@ -238,16 +245,15 @@ export async function hasInternetPermissionFromManifest(appPath) {
 /**
  * Retrieve the path to the recent installed Android platform.
  *
- * @param {string} sdkRoot
- * @return {Promise<import('./types').PlatformInfo>} The resulting path to the newest installed platform.
+ * @param sdkRoot
+ * @return The resulting path to the newest installed platform.
  */
-export async function getAndroidPlatformAndPath(sdkRoot) {
+export async function getAndroidPlatformAndPath(sdkRoot: string): Promise<PlatformInfo> {
   const propsPaths = await fs.glob('*/build.prop', {
     cwd: path.resolve(sdkRoot, 'platforms'),
     absolute: true,
   });
-  /** @type {Record<string, import('./types').PlatformInfo>} */
-  const platformsMapping = {};
+  const platformsMapping: Record<string, PlatformInfo> = {};
   for (const propsPath of propsPaths) {
     const propsContent = await fs.readFile(propsPath, 'utf-8');
     const platformPath = path.dirname(propsPath);
@@ -280,3 +286,4 @@ export async function getAndroidPlatformAndPath(sdkRoot) {
 }
 
 // #endregion
+

package/lib/tools/{apks-utils.js → apks-utils.ts}

@@ -7,13 +7,14 @@ import {LRUCache} from 'lru-cache';
 import {getJavaForOs, unzipFile, buildInstallArgs, APK_INSTALL_TIMEOUT} from '../helpers.js';
 import AsyncLock from 'async-lock';
 import B from 'bluebird';
+import type {ADB} from '../adb.js';
+import type {InstallMultipleApksOptions, InstallApksOptions, StringRecord} from './types.js';
 
 const BASE_APK = 'base-master.apk';
-const LANGUAGE_APK = (lang) => `base-${lang}.apk`;
-/** @type {LRUCache<string, string>} */
-const APKS_CACHE = new LRUCache({
+const LANGUAGE_APK = (lang: string) => `base-${lang}.apk`;
+const APKS_CACHE = new LRUCache<string, string>({
   max: 10,
-  dispose: (extractedFilesRoot) => fs.rimraf(/** @type {string} */ (extractedFilesRoot)),
+  dispose: (extractedFilesRoot) => fs.rimraf(extractedFilesRoot),
 });
 const APKS_CACHE_GUARD = new AsyncLock();
 const BUNDLETOOL_TIMEOUT_MS = 4 * 60 * 1000;
@@ -24,7 +25,7 @@ process.on('exit', () => {
     return;
   }
 
-  const paths = /** @type {string[]} */ ([...APKS_CACHE.values()]);
+  const paths = [...APKS_CACHE.values()];
   log.debug(
     `Performing cleanup of ${paths.length} cached .apks ` + util.pluralize('package', paths.length),
   );
@@ -33,7 +34,7 @@ process.on('exit', () => {
       // Asynchronous calls are not supported in onExit handler
       fs.rimrafSync(appPath);
     } catch (e) {
-      log.warn(e.message);
+      log.warn((e as Error).message);
     }
   }
 });
@@ -44,17 +45,15 @@ process.on('exit', () => {
  * The resulting temporary path, where the .apks file has been extracted,
  * will be stored into the internal LRU cache for better performance.
  *
- * @param {string} apks - The full path to the .apks file
- * @param {string|string[]} dstPath - The relative path to the destination file,
+ * @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 {Promise<string>} Full path to the extracted file
+ * @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, dstPath) {
-  if (!_.isArray(dstPath)) {
-    dstPath = [dstPath];
-  }
+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,
@@ -64,9 +63,12 @@ async function extractFromApks(apks, dstPath) {
     log.debug(`Calculated '${apks}' hash: ${apksHash}`);
 
     if (APKS_CACHE.has(apksHash)) {
-      const resultPath = path.resolve(/** @type {string} */ (APKS_CACHE.get(apksHash)), ...dstPath);
-      if (await fs.exists(resultPath)) {
-        return resultPath;
+      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);
     }
@@ -74,10 +76,10 @@ async function extractFromApks(apks, dstPath) {
     const tmpRoot = await tempDir.openDir();
     log.debug(`Unpacking application bundle at '${apks}' to '${tmpRoot}'`);
     await unzipFile(apks, tmpRoot);
-    const resultPath = path.resolve(tmpRoot, ...(_.isArray(dstPath) ? dstPath : [dstPath]));
+    const resultPath = path.resolve(tmpRoot, ...normalizedDstPath);
     if (!(await fs.exists(resultPath))) {
       throw new Error(
-        `${_.isArray(dstPath) ? dstPath.join(path.sep) : dstPath} cannot be found in '${apks}' bundle. ` +
+        `${normalizedDstPath.join(path.sep)} cannot be found in '${apks}' bundle. ` +
           `Does the archive contain a valid application bundle?`,
       );
     }
@@ -89,20 +91,20 @@ async function extractFromApks(apks, dstPath) {
 /**
  * Executes bundletool utility with given arguments and returns the actual stdout
  *
- * @this {import('../adb.js').ADB}
- * @param {Array<String>} args - the list of bundletool arguments
- * @param {string} errorMsg - The customized error message string
- * @returns {Promise<string>} the actual command stdout
+ * @param args - the list of bundletool arguments
+ * @param errorMsg - The customized error message string
+ * @returns the actual command stdout
  * @throws {Error} If bundletool jar does not exist in PATH or there was an error while
  * executing it
  */
-export async function execBundletool(args, errorMsg) {
+export async function execBundletool(
+  this: ADB,
+  args: string[],
+  errorMsg: string,
+): Promise<string> {
   await this.initBundletool();
-  args = [
-    '-jar',
-    /** @type {import('./types').StringRecord} */ (this.binaries).bundletool,
-    ...args,
-  ];
+  const binaries = this.binaries as StringRecord;
+  args = ['-jar', binaries.bundletool, ...args];
   const env = process.env;
   if (this.adbPort) {
     env.ANDROID_ADB_SERVER_PORT = `${this.adbPort}`;
@@ -111,7 +113,7 @@ export async function execBundletool(args, errorMsg) {
     env.ANDROID_ADB_SERVER_HOST = this.adbHost;
   }
   log.debug(`Executing bundletool with arguments: ${JSON.stringify(args)}`);
-  let stdout;
+  let stdout: string;
   try {
     ({stdout} = await exec(await getJavaForOs(), args, {
       env,
@@ -120,31 +122,30 @@ export async function execBundletool(args, errorMsg) {
     log.debug(`Command stdout: ${_.truncate(stdout, {length: 300})}`);
     return stdout;
   } catch (e) {
-    if (e.stdout) {
-      log.debug(`Command stdout: ${e.stdout}`);
+    const err = e as Error & {stdout?: string; stderr?: string};
+    if (err.stdout) {
+      log.debug(`Command stdout: ${err.stdout}`);
     }
-    if (e.stderr) {
-      log.debug(`Command stderr: ${e.stderr}`);
+    if (err.stderr) {
+      log.debug(`Command stderr: ${err.stderr}`);
     }
-    throw new Error(`${errorMsg}. Original error: ${e.message}`);
+    throw new Error(`${errorMsg}. Original error: ${err.message}`);
   }
 }
 
 /**
  *
- * @this {import('../adb.js').ADB}
- * @param {string} specLocation - The full path to the generated device spec location
- * @returns {Promise<string>} The same `specLocation` value
+ * @param specLocation - The full path to the generated device spec location
+ * @returns The same `specLocation` value
  * @throws {Error} If it is not possible to retrieve the spec for the current device
  */
-export async function getDeviceSpec(specLocation) {
-  /** @type {string[]} */
-  const args = [
+export async function getDeviceSpec(this: ADB, specLocation: string): Promise<string> {
+  const args: string[] = [
     'get-device-spec',
     '--adb',
     this.executable.path,
     '--device-id',
-    /** @type {string} */ (this.curDeviceId),
+    this.curDeviceId as string,
     '--output',
     specLocation,
   ];
@@ -156,15 +157,18 @@ export async function getDeviceSpec(specLocation) {
 /**
  * Installs the given apks into the device under test
  *
- * @this {import('../adb.js').ADB}
- * @param {Array<string>} apkPathsToInstall - The full paths to install apks
- * @param {import('./types').InstallMultipleApksOptions} [options={}] - Installation options
+ * @param apkPathsToInstall - The full paths to install apks
+ * @param options - Installation options
  */
-export async function installMultipleApks(apkPathsToInstall, options = {}) {
+export async function installMultipleApks(
+  this: ADB,
+  apkPathsToInstall: string[],
+  options: InstallMultipleApksOptions = {},
+): Promise<string> {
   const installArgs = buildInstallArgs(await this.getApiLevel(), options);
   return await this.adbExec(['install-multiple', ...installArgs, ...apkPathsToInstall], {
     // @ts-ignore This validation works
-    timeout: isNaN(options.timeout) ? undefined : options.timeout,
+    timeout: isNaN(Number(options.timeout)) ? undefined : options.timeout,
     timeoutCapName: options.timeoutCapName,
   });
 }
@@ -172,16 +176,18 @@ export async function installMultipleApks(apkPathsToInstall, options = {}) {
 /**
  * Installs the given .apks package into the device under test
  *
- * @this {import('../adb.js').ADB}
- * @param {string} apks - The full path to the .apks file
- * @param {import('./types').InstallApksOptions} [options={}] - Installation options
+ * @param apks - The full path to the .apks file
+ * @param options - Installation options
  * @throws {Error} If the .apks bundle cannot be installed
  */
-export async function installApks(apks, options = {}) {
+export async function installApks(
+  this: ADB,
+  apks: string,
+  options: InstallApksOptions = {},
+): Promise<void> {
   const {grantPermissions, allowTestPackages, timeout} = options;
 
-  /** @type {string[]} */
-  const args = [
+  const args: string[] = [
     'install-apks',
     '--adb',
     this.executable.path,
@@ -190,13 +196,12 @@ export async function installApks(apks, options = {}) {
     '--timeout-millis',
     `${timeout || APKS_INSTALL_TIMEOUT}`,
     '--device-id',
-    /** @type {string} */ (this.curDeviceId),
+    this.curDeviceId as string,
   ];
   if (allowTestPackages) {
     args.push('--allow-test-only');
   }
-  /** @type {Promise[]} */
-  const tasks = [
+  const tasks: Promise<any>[] = [
     this.execBundletool(
       args,
       `Cannot install '${path.basename(apks)}' to the device ${this.curDeviceId}`,
@@ -215,12 +220,11 @@ export async function installApks(apks, options = {}) {
 /**
  * Extracts and returns the full path to the master .apk file inside the bundle.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} apks - The full path to the .apks file
- * @returns {Promise<string>} The full path to the master bundle .apk
+ * @param apks - The full path to the .apks file
+ * @returns The full path to the master bundle .apk
  * @throws {Error} If there was an error while extracting/finding the file
  */
-export async function extractBaseApk(apks) {
+export async function extractBaseApk(this: ADB, apks: string): Promise<string> {
   return await extractFromApks(apks, ['splits', BASE_APK]);
 }
 
@@ -228,20 +232,23 @@ export async function extractBaseApk(apks) {
  * Extracts and returns the full path to the .apk, which contains the corresponding
  * resources for the given language in the .apks bundle.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} apks - The full path to the .apks file
- * @param {?string} [language=null] - The language abbreviation. The default language is
+ * @param apks - The full path to the .apks file
+ * @param language - The language abbreviation. The default language is
  * going to be selected if it is not set.
- * @returns {Promise<string>} The full path to the corresponding language .apk or the master .apk
+ * @returns The full path to the corresponding language .apk or the master .apk
  * if language split is not enabled for the bundle.
  * @throws {Error} If there was an error while extracting/finding the file
  */
-export async function extractLanguageApk(apks, language = null) {
+export async function extractLanguageApk(
+  this: ADB,
+  apks: string,
+  language: string | null = null,
+): Promise<string> {
   if (language) {
     try {
       return await extractFromApks(apks, ['splits', LANGUAGE_APK(language)]);
     } catch (e) {
-      log.debug(e.message);
+      log.debug((e as Error).message);
       log.info(
         `Assuming that splitting by language is not enabled for the '${apks}' bundle ` +
           `and returning the main apk instead`,
@@ -266,9 +273,10 @@ export async function extractLanguageApk(apks, language = null) {
 
 /**
  *
- * @param {string} output
- * @returns {boolean}
+ * @param output
+ * @returns
  */
-export function isTestPackageOnlyError(output) {
+export function isTestPackageOnlyError(output: string): boolean {
   return /\[INSTALL_FAILED_TEST_ONLY\]/.test(output);
 }
+