appium-xcuitest-driver 10.2.2 → 10.4.0

package/lib/commands/execute.js

@@ -3,6 +3,78 @@ import {XCUITestDriver} from '../driver';
 import {errors, errorFromCode, errorFromW3CJsonCode} from 'appium/driver';
 import {util} from 'appium/support';
 
+/**
+ * Collect the response of an async script execution
+ * @this {XCUITestDriver}
+ * @deprecated
+ * @privateRemarks It's unclear what this is for. Don't use it.
+ */
+export async function receiveAsyncResponse(status, value) {
+  this.log.debug(`Received async response: ${JSON.stringify(value)}`);
+  if (!util.hasValue(this.asyncPromise)) {
+    this.log.warn(
+      `Received async response when we were not expecting one! ` +
+        `Response was: ${JSON.stringify(value)}`,
+    );
+    return;
+  }
+
+  if (util.hasValue(status) && status !== 0) {
+    // MJSONWP
+    return this.asyncPromise.reject(errorFromCode(status, value.message));
+  }
+  if (!util.hasValue(status) && value && _.isString(value.error)) {
+    // W3C
+    return this.asyncPromise.reject(
+      errorFromW3CJsonCode(value.error, value.message, value.stacktrace),
+    );
+  }
+  return this.asyncPromise.resolve(value);
+}
+
+/**
+ * @template {ExecuteMethodArgs} [TArgs = unknown[]]
+ * @template [TReturn = unknown]
+ * @param {string} script - Either a script to run, or in the case of an Execute Method, the name of the script to execute.
+ * @param {TArgs} [args]
+ * @this {XCUITestDriver}
+ * @returns {Promise<TReturn>}
+ */
+export async function execute(script, args) {
+  // TODO: create a type that converts args to the parameters of the associated method using the `command` prop of `executeMethodMap`
+  script = script.trim().replace(/^mobile:\s*/, 'mobile: ');
+  if (isExecuteMethod(script)) {
+    const executeMethodArgs = preprocessExecuteMethodArgs(script, args);
+    return await this.executeMethod(script, [executeMethodArgs]);
+  } else if (this.isWebContext()) {
+    const atomsArgs = this.convertElementsForAtoms(/** @type {readonly any[]} */ (args));
+    const result = await this.executeAtom('execute_script', [script, atomsArgs]);
+    return this.cacheWebElements(result);
+  } else {
+    throw new errors.NotImplementedError();
+  }
+}
+
+/**
+ * @this {XCUITestDriver}
+ * @group Mobile Web Only
+ */
+export async function executeAsync(script, args) {
+  if (!this.isWebContext()) {
+    throw new errors.NotImplementedError();
+  }
+
+  args = this.convertElementsForAtoms(args);
+  this.asyncWaitMs = this.asyncWaitMs || 0;
+  const promise = (/** @type {import('appium-remote-debugger').RemoteDebugger} */ (this.remote)).executeAtomAsync(
+    'execute_async_script',
+    [script, args, this.asyncWaitMs],
+    this.curWebFrames,
+  );
+  return this.cacheWebElements(await this.waitForAtom(promise));
+}
+
+
 /**
  * Checks if script expects a particular parameter (either optional or required).
  * @template {keyof XCUITestDriver.executeMethodMap} Script
@@ -71,78 +143,6 @@ function preprocessExecuteMethodArgs(script, args) {
   return executeMethodArgs;
 }
 
-export default {
-  /**
-   * Collect the response of an async script execution
-   * @this {XCUITestDriver}
-   * @deprecated
-   * @privateRemarks It's unclear what this is for. Don't use it.
-   */
-  async receiveAsyncResponse(status, value) {
-    this.log.debug(`Received async response: ${JSON.stringify(value)}`);
-    if (!util.hasValue(this.asyncPromise)) {
-      this.log.warn(
-        `Received async response when we were not expecting one! ` +
-          `Response was: ${JSON.stringify(value)}`,
-      );
-      return;
-    }
-
-    if (util.hasValue(status) && status !== 0) {
-      // MJSONWP
-      return this.asyncPromise.reject(errorFromCode(status, value.message));
-    }
-    if (!util.hasValue(status) && value && _.isString(value.error)) {
-      // W3C
-      return this.asyncPromise.reject(
-        errorFromW3CJsonCode(value.error, value.message, value.stacktrace),
-      );
-    }
-    return this.asyncPromise.resolve(value);
-  },
-
-  /**
-   * @template {ExecuteMethodArgs} [TArgs = unknown[]]
-   * @template [TReturn = unknown]
-   * @param {string} script - Either a script to run, or in the case of an Execute Method, the name of the script to execute.
-   * @param {TArgs} [args]
-   * @this {XCUITestDriver}
-   * @returns {Promise<TReturn>}
-   */
-  async execute(script, args) {
-    // TODO: create a type that converts args to the parameters of the associated method using the `command` prop of `executeMethodMap`
-    script = script.trim().replace(/^mobile:\s*/, 'mobile: ');
-    if (isExecuteMethod(script)) {
-      const executeMethodArgs = preprocessExecuteMethodArgs(script, args);
-      return await this.executeMethod(script, [executeMethodArgs]);
-    } else if (this.isWebContext()) {
-      const atomsArgs = this.convertElementsForAtoms(/** @type {readonly any[]} */ (args));
-      const result = await this.executeAtom('execute_script', [script, atomsArgs]);
-      return this.cacheWebElements(result);
-    } else {
-      throw new errors.NotImplementedError();
-    }
-  },
-  /**
-   * @this {XCUITestDriver}
-   * @group Mobile Web Only
-   */
-  async executeAsync(script, args) {
-    if (!this.isWebContext()) {
-      throw new errors.NotImplementedError();
-    }
-
-    args = this.convertElementsForAtoms(args);
-    this.asyncWaitMs = this.asyncWaitMs || 0;
-    const promise = (/** @type {import('appium-remote-debugger').RemoteDebugger} */ (this.remote)).executeAtomAsync(
-      'execute_async_script',
-      [script, args, this.asyncWaitMs],
-      this.curWebFrames,
-    );
-    return this.cacheWebElements(await this.waitForAtom(promise));
-  },
-};
-
 /**
  * @template [T=any]
  * @typedef {import('@appium/types').StringRecord<T>} StringRecord

package/lib/commands/file-movement.js

@@ -2,7 +2,7 @@ import _ from 'lodash';
 import {fs, tempDir, mkdirp, zip, util} from 'appium/support';
 import path from 'path';
 import {services} from 'appium-ios-device';
-import {pullFile, pullFolder, pushFile} from '../ios-fs-helpers';
+import {pullFile as iosPullFile, pullFolder as iosPullFolder, pushFile as iosPushFile} from '../ios-fs-helpers';
 import {errors} from 'appium/driver';
 
 const CONTAINER_PATH_MARKER = '@';
@@ -192,7 +192,7 @@ async function pushFileToSimulator(remotePath, base64Data) {
 async function pushFileToRealDevice(remotePath, base64Data) {
   const {service, relativePath} = await createService.bind(this)(remotePath);
   try {
-    await pushFile(service, Buffer.from(base64Data, 'base64'), relativePath);
+    await iosPushFile(service, Buffer.from(base64Data, 'base64'), relativePath);
   } catch (e) {
     this.log.debug(e.stack);
     throw new Error(`Could not push the file to '${remotePath}'. Original error: ${e.message}`);
@@ -291,8 +291,8 @@ async function pullFromRealDevice(remotePath, isFile) {
     }
 
     return fileInfo.isFile()
-      ? (await pullFile(service, relativePath)).toString('base64')
-      : (await pullFolder(service, relativePath)).toString();
+      ? (await iosPullFile(service, relativePath)).toString('base64')
+      : (await iosPullFolder(service, relativePath)).toString();
   } finally {
     service.close();
   }
@@ -369,143 +369,141 @@ async function deleteFromRealDevice(remotePath) {
   }
 }
 
-export default {
-  /**
-   * Pushes the given data to a file on the remote device
-   *
-   * @param {string} remotePath The full path to the remote file or
-   * a file inside a package bundle. Check the documentation on
-   * `pushFileToRealDevice` and `pushFileToSimulator` for more information
-   * on acceptable values.
-   * @param {string} base64Data Base64 encoded data to be written to the
-   * remote file. The remote file will be silently overridden if it already exists.
-   * @throws {Error} If there was an error while pushing the data
-   * @this {XCUITestDriver}
-   */
-  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`,
-      );
-    }
-    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');
-    }
-    return this.isSimulator()
-      ? await pushFileToSimulator.bind(this)(remotePath, base64Data)
-      : await pushFileToRealDevice.bind(this)(remotePath, base64Data);
-  },
+/**
+ * Pushes the given data to a file on the remote device
+ *
+ * @param {string} remotePath The full path to the remote file or
+ * a file inside a package bundle. Check the documentation on
+ * `pushFileToRealDevice` and `pushFileToSimulator` for more information
+ * on acceptable values.
+ * @param {string} base64Data Base64 encoded data to be written to the
+ * remote file. The remote file will be silently overridden if it already exists.
+ * @throws {Error} If there was an error while pushing the data
+ * @this {XCUITestDriver}
+ */
+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`,
+    );
+  }
+  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');
+  }
+  return this.isSimulator()
+    ? await pushFileToSimulator.bind(this)(remotePath, base64Data)
+    : await pushFileToRealDevice.bind(this)(remotePath, base64Data);
+}
 
