appium-xcuitest-driver 10.2.2 → 10.4.0

package/lib/commands/xctest-record-screen.js

@@ -91,115 +91,113 @@ async function retrieveXcTestScreenRecording(uuid) {
     : await retrieveRecodingFromSimulator.bind(this)(uuid);
 }
 
-export default {
-  /**
-   * Start a new screen recording via XCTest.
-   *
-   * Even though the feature is available for real devices
-   * there is no possibility to delete stored video files yet,
-   * which may lead to internal storage overload.
-   * That is why it was put under a security feature flag.
-   *
-   * If the recording is already running this API is a noop.
-   *
-   * @since Xcode 15/iOS 17
-   * @param {number} [fps] FPS value
-   * @param {number} [codec] Video codec, where 0 is h264, 1 is HEVC
-   * @returns {Promise<XcTestScreenRecordingInfo>} The information
-   * about a newly created or a running the screen recording.
-   * @throws {Error} If screen recording has failed to start.
-   * @this {XCUITestDriver}
-   */
-  async mobileStartXctestScreenRecording(fps, codec) {
-    if (this.isRealDevice()) {
-      // This feature might be used to abuse real devices as there is no
-      // reliable way (yet) to cleanup video recordings stored there
-      // by the testmanagerd daemon
-      this.assertFeatureEnabled(FEATURE_NAME);
-    }
+/**
+ * Start a new screen recording via XCTest.
+ *
+ * Even though the feature is available for real devices
+ * there is no possibility to delete stored video files yet,
+ * which may lead to internal storage overload.
+ * That is why it was put under a security feature flag.
+ *
+ * If the recording is already running this API is a noop.
+ *
+ * @since Xcode 15/iOS 17
+ * @param {number} [fps] FPS value
+ * @param {number} [codec] Video codec, where 0 is h264, 1 is HEVC
+ * @returns {Promise<XcTestScreenRecordingInfo>} The information
+ * about a newly created or a running the screen recording.
+ * @throws {Error} If screen recording has failed to start.
+ * @this {XCUITestDriver}
+ */
+export async function mobileStartXctestScreenRecording(fps, codec) {
+  if (this.isRealDevice()) {
+    // This feature might be used to abuse real devices as there is no
+    // reliable way (yet) to cleanup video recordings stored there
+    // by the testmanagerd daemon
+    this.assertFeatureEnabled(FEATURE_NAME);
+  }
 
-    const opts = {};
-    if (_.isInteger(codec)) {
-      opts.codec = codec;
-    }
-    if (_.isInteger(fps)) {
-      opts.fps = fps;
-    }
-    const response = /** @type {XcTestScreenRecordingInfo} */ (
-      await this.proxyCommand('/wda/video/start', 'POST', opts)
-    );
-    this.log.info(`Started a new screen recording: ${JSON.stringify(response)}`);
-    return response;
-  },
+  const opts = {};
+  if (_.isInteger(codec)) {
+    opts.codec = codec;
+  }
+  if (_.isInteger(fps)) {
+    opts.fps = fps;
+  }
+  const response = /** @type {XcTestScreenRecordingInfo} */ (
+    await this.proxyCommand('/wda/video/start', 'POST', opts)
+  );
+  this.log.info(`Started a new screen recording: ${JSON.stringify(response)}`);
+  return response;
+}
 
-  /**
-   * Retrieves information about the current running screen recording.
-   * If no screen recording is running then `null` is returned.
-   *
-   * @returns {Promise<XcTestScreenRecordingInfo?>}
-   */
-  async mobileGetXctestScreenRecordingInfo() {
-    return /** @type {XcTestScreenRecordingInfo?} */ (
-      await this.proxyCommand('/wda/video', 'GET')
-    );
-  },
+/**
+ * Retrieves information about the current running screen recording.
+ * If no screen recording is running then `null` is returned.
+ *
+ * @returns {Promise<XcTestScreenRecordingInfo?>}
+ */
+export async function mobileGetXctestScreenRecordingInfo() {
+  return /** @type {XcTestScreenRecordingInfo?} */ (
+    await this.proxyCommand('/wda/video', 'GET')
+  );
+}
 
-  /**
-   * Stop screen recording previously started by mobileStartXctestScreenRecording API.
-   *
-   * An error is thrown if no screen recording is running.
-   *
-   * The resulting movie is returned as base-64 string or is uploaded to
-   * a remote location if corresponding options have been provided.
-   *
-   * The resulting movie is automatically deleted FOR SIMULATORS ONLY.
-   * In order to clean it up from a real device it is necessary to properly
-   * shut down XCTest by calling `GET /wda/shutdown` API to the WebDriverAgent server running
-   * on the device directly or by doing factory reset.
-   *
-   * @since Xcode 15/iOS 17
-   * @param {string} [remotePath] The path to the remote location, where the resulting video should be
-   * uploaded.
-   * The following protocols are supported: `http`, `https`, `ftp`. Null or empty
-   * string value (the default setting) means the content of resulting file
-   * should be encoded as Base64 and passed as the endpoint response value. An
-   * exception will be thrown if the generated media file is too big to fit into
-   * the available process memory.
-   * @param {string} [user] The name of the user for the remote authentication.
-   * Only works if `remotePath` is provided.
-   * @param {string} [pass] The password for the remote authentication.
-   * Only works if `remotePath` is provided.
-   * @param {import('@appium/types').HTTPHeaders} [headers] Additional headers mapping for multipart http(s) uploads
-   * @param {string} [fileFieldName] The name of the form field where the file content BLOB should be stored for
-   * http(s) uploads
-   * @param {Record<string, any> | [string, any][]} [formFields] Additional form fields for multipart http(s) uploads
-   * @param {'PUT' | 'POST' | 'PATCH'} [method='PUT'] The http multipart upload method name.
-   * Only works if `remotePath` is provided.
-   * @returns {Promise<XcTestScreenRecording>}
-   * @throws {Error} If there was an error while retrieving the video
-   * file or the file content cannot be uploaded to the remote location.
-   * @this {XCUITestDriver}
-   */
-  async mobileStopXctestScreenRecording(remotePath, user, pass, headers, fileFieldName, formFields, method) {
-    const screenRecordingInfo = await this.mobileGetXctestScreenRecordingInfo();
-    if (!screenRecordingInfo) {
-      throw new Error('There is no active screen recording. Did you start one beforehand?');
-    }
+/**
+ * Stop screen recording previously started by mobileStartXctestScreenRecording API.
+ *
+ * An error is thrown if no screen recording is running.
+ *
+ * The resulting movie is returned as base-64 string or is uploaded to
+ * a remote location if corresponding options have been provided.
+ *
+ * The resulting movie is automatically deleted FOR SIMULATORS ONLY.
+ * In order to clean it up from a real device it is necessary to properly
+ * shut down XCTest by calling `GET /wda/shutdown` API to the WebDriverAgent server running
+ * on the device directly or by doing factory reset.
+ *
+ * @since Xcode 15/iOS 17
+ * @param {string} [remotePath] The path to the remote location, where the resulting video should be
+ * uploaded.
+ * The following protocols are supported: `http`, `https`, `ftp`. Null or empty
+ * string value (the default setting) means the content of resulting file
+ * should be encoded as Base64 and passed as the endpoint response value. An
+ * exception will be thrown if the generated media file is too big to fit into
+ * the available process memory.
+ * @param {string} [user] The name of the user for the remote authentication.
+ * Only works if `remotePath` is provided.
+ * @param {string} [pass] The password for the remote authentication.
+ * Only works if `remotePath` is provided.
+ * @param {import('@appium/types').HTTPHeaders} [headers] Additional headers mapping for multipart http(s) uploads
+ * @param {string} [fileFieldName] The name of the form field where the file content BLOB should be stored for
+ * http(s) uploads
+ * @param {Record<string, any> | [string, any][]} [formFields] Additional form fields for multipart http(s) uploads
+ * @param {'PUT' | 'POST' | 'PATCH'} [method='PUT'] The http multipart upload method name.
+ * Only works if `remotePath` is provided.
+ * @returns {Promise<XcTestScreenRecording>}
+ * @throws {Error} If there was an error while retrieving the video
+ * file or the file content cannot be uploaded to the remote location.
+ * @this {XCUITestDriver}
+ */
+export async function mobileStopXctestScreenRecording(remotePath, user, pass, headers, fileFieldName, formFields, method) {
+  const screenRecordingInfo = await this.mobileGetXctestScreenRecordingInfo();
+  if (!screenRecordingInfo) {
+    throw new Error('There is no active screen recording. Did you start one beforehand?');
+  }
 
-    this.log.debug(`Stopping the active screen recording: ${JSON.stringify(screenRecordingInfo)}`);
-    await this.proxyCommand('/wda/video/stop', 'POST', {});
-    const videoPath = await retrieveXcTestScreenRecording.bind(this)(screenRecordingInfo.uuid);
-    const result = /** @type {XcTestScreenRecording} */ (screenRecordingInfo);
-    try {
-      result.payload = await encodeBase64OrUpload(videoPath, remotePath, {
-        user, pass, headers, fileFieldName, formFields, method
-      });
-    } finally {
-      await fs.rimraf(videoPath);
-    }
-    return result;
-  },
-};
+  this.log.debug(`Stopping the active screen recording: ${JSON.stringify(screenRecordingInfo)}`);
+  await this.proxyCommand('/wda/video/stop', 'POST', {});
+  const videoPath = await retrieveXcTestScreenRecording.bind(this)(screenRecordingInfo.uuid);
+  const result = /** @type {XcTestScreenRecording} */ (screenRecordingInfo);
+  try {
+    result.payload = await encodeBase64OrUpload(videoPath, remotePath, {
+      user, pass, headers, fileFieldName, formFields, method
+    });
+  } finally {
+    await fs.rimraf(videoPath);
+  }
+  return result;
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver

package/lib/commands/xctest.js

@@ -3,9 +3,6 @@ import {logger} from 'appium/support';
 import _ from 'lodash';
 import {errors} from 'appium/driver';
 
-/**
- * @type {360000}
- */
 const XCTEST_TIMEOUT = 360000; // 60 minute timeout
 
 const xctestLog = logger.getLogger('XCTest');
@@ -133,156 +130,154 @@ export function parseXCTestStdout(stdout) {
  * @property {XCTestResult[]} results The output of the failed test (if there is output)
  */
 
-export default {
-  /**
-   * Run a native XCTest script.
-   *
-   * Launches a subprocess that runs the XC Test and blocks until it is completed. Parses the stdout of the process and returns its result as an array.
-   *
-   * **Facebook's [IDB](https://github.com/facebook/idb) tool is required** to run such tests; see [the idb docs](https://fbidb.io/docs/test-execution/) for reference.
-   *
-   * @param {string} testRunnerBundleId - Test app bundle (e.g.: `io.appium.XCTesterAppUITests.xctrunner`)
-   * @param {string} appUnderTestBundleId - App-under-test bundle
-   * @param {string} xcTestBundleId - XCTest bundle ID
-   * @param {string[]} args - Launch arguments to start the test with (see [reference documentation](https://developer.apple.com/documentation/xctest/xcuiapplication/1500477-launcharguments))
-   * @param {'app'|'ui'|'logic'} testType - XC test type
-   * @param {import('@appium/types').StringRecord} [env] - Environment variables passed to test
-   * @param {number} timeout - Timeout (in ms) for session completion.
-   * @throws {XCUITestError} Error thrown if subprocess returns non-zero exit code
-   * @returns {Promise<import('./types').RunXCTestResult>} The array of test results
-   * @this {XCUITestDriver}
-   */
-  async mobileRunXCTest(
+/**
+ * Run a native XCTest script.
+ *
+ * Launches a subprocess that runs the XC Test and blocks until it is completed. Parses the stdout of the process and returns its result as an array.
+ *
+ * **Facebook's [IDB](https://github.com/facebook/idb) tool is required** to run such tests; see [the idb docs](https://fbidb.io/docs/test-execution/) for reference.
+ *
+ * @param {string} testRunnerBundleId - Test app bundle (e.g.: `io.appium.XCTesterAppUITests.xctrunner`)
+ * @param {string} appUnderTestBundleId - App-under-test bundle
+ * @param {string} xcTestBundleId - XCTest bundle ID
+ * @param {string[]} args - Launch arguments to start the test with (see [reference documentation](https://developer.apple.com/documentation/xctest/xcuiapplication/1500477-launcharguments))
+ * @param {'app'|'ui'|'logic'} testType - XC test type
+ * @param {import('@appium/types').StringRecord} [env] - Environment variables passed to test
+ * @param {number} timeout - Timeout (in ms) for session completion.
+ * @throws {XCUITestError} Error thrown if subprocess returns non-zero exit code
+ * @returns {Promise<import('./types').RunXCTestResult>} The array of test results
+ * @this {XCUITestDriver}
+ */
+export async function mobileRunXCTest(
+  testRunnerBundleId,
+  appUnderTestBundleId,
+  xcTestBundleId,
+  args = [],
+  testType = 'ui',
+  env,
+  timeout = XCTEST_TIMEOUT,
+) {
+  const subproc = await assertIDB(this.opts).runXCUITest(
     testRunnerBundleId,
     appUnderTestBundleId,
     xcTestBundleId,
-    args = [],
-    testType = 'ui',
-    env,
-    timeout = XCTEST_TIMEOUT,
-  ) {
-    const subproc = await assertIDB(this.opts).runXCUITest(
-      testRunnerBundleId,
-      appUnderTestBundleId,
-      xcTestBundleId,
-      {env, args, testType},
-    );
-    return await new B((resolve, reject) => {
-      let mostRecentLogObject = null;
-      let xctestTimeout;
-      let lastErrorMessage = null;
-      if (timeout > 0) {
-        xctestTimeout = setTimeout(
-          () =>
-            reject(
-              new errors.TimeoutError(
-                `Timed out after '${timeout}ms' waiting for XCTest to complete`,
-              ),
+    {env, args, testType},
+  );
+  return await new B((resolve, reject) => {
+    let mostRecentLogObject = null;
+    let xctestTimeout;
+    let lastErrorMessage = null;
+    if (timeout > 0) {
+      xctestTimeout = setTimeout(
+        () =>
+          reject(
+            new errors.TimeoutError(
+              `Timed out after '${timeout}ms' waiting for XCTest to complete`,
             ),
-          timeout,
-        );
-      }
+          ),
+        timeout,
+      );
+    }
 
-      subproc.on('output', (stdout, stderr) => {
-        if (stdout) {
-          try {
-            mostRecentLogObject = parseXCTestStdout(stdout);
-          } catch (err) {
-            // Fails if log parsing fails.
-            // This is in case IDB changes the way that logs are formatted and
-            // it breaks 'parseXCTestStdout'. If that happens we still want the process
-            // to finish
-            this.log.warn(`Failed to parse logs from test output: '${stdout}'`);
-            this.log.debug(err.stack);
-          }
+    subproc.on('output', (stdout, stderr) => {
+      if (stdout) {
+        try {
+          mostRecentLogObject = parseXCTestStdout(stdout);
+        } catch (err) {
+          // Fails if log parsing fails.
+          // This is in case IDB changes the way that logs are formatted and
+          // it breaks 'parseXCTestStdout'. If that happens we still want the process
+          // to finish
+          this.log.warn(`Failed to parse logs from test output: '${stdout}'`);
+          this.log.debug(err.stack);
         }
+      }
 
-        if (stderr) {
-          lastErrorMessage = stderr;
-          xctestLog.error(stderr);
-        }
-        if (stdout) {
-          xctestLog.info(stdout);
-        }
-      });
+      if (stderr) {
+        lastErrorMessage = stderr;
+        xctestLog.error(stderr);
+      }
+      if (stdout) {
+        xctestLog.info(stdout);
+      }
+    });
 
-      subproc.on('exit', (code, signal) => {
-        clearTimeout(xctestTimeout);
-        if (code !== 0) {
-          const err = /** @type {any} */ (new Error(lastErrorMessage || mostRecentLogObject));
-          err.code = code;
-          if (signal != null) {
-            err.signal = signal;
-          }
-          if (mostRecentLogObject) {
-            err.result = mostRecentLogObject;
-          }
-          return reject(err);
+    subproc.on('exit', (code, signal) => {
+      clearTimeout(xctestTimeout);
+      if (code !== 0) {
+        const err = /** @type {any} */ (new Error(lastErrorMessage || mostRecentLogObject));
+        err.code = code;
+        if (signal != null) {
+          err.signal = signal;
+        }
+        if (mostRecentLogObject) {
+          err.result = mostRecentLogObject;
         }
-        resolve({
-          code,
-          signal,
-          results: mostRecentLogObject,
-          passed: true,
-        });
+        return reject(err);
+      }
+      resolve({
+        code,
+        signal,
+        results: mostRecentLogObject,
+        passed: true,
       });
     });
-  },
+  });
+}
 
-  /**
-   * Installs an XCTest bundle to the device under test.
-   *
-   * **Facebook's [IDB](https://github.com/facebook/idb) tool is required** for this command to work.
-   *
-   * @param {string} xctestApp - Path of the XCTest app (URL or filename with extension `.app`)
-   * @returns {Promise<void>}
-   * @this {XCUITestDriver}
-   */
-  async mobileInstallXCTestBundle(xctestApp) {
-    if (!_.isString(xctestApp)) {
-      throw new errors.InvalidArgumentError(
-        `'xctestApp' is a required parameter for 'installXCTestBundle' and ` +
-          `must be a string. Found '${xctestApp}'`,
-      );
-    }
-    xctestLog.info(`Installing bundle '${xctestApp}'`);
-    const idb = assertIDB(this.opts);
-    const res = await this.helpers.configureApp(xctestApp, '.xctest');
-    await idb.installXCTestBundle(res);
-  },
+/**
+ * Installs an XCTest bundle to the device under test.
+ *
+ * **Facebook's [IDB](https://github.com/facebook/idb) tool is required** for this command to work.
+ *
+ * @param {string} xctestApp - Path of the XCTest app (URL or filename with extension `.app`)
+ * @returns {Promise<void>}
+ * @this {XCUITestDriver}
+ */
+export async function mobileInstallXCTestBundle(xctestApp) {
+  if (!_.isString(xctestApp)) {
+    throw new errors.InvalidArgumentError(
+      `'xctestApp' is a required parameter for 'installXCTestBundle' and ` +
+        `must be a string. Found '${xctestApp}'`,
+    );
+  }
+  xctestLog.info(`Installing bundle '${xctestApp}'`);
+  const idb = assertIDB(this.opts);
+  const res = await this.helpers.configureApp(xctestApp, '.xctest');
+  await idb.installXCTestBundle(res);
+}
 
-  /**
-   * List XCTest bundles that are installed on the device.
-   *
-   * **Facebook's [IDB](https://github.com/facebook/idb) tool is required** for this command to work.
-   *
-   * @returns {Promise<string[]>} List of XCTest bundles (e.g.: `XCTesterAppUITests.XCTesterAppUITests/testLaunchPerformance`)
-   * @this {XCUITestDriver}
-   */
-  async mobileListXCTestBundles() {
-    return await assertIDB(this.opts).listXCTestBundles();
-  },
+/**
+ * List XCTest bundles that are installed on the device.
+ *
+ * **Facebook's [IDB](https://github.com/facebook/idb) tool is required** for this command to work.
+ *
+ * @returns {Promise<string[]>} List of XCTest bundles (e.g.: `XCTesterAppUITests.XCTesterAppUITests/testLaunchPerformance`)
+ * @this {XCUITestDriver}
+ */
+export async function mobileListXCTestBundles() {
+  return await assertIDB(this.opts).listXCTestBundles();
+}
 
-  /**
-   * List XCTests in a test bundle
-   *
-   * **Facebook's [IDB](https://github.com/facebook/idb) tool is required** for this command to work.
-   * @param {string} bundle - Bundle ID of the XCTest
-   *
-   * @returns {Promise<string[]>} The list of xctests in the test bundle (e.g., `['XCTesterAppUITests.XCTesterAppUITests/testExample', 'XCTesterAppUITests.XCTesterAppUITests/testLaunchPerformance']`)
-   * @this {XCUITestDriver}
-   */
-  async mobileListXCTestsInTestBundle(bundle) {
-    if (!_.isString(bundle)) {
-      throw new errors.InvalidArgumentError(
-        `'bundle' is a required parameter for 'listXCTestsInTestBundle' and ` +
-          `must be a string. Found '${bundle}'`,
-      );
-    }
-    const idb = assertIDB(this.opts);
-    return await idb.listXCTestsInTestBundle(bundle);
-  },
-};
+/**
+ * List XCTests in a test bundle
+ *
+ * **Facebook's [IDB](https://github.com/facebook/idb) tool is required** for this command to work.
+ * @param {string} bundle - Bundle ID of the XCTest
+ *
+ * @returns {Promise<string[]>} The list of xctests in the test bundle (e.g., `['XCTesterAppUITests.XCTesterAppUITests/testExample', 'XCTesterAppUITests.XCTesterAppUITests/testLaunchPerformance']`)
+ * @this {XCUITestDriver}
+ */
+export async function mobileListXCTestsInTestBundle(bundle) {
+  if (!_.isString(bundle)) {
+    throw new errors.InvalidArgumentError(
+      `'bundle' is a required parameter for 'listXCTestsInTestBundle' and ` +
+        `must be a string. Found '${bundle}'`,
+    );
+  }
+  const idb = assertIDB(this.opts);
+  return await idb.listXCTestsInTestBundle(bundle);
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver