@limrun/appium-xcuitest-driver 10.4.3-lim.1

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

@@ -0,0 +1,204 @@
+import _ from 'lodash';
+import {fs, util} from 'appium/support';
+import {encodeBase64OrUpload} from '../utils';
+import path from 'node:path';
+
+const MOV_EXT = '.mov';
+const FEATURE_NAME = 'xctest_screen_record';
+const DOMAIN_IDENTIFIER = 'com.apple.testmanagerd';
+const DOMAIN_TYPE = 'appDataContainer';
+const USERNAME = 'mobile';
+const SUBDIRECTORY = 'Attachments';
+
+/**
+ * @typedef {Object} XcTestScreenRecordingInfo
+ * @property {string} uuid Unique identifier of the video being recorded
+ * @property {number} fps FPS value
+ * @property {number} codec Video codec, where 0 is h264
+ * @property {number} startedAt The timestamp when the screen recording has started in float Unix seconds
+ */
+
+/**
+ * @typedef {Object} XcTestScreenRecordingType
+ * @property {string} payload Base64-encoded content of the recorded media
+ * file if `remotePath` parameter is empty or null or an empty string otherwise.
+ * The media is expected to a be a valid QuickTime movie (.mov).
+ * @typedef {XcTestScreenRecordingInfo & XcTestScreenRecordingType} XcTestScreenRecording
+ */
+
+/**
+ * @this {XCUITestDriver}
+ * @param {string} uuid Unique identifier of the video being recorded
+ * @returns {Promise<string>} The full path to the screen recording movie
+ */
+async function retrieveRecodingFromSimulator(uuid) {
+  const device = /** @type {import('../driver').Simulator} */ (this.device);
+  const dataRoot = /** @type {string} */ (device.getDir());
+  // On Simulators the path looks like
+  // $HOME/Library/Developer/CoreSimulator/Devices/F8E1968A-8443-4A9A-AB86-27C54C36A2F6/data/Containers/Data/InternalDaemon/4E3FE8DF-AD0A-41DA-B6EC-C35E5798C219/Attachments/A044DAF7-4A58-4CD5-95C3-29B4FE80C377
+  const internalDaemonRoot = path.resolve(dataRoot, 'Containers', 'Data', 'InternalDaemon');
+  const videoPaths = await fs.glob(`*/Attachments/${uuid}`, {
+    cwd: internalDaemonRoot,
+    absolute: true,
+  });
+  if (_.isEmpty(videoPaths)) {
+    throw new Error(
+      `Unable to locate XCTest screen recording identified by '${uuid}' for the Simulator ${device.udid}`
+    );
+  }
+  const videoPath = videoPaths[0];
+  const {size} = await fs.stat(videoPath);
+  this.log.debug(`Located the video at '${videoPath}' (${util.toReadableSizeString(size)})`);
+  return videoPath;
+}
+
+/**
+ * @this {XCUITestDriver}
+ * @param {string} uuid Unique identifier of the video being recorded
+ * @returns {Promise<string>} The full path to the screen recording movie
+ */
+async function retrieveRecodingFromRealDevice(uuid) {
+  const device = /** @type {import('../real-device').RealDevice} */ (this.device);
+
+  const fileNames = await device.devicectl.listFiles(DOMAIN_TYPE, DOMAIN_IDENTIFIER, {
+    username: USERNAME,
+    subdirectory: SUBDIRECTORY,
+  });
+  if (!fileNames.includes(uuid)) {
+    throw new Error(
+      `Unable to locate XCTest screen recording identified by '${uuid}' for the device ${this.opts.udid}`
+    );
+  }
+  const videoPath = path.join(/** @type {string} */ (this.opts.tmpDir), `${uuid}${MOV_EXT}`);
+  await device.devicectl.pullFile(`${SUBDIRECTORY}/${uuid}`, videoPath, {
+    username: USERNAME,
+    domainIdentifier: DOMAIN_IDENTIFIER,
+    domainType: DOMAIN_TYPE,
+  });
+  const {size} = await fs.stat(videoPath);
+  this.log.debug(`Pulled the video to '${videoPath}' (${util.toReadableSizeString(size)})`);
+  return videoPath;
+}
+
+/**
+ * @this {XCUITestDriver}
+ * @param {string} uuid Unique identifier of the video being recorded
+ * @returns {Promise<string>} The full path to the screen recording movie
+ */
+async function retrieveXcTestScreenRecording(uuid) {
+  return this.isRealDevice()
+    ? await retrieveRecodingFromRealDevice.bind(this)(uuid)
+    : await retrieveRecodingFromSimulator.bind(this)(uuid);
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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}
+ */
+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;
+}
+
+/**
+ * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
+ */

package/lib/commands/xctest.js