-  /**
-   * Pushes the given data to a file on the remote device.
-   *
-   * @param {string} remotePath - The full path to the remote file
-   * or a specially formatted path, which points to an item inside an app bundle.
-   * @param {string} payload - Base64-encoded content of the file to be pushed.
-   * @this {XCUITestDriver}
-   */
-  async mobilePushFile(remotePath, payload) {
-    return await this.pushFile(remotePath, payload);
-  },
+/**
+ * Pushes the given data to a file on the remote device.
+ *
+ * @param {string} remotePath - The full path to the remote file
+ * or a specially formatted path, which points to an item inside an app bundle.
+ * @param {string} payload - Base64-encoded content of the file to be pushed.
+ * @this {XCUITestDriver}
+ */
+export async function mobilePushFile(remotePath, payload) {
+  return await this.pushFile(remotePath, payload);
+}
 
-  /**
-   * Pulls a remote file from the device.
-   *
-   * @param {string} remotePath The full path to the remote file
-   * or a specially formatted path, which points to an item inside app bundle.
-   * See the documentation for `pullFromRealDevice` and `pullFromSimulator`
-   * to get more information on acceptable values.
-   * @returns {Promise<string>} Base64 encoded content of the pulled file
-   * @throws {Error} If the pull operation failed
-   * @this {XCUITestDriver}
-   */
-  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`,
-      );
-    }
-    return this.isSimulator()
-      ? await pullFromSimulator.bind(this)(remotePath, true)
-      : await pullFromRealDevice.bind(this)(remotePath, true);
-  },
+/**
+ * Pulls a remote file from the device.
+ *
+ * @param {string} remotePath The full path to the remote file
+ * or a specially formatted path, which points to an item inside app bundle.
+ * See the documentation for `pullFromRealDevice` and `pullFromSimulator`
+ * to get more information on acceptable values.
+ * @returns {Promise<string>} Base64 encoded content of the pulled file
+ * @throws {Error} If the pull operation failed
+ * @this {XCUITestDriver}
+ */
+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`,
+    );
+  }
+  return this.isSimulator()
+    ? await pullFromSimulator.bind(this)(remotePath, true)
+    : await pullFromRealDevice.bind(this)(remotePath, true);
+}
 
