appium-xcuitest-driver 10.2.2 → 10.4.0

package/lib/commands/performance.js

@@ -21,6 +21,138 @@ 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 {
@@ -255,139 +387,6 @@ export class PerfRecorder {
   }
 }
 
-export default {
-  /**
-   * 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}
-   */
-  async 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}
-   */
-  async 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;
-  },
-};
-
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
  */

package/lib/commands/permissions.js

@@ -4,83 +4,81 @@ import {assertSimulator as _assertSimulator} from '../utils';
 
 const assertSimulator = _.partial(_assertSimulator, 'Permission-related operations');
 
-export default {
-  /**
-   * 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}
-   */
-  async 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 {
+/**
+ * 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 either a string or an integer. ` +
-          `'${service}' is passed instead`,
+        `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});
-  },
+  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
-   */
-  async mobileGetPermission(bundleId, service) {
-    if (!service) {
-      throw new Error(`The 'service' option is expected to be present`);
-    }
-    assertSimulator(this);
+/**
+ * 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)
-      )
-    );
-  },
+  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}
-   */
-  async mobileSetPermissions(access, bundleId) {
-    if (!_.isPlainObject(access)) {
-      throw new Error(`The 'access' option is expected to be a map`);
-    }
-    assertSimulator(this);
+/**
+ * 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);
-  },
-};
+  await /** @type {import('../driver').Simulator} */ (this.device).setPermissions(bundleId, access);
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver

package/lib/commands/proxy-helper.js

@@ -46,76 +46,75 @@ const WDA_ROUTES = /** @type {const} */ ({
 });
 
 /**
- * @param {string} endpoint
+ * Proxies a command to WebDriverAgent
+ * @template [TReq=any]
+ * @template [TRes=unknown]
+ * @param {string} url
  * @param {AllowedHttpMethod} method
- * @returns {string|undefined}
+ * @param {TReq} [body]
+ * @param {boolean} isSessionCommand
+ * @this {import('../driver').XCUITestDriver}
+ * @returns {Promise<TRes>}
  */
-function wdaRouteToCommandName(endpoint, method) {
-  if (endpoint in WDA_ROUTES) {
-    return WDA_ROUTES[endpoint][method];
+export async function proxyCommand(url, method, body, isSessionCommand = true) {
+  if (this.shutdownUnexpectedly) {
+    return /** @type {TRes} */ (undefined);
   }
-}
-export default {
-  /**
-   * Proxies a command to WebDriverAgent
-   * @template [TReq=any]
-   * @template [TRes=unknown]
-   * @param {string} url
-   * @param {AllowedHttpMethod} method
-   * @param {TReq} [body]
-   * @param {boolean} isSessionCommand
-   * @this {import('../driver').XCUITestDriver}
-   * @returns {Promise<TRes>}
-   */
-  async proxyCommand(url, method, body, isSessionCommand = true) {
-    if (this.shutdownUnexpectedly) {
-      return /** @type {TRes} */ (undefined);
-    }
 
-    if (!url) {
-      throw this.log.errorWithException('Proxying requires an endpoint');
-    } else if (!SUPPORTED_METHODS.has(method)) {
-      throw this.log.errorWithException(
-        `Proxying only works for the following HTTP methods: ${[...SUPPORTED_METHODS].join(', ')}`,
-      );
-    }
+  if (!url) {
+    throw this.log.errorWithException('Proxying requires an endpoint');
+  } else if (!SUPPORTED_METHODS.has(method)) {
+    throw this.log.errorWithException(
+      `Proxying only works for the following HTTP methods: ${[...SUPPORTED_METHODS].join(', ')}`,
+    );
+  }
 
-    if (!this.wda) {
-      throw new Error('Cannot call proxyCommand without WDA driver active');
-    }
-    const proxy = isSessionCommand ? this.wda.jwproxy : this.wda.noSessionProxy;
-    if (!proxy) {
-      throw new Error('Cannot call proxyCommand without WDA proxy active');
-    }
+  if (!this.wda) {
+    throw new Error('Cannot call proxyCommand without WDA driver active');
+  }
+  const proxy = isSessionCommand ? this.wda.jwproxy : this.wda.noSessionProxy;
+  if (!proxy) {
+    throw new Error('Cannot call proxyCommand without WDA proxy active');
+  }
 
-    let cmdName = wdaRouteToCommandName(url, method) || routeToCommandName(url, method);
-    const timeout = this._getCommandTimeout(cmdName);
-    if (!cmdName) {
-      // this should never happen except when adding new routes
-      cmdName = 'Unknown'; // just for logging purposes below
-      this.log.info(`Proxying to WDA with an unknown route: ${method} ${url}`);
-    }
+  let cmdName = wdaRouteToCommandName(url, method) || routeToCommandName(url, method);
+  const timeout = this._getCommandTimeout(cmdName);
+  if (!cmdName) {
+    // this should never happen except when adding new routes
+    cmdName = 'Unknown'; // just for logging purposes below
+    this.log.info(`Proxying to WDA with an unknown route: ${method} ${url}`);
+  }
 
-    if (!timeout) {
-      return /** @type {TRes} */ (await proxy.command(url, method, body));
-    }
+  if (!timeout) {
+    return /** @type {TRes} */ (await proxy.command(url, method, body));
+  }
 
-    this.log.debug(`Setting custom timeout to ${timeout} ms for '${cmdName}' command`);
-    try {
-      return /** @type {TRes} */ (await B.resolve(proxy.command(url, method, body)).timeout(timeout));
-    } catch (e) {
-      if (!(e instanceof B.Promise.TimeoutError)) {
-        throw e;
-      }
-      proxy.cancelActiveRequests();
-      const error = new errors.TimeoutError(
-        `Appium did not get any response from '${cmdName}' command in ${timeout} ms`
-      );
-      await this.startUnexpectedShutdown(error);
-      throw error;
+  this.log.debug(`Setting custom timeout to ${timeout} ms for '${cmdName}' command`);
+  try {
+    return /** @type {TRes} */ (await B.resolve(proxy.command(url, method, body)).timeout(timeout));
+  } catch (e) {
+    if (!(e instanceof B.Promise.TimeoutError)) {
+      throw e;
     }
-  },
-};
+    proxy.cancelActiveRequests();
+    const error = new errors.TimeoutError(
+      `Appium did not get any response from '${cmdName}' command in ${timeout} ms`
+    );
+    await this.startUnexpectedShutdown(error);
+    throw error;
+  }
+}
+
+/**
+ * @param {string} endpoint
+ * @param {AllowedHttpMethod} method
+ * @returns {string|undefined}
+ */
+function wdaRouteToCommandName(endpoint, method) {
+  if (endpoint in WDA_ROUTES) {
+    return WDA_ROUTES[endpoint][method];
+  }
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver