appium-android-driver 7.8.3 → 8.0.1

package/lib/commands/file-actions.js

@@ -1,17 +1,260 @@
-// @ts-check
-
 import _ from 'lodash';
 import {fs, util, zip, tempDir} from '@appium/support';
 import path from 'path';
 import {errors} from 'appium/driver';
 import {requireArgs} from '../utils';
-import {mixin} from './mixins';
 
 const CONTAINER_PATH_MARKER = '@';
 // https://regex101.com/r/PLdB0G/2
 const CONTAINER_PATH_PATTERN = new RegExp(`^${CONTAINER_PATH_MARKER}([^/]+)/(.+)`);
 const ANDROID_MEDIA_RESCAN_INTENT = 'android.intent.action.MEDIA_SCANNER_SCAN_FILE';
 
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} remotePath
+ * @returns {Promise<string>}
+ */
+export async function pullFile(remotePath) {
+  if (remotePath.endsWith('/')) {
+    throw new errors.InvalidArgumentError(
+      `It is expected that remote path points to a file and not to a folder. ` +
+        `'${remotePath}' is given instead`,
+    );
+  }
+  let tmpDestination = null;
+  if (remotePath.startsWith(CONTAINER_PATH_MARKER)) {
+    const [packageId, pathInContainer] = parseContainerPath(remotePath);
+    this.log.debug(
+      `Parsed package identifier '${packageId}' from '${remotePath}'. Will get the data from '${pathInContainer}'`,
+    );
+    tmpDestination = `/data/local/tmp/${path.posix.basename(pathInContainer)}`;
+    try {
+      await this.adb.shell(['run-as', packageId, `chmod 777 '${escapePath(pathInContainer)}'`]);
+      await this.adb.shell([
+        'run-as',
+        packageId,
+        `cp -f '${escapePath(pathInContainer)}' '${escapePath(tmpDestination)}'`,
+      ]);
+    } catch (e) {
+      this.log.errorAndThrow(
+        `Cannot access the container of '${packageId}' application. ` +
+          `Is the application installed and has 'debuggable' build option set to true? ` +
+          `Original error: ${/** @type {Error} */ (e).message}`,
+      );
+    }
+  }
+  const localFile = await tempDir.path({prefix: 'appium', suffix: '.tmp'});
+  try {
+    await this.adb.pull(tmpDestination || remotePath, localFile);
+    return (await util.toInMemoryBase64(localFile)).toString();
+  } finally {
+    if (await fs.exists(localFile)) {
+      await fs.unlink(localFile);
+    }
+    if (tmpDestination) {
+      await this.adb.shell(['rm', '-f', tmpDestination]);
+    }
+  }
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').PullFileOpts} opts
+ * @returns {Promise<string>}
+ */
+export async function mobilePullFile(opts) {
+  const {remotePath} = requireArgs('remotePath', opts);
+  return await this.pullFile(remotePath);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} remotePath
+ * @param {string} base64Data
+ * @returns {Promise<void>}
+ */
+export async function pushFile(remotePath, base64Data) {
+  if (remotePath.endsWith('/')) {
+    throw new errors.InvalidArgumentError(
+      `It is expected that remote path points to a file and not to a folder. ` +
+        `'${remotePath}' is given instead`,
+    );
+  }
+  const localFile = await tempDir.path({prefix: 'appium', suffix: '.tmp'});
+  if (_.isArray(base64Data)) {
+    // some clients (ahem) java, send a byte array encoding utf8 characters
+    // instead of a string, which would be infinitely better!
+    base64Data = Buffer.from(base64Data).toString('utf8');
+  }
+  const content = Buffer.from(base64Data, 'base64');
+  let tmpDestination = null;
+  try {
+    await fs.writeFile(localFile, content.toString('binary'), 'binary');
+    if (remotePath.startsWith(CONTAINER_PATH_MARKER)) {
+      const [packageId, pathInContainer] = parseContainerPath(remotePath);
+      this.log.debug(
+        `Parsed package identifier '${packageId}' from '${remotePath}'. ` +
+          `Will put the data into '${pathInContainer}'`,
+      );
+      tmpDestination = `/data/local/tmp/${path.posix.basename(pathInContainer)}`;
+      try {
+        await this.adb.shell([
+          'run-as',
+          packageId,
+          `mkdir -p '${escapePath(path.posix.dirname(pathInContainer))}'`,
+        ]);
+        await this.adb.shell(['run-as', packageId, `touch '${escapePath(pathInContainer)}'`]);
+        await this.adb.shell(['run-as', packageId, `chmod 777 '${escapePath(pathInContainer)}'`]);
+        await this.adb.push(localFile, tmpDestination);
+        await this.adb.shell([
+          'run-as',
+          packageId,
+          `cp -f '${escapePath(tmpDestination)}' '${escapePath(pathInContainer)}'`,
+        ]);
+      } catch (e) {
+        this.log.errorAndThrow(
+          `Cannot access the container of '${packageId}' application. ` +
+            `Is the application installed and has 'debuggable' build option set to true? ` +
+            `Original error: ${/** @type {Error} */ (e).message}`,
+        );
+      }
+    } else {
+      // adb push creates folders and overwrites existing files.
+      await this.adb.push(localFile, remotePath);
+
+      // if we have pushed a file, it might be a media file, so ensure that
+      // apps know about it
+      await scanMedia.bind(this)(remotePath);
+    }
+  } finally {
+    if (await fs.exists(localFile)) {
+      await fs.unlink(localFile);
+    }
+    if (tmpDestination) {
+      await this.adb.shell(['rm', '-f', tmpDestination]);
+    }
+  }
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').PushFileOpts} opts
+ * @returns {Promise<void>}
+ */
+export async function mobilePushFile(opts) {
+  const {remotePath, payload} = requireArgs(['remotePath', 'payload'], opts);
+  return await this.pushFile(remotePath, payload);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} remotePath
+ * @returns {Promise<string>}
+ */
+export async function pullFolder(remotePath) {
+  const tmpRoot = await tempDir.openDir();
+  try {
+    await this.adb.pull(remotePath, tmpRoot);
+    return (
+      await zip.toInMemoryZip(tmpRoot, {
+        encodeToBase64: true,
+      })
+    ).toString();
+  } finally {
+    await fs.rimraf(tmpRoot);
+  }
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').PullFolderOpts} opts
+ * @returns {Promise<string>}
+ */
+export async function mobilePullFolder(opts) {
+  const {remotePath} = requireArgs('remotePath', opts);
+  return await this.pullFolder(remotePath);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').DeleteFileOpts} opts
+ * @returns {Promise<boolean>}
+ */
+export async function mobileDeleteFile(opts) {
+  const {remotePath} = requireArgs('remotePath', opts);
+  if (remotePath.endsWith('/')) {
+    throw new errors.InvalidArgumentError(
+      `It is expected that remote path points to a folder and not to a file. ` +
+        `'${remotePath}' is given instead`,
+    );
+  }
+  return await deleteFileOrFolder.call(this, this.adb, remotePath);
+}
+
+/**
+ * Deletes the given folder or file from the remote device
+ *
+ * @param {ADB} adb
+ * @param {string} remotePath The full path to the remote folder
+ * or file (folder names must end with a single slash)
+ * @throws {Error} If the provided remote path is invalid or
+ * the package content cannot be accessed
+ * @returns {Promise<boolean>} `true` if the remote item has been successfully deleted.
+ * If the remote path is valid, but the remote path does not exist
+ * this function return `false`.
+ * @this {import('../driver').AndroidDriver}
+ */
+async function deleteFileOrFolder(adb, remotePath) {
+  const {isDir, isPresent, isFile} = createFSTests(adb);
+  let dstPath = remotePath;
+  /** @type {string|undefined} */
+  let pkgId;
+  if (remotePath.startsWith(CONTAINER_PATH_MARKER)) {
+    const [packageId, pathInContainer] = parseContainerPath(remotePath);
+    this.log.debug(`Parsed package identifier '${packageId}' from '${remotePath}'`);
+    dstPath = pathInContainer;
+    pkgId = packageId;
+  }
+
+  if (pkgId) {
+    try {
+      await adb.shell(['run-as', pkgId, 'ls']);
+    } catch (e) {
+      this.log.errorAndThrow(
+        `Cannot access the container of '${pkgId}' application. ` +
+          `Is the application installed and has 'debuggable' build option set to true? ` +
+          `Original error: ${/** @type {Error} */ (e).message}`,
+      );
+    }
+  }
+
+  if (!(await isPresent(dstPath, pkgId))) {
+    this.log.info(`The item at '${dstPath}' does not exist. Perhaps, already deleted?`);
+    return false;
+  }
+
+  const expectsFile = !remotePath.endsWith('/');
+  if (expectsFile && !(await isFile(dstPath, pkgId))) {
+    this.log.errorAndThrow(`The item at '${dstPath}' is not a file`);
+  } else if (!expectsFile && !(await isDir(dstPath, pkgId))) {
+    this.log.errorAndThrow(`The item at '${dstPath}' is not a folder`);
+  }
+
+  if (pkgId) {
+    await adb.shell(['run-as', pkgId, `rm -f${expectsFile ? '' : 'r'} '${escapePath(dstPath)}'`]);
+  } else {
+    await adb.shell(['rm', `-f${expectsFile ? '' : 'r'}`, dstPath]);
+  }
+  if (await isPresent(dstPath, pkgId)) {
+    this.log.errorAndThrow(
+      `The item at '${dstPath}' still exists after being deleted. ` + `Is it writable?`,
+    );
+  }
+  return true;
+}
+
+// #region Internal helpers
+
 /**
  * Parses the actual destination path from the given value
  *
@@ -26,7 +269,7 @@ function parseContainerPath(remotePath) {
   if (!match) {
     throw new Error(
       `It is expected that package identifier is separated from the relative path with a single slash. ` +
-        `'${remotePath}' is given instead`
+        `'${remotePath}' is given instead`,
     );
   }
   return [match[1], path.posix.resolve(`/data/data/${match[1]}`, match[2])];
@@ -62,7 +305,7 @@ async function scanMedia(remotePath) {
     this.log.warn(
       `Ignoring an unexpected error upon media scanning of '${remotePath}': ${
         err.stderr ?? err.message
-      }`
+      }`,
     );
   }
 }
@@ -78,158 +321,6 @@ function escapePath(p) {
   return p.replace(/'/g, `\\'`);
 }
 
-/**
- * @type {import('./mixins').FileActionsMixin & ThisType<import('../driver').AndroidDriver>}
- * @satisfies {import('@appium/types').ExternalDriver}
- */
-const FileActionsMixin = {
-  async pullFile(remotePath) {
-    if (remotePath.endsWith('/')) {
-      throw new errors.InvalidArgumentError(
-        `It is expected that remote path points to a file and not to a folder. ` +
-          `'${remotePath}' is given instead`
-      );
-    }
-    let tmpDestination = null;
-    if (remotePath.startsWith(CONTAINER_PATH_MARKER)) {
-      const [packageId, pathInContainer] = parseContainerPath(remotePath);
-      this.log.debug(
-        `Parsed package identifier '${packageId}' from '${remotePath}'. Will get the data from '${pathInContainer}'`
-      );
-      tmpDestination = `/data/local/tmp/${path.posix.basename(pathInContainer)}`;
-      try {
-        await this.adb.shell(['run-as', packageId, `chmod 777 '${escapePath(pathInContainer)}'`]);
-        await this.adb.shell([
-          'run-as',
-          packageId,
-          `cp -f '${escapePath(pathInContainer)}' '${escapePath(tmpDestination)}'`,
-        ]);
-      } catch (e) {
-        this.log.errorAndThrow(
-          `Cannot access the container of '${packageId}' application. ` +
-            `Is the application installed and has 'debuggable' build option set to true? ` +
-            `Original error: ${/** @type {Error} */ (e).message}`
-        );
-      }
-    }
-    const localFile = await tempDir.path({prefix: 'appium', suffix: '.tmp'});
-    try {
-      await this.adb.pull(tmpDestination || remotePath, localFile);
-      return (await util.toInMemoryBase64(localFile)).toString();
-    } finally {
-      if (await fs.exists(localFile)) {
-        await fs.unlink(localFile);
-      }
-      if (tmpDestination) {
-        await this.adb.shell(['rm', '-f', tmpDestination]);
-      }
-    }
-  },
-
-  async mobilePullFile(opts) {
-    const {remotePath} = requireArgs('remotePath', opts);
-    return await this.pullFile(remotePath);
-  },
-
-  async pushFile(remotePath, base64Data) {
-    if (remotePath.endsWith('/')) {
-      throw new errors.InvalidArgumentError(
-        `It is expected that remote path points to a file and not to a folder. ` +
-          `'${remotePath}' is given instead`
-      );
-    }
-    const localFile = await tempDir.path({prefix: 'appium', suffix: '.tmp'});
-    if (_.isArray(base64Data)) {
-      // some clients (ahem) java, send a byte array encoding utf8 characters
-      // instead of a string, which would be infinitely better!
-      base64Data = Buffer.from(base64Data).toString('utf8');
-    }
-    const content = Buffer.from(base64Data, 'base64');
-    let tmpDestination = null;
-    try {
-      await fs.writeFile(localFile, content.toString('binary'), 'binary');
-      if (remotePath.startsWith(CONTAINER_PATH_MARKER)) {
-        const [packageId, pathInContainer] = parseContainerPath(remotePath);
-        this.log.debug(
-          `Parsed package identifier '${packageId}' from '${remotePath}'. ` +
-            `Will put the data into '${pathInContainer}'`
-        );
-        tmpDestination = `/data/local/tmp/${path.posix.basename(pathInContainer)}`;
-        try {
-          await this.adb.shell([
-            'run-as',
-            packageId,
-            `mkdir -p '${escapePath(path.posix.dirname(pathInContainer))}'`,
-          ]);
-          await this.adb.shell(['run-as', packageId, `touch '${escapePath(pathInContainer)}'`]);
-          await this.adb.shell(['run-as', packageId, `chmod 777 '${escapePath(pathInContainer)}'`]);
-          await this.adb.push(localFile, tmpDestination);
-          await this.adb.shell([
-            'run-as',
-            packageId,
-            `cp -f '${escapePath(tmpDestination)}' '${escapePath(pathInContainer)}'`,
-          ]);
-        } catch (e) {
-          this.log.errorAndThrow(
-            `Cannot access the container of '${packageId}' application. ` +
-              `Is the application installed and has 'debuggable' build option set to true? ` +
-              `Original error: ${/** @type {Error} */ (e).message}`
-          );
-        }
-      } else {
-        // adb push creates folders and overwrites existing files.
-        await this.adb.push(localFile, remotePath);
-
-        // if we have pushed a file, it might be a media file, so ensure that
-        // apps know about it
-        await scanMedia.bind(this)(remotePath);
-      }
-    } finally {
-      if (await fs.exists(localFile)) {
-        await fs.unlink(localFile);
-      }
-      if (tmpDestination) {
-        await this.adb.shell(['rm', '-f', tmpDestination]);
-      }
-    }
-  },
-
-  async mobilePushFile(opts) {
-    const {remotePath, payload} = requireArgs(['remotePath', 'payload'], opts);
-    return await this.pushFile(remotePath, payload);
-  },
-
-  async pullFolder(remotePath) {
-    const tmpRoot = await tempDir.openDir();
-    try {
-      await this.adb.pull(remotePath, tmpRoot);
-      return (
-        await zip.toInMemoryZip(tmpRoot, {
-          encodeToBase64: true,
-        })
-      ).toString();
-    } finally {
-      await fs.rimraf(tmpRoot);
-    }
-  },
-
-  async mobilePullFolder(opts) {
-    const {remotePath} = requireArgs('remotePath', opts);
-    return await this.pullFolder(remotePath);
-  },
-
-  async mobileDeleteFile(opts) {
-    const {remotePath} = requireArgs('remotePath', opts);
-    if (remotePath.endsWith('/')) {
-      throw new errors.InvalidArgumentError(
-        `It is expected that remote path points to a folder and not to a file. ` +
-          `'${remotePath}' is given instead`
-      );
-    }
-    return await deleteFileOrFolder.call(this, this.adb, remotePath);
-  },
-};
-
 /**
  * Factory providing filesystem test functions using ADB
  * @param {ADB} adb
@@ -272,72 +363,8 @@ function createFSTests(adb) {
   return {isFile, isDir, isPresent};
 }
 
-/**
- * Deletes the given folder or file from the remote device
- *
- * @param {ADB} adb
- * @param {string} remotePath The full path to the remote folder
- * or file (folder names must end with a single slash)
- * @throws {Error} If the provided remote path is invalid or
- * the package content cannot be accessed
- * @returns {Promise<boolean>} `true` if the remote item has been successfully deleted.
- * If the remote path is valid, but the remote path does not exist
- * this function return `false`.
- * @this {import('../driver').AndroidDriver}
- */
-async function deleteFileOrFolder(adb, remotePath) {
-  const {isDir, isPresent, isFile} = createFSTests(adb);
-  let dstPath = remotePath;
-  /** @type {string|undefined} */
-  let pkgId;
-  if (remotePath.startsWith(CONTAINER_PATH_MARKER)) {
-    const [packageId, pathInContainer] = parseContainerPath(remotePath);
-    this.log.debug(`Parsed package identifier '${packageId}' from '${remotePath}'`);
-    dstPath = pathInContainer;
-    pkgId = packageId;
-  }
-
-  if (pkgId) {
-    try {
-      await adb.shell(['run-as', pkgId, 'ls']);
-    } catch (e) {
-      this.log.errorAndThrow(
-        `Cannot access the container of '${pkgId}' application. ` +
-          `Is the application installed and has 'debuggable' build option set to true? ` +
-          `Original error: ${/** @type {Error} */ (e).message}`
-      );
-    }
-  }
-
-  if (!(await isPresent(dstPath, pkgId))) {
-    this.log.info(`The item at '${dstPath}' does not exist. Perhaps, already deleted?`);
-    return false;
-  }
-
-  const expectsFile = !remotePath.endsWith('/');
-  if (expectsFile && !(await isFile(dstPath, pkgId))) {
-    this.log.errorAndThrow(`The item at '${dstPath}' is not a file`);
-  } else if (!expectsFile && !(await isDir(dstPath, pkgId))) {
-    this.log.errorAndThrow(`The item at '${dstPath}' is not a folder`);
-  }
-
-  if (pkgId) {
-    await adb.shell(['run-as', pkgId, `rm -f${expectsFile ? '' : 'r'} '${escapePath(dstPath)}'`]);
-  } else {
-    await adb.shell(['rm', `-f${expectsFile ? '' : 'r'}`, dstPath]);
-  }
-  if (await isPresent(dstPath, pkgId)) {
-    this.log.errorAndThrow(
-      `The item at '${dstPath}' still exists after being deleted. ` + `Is it writable?`
-    );
-  }
-  return true;
-}
-
-mixin(FileActionsMixin);
+// #endregion
 
 /**
  * @typedef {import('appium-adb').ADB} ADB
  */
-
-export default FileActionsMixin;

package/lib/commands/find.ts

@@ -1,35 +1,34 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
 /**
- * @privateRemarks This file needed to be converted to TS because the overload of `findElOrEls` is seemingly impossible to express in JS since the value of `this` cannot be bound via a type assertion.
  * @module
  */
 
 import _ from 'lodash';
-import {mixin, type FindMixin} from './mixins';
 import {errors, isErrorType} from 'appium/driver';
 import type {AndroidDriver} from '../driver';
 import type {Element} from '@appium/types';
 import type {FindElementOpts} from './types';
 
-async function findElOrEls(
+export async function findElOrEls(
   this: AndroidDriver,
   strategy: string,
   selector: string,
   mult: true,
-  context?: string
+  context?: string,
 ): Promise<Element[]>;
-async function findElOrEls(
+export async function findElOrEls(
   this: AndroidDriver,
   strategy: string,
   selector: string,
   mult: false,
-  context?: string
+  context?: string,
 ): Promise<Element>;
-async function findElOrEls(
+export async function findElOrEls(
   this: AndroidDriver,
   strategy: string,
   selector: string,
   mult: boolean,
-  context = ''
+  context = '',
 ) {
   if (!selector) {
     throw new Error('Must provide a selector when finding elements');
@@ -89,14 +88,9 @@ async function findElOrEls(
   return element as Element;
 }
 
-const FindMixin: FindMixin & ThisType<AndroidDriver> = {
-  async doFindElementOrEls(params) {
-    throw new errors.NotImplementedError('Not implemented');
-  },
-
-  findElOrEls,
-};
-
-mixin(FindMixin);
-
-export default FindMixin;
+export async function doFindElementOrEls(
+  this: AndroidDriver,
+  params: FindElementOpts,
+): Promise<Element | Element[]> {
+  throw new errors.NotImplementedError('Not implemented');
+}