-  /**
-   * Pulls a remote file from the device.
-   *
-   * @param {string} remotePath - The full path to the remote file
-   * or a specially formatted path, which points to an item inside app bundle.  See the documentation for `pullFromRealDevice` and `pullFromSimulator` to get more information on acceptable values.
-   * @returns {Promise<string>} The same as in `pullFile`
-   * @this {XCUITestDriver}
-   */
-  async mobilePullFile(remotePath) {
-    return await this.pullFile(remotePath);
-  },
+/**
+ * Pulls a remote file from the device.
+ *
+ * @param {string} remotePath - The full path to the remote file
+ * or a specially formatted path, which points to an item inside app bundle.  See the documentation for `pullFromRealDevice` and `pullFromSimulator` to get more information on acceptable values.
+ * @returns {Promise<string>} The same as in `pullFile`
+ * @this {XCUITestDriver}
+ */
+export async function mobilePullFile(remotePath) {
+  return await this.pullFile(remotePath);
+}
 
-  /**
-   * Delete a remote folder from the device.
-   *
-   * @param {string} remotePath - The full path to the remote folder or a specially formatted path, which points to an item inside app bundle. See the documentation for `pullFromRealDevice` and `pullFromSimulator` to get more information on acceptable values.
-   * @this {XCUITestDriver}
-   * @returns {Promise<void>}
-   */
-  async mobileDeleteFolder(remotePath) {
-    if (!remotePath.endsWith('/')) {
-      remotePath = `${remotePath}/`;
-    }
-    await deleteFileOrFolder.bind(this)(remotePath);
-  },
+/**
+ * Delete a remote folder from the device.
+ *
+ * @param {string} remotePath - The full path to the remote folder or a specially formatted path, which points to an item inside app bundle. See the documentation for `pullFromRealDevice` and `pullFromSimulator` to get more information on acceptable values.
+ * @this {XCUITestDriver}
+ * @returns {Promise<void>}
+ */
+export async function mobileDeleteFolder(remotePath) {
+  if (!remotePath.endsWith('/')) {
+    remotePath = `${remotePath}/`;
+  }
+  await deleteFileOrFolder.bind(this)(remotePath);
+}
 
