appium-xcuitest-driver 10.3.0 → 10.4.1

package/lib/commands/navigation.js

@@ -7,114 +7,110 @@ import { isTvOs } from '../utils';
 const CLOSE_WINDOW_TIMEOUT = 5000;
 const CLOSE_WINDOW_INTERVAL = 100;
 
-const commands = {
-  /**
-   * @this {XCUITestDriver}
-   */
-  async back() {
-    if (!this.isWebContext()) {
-      await this.nativeBack();
-    } else {
-      await this.mobileWebNav('back');
-    }
-  },
-  /**
-   * @this {XCUITestDriver}
-   */
-  async forward() {
-    if (!this.isWebContext()) {
-    }
-    await this.mobileWebNav('forward');
-  },
-  /**
-   * @this {XCUITestDriver}
-   */
-  async closeWindow() {
-    if (!this.isWebContext()) {
-      throw new errors.NotImplementedError();
-    }
+/**
+ * @this {XCUITestDriver}
+ */
+export async function back() {
+  if (!this.isWebContext()) {
+    await this.nativeBack();
+  } else {
+    await this.mobileWebNav('back');
+  }
+}
 
-    // since the window will be closed and the execution context gone, return
-    // first before closing. Waiting for close will happen in the finally block
-    const script = `setTimeout(function () {window.open('','_self').close();}, 0); return true;`;
-    const context = this.curContext;
-    try {
-      return await this.executeAtom('execute_script', [script, []], true);
-    } finally {
-      // wait for the window to successfully change...
-      try {
-        await waitForCondition(() => this.curContext !== context, {
-          waitMs: CLOSE_WINDOW_TIMEOUT,
-          intervalMs: CLOSE_WINDOW_INTERVAL,
-        });
-      } catch {
-        this.log.debug('Context has not yet been changed after closing window. Continuing...');
-      }
-    }
-  },
+/**
+ * @this {XCUITestDriver}
+ */
+export async function forward() {
+  if (!this.isWebContext()) {
+  }
+  await this.mobileWebNav('forward');
+}
 
-  /**
-   * Opens the given URL with the default application assigned to handle it based on the URL
-   * scheme, or the application provided as an optional parameter
-   *
-   * (Note: the version of Xcode must be 14.3+ and iOS must be 16.4+)
-   *
-   * @param {string} url - the URL to be opened, e.g. `myscheme://yolo`
-   * @param {string} [bundleId] - the application to open the given URL with. If not provided, then
-   * the application assigned by the operating system to handle URLs of the appropriate type
-   * @returns {Promise<void>}
-   * @since 4.17
-   * @this {XCUITestDriver}
-   */
-  async mobileDeepLink(url, bundleId) {
-    return await this.proxyCommand('/url', 'POST', {
-      url,
-      bundleId,
-    });
-  },
-};
+/**
+ * @this {XCUITestDriver}
+ */
+export async function closeWindow() {
+  if (!this.isWebContext()) {
+    throw new errors.NotImplementedError();
+  }
 
-const helpers = {
-  /**
-   * @this {XCUITestDriver}
-   */
-  async nativeBack() {
-    if (isTvOs(this.opts.platformName)) {
-      this.log.debug(`Sending Menu button as back behavior in tvOS`);
-      return await this.mobilePressButton('Menu');
+  // since the window will be closed and the execution context gone, return
+  // first before closing. Waiting for close will happen in the finally block
+  const script = `setTimeout(function () {window.open('','_self').close();}, 0); return true;`;
+  const context = this.curContext;
+  try {
+    return await this.executeAtom('execute_script', [script, []], true);
+  } finally {
+    // wait for the window to successfully change...
+    try {
+      await waitForCondition(() => this.curContext !== context, {
+        waitMs: CLOSE_WINDOW_TIMEOUT,
+        intervalMs: CLOSE_WINDOW_INTERVAL,
+      });
+    } catch {
+      this.log.debug('Context has not yet been changed after closing window. Continuing...');
     }
+  }
+}
 
-    try {
-      let navBar = await this.findNativeElementOrElements(
-        'class name',
-        'XCUIElementTypeNavigationBar',
-        false,
-      );
-      let buttons = await this.findNativeElementOrElements(
-        'class name',
-        'XCUIElementTypeButton',
-        true,
-        navBar,
-      );
-      if (buttons?.length === 0) {
-        throw new Error('No buttons found in navigation bar');
-      }
+/**
+ * Opens the given URL with the default application assigned to handle it based on the URL
+ * scheme, or the application provided as an optional parameter
+ *
+ * (Note: the version of Xcode must be 14.3+ and iOS must be 16.4+)
+ *
+ * @param {string} url - the URL to be opened, e.g. `myscheme://yolo`
+ * @param {string} [bundleId] - the application to open the given URL with. If not provided, then
+ * the application assigned by the operating system to handle URLs of the appropriate type
+ * @returns {Promise<void>}
+ * @since 4.17
+ * @this {XCUITestDriver}
+ */
+export async function mobileDeepLink(url, bundleId) {
+  return await this.proxyCommand('/url', 'POST', {
+    url,
+    bundleId,
+  });
+}
 
-      let backButton = _.filter(buttons, (value) => value.label === 'Back')[0];
-      if (backButton) {
-        this.log.debug(`Found navigation bar 'back' button. Clicking.`);
-      } else {
-        this.log.debug(`Unable to find 'Back' button. Trying first button in navigation bar`);
-        backButton = buttons?.[0];
-      }
-      await this.nativeClick(/** @type {string} */ (backButton));
-    } catch (err) {
-      this.log.error(`Unable to find navigation bar and back button: ${err.message}`);
+/**
+ * @this {XCUITestDriver}
+ */
+export async function nativeBack() {
+  if (isTvOs(this.opts.platformName)) {
+    this.log.debug(`Sending Menu button as back behavior in tvOS`);
+    return await this.mobilePressButton('Menu');
+  }
+
+  try {
+    let navBar = await this.findNativeElementOrElements(
+      'class name',
+      'XCUIElementTypeNavigationBar',
+      false,
+    );
+    let buttons = await this.findNativeElementOrElements(
+      'class name',
+      'XCUIElementTypeButton',
+      true,
+      navBar,
+    );
+    if (buttons?.length === 0) {
+      throw new Error('No buttons found in navigation bar');
     }
-  },
-};
 
-export default {...helpers, ...commands};
+    let backButton = _.filter(buttons, (value) => value.label === 'Back')[0];
+    if (backButton) {
+      this.log.debug(`Found navigation bar 'back' button. Clicking.`);
+    } else {
+      this.log.debug(`Unable to find 'Back' button. Trying first button in navigation bar`);
+      backButton = buttons?.[0];
+    }
+    await this.nativeClick(/** @type {string} */ (backButton));
+  } catch (err) {
+    this.log.error(`Unable to find navigation bar and back button: ${err.message}`);
+  }
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver

package/lib/commands/notifications.js

@@ -1,67 +1,65 @@
 import {errors} from 'appium/driver';
 import _ from 'lodash';
 
-export default {
-  /**
-   * Simulates push notification delivery to a simulated device.
-   *
-   * **Only "remote" push notifications are supported.** VoIP, Complication, File Provider, and other types are unsupported.
-   *
-   * Supported in Xcode SDK 11.4+.
-   * @param {string} bundleId - The bundle identifier of the target application
-   * @param {import('./types').PushPayload} payload - Valid push payload.
-   * @group Simulator Only
-   * @this {XCUITestDriver}
-   */
-  async mobilePushNotification(bundleId, payload) {
-    if (!this.isSimulator()) {
-      throw new Error('This extension only works on Simulator');
-    }
+/**
+ * Simulates push notification delivery to a simulated device.
+ *
+ * **Only "remote" push notifications are supported.** VoIP, Complication, File Provider, and other types are unsupported.
+ *
+ * Supported in Xcode SDK 11.4+.
+ * @param {string} bundleId - The bundle identifier of the target application
+ * @param {import('./types').PushPayload} payload - Valid push payload.
+ * @group Simulator Only
+ * @this {XCUITestDriver}
+ */
+export async function mobilePushNotification(bundleId, payload) {
+  if (!this.isSimulator()) {
+    throw new Error('This extension only works on Simulator');
+  }
 
-    if (!bundleId) {
-      throw new errors.InvalidArgumentError(
-        `'bundleId' argument must be a valid bundle identifier string`,
-      );
-    }
-    if (!_.isPlainObject(payload)) {
-      throw new errors.InvalidArgumentError(
-        `The 'payload' argument value must be a valid dictionary. ` +
-          `Got ${JSON.stringify(payload)} instead`,
-      );
-    }
-    if (!_.isPlainObject(payload.aps)) {
-      throw new errors.InvalidArgumentError(
-        `The 'payload.aps' value must be a valid dictionary. ` +
-          `Got ${JSON.stringify(payload.aps)} instead`,
-      );
-    }
-    return await /** @type {import('../driver').Simulator} */ (this.device).pushNotification({
-      ...payload,
-      'Simulator Target Bundle': bundleId,
-    });
-  },
+  if (!bundleId) {
+    throw new errors.InvalidArgumentError(
+      `'bundleId' argument must be a valid bundle identifier string`,
+    );
+  }
+  if (!_.isPlainObject(payload)) {
+    throw new errors.InvalidArgumentError(
+      `The 'payload' argument value must be a valid dictionary. ` +
+        `Got ${JSON.stringify(payload)} instead`,
+    );
+  }
+  if (!_.isPlainObject(payload.aps)) {
+    throw new errors.InvalidArgumentError(
+      `The 'payload.aps' value must be a valid dictionary. ` +
+        `Got ${JSON.stringify(payload.aps)} instead`,
+    );
+  }
+  return await /** @type {import('../driver').Simulator} */ (this.device).pushNotification({
+    ...payload,
+    'Simulator Target Bundle': bundleId,
+  });
+}
 
-  /**
-   * Blocks until the expected notification is delivered.
-   *
-   * This method is a thin wrapper over the
-   * [`XCTNSNotificationExpectation`](https://developer.apple.com/documentation/xctest/xctnsnotificationexpectation?language=objc) and
-   * [`XCTDarwinNotificationExpectation`](https://developer.apple.com/documentation/xctest/xctdarwinnotificationexpectation?language=objc) entities.
-   *
-   * @param {string} name - The name of the notification to expect
-   * @param {import('./types').NotificationType} type - Which notification type to expect.
-   * @param {number} timeoutSeconds - For how long to wait until the notification is delivered (in float seconds).
-   * @throws A [`TimeoutError`](https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/error_exports_TimeoutError.html) if the expected notification has not been delivered within the given timeout.
-   * @this {XCUITestDriver}
-   */
-  async mobileExpectNotification(name, type = 'plain', timeoutSeconds = 60) {
-    return await this.proxyCommand('/wda/expectNotification', 'POST', {
-      name,
-      type,
-      timeout: timeoutSeconds,
-    });
-  },
-};
+/**
+ * Blocks until the expected notification is delivered.
+ *
+ * This method is a thin wrapper over the
+ * [`XCTNSNotificationExpectation`](https://developer.apple.com/documentation/xctest/xctnsnotificationexpectation?language=objc) and
+ * [`XCTDarwinNotificationExpectation`](https://developer.apple.com/documentation/xctest/xctdarwinnotificationexpectation?language=objc) entities.
+ *
+ * @param {string} name - The name of the notification to expect
+ * @param {import('./types').NotificationType} type - Which notification type to expect.
+ * @param {number} timeoutSeconds - For how long to wait until the notification is delivered (in float seconds).
+ * @throws A [`TimeoutError`](https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/error_exports_TimeoutError.html) if the expected notification has not been delivered within the given timeout.
+ * @this {XCUITestDriver}
+ */
+export async function mobileExpectNotification(name, type = 'plain', timeoutSeconds = 60) {
+  return await this.proxyCommand('/wda/expectNotification', 'POST', {
+    name,
+    type,
+    timeout: timeoutSeconds,
+  });
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver

package/lib/commands/pasteboard.js

@@ -1,43 +1,41 @@
-export default {
-  /**
-   * Sets the Simulator's pasteboard content to the given value.
-   *
-   * Does not work for real devices.
-   * @param {string} content - The content to set
-   * @param {string} encoding - The content's encoding
-   * @group Simulator Only
-   * @returns {Promise<void>}
-   * @this {XCUITestDriver}
-   */
-  async mobileSetPasteboard(content, encoding = 'utf8') {
-    if (!this.isSimulator()) {
-      throw new Error('Setting pasteboard content is not supported on real devices');
-    }
-    if (!content) {
-      // can be empty string
-      throw new Error('Pasteboard content is mandatory to set');
-    }
-    return await /** @type {import('../driver').Simulator} */ (this.device).simctl.setPasteboard(
-      content, /** @type {BufferEncoding} */ (encoding)
-    );
-  },
+/**
+ * Sets the Simulator's pasteboard content to the given value.
+ *
+ * Does not work for real devices.
+ * @param {string} content - The content to set
+ * @param {string} encoding - The content's encoding
+ * @group Simulator Only
+ * @returns {Promise<void>}
+ * @this {XCUITestDriver}
+ */
+export async function mobileSetPasteboard(content, encoding = 'utf8') {
+  if (!this.isSimulator()) {
+    throw new Error('Setting pasteboard content is not supported on real devices');
+  }
+  if (!content) {
+    // can be empty string
+    throw new Error('Pasteboard content is mandatory to set');
+  }
+  return await /** @type {import('../driver').Simulator} */ (this.device).simctl.setPasteboard(
+    content, /** @type {BufferEncoding} */ (encoding)
+  );
+}
 
-  /**
-   * Gets the Simulator's pasteboard content.
-   *
-   * Does not work for real devices.
-   * @param {string} encoding - Expected encoding of returned string
-   * @group Simulator Only
-   * @this {XCUITestDriver}
-   * @returns {Promise<string>} The pasteboard content string
-   */
-  async mobileGetPasteboard(encoding = 'utf8') {
-    if (!this.isSimulator()) {
-      throw new Error('Getting pasteboard content is not supported on real devices');
-    }
-    return await /** @type {import('../driver').Simulator} */ (this.device).simctl.getPasteboard(encoding);
-  },
-};
+/**
+ * Gets the Simulator's pasteboard content.
+ *
+ * Does not work for real devices.
+ * @param {string} encoding - Expected encoding of returned string
+ * @group Simulator Only
+ * @this {XCUITestDriver}
+ * @returns {Promise<string>} The pasteboard content string
+ */
+export async function mobileGetPasteboard(encoding = 'utf8') {
+  if (!this.isSimulator()) {
+    throw new Error('Getting pasteboard content is not supported on real devices');
+  }
+  return await /** @type {import('../driver').Simulator} */ (this.device).simctl.getPasteboard(encoding);
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver

package/lib/commands/pcap.js

@@ -71,99 +71,97 @@ export class TrafficCapture {
   }
 }
 
-export default {
-  /**
-   * Records the given network traffic capture into a .pcap file.
-   *
-   * @param {number} timeLimitSec - The maximum recording time, in seconds. The maximum value is `43200` (12 hours).
-   * @param {boolean} forceRestart - Whether to restart traffic capture process forcefully when startPcap is called (`true`) or ignore the call until the current traffic capture is completed (`false`, the default value).
-   * @throws {Error} If network traffic capture has failed to start.
-   * @returns {Promise<void>}
-   * @this {XCUITestDriver}
-   */
-  async mobileStartPcap(timeLimitSec = 180, forceRestart = false) {
-    if (this.isSimulator()) {
-      throw this.log.errorWithException('Network traffic capture only works on real devices');
-    }
+/**
+ * Records the given network traffic capture into a .pcap file.
+ *
+ * @param {number} timeLimitSec - The maximum recording time, in seconds. The maximum value is `43200` (12 hours).
+ * @param {boolean} forceRestart - Whether to restart traffic capture process forcefully when startPcap is called (`true`) or ignore the call until the current traffic capture is completed (`false`, the default value).
+ * @throws {Error} If network traffic capture has failed to start.
+ * @returns {Promise<void>}
+ * @this {XCUITestDriver}
+ */
+export async function mobileStartPcap(timeLimitSec = 180, forceRestart = false) {
+  if (this.isSimulator()) {
+    throw this.log.errorWithException('Network traffic capture only works on real devices');
+  }
 
-    if (this._trafficCapture?.isCapturing()) {
-      this.log.info(`There is an active traffic capture process`);
-      if (forceRestart) {
-        this.log.info(`Stopping it because 'forceRestart' option is set to true`);
-        await this._trafficCapture.interrupt(true);
-      } else {
-        this.log.info(
-          `Doing nothing. ` +
-            `Set 'forceRestart' option to true if you'd like to start a new traffic capture session`,
-        );
-        return;
-      }
-    }
-    if (this._trafficCapture) {
-      await this._trafficCapture.cleanup();
-      this._trafficCapture = null;
+  if (this._trafficCapture?.isCapturing()) {
+    this.log.info(`There is an active traffic capture process`);
+    if (forceRestart) {
+      this.log.info(`Stopping it because 'forceRestart' option is set to true`);
+      await this._trafficCapture.interrupt(true);
+    } else {
+      this.log.info(
+        `Doing nothing. ` +
+          `Set 'forceRestart' option to true if you'd like to start a new traffic capture session`,
+      );
+      return;
     }
+  }
+  if (this._trafficCapture) {
+    await this._trafficCapture.cleanup();
+    this._trafficCapture = null;
+  }
 
-    const resultPath = await tempDir.path({
-      prefix: `appium_${util.uuidV4().substring(0, 8)}`,
-      suffix: DEFAULT_EXT,
-    });
-    const trafficCollector = new TrafficCapture(this.device.udid, this.log, resultPath);
+  const resultPath = await tempDir.path({
+    prefix: `appium_${util.uuidV4().substring(0, 8)}`,
+    suffix: DEFAULT_EXT,
+  });
+  const trafficCollector = new TrafficCapture(this.device.udid, this.log, resultPath);
+
+  const timeoutSeconds = parseInt(String(timeLimitSec), 10);
+  if (isNaN(timeoutSeconds) || timeoutSeconds > MAX_CAPTURE_TIME_SEC || timeoutSeconds <= 0) {
+    throw new errors.InvalidArgumentError(
+      `The timeLimitSec value must be in range [1, ${MAX_CAPTURE_TIME_SEC}] seconds. ` +
+        `The value of '${timeLimitSec}' has been passed instead.`,
+    );
+  }
 
-    const timeoutSeconds = parseInt(String(timeLimitSec), 10);
-    if (isNaN(timeoutSeconds) || timeoutSeconds > MAX_CAPTURE_TIME_SEC || timeoutSeconds <= 0) {
-      throw new errors.InvalidArgumentError(
-        `The timeLimitSec value must be in range [1, ${MAX_CAPTURE_TIME_SEC}] seconds. ` +
-          `The value of '${timeLimitSec}' has been passed instead.`,
-      );
-    }
+  try {
+    await trafficCollector.start(timeoutSeconds);
+  } catch (e) {
+    await trafficCollector.interrupt(true);
+    await trafficCollector.cleanup();
+    throw e;
+  }
+  this._trafficCapture = trafficCollector;
+}
 
-    try {
-      await trafficCollector.start(timeoutSeconds);
-    } catch (e) {
-      await trafficCollector.interrupt(true);
-      await trafficCollector.cleanup();
-      throw e;
-    }
-    this._trafficCapture = trafficCollector;
-  },
-
-  /**
-   * Stops network traffic capture.
-   *
-   * If no traffic capture process is running, then the endpoint will try to get the recently recorded file.
-   *
-   * If no previously recorded file is found and no active traffic capture processes are running, then the method returns an empty string.
-   *
-   * @remarks Network capture files can be viewed in [Wireshark](https://www.wireshark.org/) and other similar applications.
-   * @returns {Promise<string>} Base64-encoded content of the recorded pcap file or an empty string if no traffic capture has been started before.
-   * @throws {Error} If there was an error while getting the capture file.
-   * @this {XCUITestDriver}
-   */
-  async mobileStopPcap() {
-    if (!this._trafficCapture) {
-      this.log.info('Network traffic collector has not been started. There is nothing to stop');
-      return '';
-    }
+/**
+ * Stops network traffic capture.
+ *
+ * If no traffic capture process is running, then the endpoint will try to get the recently recorded file.
+ *
+ * If no previously recorded file is found and no active traffic capture processes are running, then the method returns an empty string.
+ *
+ * @remarks Network capture files can be viewed in [Wireshark](https://www.wireshark.org/) and other similar applications.
+ * @returns {Promise<string>} Base64-encoded content of the recorded pcap file or an empty string if no traffic capture has been started before.
+ * @throws {Error} If there was an error while getting the capture file.
+ * @this {XCUITestDriver}
+ */
+export async function mobileStopPcap() {
+  if (!this._trafficCapture) {
+    this.log.info('Network traffic collector has not been started. There is nothing to stop');
+    return '';
+  }
 
-    let resultPath;
-    try {
-      resultPath = await this._trafficCapture.finish();
-      if (!(await fs.exists(resultPath))) {
-        throw this.log.errorWithException(
-          `The network traffic capture utility has failed ` +
-            `to store the actual traffic capture at '${resultPath}'`,
-        );
-      }
-    } catch (e) {
-      await this._trafficCapture.interrupt(true);
-      await this._trafficCapture.cleanup();
-      this._trafficCapture = null;
-      throw e;
+  let resultPath;
+  try {
+    resultPath = await this._trafficCapture.finish();
+    if (!(await fs.exists(resultPath))) {
+      throw this.log.errorWithException(
+        `The network traffic capture utility has failed ` +
+          `to store the actual traffic capture at '${resultPath}'`,
+      );
     }
-    return await encodeBase64OrUpload(resultPath);
-  },
-};
+  } catch (e) {
+    await this._trafficCapture.interrupt(true);
+    await this._trafficCapture.cleanup();
+    this._trafficCapture = null;
+    throw e;
+  }
+  return await encodeBase64OrUpload(resultPath);
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver