appium-xcuitest-driver 10.3.0 → 10.4.1

package/lib/commands/screenshots.js

@@ -3,134 +3,134 @@ import _ from 'lodash';
 import {errors} from 'appium/driver';
 import {util, imageUtil} from 'appium/support';
 
-export default {
-  /**
-   * @this {XCUITestDriver}
-   * @returns {Promise<string>}
-   */
-  async getScreenshot() {
-    if (this.isWebContext()) {
-      const webScreenshotMode = (await this.settings.getSettings()).webScreenshotMode;
-      switch (_.toLower(webScreenshotMode)) {
-        case 'page':
-        case 'viewport':
-          return await (/** @type {import('appium-remote-debugger').RemoteDebugger} */ (this.remote)).captureScreenshot({
-            coordinateSystem: /** @type {'Viewport'|'Page'} */ (_.capitalize(webScreenshotMode)),
-          });
-        case 'native':
-        case undefined:
-        case null:
-          break;
-        default:
-          this.log.warn(
-            `The webScreenshotMode setting value '${webScreenshotMode}' is not known. ` +
-            `Supported values are: page, viewport and native. Falling back to the native mode.`
-          );
-          break;
-      }
-    }
-
-    const getScreenshotFromWDA = async () => {
-      this.log.debug(`Taking screenshot with WDA`);
-      const data = await this.proxyCommand('/screenshot', 'GET');
-      if (!_.isString(data)) {
-        throw new Error(`Unable to take screenshot. WDA returned '${JSON.stringify(data)}'`);
-      }
-      return data;
-    };
-
-    // if we've specified an mjpeg server, use that
-    if (this.mjpegStream) {
-      this.log.info(`mjpeg video stream provided, returning latest frame as screenshot`);
-      const data = await this.mjpegStream.lastChunkPNGBase64();
-      if (data) {
-        return data;
-      }
-      this.log.warn(
-        'Tried to get screenshot from active MJPEG stream, but there ' +
-          'was no data yet. Falling back to regular screenshot methods.',
-      );
+/**
+ * @this {XCUITestDriver}
+ * @returns {Promise<string>}
+ */
+export async function getScreenshot() {
+  if (this.isWebContext()) {
+    const webScreenshotMode = (await this.settings.getSettings()).webScreenshotMode;
+    switch (_.toLower(webScreenshotMode)) {
+      case 'page':
+      case 'viewport':
+        return await (/** @type {import('appium-remote-debugger').RemoteDebugger} */ (this.remote)).captureScreenshot({
+          coordinateSystem: /** @type {'Viewport'|'Page'} */ (_.capitalize(webScreenshotMode)),
+        });
+      case 'native':
+      case undefined:
+      case null:
+        break;
+      default:
+        this.log.warn(
+          `The webScreenshotMode setting value '${webScreenshotMode}' is not known. ` +
+          `Supported values are: page, viewport and native. Falling back to the native mode.`
+        );
+        break;
     }
+  }
 
-    try {
-      return await getScreenshotFromWDA();
-    } catch (err) {
-      this.log.warn(`Error getting screenshot: ${err.message}`);
+  const getScreenshotFromWDA = async () => {
+    this.log.debug(`Taking screenshot with WDA`);
+    const data = await this.proxyCommand('/screenshot', 'GET');
+    if (!_.isString(data)) {
+      throw new Error(`Unable to take screenshot. WDA returned '${JSON.stringify(data)}'`);
     }
+    return data;
+  };
 
-    // simulator attempt
-    if (this.isSimulator()) {
-      this.log.info(`Falling back to 'simctl io screenshot' API`);
-      const payload = await /** @type {import('../driver').Simulator} */ (this.device).simctl.getScreenshot();
-      if (!payload) {
-        throw new errors.UnableToCaptureScreen();
-      }
-      return payload;
+  // if we've specified an mjpeg server, use that
+  if (this.mjpegStream) {
+    this.log.info(`mjpeg video stream provided, returning latest frame as screenshot`);
+    const data = await this.mjpegStream.lastChunkPNGBase64();
+    if (data) {
+      return data;
     }
+    this.log.warn(
+      'Tried to get screenshot from active MJPEG stream, but there ' +
+        'was no data yet. Falling back to regular screenshot methods.',
+    );
+  }
 
-    // Retry for real devices only. Fail fast on Simulator if simctl does not work as expected
-    return /** @type {string} */ (await retryInterval(2, 1000, getScreenshotFromWDA));
-  },
-  /**
-   * @this {XCUITestDriver}
-   */
-  async getElementScreenshot(el) {
-    el = util.unwrapElement(el);
-    if (this.isWebContext()) {
-      const atomsElement = this.getAtomsElement(el);
-      const {width, height} = await this.executeAtom('get_size', [atomsElement]);
-      if (!width || !height) {
-        throw new errors.UnableToCaptureScreen('Cannot take a screenshot of a zero-size element');
-      }
-      const {x, y} = await this.executeAtom('get_top_left_coordinates', [atomsElement]);
-      return await (/** @type {import('appium-remote-debugger').RemoteDebugger} */ (this.remote))
-        .captureScreenshot({rect: {x, y, width, height}});
-    }
+  try {
+    return await getScreenshotFromWDA();
+  } catch (err) {
+    this.log.warn(`Error getting screenshot: ${err.message}`);
+  }
 
-    const data = await this.proxyCommand(`/element/${el}/screenshot`, 'GET');
-    if (!_.isString(data)) {
-      throw new errors.UnableToCaptureScreen(
-        `Unable to take an element screenshot. WDA returned: ${JSON.stringify(data)}`,
-      );
-    }
-    return data;
-  },
-  /**
-   * @this {XCUITestDriver}
-   * @returns {Promise<string>}
-   */
-  async getViewportScreenshot() {
-    if (this.isWebContext()) {
-      return await (/** @type {import('appium-remote-debugger').RemoteDebugger} */ (this.remote))
-        .captureScreenshot();
+  // simulator attempt
+  if (this.isSimulator()) {
+    this.log.info(`Falling back to 'simctl io screenshot' API`);
+    const payload = await /** @type {import('../driver').Simulator} */ (this.device).simctl.getScreenshot();
+    if (!payload) {
+      throw new errors.UnableToCaptureScreen();
     }
+    return payload;
+  }
 
-    const screenshot = await this.getScreenshot();
-    // if we don't have a status bar, there's nothing to crop, so we can avoid
-    // extra calls and return straight away
-    if ((await this.getStatusBarHeight()) === 0) {
-      return screenshot;
-    }
+  // Retry for real devices only. Fail fast on Simulator if simctl does not work as expected
+  return /** @type {string} */ (await retryInterval(2, 1000, getScreenshotFromWDA));
+}
 
-    const sharp = imageUtil.requireSharp();
-    const {width, height} = await sharp(Buffer.from(screenshot, 'base64')).metadata();
+/**
+ * @this {XCUITestDriver}
+ */
+export async function getElementScreenshot(el) {
+  el = util.unwrapElement(el);
+  if (this.isWebContext()) {
+    const atomsElement = this.getAtomsElement(el);
+    const {width, height} = await this.executeAtom('get_size', [atomsElement]);
     if (!width || !height) {
-      throw new errors.UnableToCaptureScreen('The device screenshot is empty');
-    }
-    this.log.debug(`Screenshot dimensions: ${width}x${height}`);
-    const region = await this.getViewportRect();
-    if (region.width + region.left > width) {
-      this.log.info('Viewport region exceeds screenshot width, adjusting region to fit');
-      region.width = width - region.left;
-    }
-    if (region.height + region.top > height) {
-      this.log.info('Viewport region exceeds screenshot height, adjusting region to fit');
-      region.height = height - region.top;
+      throw new errors.UnableToCaptureScreen('Cannot take a screenshot of a zero-size element');
     }
-    this.log.debug(`Calculated viewport rect: ${JSON.stringify(region)}`);
-    return await imageUtil.cropBase64Image(screenshot, region);
-  },
-};
+    const {x, y} = await this.executeAtom('get_top_left_coordinates', [atomsElement]);
+    return await (/** @type {import('appium-remote-debugger').RemoteDebugger} */ (this.remote))
+      .captureScreenshot({rect: {x, y, width, height}});
+  }
+
+  const data = await this.proxyCommand(`/element/${el}/screenshot`, 'GET');
+  if (!_.isString(data)) {
+    throw new errors.UnableToCaptureScreen(
+      `Unable to take an element screenshot. WDA returned: ${JSON.stringify(data)}`,
+    );
+  }
+  return data;
+}
+
+/**
+ * @this {XCUITestDriver}
+ * @returns {Promise<string>}
+ */
+export async function getViewportScreenshot() {
+  if (this.isWebContext()) {
+    return await (/** @type {import('appium-remote-debugger').RemoteDebugger} */ (this.remote))
+      .captureScreenshot();
+  }
+
+  const screenshot = await this.getScreenshot();
+  // if we don't have a status bar, there's nothing to crop, so we can avoid
+  // extra calls and return straight away
+  if ((await this.getStatusBarHeight()) === 0) {
+    return screenshot;
+  }
+
+  const sharp = imageUtil.requireSharp();
+  const {width, height} = await sharp(Buffer.from(screenshot, 'base64')).metadata();
+  if (!width || !height) {
+    throw new errors.UnableToCaptureScreen('The device screenshot is empty');
+  }
+  this.log.debug(`Screenshot dimensions: ${width}x${height}`);
+  const region = await this.getViewportRect();
+  if (region.width + region.left > width) {
+    this.log.info('Viewport region exceeds screenshot width, adjusting region to fit');
+    region.width = width - region.left;
+  }
+  if (region.height + region.top > height) {
+    this.log.info('Viewport region exceeds screenshot height, adjusting region to fit');
+    region.height = height - region.top;
+  }
+  this.log.debug(`Calculated viewport rect: ${JSON.stringify(region)}`);
+  return await imageUtil.cropBase64Image(screenshot, region);
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver

package/lib/commands/simctl.js

@@ -29,39 +29,35 @@ const SUBCOMMANDS_HAS_DEVICE = [
   'uninstall'
 ];
 
-const commands = {
-  /**
-   * Run the given command with arguments as `xcrun simctl` subcommand.
-   * This method works behind the 'simctl' security flag.
-   * @this {XCUITestDriver}
-   * @param {string} command Subcommand to run with `xcrun simctl`
-   * @param {string[]} [args=[]] arguments for the subcommand. The arguments should be after <device> in the help.
-   * @param {number|undefined} timeout - The maximum number of milliseconds
-   * @returns {Promise<SimctlExecResponse>}
-   * @throws {Error} If the simctl subcommand command returns non-zero return code, or the given subcommand was invalid.
-   */
-  async mobileSimctl(command, args = [], timeout = undefined) {
-    if (!this.isSimulator()) {
-      throw new errors.UnsupportedOperationError(`Only simulator is supported.`);
-    };
-
-    if (!this.opts.udid) {
-      throw new errors.InvalidArgumentError(`Unknown device or simulator UDID: '${this.opts.udid}'`);
-    }
+/**
+ * Run the given command with arguments as `xcrun simctl` subcommand.
+ * This method works behind the 'simctl' security flag.
+ * @this {XCUITestDriver}
+ * @param {string} command Subcommand to run with `xcrun simctl`
+ * @param {string[]} [args=[]] arguments for the subcommand. The arguments should be after <device> in the help.
+ * @param {number|undefined} timeout - The maximum number of milliseconds
+ * @returns {Promise<SimctlExecResponse>}
+ * @throws {Error} If the simctl subcommand command returns non-zero return code, or the given subcommand was invalid.
+ */
+export async function mobileSimctl(command, args = [], timeout = undefined) {
+  if (!this.isSimulator()) {
+    throw new errors.UnsupportedOperationError(`Only simulator is supported.`);
+  }
 
-    if (!SUBCOMMANDS_HAS_DEVICE.includes(command)) {
-      throw new errors.InvalidArgumentError(`The given command '${command}' is not supported. ` +
-        `Available subcommands are ${SUBCOMMANDS_HAS_DEVICE.join(',')}`);
-    }
+  if (!this.opts.udid) {
+    throw new errors.InvalidArgumentError(`Unknown device or simulator UDID: '${this.opts.udid}'`);
+  }
 
-    return await /** @type {import('./../driver').Simulator} */ (this.device).simctl.exec(
-      command,
-      {args: [this.opts.udid, ...args], timeout}
-    );
+  if (!SUBCOMMANDS_HAS_DEVICE.includes(command)) {
+    throw new errors.InvalidArgumentError(`The given command '${command}' is not supported. ` +
+      `Available subcommands are ${SUBCOMMANDS_HAS_DEVICE.join(',')}`);
   }
-};
 
-export default {...commands};
+  return await /** @type {import('./../driver').Simulator} */ (this.device).simctl.exec(
+    command,
+    {args: [this.opts.udid, ...args], timeout}
+  );
+}
 
 /**
  * @typedef {Object} SimctlExecResponse

package/lib/commands/source.js

@@ -3,54 +3,51 @@ import js2xml from 'js2xmlparser2';
 
 const APPIUM_AUT_TAG = 'AppiumAUT';
 
-const commands = {
-  /**
-   * @this {XCUITestDriver}
-   */
-  async getPageSource() {
-    if (this.isWebContext()) {
-      const script = 'return document.documentElement.outerHTML';
-      return await this.executeAtom('execute_script', [script, []]);
-    }
+/**
+ * @this {XCUITestDriver}
+ */
+export async function getPageSource() {
+  if (this.isWebContext()) {
+    const script = 'return document.documentElement.outerHTML';
+    return await this.executeAtom('execute_script', [script, []]);
+  }
 
-    const {
-      pageSourceExcludedAttributes: excludedAttributes,
-      useJSONSource
-    } = await this.settings.getSettings();
-    const hasExcludedAttributes = _.isString(excludedAttributes) && !_.isEmpty(excludedAttributes);
-    if (useJSONSource) {
-      const srcTree = await this.mobileGetSource('json', hasExcludedAttributes ? excludedAttributes : undefined);
-      return getSourceXml(getTreeForXML(srcTree));
-    }
+  const {
+    pageSourceExcludedAttributes: excludedAttributes,
+    useJSONSource
+  } = await this.settings.getSettings();
+  const hasExcludedAttributes = _.isString(excludedAttributes) && !_.isEmpty(excludedAttributes);
+  if (useJSONSource) {
+    const srcTree = await this.mobileGetSource('json', hasExcludedAttributes ? excludedAttributes : undefined);
+    return getSourceXml(getTreeForXML(srcTree));
+  }
 
-    return await this.mobileGetSource('xml', hasExcludedAttributes ? excludedAttributes : undefined);
-  },
-};
+  return await this.mobileGetSource('xml', hasExcludedAttributes ? excludedAttributes : undefined);
+}
+
+/**
+ * Retrieve the source tree of the current page in XML or JSON format.
+ *
+ * @param {import('./types').SourceFormat} format - Page tree source representation format.
+ * @param {string} [excludedAttributes] A comma-separated string of attribute names to exclude from the output. Only works if `format` is `xml`.
+ * @privateRemarks Why isn't `excludedAttributes` an array?
+ * @returns {Promise<string>} The source tree of the current page in the given format.
+ * @this {XCUITestDriver}
+ */
+export async function mobileGetSource(format = 'xml', excludedAttributes) {
+  const paramsMap = {
+    format,
+    scope: APPIUM_AUT_TAG,
+  };
+  if (excludedAttributes) {
+    paramsMap.excluded_attributes = excludedAttributes;
+  }
+  const query = Object.entries(paramsMap)
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join('&');
+  return /** @type {string} */ (await this.proxyCommand(`/source?${query}`, 'GET'));
+}
 
-const helpers = {
-  /**
-   * Retrieve the source tree of the current page in XML or JSON format.
-   *
-   * @param {import('./types').SourceFormat} format - Page tree source representation format.
-   * @param {string} [excludedAttributes] A comma-separated string of attribute names to exclude from the output. Only works if `format` is `xml`.
-   * @privateRemarks Why isn't `excludedAttributes` an array?
-   * @returns {Promise<string>} The source tree of the current page in the given format.
-   * @this {XCUITestDriver}
-   */
-  async mobileGetSource(format = 'xml', excludedAttributes) {
-    const paramsMap = {
-      format,
-      scope: APPIUM_AUT_TAG,
-    };
-    if (excludedAttributes) {
-      paramsMap.excluded_attributes = excludedAttributes;
-    }
-    const query = Object.entries(paramsMap)
-      .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-      .join('&');
-    return /** @type {string} */ (await this.proxyCommand(`/source?${query}`, 'GET'));
-  },
-};
 /**
  * Will get JSON of the form:
  *
@@ -129,7 +126,6 @@ function getSourceXml(jsonSource) {
   });
 }
 
-export default {...helpers, ...commands};
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
  */

package/lib/commands/timeouts.js

@@ -1,71 +1,67 @@
-const commands = {
-  /**
-   * @this {XCUITestDriver}
-   */
-  async pageLoadTimeoutW3C(ms) {
-    await this.setPageLoadTimeout(this.parseTimeoutArgument(ms));
-  },
-  /**
-   * @this {XCUITestDriver}
-   */
-  async pageLoadTimeoutMJSONWP(ms) {
-    await this.setPageLoadTimeout(this.parseTimeoutArgument(ms));
-  },
+/**
+ * @this {XCUITestDriver}
+ */
+export async function pageLoadTimeoutW3C(ms) {
+  await this.setPageLoadTimeout(this.parseTimeoutArgument(ms));
+}
 
-  /**
-   * @this {XCUITestDriver}
-   */
-  async scriptTimeoutW3C(ms) {
-    // XXX: this is synchronous
-    await this.setAsyncScriptTimeout(this.parseTimeoutArgument(ms));
-  },
+/**
+ * @this {XCUITestDriver}
+ */
+export async function pageLoadTimeoutMJSONWP(ms) {
+  await this.setPageLoadTimeout(this.parseTimeoutArgument(ms));
+}
 
-  /**
-   * Alias for {@linkcode XCUITestDriver.scriptTimeoutW3C}.
-   *
-   * @param {number} ms - the timeout
-   * @this {XCUITestDriver}
-   * @deprecated Use {@linkcode XCUITestDriver.scriptTimeoutW3C} instead
-   */
-  async scriptTimeoutMJSONWP(ms) {
-    await this.asyncScriptTimeout(ms);
-  },
+/**
+ * @this {XCUITestDriver}
+ */
+export async function scriptTimeoutW3C(ms) {
+  // XXX: this is synchronous
+  await this.setAsyncScriptTimeout(this.parseTimeoutArgument(ms));
+}
 
-  /**
-   * Alias for {@linkcode XCUITestDriver.scriptTimeoutW3C}.
-   *
-   * @param {number} ms - the timeout
-   *
-   * @deprecated Use {@linkcode XCUITestDriver.scriptTimeoutW3C} instead
-   * @this {XCUITestDriver}
-   */
-  async asyncScriptTimeout(ms) {
-    await this.scriptTimeoutW3C(ms);
-  },
-};
+/**
+ * Alias for {@linkcode XCUITestDriver.scriptTimeoutW3C}.
+ *
+ * @param {number} ms - the timeout
+ * @this {XCUITestDriver}
+ * @deprecated Use {@linkcode XCUITestDriver.scriptTimeoutW3C} instead
+ */
+export async function scriptTimeoutMJSONWP(ms) {
+  await this.asyncScriptTimeout(ms);
+}
 
-const helpers = {
-  /**
-   * @this {XCUITestDriver}
-   */
-  setPageLoadTimeout(ms) {
-    ms = parseInt(ms, 10);
-    this.pageLoadMs = ms;
-    if (this.remote) {
-      this.remote.pageLoadMs = ms;
-    }
-    this.log.debug(`Set page load timeout to ${ms}ms`);
-  },
-  /**
-   * @this {XCUITestDriver}
-   */
-  setAsyncScriptTimeout(ms) {
-    this.asyncWaitMs = ms;
-    this.log.debug(`Set async script timeout to ${ms}ms`);
-  },
-};
+/**
+ * Alias for {@linkcode XCUITestDriver.scriptTimeoutW3C}.
+ *
+ * @param {number} ms - the timeout
+ *
+ * @deprecated Use {@linkcode XCUITestDriver.scriptTimeoutW3C} instead
+ * @this {XCUITestDriver}
+ */
+export async function asyncScriptTimeout(ms) {
+  await this.scriptTimeoutW3C(ms);
+}
 
-export default {...helpers, ...commands};
+/**
+ * @this {XCUITestDriver}
+ */
+export function setPageLoadTimeout(ms) {
+  ms = parseInt(ms, 10);
+  this.pageLoadMs = ms;
+  if (this.remote) {
+    this.remote.pageLoadMs = ms;
+  }
+  this.log.debug(`Set page load timeout to ${ms}ms`);
+}
+
+/**
+ * @this {XCUITestDriver}
+ */
+export function setAsyncScriptTimeout(ms) {
+  this.asyncWaitMs = ms;
+  this.log.debug(`Set async script timeout to ${ms}ms`);
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver