appium-adb 14.1.2 → 14.1.3

package/lib/tools/{fs-commands.js → fs-commands.ts}

@@ -1,14 +1,15 @@
 import _ from 'lodash';
 import path from 'path';
+import type {ADB} from '../adb.js';
+import type {TeenProcessExecOptions} from 'teen_process';
 
 /**
  * Verify whether a remote path exists on the device under test.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} remotePath - The remote path to verify.
- * @return {Promise<boolean>} True if the given path exists on the device.
+ * @param remotePath - The remote path to verify.
+ * @return True if the given path exists on the device.
  */
-export async function fileExists(remotePath) {
+export async function fileExists(this: ADB, remotePath: string): Promise<boolean> {
   const passFlag = '__PASS__';
   const checkCmd = `[ -e '${remotePath.replace(/'/g, `\\'`)}' ] && echo ${passFlag}`;
   try {
@@ -21,24 +22,23 @@ export async function fileExists(remotePath) {
 /**
  * Get the output of _ls_ command on the device under test.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} remotePath - The remote path (the first argument to the _ls_ command).
- * @param {string[]} [opts] - Additional _ls_ options.
- * @return {Promise<string[]>} The _ls_ output as an array of split lines.
+ * @param remotePath - The remote path (the first argument to the _ls_ command).
+ * @param opts - Additional _ls_ options.
+ * @return The _ls_ output as an array of split lines.
  *                          An empty array is returned of the given _remotePath_
  *                          does not exist.
  */
-export async function ls(remotePath, opts = []) {
+export async function ls(this: ADB, remotePath: string, opts: string[] = []): Promise<string[]> {
   try {
-    let args = ['ls', ...opts, remotePath];
-    let stdout = await this.shell(args);
-    let lines = stdout.split('\n');
+    const args = ['ls', ...opts, remotePath];
+    const stdout = await this.shell(args);
+    const lines = stdout.split('\n');
     return lines
       .map((l) => l.trim())
       .filter(Boolean)
       .filter((l) => l.indexOf('No such file') === -1);
   } catch (err) {
-    if (err.message.indexOf('No such file or directory') === -1) {
+    if ((err as Error).message.indexOf('No such file or directory') === -1) {
       throw err;
     }
     return [];
@@ -48,12 +48,11 @@ export async function ls(remotePath, opts = []) {
 /**
  * Get the size of the particular file located on the device under test.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} remotePath - The remote path to the file.
- * @return {Promise<number>} File size in bytes.
+ * @param remotePath - The remote path to the file.
+ * @return File size in bytes.
  * @throws {Error} If there was an error while getting the size of the given file.
  */
-export async function fileSize(remotePath) {
+export async function fileSize(this: ADB, remotePath: string): Promise<number> {
   try {
     const files = await this.ls(remotePath, ['-la']);
     if (files.length !== 1) {
@@ -66,7 +65,7 @@ export async function fileSize(remotePath) {
     }
     return parseInt(match[1], 10);
   } catch (err) {
-    throw new Error(`Unable to get file size for '${remotePath}': ${err.message}`);
+    throw new Error(`Unable to get file size for '${remotePath}': ${(err as Error).message}`);
   }
 }
 
@@ -74,25 +73,28 @@ export async function fileSize(remotePath) {
  * Forcefully recursively remove a path on the device under test.
  * Be careful while calling this method.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} path - The path to be removed recursively.
+ * @param path - The path to be removed recursively.
  */
-export async function rimraf(path) {
+export async function rimraf(this: ADB, path: string): Promise<void> {
   await this.shell(['rm', '-rf', path]);
 }
 
 /**
  * Send a file to the device under test.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} localPath - The path to the file on the local file system.
- * @param {string} remotePath - The destination path on the remote device.
- * @param {object} [opts] - Additional options mapping. See
+ * @param localPath - The path to the file on the local file system.
+ * @param remotePath - The destination path on the remote device.
+ * @param opts - Additional options mapping. See
  *                        https://github.com/appium/node-teen_process,
  *                        _exec_ method options, for more information about available
  *                        options.
  */
-export async function push(localPath, remotePath, opts) {
+export async function push(
+  this: ADB,
+  localPath: string,
+  remotePath: string,
+  opts?: TeenProcessExecOptions,
+): Promise<void> {
   await this.mkdir(path.posix.dirname(remotePath));
   await this.adbExec(['push', localPath, remotePath], opts);
 }
@@ -100,15 +102,19 @@ export async function push(localPath, remotePath, opts) {
 /**
  * Receive a file from the device under test.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} remotePath - The source path on the remote device.
- * @param {string} localPath - The destination path to the file on the local file system.
- * @param {import('teen_process').TeenProcessExecOptions} [opts={}] - Additional options mapping. See
+ * @param remotePath - The source path on the remote device.
+ * @param localPath - The destination path to the file on the local file system.
+ * @param opts - Additional options mapping. See
  * https://github.com/appium/node-teen_process,
  * _exec_ method options, for more information about available
  * options.
  */
-export async function pull(remotePath, localPath, opts = {}) {
+export async function pull(
+  this: ADB,
+  remotePath: string,
+  localPath: string,
+  opts: TeenProcessExecOptions = {},
+): Promise<void> {
   // pull folder can take more time, increasing time out to 60 secs
   await this.adbExec(['pull', remotePath, localPath], {...opts, timeout: opts.timeout ?? 60000});
 }
@@ -116,12 +122,12 @@ export async function pull(remotePath, localPath, opts = {}) {
 /**
  * Recursively create a new folder on the device under test.
  *
- * @this {import('../adb.js').ADB}
- * @param {string} remotePath - The new path to be created.
- * @return {Promise<string>} mkdir command output.
+ * @param remotePath - The new path to be created.
+ * @return mkdir command output.
  */
-export async function mkdir(remotePath) {
+export async function mkdir(this: ADB, remotePath: string): Promise<string> {
   return /\s+/.test(remotePath)
     ? await this.shell([`mkdir -p '${remotePath.replace(/'/g, `\\'`)}'`])
     : await this.shell(['mkdir', '-p', remotePath]);
 }
