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

package/lib/commands/pcap.js

@@ -0,0 +1,168 @@
+import { Pyidevice } from '../real-device-clients/py-ios-device-client';
+import {fs, tempDir, util} from 'appium/support';
+import {encodeBase64OrUpload} from '../utils';
+import {errors} from 'appium/driver';
+
+const MAX_CAPTURE_TIME_SEC = 60 * 60 * 12;
+const DEFAULT_EXT = '.pcap';
+
+export class TrafficCapture {
+  /** @type {import('teen_process').SubProcess|null} */
+  mainProcess;
+  constructor(udid, log, resultPath) {
+    this.udid = udid;
+    this.log = log;
+    this.resultPath = resultPath;
+    this.mainProcess = null;
+  }
+
+  async start(timeoutSeconds) {
+    this.mainProcess = /** @type {import('teen_process').SubProcess} */ (
+      await new Pyidevice({
+        udid: this.udid,
+        log: this.log,
+      }).collectPcap(this.resultPath)
+    );
+    this.mainProcess.on('line-stderr', (line) => this.log.info(`[Pcap] ${line}`));
+    this.log.info(
+      `Starting network traffic capture session on the device '${this.udid}'. ` +
+        `Will timeout in ${timeoutSeconds}s`,
+    );
+    setTimeout(async () => await this.interrupt(), timeoutSeconds * 1000);
+    this.mainProcess.once('exit', (code, signal) => {
+      this.log.debug(
+        `The traffic capture session on the device '${this.udid}' has exited ` +
+          `with code ${code}, signal ${signal}`,
+      );
+    });
+  }
+
+  isCapturing() {
+    return !!this.mainProcess?.isRunning;
+  }
+
+  async interrupt(force = false) {
+    if (this.isCapturing()) {
+      const interruptPromise = this.mainProcess?.stop(force ? 'SIGTERM' : 'SIGINT');
+      this.mainProcess = null;
+      try {
+        await interruptPromise;
+      } catch (e) {
+        this.log.warn(
+          `Cannot ${force ? 'terminate' : 'interrupt'} the traffic capture session. ` +
+            `Original error: ${e.message}`,
+        );
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  async finish() {
+    await this.interrupt();
+    return this.resultPath;
+  }
+
+  async cleanup() {
+    if (await fs.exists(this.resultPath)) {
+      await fs.rimraf(this.resultPath);
+    }
+  }
+}
+
+/**
+ * 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;
+  }
+
+  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.`,
+    );
+  }
+
+  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}
+ */
+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;
+  }
+  return await encodeBase64OrUpload(resultPath);
+}
+
+/**
+ * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
+ */

package/lib/commands/performance.js

@@ -0,0 +1,392 @@
+import _ from 'lodash';
+import path from 'path';
+import {fs, zip, logger, util, tempDir} from 'appium/support';
+import {SubProcess, exec} from 'teen_process';
+import {encodeBase64OrUpload} from '../utils';
+import { XCRUN, requireXcrun } from '../xcrun';
+import {waitForCondition} from 'asyncbox';
+import B from 'bluebird';
+
+const PERF_RECORD_FEAT_NAME = 'perf_record';
+const PERF_RECORD_SECURITY_MESSAGE =
+  'Performance measurement requires relaxing security for simulator. ' +
+  `Please set '--relaxed-security' or '--allow-insecure' with '${PERF_RECORD_FEAT_NAME}' ` +
+  'referencing https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/security.md for more details.';
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const STOP_TIMEOUT_MS = 3 * 60 * 1000;
+const STARTUP_TIMEOUT_MS = 60 * 1000;
+const DEFAULT_PROFILE_NAME = 'Activity Monitor';
+const DEFAULT_EXT = '.trace';
+const DEFAULT_PID = 'current';
+const INSTRUMENTS = 'instruments';
+const XCTRACE = 'xctrace';
+
+/**
+ * Starts performance profiling for the device under test.
+ *
+ * Relaxing security is mandatory for simulators. It can always work for real devices.
+ *
+ * Since XCode 12 the method tries to use `xctrace` tool to record performance stats.
+ *
+ * The `instruments` developer utility is used as a fallback for this purpose if `xctrace` is not available.
+ *
+ * It is possible to record multiple profiles at the same time.
+ *
+ * Read [Recording, Pausing, and Stopping Traces](https://developer.apple.com/library/content/documentation/DeveloperTools/Conceptual/InstrumentsUserGuide/Recording,Pausing,andStoppingTraces.html) for more details.
+ *
+ * @param {number} timeout - The maximum count of milliseconds to record the profiling information.
+ * @param {string} profileName - The name of existing performance profile to apply. Can also contain the full path to the chosen template on the server file system. Note: not all profiles are supported on mobile devices.
+ * @param {number|'current'} [pid] -  The ID of the process to measure the performance for. Set it to `current` in order to measure the performance of the process, which belongs to the currently active application.  All processes running on the device are measured if `pid` is unset (the default setting).
+ * @this {XCUITestDriver}
+ */
+export async function mobileStartPerfRecord(
+  timeout = DEFAULT_TIMEOUT_MS,
+  profileName = DEFAULT_PROFILE_NAME,
+  pid,
+) {
+  if (!this.isFeatureEnabled(PERF_RECORD_FEAT_NAME) && !this.isRealDevice()) {
+    throw this.log.errorWithException(PERF_RECORD_SECURITY_MESSAGE);
+  }
+
+  if (!_.isEmpty(this._perfRecorders)) {
+    for (const recorder of this._perfRecorders.filter((x) => x.profileName === profileName)) {
+      if (recorder.isRunning()) {
+        this.log.debug(
+          `Performance recorder for '${profileName}' on device '${this.device.udid}' ` +
+            ` is already running. Doing nothing`,
+        );
+        return;
+      }
+      _.pull(this._perfRecorders, recorder);
+      await recorder.stop(true);
+    }
+  }
+
+  let realPid;
+  if (pid) {
+    if (_.toLower(String(pid)) === DEFAULT_PID) {
+      const appInfo = /** @type {import('./types').ActiveAppInfo} */ (
+        await this.proxyCommand('/wda/activeAppInfo', 'GET')
+      );
+      realPid = appInfo.pid;
+    } else {
+      realPid = pid;
+    }
+  }
+  const recorder = new PerfRecorder(await tempDir.openDir(), this.device.udid, {
+    timeout: parseInt(String(timeout), 10),
+    profileName,
+    pid: parseInt(String(realPid), 10),
+  });
+  await recorder.start();
+  this._perfRecorders = [...(this._perfRecorders || []), recorder];
+}
+
+/**
+ * Stops performance recording operation previously started by {@linkcode XCUITestDriver.mobileStartPerfRecord mobile: startPerfRecord}.
+ *
+ * If the previous call has already been completed due to the timeout, then its result is returned immediately. An error is thrown if the performance recording failed to start.
+ *
+ * The resulting file in `.trace` format can be either returned directly as base64-encoded zip archive or uploaded to a remote location (such files can be pretty large). Afterwards it is possible to unarchive and open such files with Xcode Dev Tools.
+ *
+ * @param {string} [remotePath] - The path to the remote location, where the resulting zipped `.trace` file 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 zipped, encoded as Base64 and passed as the endpoint response value. An exception will be thrown if the generated 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('axios').Method} [method] -  The http multipart upload method name. Only works if `remotePath` is provided. Defaults to `PUT`
+ * @param {string} profileName -  The name of existing performance profile to stop the recording for. Multiple recorders for different profile names could be executed at the same time.
+ * @param {Record<string,any>} [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. Defaults to `file`
+ * @param {Record<string,any>|([string, any])[]} [formFields] - Additional form fields for multipart http(s) uploads
+ *
+ * @returns {Promise<string>} The resulting file in `.trace` format. This file can either be returned directly as base64-encoded `.zip` archive or uploaded to a remote location (note that such files may be large), _depending on the `remotePath` argument value._  Thereafter, the file may be unarchived and opened with Xcode Developer Tools.
+ * @throws {Error} If no performance recording with given profile name/device udid combination
+ * has been started before or the resulting .trace file has not been generated properly.
+ * @this {XCUITestDriver}
+ */
+export async function mobileStopPerfRecord(
+  remotePath,
+  user,
+  pass,
+  method,
+  profileName = DEFAULT_PROFILE_NAME,
+  headers,
+  fileFieldName,
+  formFields,
+) {
+  if (!this.isFeatureEnabled(PERF_RECORD_FEAT_NAME) && !this.isRealDevice()) {
+    throw this.log.errorWithException(PERF_RECORD_SECURITY_MESSAGE);
+  }
+
+  if (_.isEmpty(this._perfRecorders)) {
+    this.log.info('No performance recorders have been started. Doing nothing');
+    return '';
+  }
+
+  const recorders = this._perfRecorders.filter((x) => x.profileName === profileName);
+  if (_.isEmpty(recorders)) {
+    throw this.log.errorWithException(
+      `There are no records for performance profile '${profileName}' ` +
+        `and device ${this.device.udid}. Have you started the profiling before?`,
+    );
+  }
+
+  const recorder = _.first(recorders);
+  const resultPath = await /** @type {PerfRecorder} */ (recorder).stop();
+  if (!(await fs.exists(resultPath))) {
+    throw this.log.errorWithException(
+      `There is no ${DEFAULT_EXT} file found for performance profile '${profileName}' ` +
+        `and device ${this.device.udid}. Make sure the selected profile is supported on this device`,
+    );
+  }
+
+  const result = await encodeBase64OrUpload(resultPath, remotePath, {
+    user,
+    pass,
+    method,
+    headers,
+    fileFieldName,
+    formFields,
+  });
+  _.pull(this._perfRecorders, recorder);
+  await fs.rimraf(resultPath);
+  return result;
+}
+
+
+async function requireXctrace() {
+  const xcrunPath = await requireXcrun();
+  try {
+    await exec(xcrunPath, [XCTRACE, 'help']);
+  } catch (e) {
+    throw new Error(
+      `${XCTRACE} is not available for the active Xcode version. ` +
+        `Please make sure XCode is up to date. Original error: ${e.stderr || e.message}`,
+    );
+  }
+  return xcrunPath;
+}
+
+async function requireInstruments() {
+  try {
+    return await fs.which(INSTRUMENTS);
+  } catch {
+    throw new Error(
+      `${INSTRUMENTS} has not been found in PATH. ` +
+        `Please make sure XCode development tools are installed`,
+    );
+  }
+}
+
+export class PerfRecorder {
+  /** @type {import('teen_process').SubProcess|null} */
+  _process;
+  constructor(reportRoot, udid, opts = {}) {
+    this._process = null;
+    this._zippedReportPath = '';
+    this._timeout = opts.timeout && opts.timeout > 0 ? opts.timeout : DEFAULT_TIMEOUT_MS;
+    this._profileName = opts.profileName || DEFAULT_PROFILE_NAME;
+    this._reportPath = path.resolve(
+      reportRoot,
+      `appium_perf__${this._profileName.replace(/\W/g, '_')}__${Date.now()}${DEFAULT_EXT}`,
+    );
+    this._pid = opts.pid;
+    this._udid = udid;
+    this._logger = logger.getLogger(
+      `${_.truncate(this._profileName, {length: 10})}@${this._udid.substring(0, 8)}`,
+    );
+    this._archivePromise = null;
+  }
+
+  get profileName() {
+    return this._profileName;
+  }
+
+  async getOriginalReportPath() {
+    return (await fs.exists(this._reportPath)) ? this._reportPath : '';
+  }
+
+  async getZippedReportPath() {
+    // This is to prevent possible race conditions, because the archive operation
+    // could be pretty time-intensive
+    if (!this._archivePromise) {
+      this._archivePromise = (async () => {
+        const originalReportPath = await this.getOriginalReportPath();
+        if (!originalReportPath) {
+          return '';
+        }
+        const zippedReportPath = await tempDir.path({
+          prefix: path.parse(originalReportPath).name,
+          suffix: '.zip',
+        });
+        await zip.toArchive(zippedReportPath, {
+          cwd: path.dirname(this._reportPath),
+        });
+        await fs.rimraf(path.dirname(this._reportPath));
+        this._zippedReportPath = zippedReportPath;
+        return this._zippedReportPath;
+      })();
+    }
+    return await this._archivePromise;
+  }
+
+  isRunning() {
+    return !!this._process?.isRunning;
+  }
+
+  async _enforceTermination() {
+    if (this._process && this.isRunning()) {
+      this._logger.debug('Force-stopping the currently running perf recording');
+      try {
+        await this._process.stop('SIGKILL');
+      } catch {}
+    }
+    this._process = null;
+    const performCleanup = async () => {
+      try {
+        await B.all(
+          [this._zippedReportPath, path.dirname(this._reportPath)]
+            .filter(Boolean)
+            .map((x) => fs.rimraf(x)),
+        );
+      } catch (e) {
+        this._logger.warn(e.message);
+      }
+    };
+    if (this._archivePromise) {
+      (async () => {
+        try {
+          await this._archivePromise;
+        } catch {
+        } finally {
+          await performCleanup();
+          this._archivePromise = null;
+        }
+      })();
+    }
+    await performCleanup();
+    return '';
+  }
+
+  async start() {
+    let binaryPath;
+    try {
+      binaryPath = await requireXctrace();
+    } catch (e) {
+      this._logger.debug(e.message);
+      this._logger.warn(`Defaulting to ${INSTRUMENTS} usage`);
+      binaryPath = await requireInstruments();
+    }
+
+    const args = [];
+    const toolName = path.basename(binaryPath) === XCRUN ? XCTRACE : INSTRUMENTS;
+    if (toolName === XCTRACE) {
+      args.push(
+        XCTRACE,
+        'record',
+        '--device',
+        this._udid,
+        '--template',
+        this._profileName,
+        '--output',
+        this._reportPath,
+        '--time-limit',
+        `${this._timeout}ms`,
+      );
+      if (this._pid) {
+        args.push('--attach', `${this._pid}`);
+      } else {
+        args.push('--all-processes');
+      }
+    } else {
+      // https://help.apple.com/instruments/mac/current/#/devb14ffaa5
+      args.push(
+        '-w',
+        this._udid,
+        '-t',
+        this._profileName,
+        '-D',
+        this._reportPath,
+        '-l',
+        `${this._timeout}`,
+      );
+      if (this._pid) {
+        args.push('-p', `${this._pid}`);
+      }
+    }
+    const fullCmd = [binaryPath, ...args];
+    this._process = new SubProcess(fullCmd[0], fullCmd.slice(1));
+    this._archivePromise = null;
+    this._logger.debug(`Starting performance recording: ${util.quote(fullCmd)}`);
+    for (const streamName of ['stdout', 'stderr']) {
+      this._process.on(`line-${streamName}`, (line) => this._logger.debug(`[${toolName}] ${line}`));
+    }
+    this._process.once('exit', async (code, signal) => {
+      this._process = null;
+      if (code === 0) {
+        this._logger.debug('Performance recording exited without errors');
+        try {
+          // cache zipped report
+          await this.getZippedReportPath();
+        } catch (e) {
+          this._logger.warn(e);
+        }
+      } else {
+        await this._enforceTermination();
+        this._logger.warn(`Performance recording exited with error code ${code}, signal ${signal}`);
+      }
+    });
+    await this._process.start(0);
+    try {
+      await waitForCondition(
+        async () => {
+          if (await this.getOriginalReportPath()) {
+            return true;
+          }
+          if (!this._process) {
+            throw new Error(`${toolName} process died unexpectedly`);
+          }
+          return false;
+        },
+        {
+          waitMs: STARTUP_TIMEOUT_MS,
+          intervalMs: 500,
+        },
+      );
+    } catch {
+      await this._enforceTermination();
+      const listProfilesCommand =
+        toolName === XCTRACE ? `${XCRUN} ${XCTRACE} list templates` : `${INSTRUMENTS} -s`;
+      throw this._logger.errorWithException(
+        `There is no ${DEFAULT_EXT} file found for performance profile ` +
+          `'${this._profileName}'. Make sure the profile is supported on this device. ` +
+          `You could use '${listProfilesCommand}' command to see the list of all available profiles. ` +
+          `Check the server log for more details`,
+      );
+    }
+    this._logger.info(`The performance recording has started. Will timeout in ${this._timeout}ms`);
+  }
+
+  async stop(force = false) {
+    if (force) {
+      return await this._enforceTermination();
+    }
+
+    if (!this.isRunning()) {
+      this._logger.debug('Performance recording is not running. Returning the recent result');
+      return await this.getZippedReportPath();
+    }
+
+    try {
+      await this._process?.stop('SIGINT', STOP_TIMEOUT_MS);
+    } catch {
+      throw this._logger.errorWithException(
+        `Performance recording has failed to exit after ${STOP_TIMEOUT_MS}ms`,
+      );
+    }
+    return await this.getZippedReportPath();
+  }
+}
+
+/**
+ * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
+ */

package/lib/commands/permissions.js

@@ -0,0 +1,85 @@
+import _ from 'lodash';
+import {PermissionService} from './enum';
+import {assertSimulator as _assertSimulator} from '../utils';
+
+const assertSimulator = _.partial(_assertSimulator, 'Permission-related operations');
+
+/**
+ * Resets the given permission for the active application under test.
+ * Works for both Simulator and real devices using Xcode SDK 11.4+
+ *
+ * @param {PermissionService|number} service - One of the available service names. This could also be an integer protected resource identifier; see [this list](https://developer.apple.com/documentation/xctest/xcuiprotectedresource?language=objc)
+ * @throws {Error} If permission reset fails on the device.
+ * @this {XCUITestDriver}
+ */
+export async function mobileResetPermission(service) {
+  if (!service) {
+    throw new Error(`The 'service' option is expected to be present`);
+  }
+  let resource;
+  if (_.isString(service)) {
+    resource = PermissionService[_.toLower(service)];
+    if (!resource) {
+      throw new Error(
+        `The 'service' value must be one of ` + `${JSON.stringify(_.keys(PermissionService))}`,
+      );
+    }
+  } else if (_.isInteger(service)) {
+    resource = service;
+  } else {
+    throw new Error(
+      `The 'service' value must be either a string or an integer. ` +
+        `'${service}' is passed instead`,
+    );
+  }
+
+  await this.proxyCommand('/wda/resetAppAuth', 'POST', {resource});
+}
+
+/**
+ * Gets application permission state on a simulated device.
+ *
+ * **This method requires [WIX applesimutils](https://github.com/wix/AppleSimulatorUtils) to be installed on the Appium server host.**
+ *
+ * @param {string} bundleId - Bundle identifier of the target application
+ * @param {import('./enum').PermissionService} service - Service name
+ * @returns {Promise<import('./types').PermissionState>} Either 'yes', 'no', 'unset' or 'limited'
+ * @throws {Error} If permission getting fails or the device is not a Simulator.
+ * @this {XCUITestDriver}
+ * @group Simulator Only
+ */
+export async function mobileGetPermission(bundleId, service) {
+  if (!service) {
+    throw new Error(`The 'service' option is expected to be present`);
+  }
+  assertSimulator(this);
+
+  return /** @type {import('./types').PermissionState} */ (
+    await /** @type {import('../driver').Simulator} */ (this.device).getPermission(
+      bundleId, String(service)
+    )
+  );
+}
+
+/**
+ * Set application permission state on Simulator.
+ *
+ * @param {Record<Partial<import('./types').AccessRule>, import('./types').PermissionState>} access - One or more access rules to set.
+ * @param {string} bundleId - Bundle identifier of the target application
+ * @since Xcode SDK 11.4
+ * @throws {Error} If permission setting fails or the device is not a Simulator.
+ * @group Simulator Only
+ * @this {XCUITestDriver}
+ */
+export async function mobileSetPermissions(access, bundleId) {
+  if (!_.isPlainObject(access)) {
+    throw new Error(`The 'access' option is expected to be a map`);
+  }
+  assertSimulator(this);
+
+  await /** @type {import('../driver').Simulator} */ (this.device).setPermissions(bundleId, access);
+}
+
+/**
+ * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
+ */