-  /**
-   * Delete a remote file from the device.
-   *
-   * @param {string} remotePath - The full path to the remote file or a specially formatted path, which points to an item inside app bundle. See the documentation for `pullFromRealDevice` and `pullFromSimulator` to get more information on acceptable values.
-   * @this {XCUITestDriver}
-   * @returns {Promise<void>}
-   */
-  async mobileDeleteFile(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`,
-      );
-    }
-    await deleteFileOrFolder.bind(this)(remotePath);
-  },
+/**
+ * Delete a remote file from the device.
+ *
+ * @param {string} remotePath - The full path to the remote file or a specially formatted path, which points to an item inside app bundle. See the documentation for `pullFromRealDevice` and `pullFromSimulator` to get more information on acceptable values.
+ * @this {XCUITestDriver}
+ * @returns {Promise<void>}
+ */
+export async function mobileDeleteFile(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`,
+    );
+  }
+  await deleteFileOrFolder.bind(this)(remotePath);
+}
 
-  /**
-   * Pulls the whole folder from the remote device
-   *
-   * @param {string} remotePath The full path to a folder on the
-   * remote device or a folder inside an application bundle
-   * @returns {Promise<string>} Zipped and base64-encoded content of the folder
-   * @throws {Error} If there was a failure while getting the folder content
-   * @this {XCUITestDriver}
-   */
-  async pullFolder(remotePath) {
-    if (!remotePath.endsWith('/')) {
-      remotePath = `${remotePath}/`;
-    }
-    return this.isSimulator()
-      ? await pullFromSimulator.bind(this)(remotePath, false)
-      : await pullFromRealDevice.bind(this)(remotePath, false);
-  },
+/**
+ * Pulls the whole folder from the remote device
+ *
+ * @param {string} remotePath The full path to a folder on the
+ * remote device or a folder inside an application bundle
+ * @returns {Promise<string>} Zipped and base64-encoded content of the folder
+ * @throws {Error} If there was a failure while getting the folder content
+ * @this {XCUITestDriver}
+ */
+export async function pullFolder(remotePath) {
+  if (!remotePath.endsWith('/')) {
+    remotePath = `${remotePath}/`;
+  }
+  return this.isSimulator()
+    ? await pullFromSimulator.bind(this)(remotePath, false)
+    : await pullFromRealDevice.bind(this)(remotePath, false);
+}
 
-  /**
-   * Pulls the whole folder from the device under test.
-   *
-   * @param {string} remotePath - The full path to the remote folder
-   * @returns {Promise<string>} The same as `pullFolder`
-   * @this {XCUITestDriver}
-   */
-  async mobilePullFolder(remotePath) {
-    return await this.pullFolder(remotePath);
-  },
-};
+/**
+ * Pulls the whole folder from the device under test.
+ *
+ * @param {string} remotePath - The full path to the remote folder
+ * @returns {Promise<string>} The same as `pullFolder`
+ * @this {XCUITestDriver}
+ */
+export async function mobilePullFolder(remotePath) {
+  return await this.pullFolder(remotePath);
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver