feat: Add mobile wrappers for file actions (#760)

Author: mykola-mokhnach

lib/commands/app-management.js

@@ -3,28 +3,13 @@ import { waitForCondition } from 'asyncbox';
 import { util } from 'appium/support';
 import { APP_STATE } from '../android-helpers';
 import { errors } from 'appium/driver';
+import { requireArgs } from '../utils';
 
 const APP_EXTENSIONS = ['.apk', '.apks'];
 const RESOLVER_ACTIVITY_NAME = 'android/com.android.internal.app.ResolverActivity';
 
 const commands = {};
 
-/**
- * Assert the presence of particular keys in the given object
- *
- * @param {string|Array<string>} argNames one or more key names
- * @param {Object} opts the object to check
- * @returns {Object} the same given object
- */
-function requireArgs (argNames, opts = {}) {
-  for (const argName of (_.isArray(argNames) ? argNames : [argNames])) {
-    if (!_.has(opts, argName)) {
-      throw new errors.InvalidArgumentError(`'${argName}' argument must be provided`);
-    }
-  }
-  return opts;
-}
-
 /**
  * Verify whether an application is installed or not
  *

lib/commands/execute.js

@@ -46,6 +46,9 @@ extensions.executeMobile = async function executeMobile (mobileCommand, opts = {
 
     listSms: 'mobileListSms',
 
+    pushFile: 'mobilePushFile',
+    pullFile: 'mobilePullFile',
+    pullFolder: 'mobilePullFolder',
     deleteFile: 'mobileDeleteFile',
 
     isAppInstalled: 'mobileIsAppInstalled',

lib/commands/file-actions.js

@@ -2,6 +2,7 @@ import _ from 'lodash';
 import { fs, util, zip, tempDir } from 'appium/support';
 import path from 'path';
 import { errors } from 'appium/driver';
+import { requireArgs } from '../utils';
 
 
 const CONTAINER_PATH_MARKER = '@';
@@ -115,9 +116,31 @@ commands.pullFile = async function pullFile (remotePath) {
 };
 
 /**
- * Pushed the given data to a file on the remote device
+ * @typedef {Object} PullFileOptions
+ * @property {string} remotePath The full path to the remote file
+ * or a specially formatted path, which points to an item inside an app bundle,
+ * for example `@my.app.id/my/path`. It is mandatory for the app bundle to have
+ * debugging enabled in order to use the latter remotePath format.
+ */
+
+/**
+ * Pulls a remote file from the device.
+ *
+ * @param {PullFileOptions} opts
+ * @returns {string} The same as `pullFile`
+ */
+commands.mobilePullFile = async function mobilePullFile (opts = {}) {
+  const { remotePath } = requireArgs('remotePath', opts);
+  return await this.pullFile(remotePath);
+};
+
+/**
+ * Pushes the given data to a file on the remote device
  * It is required, that a package has debugging flag enabled
  * in order to access its files.
+ * After a file is pushed it gets automatically scanned for possible
+ * media occurrences. If the scan succeeds then the file is added to the
+ * media library.
  *
  * @param {string} remotePath The full path to the remote file or
  * a file inside a package bundle
@@ -181,6 +204,25 @@ commands.pushFile = async function pushFile (remotePath, base64Data) {
   }
 };
 
+/**
+ * @typedef {Object} PushFileOptions
+ * @property {string} remotePath The full path to the remote file
+ * or a specially formatted path, which points to an item inside an app bundle,
+ * for example `@my.app.id/my/path`. It is mandatory for the app bundle to have
+ * debugging enabled in order to use the latter remotePath format.
+ * @property {string} payload Base64-encoded content of the file to be pushed.
+ */
+
+/**
+ * Pushes the given data to a file on the remote device.
+ *
+ * @param {PushFileOptions} opts
+ */
+commands.mobilePushFile = async function mobilePushFile (opts = {}) {
+  const { remotePath, payload } = requireArgs(['remotePath', 'payload'], opts);
+  return await this.pushFile(remotePath, payload);
+};
+
 /**
  * Pulls the whole folder from the remote device
  *
@@ -190,11 +232,31 @@ commands.pushFile = async function pushFile (remotePath, base64Data) {
  * @throws {Error} If there was a failure while getting the folder content
  */
 commands.pullFolder = async function pullFolder (remotePath) {
-  let localFolder = await tempDir.path({prefix: 'appium'});
-  await this.adb.pull(remotePath, localFolder);
-  return (await zip.toInMemoryZip(localFolder, {
-    encodeToBase64: true,
-  })).toString();
+  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);
+  }
+};
+
+/**
+ * @typedef {Object} PullFolderOptions
+ * @property {string} remotePath The full path to the remote folder.
+ */
+
+/**
+ * Pulls the whole folder from the device under test.
+ *
+ * @param {PullFolderOptions} opts
+ * @returns {string} The same as `pullFolder`
+ */
+commands.mobilePullFolder = async function mobilePullFolder (opts = {}) {
+  const { remotePath } = requireArgs('remotePath', opts);
+  return await this.pullFolder(remotePath);
 };
 
 /**

lib/utils.js

@@ -0,0 +1,19 @@
+import _ from 'lodash';
+import { errors } from 'appium/driver';
+
+
+/**
+ * Assert the presence of particular keys in the given object
+ *
+ * @param {string|Array<string>} argNames one or more key names
+ * @param {Object} opts the object to check
+ * @returns {Object} the same given object
+ */
+export function requireArgs (argNames, opts = {}) {
+  for (const argName of (_.isArray(argNames) ? argNames : [argNames])) {
+    if (!_.has(opts, argName)) {
+      throw new errors.InvalidArgumentError(`'${argName}' argument must be provided`);
+    }
+  }
+  return opts;
+}