+

package/lib/tools/{general-commands.js → general-commands.ts}

@@ -1,16 +1,17 @@
 import {log} from '../logger.js';
 import _ from 'lodash';
 import {fs, util} from '@appium/support';
-import {SubProcess, exec} from 'teen_process';
+import {SubProcess, exec, type ExecError} from 'teen_process';
+import type {ADB} from '../adb.js';
+import type {ScreenrecordOptions, StringRecord} from './types.js';
 
 /**
  * Get the path to adb executable amd assign it
  * to this.executable.path and this.binaries.adb properties.
  *
- * @this {import('../adb.js').ADB}
- * @return {Promise<import('../adb.js').ADB>} ADB instance.
+ * @return ADB instance.
  */
-export async function getAdbWithCorrectAdbPath() {
+export async function getAdbWithCorrectAdbPath(this: ADB): Promise<ADB> {
   this.executable.path = await this.getSdkBinaryPath('adb');
   return this;
 }
@@ -18,39 +19,35 @@ export async function getAdbWithCorrectAdbPath() {
 /**
  * Get the full path to aapt tool and assign it to
  * this.binaries.aapt property
- * @this {import('../adb.js').ADB}
  */
-export async function initAapt() {
+export async function initAapt(this: ADB): Promise<void> {
   await this.getSdkBinaryPath('aapt');
 }
 
 /**
  * Get the full path to aapt2 tool and assign it to
  * this.binaries.aapt2 property
- * @this {import('../adb.js').ADB}
  */
-export async function initAapt2() {
+export async function initAapt2(this: ADB): Promise<void> {
   await this.getSdkBinaryPath('aapt2');
 }
 
 /**
  * Get the full path to zipalign tool and assign it to
  * this.binaries.zipalign property
- * @this {import('../adb.js').ADB}
  */
-export async function initZipAlign() {
+export async function initZipAlign(this: ADB): Promise<void> {
   await this.getSdkBinaryPath('zipalign');
 }
 
 /**
  * Get the full path to bundletool binary and assign it to
  * this.binaries.bundletool property
- * @this {import('../adb.js').ADB}
  */
-export async function initBundletool() {
+export async function initBundletool(this: ADB): Promise<void> {
   try {
-    /** @type {import('./types').StringRecord} */ (this.binaries).bundletool =
-      await fs.which('bundletool.jar');
+    const binaries = this.binaries as StringRecord;
+    binaries.bundletool = await fs.which('bundletool.jar');
   } catch {
     throw new Error(
       'bundletool.jar binary is expected to be present in PATH. ' +
@@ -62,12 +59,11 @@ export async function initBundletool() {
 /**
  * Retrieve the API level of the device under test.
  *
- * @this {import('../adb.js').ADB}
- * @return {Promise<number>} The API level as integer number, for example 21 for
+ * @return The API level as integer number, for example 21 for
  *                  Android Lollipop. The result of this method is cached, so all the further
  * calls return the same value as the first one.
  */
-export async function getApiLevel() {
+export async function getApiLevel(this: ADB): Promise<number> {
   if (!_.isInteger(this._apiLevel)) {
     try {
       const strOutput = await this.getDeviceProperty('ro.build.version.sdk');
@@ -92,21 +88,20 @@ export async function getApiLevel() {
       }
     } catch (e) {
       throw new Error(
-        `Error getting device API level. Original error: ${/** @type {Error} */ (e).message}`,
+        `Error getting device API level. Original error: ${(e as Error).message}`,
       );
     }
   }
-  return /** @type {number} */ (this._apiLevel);
+  return this._apiLevel as number;
 }
 
 /**
  * Verify whether a device is connected.
  *
- * @this {import('../adb.js').ADB}
- * @return {Promise<boolean>} True if at least one device is visible to adb.
+ * @return True if at least one device is visible to adb.
  */
-export async function isDeviceConnected() {
-  let devices = await this.getConnectedDevices();
+export async function isDeviceConnected(this: ADB): Promise<boolean> {
+  const devices = await this.getConnectedDevices();
   return devices.length > 0;
 }
 
@@ -114,16 +109,15 @@ export async function isDeviceConnected() {
  * Clear the active text field on the device under test by sending
  * special keyevents to it.
  *
- * @this {import('../adb.js').ADB}
- * @param {number} [length=100] - The maximum length of the text in the field to be cleared.
+ * @param length - The maximum length of the text in the field to be cleared.
  */
-export async function clearTextField(length = 100) {
+export async function clearTextField(this: ADB, length: number = 100): Promise<void> {
   // assumes that the EditText field already has focus
   log.debug(`Clearing up to ${length} characters`);
   if (length === 0) {
     return;
   }
-  let args = ['input', 'keyevent'];
+  const args = ['input', 'keyevent'];
   for (let i = 0; i < length; i++) {
     // we cannot know where the cursor is in the text field, so delete both before
     // and after so that we get rid of everything
@@ -137,9 +131,8 @@ export async function clearTextField(length = 100) {
 /**
  * Send the special keycode to the device under test in order to emulate
  * Back button tap.
- * @this {import('../adb.js').ADB}
  */
-export async function back() {
+export async function back(this: ADB): Promise<void> {
   log.debug('Pressing the BACK button');
   await this.keyevent(4);
 }
@@ -147,35 +140,32 @@ export async function back() {
 /**
  * Send the special keycode to the device under test in order to emulate
  * Home button tap.
- * @this {import('../adb.js').ADB}
  */
-export async function goToHome() {
+export async function goToHome(this: ADB): Promise<void> {
   log.debug('Pressing the HOME button');
   await this.keyevent(3);
 }
 
 /**
- * @this {import('../adb.js').ADB}
- * @return {string} the actual path to adb executable.
+ * @return the actual path to adb executable.
  */
-export function getAdbPath() {
+export function getAdbPath(this: ADB): string {
   return this.executable.path;
 }
 
 /**
  * Restart the device under test using adb commands.
  *
- * @this {import('../adb.js').ADB}
  * @throws {Error} If start fails.
  */
-export async function restart() {
+export async function restart(this: ADB): Promise<void> {
   try {
     await this.stopLogcat();
     await this.restartAdb();
     await this.waitForDevice(60);
     await this.startLogcat(this._logcatStartupParams);
   } catch (e) {
-    const err = /** @type {Error} */ (e);
+    const err = e as Error;
     throw new Error(`Restart failed. Original error: ${err.message}`);
   }
 }
@@ -184,25 +174,27 @@ export async function restart() {
  * Retrieve the `adb bugreport` command output. This
  * operation may take up to several minutes.
  *
- * @this {import('../adb.js').ADB}
- * @param {number} [timeout=120000] - Command timeout in milliseconds
- * @returns {Promise<string>} Command stdout
+ * @param timeout - Command timeout in milliseconds
+ * @returns Command stdout
  */
-export async function bugreport(timeout = 120000) {
+export async function bugreport(this: ADB, timeout: number = 120000): Promise<string> {
   return await this.adbExec(['bugreport'], {timeout});
 }
 
 /**
  * Initiate screenrecord utility on the device
  *
- * @this {import('../adb.js').ADB}
- * @param {string} destination - Full path to the writable media file destination
+ * @param destination - Full path to the writable media file destination
  *                               on the device file system.
- * @param {import('./types').ScreenrecordOptions} [options={}]
- * @returns {SubProcess} screenrecord process, which can be then controlled by the client code
+ * @param options - Screenrecord options
+ * @returns screenrecord process, which can be then controlled by the client code
  */
-export function screenrecord(destination, options = {}) {
-  const cmd = ['screenrecord'];
+export function screenrecord(
+  this: ADB,
+  destination: string,
+  options: ScreenrecordOptions = {},
+): SubProcess {
+  const cmd: string[] = ['screenrecord'];
   const {videoSize, bitRate, timeLimit, bugReport} = options;
   if (util.hasValue(videoSize)) {
     cmd.push('--size', videoSize);
@@ -226,8 +218,7 @@ export function screenrecord(destination, options = {}) {
 /**
  * Retrieves the list of features supported by the device under test
  *
- * @this {import('../adb.js').ADB}
- * @returns {Promise<string[]>} the list of supported feature names or an empty list.
+ * @returns the list of supported feature names or an empty list.
  * An example adb command output:
  * ```
  * cmd
@@ -243,7 +234,7 @@ export function screenrecord(destination, options = {}) {
  * ```
  * @throws {Error} if there was an error while retrieving the list
  */
-export async function listFeatures() {
+export async function listFeatures(this: ADB): Promise<string[]> {
   this._memoizedFeatures =
     this._memoizedFeatures ||
     _.memoize(
@@ -251,12 +242,16 @@ export async function listFeatures() {
       () => this.curDeviceId,
     );
   try {
-    return (await this._memoizedFeatures())
+    const memoizedFeatures = this._memoizedFeatures;
+    if (!memoizedFeatures) {
+      throw new Error('Memoized features function is not initialized');
+    }
+    return (await memoizedFeatures())
       .split(/\s+/)
       .map((x) => x.trim())
       .filter(Boolean);
   } catch (e) {
-    const err = /** @type {import('teen_process').ExecError} */ (e);
+    const err = e as ExecError;
     if (_.includes(err.stderr, 'unknown command')) {
       return [];
     }
@@ -274,11 +269,10 @@ export async function listFeatures() {
  * See https://github.com/aosp-mirror/platform_system_core/blob/master/adb/client/adb_install.cpp
  * for more details
  *
- * @this {import('../adb.js').ADB}
- * @returns {Promise<boolean>} `true` if the feature is supported by both adb and the
+ * @returns `true` if the feature is supported by both adb and the
  * device under test
  */
-export async function isStreamedInstallSupported() {
+export async function isStreamedInstallSupported(this: ADB): Promise<boolean> {
   const proto = Object.getPrototypeOf(this);
   proto._helpOutput = proto._helpOutput || (await this.adbExec(['help']));
   return proto._helpOutput.includes('--streaming') && (await this.listFeatures()).includes('cmd');
@@ -289,11 +283,10 @@ export async function isStreamedInstallSupported() {
  * Read https://developer.android.com/preview/features#incremental
  * for more details on it.
  *
- * @this {import('../adb.js').ADB}
- * @returns {Promise<boolean>} `true` if the feature is supported by both adb and the
+ * @returns `true` if the feature is supported by both adb and the
  * device under test
  */
-export async function isIncrementalInstallSupported() {
+export async function isIncrementalInstallSupported(this: ADB): Promise<boolean> {
   const {binary} = await this.getVersion();
   if (!binary) {
     return false;
@@ -307,29 +300,38 @@ export async function isIncrementalInstallSupported() {
 /**
  * Takes a screenshot of the given display or the default display.
  *
- * @this {import('../adb.js').ADB}
- * @param {number|string?} displayId A valid display identifier. If
+ * @param displayId A valid display identifier. If
  * no identifier is provided then the screenshot of the default display is returned.
  * Note that only recent Android APIs provide multi-screen support.
- * @returns {Promise<Buffer>} PNG screenshot payload
+ * @returns PNG screenshot payload
  */
-export async function takeScreenshot(displayId) {
+export async function takeScreenshot(
+  this: ADB,
+  displayId?: number | string,
+): Promise<Buffer> {
   const args = [...this.executable.defaultArgs, 'exec-out', 'screencap', '-p'];
   // @ts-ignore This validation works as expected
-  const displayIdStr = isNaN(displayId) ? null : `${displayId}`;
+  const displayIdStr = isNaN(Number(displayId)) ? null : `${displayId}`;
   if (displayIdStr) {
     args.push('-d', displayIdStr);
   }
-  const displayDescr = displayIdStr ? 'default display' : `display #${displayIdStr}`;
-  let stdout;
+  const displayDescr = displayIdStr ? `display #${displayIdStr}` : 'default display';
+  let stdout: Buffer;
   try {
     ({stdout} = await exec(this.executable.path, args, {encoding: 'binary', isBuffer: true}));
   } catch (e) {
-    const err = /** @type {import('teen_process').ExecError} */ (e);
+    const err = e as ExecError;
+    let outputStr = '';
+    if (err.stderr) {
+      const stderr = err.stderr as string | Buffer;
+      outputStr = typeof stderr === 'string' ? stderr : stderr.toString('utf-8');
+    } else if (err.stdout) {
+      const stdout = err.stdout as string | Buffer;
+      outputStr = typeof stdout === 'string' ? stdout : stdout.toString('utf-8');
+    }
     throw new Error(
       `Screenshot of the ${displayDescr} failed. ` +
-        // @ts-ignore The output is a buffer
-        `Code: '${err.code}', output: '${(err.stderr.length ? err.stderr : err.stdout).toString('utf-8')}'`,
+        `Code: '${err.code ?? 'unknown'}', output: '${outputStr}'`,
     );
   }
   if (stdout.length === 0) {
@@ -337,3 +339,4 @@ export async function takeScreenshot(displayId) {
   }
   return stdout;
 }
+