@@ -0,0 +1,285 @@
+import B from 'bluebird';
+import {logger} from 'appium/support';
+import _ from 'lodash';
+import {errors} from 'appium/driver';
+
+const XCTEST_TIMEOUT = 360000; // 60 minute timeout
+
+const xctestLog = logger.getLogger('XCTest');
+
+/**
+ * Asserts that IDB is present and that launchWithIDB was used
+ *
+ * @param {XCUITestDriver['opts']} opts Opts object from the driver instance
+ */
+export function assertIDB(opts) {
+  if (!this.device?.idb || !opts.launchWithIDB) {
+    throw new Error(
+      `To use XCTest runner, IDB (https://github.com/facebook/idb) must be installed ` +
+        `and sessions must be run with the "launchWithIDB" capability`,
+    );
+  }
+  return this.device.idb;
+}
+
+/**
+ * Parse the stdout of XC test log
+ * @param {string} stdout A line of standard out from `idb xctest run ...`
+ * @returns {XCTestResult[]|string[]} results The final output of the XCTest run
+ */
+export function parseXCTestStdout(stdout) {
+  // Parses a 'key' into JSON format
+  function parseKey(name) {
+    const words = name.split(' ');
+    let out = '';
+    for (const word of words) {
+      out += word.substr(0, 1).toUpperCase() + word.substr(1);
+    }
+    return out.substr(0, 1).toLowerCase() + out.substr(1);
+  }
+
+  // Parses a 'value' into JSON format
+  function parseValue(value) {
+    value = value || '';
+    switch (value.toLowerCase()) {
+      case 'true':
+        return true;
+      case 'false':
+        return false;
+      case '':
+        return null;
+      default:
+        break;
+    }
+    if (!isNaN(value)) {
+      if (!_.isString(value)) {
+        return 0;
+      } else if (value.indexOf('.') > 0) {
+        return parseFloat(value);
+      }
+      return parseInt(value, 10);
+    }
+    return value;
+  }
+  if (!stdout) {
+    return [];
+  }
+
+  // Parse each line into an array
+  const lines = stdout.trim().split('\n');
+
+  // One single string, just return the string
+  if (lines.length === 1 && !lines[0].includes('|')) {
+    return [lines[0]];
+  }
+
+  /** @type {XCTestResult[]} */
+  const results = [];
+  for (const line of lines) {
+    // The properties are split up by pipes and each property
+    // has the format "Some Key : Some Value"
+    const properties = line.split('|');
+
+    // Parse each property
+    /** @type {XCTestResult} */
+    const output = /** @type {any} */ ({});
+    let entryIndex = 0;
+    for (const prop of properties) {
+      if (entryIndex === 0) {
+        // The first property only contains one string that contains
+        // the test name (e.g.: 'XCTesterAppUITests - XCTesterAppUITests.XCTesterAppUITests/testExample')
+        output.testName = prop.trim();
+      } else if (prop.trim().startsWith('Location')) {
+        // The Location property has a value that comes after 'Location' without colon.
+        // e.g. Location /path/to/XCTesterAppUITests/XCTesterAppUITests.swift:36
+        output.location = prop.substring(prop.indexOf('Location') + 8).trim();
+      } else {
+        let [key, value] = prop.split(':');
+        output[parseKey(key.trim())] = parseValue(value ? value.trim() : '');
+      }
+      entryIndex++;
+    }
+
+    // keep backward compatibility
+    // old pattern: XCTesterAppUITests - XCTesterAppUITests.XCTesterAppUITests/testExample | Passed: True | Crashed: False | Duration: 1.485 | Failure message:  | Location :0
+    // latest pattern: XCTesterAppUITests - XCTesterAppUITests.XCTesterAppUITests/testExample | Status: passed | Duration: 1.9255789518356323
+    if (!output.passed) {
+      output.passed = output.status === 'passed';
+      output.crashed = output.status === 'crashed';
+    } else if (!output.status) {
+      if (output.passed) {
+        output.status = 'passed';
+      } else if (output.crashed) {
+        output.status = 'crashed';
+      } else {
+        output.status = 'failed';
+      }
+    }
+
+    // Add this line to the results
+    results.push(output);
+  }
+  return results;
+}
+
+/**
+ * @typedef {Error} XCUITestError
+ *
+ * @property {number} code Subprocess exit code
+ * @property {string} signal The signal (SIG*) that caused the process to fail
+ * @property {XCTestResult[]} results The output of the failed test (if there is output)
+ */
+
+/**
+ * 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,
+    {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,
+      );
+    }
+
+    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);
+      }
+    });
+
+    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);
+      }
+      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}
+ */
+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}
+ */
+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}
+ */
+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
+ * @typedef {import('./types').XCTestResult} XCTestResult
+ */