appium-xcuitest-driver 10.3.0 → 10.4.0

package/lib/commands/lock.js

@@ -1,45 +1,45 @@
 import B from 'bluebird';
 
-export default {
-  /**
-   * Lock the device (and optionally unlock the device after a certain amount of time)
-   *
-   * @param {number|string} [seconds] - the number of seconds after which to unlock the device. Set to `0` or leave empty to require manual unlock (do not automatically unlock).
-   * @defaultValue 0
-   * @this {XCUITestDriver}
-   */
-  async lock(seconds) {
-    await this.proxyCommand('/wda/lock', 'POST');
-    if (isNaN(Number(seconds))) {
-      return;
-    }
+/**
+ * Lock the device (and optionally unlock the device after a certain amount of time)
+ *
+ * @param {number|string} [seconds] - the number of seconds after which to unlock the device. Set to `0` or leave empty to require manual unlock (do not automatically unlock).
+ * @defaultValue 0
+ * @this {XCUITestDriver}
+ */
+export async function lock(seconds) {
+  await this.proxyCommand('/wda/lock', 'POST');
+  if (isNaN(Number(seconds))) {
+    return;
+  }
+
+  const floatSeconds = parseFloat(String(seconds));
+  if (floatSeconds <= 0) {
+    return;
+  }
+
+  await B.delay(floatSeconds * 1000);
+  await this.proxyCommand('/wda/unlock', 'POST');
+}
 
-    const floatSeconds = parseFloat(String(seconds));
-    if (floatSeconds <= 0) {
-      return;
-    }
+/**
+ * Unlock the device
+ *
+ * @this {XCUITestDriver}
+ */
+export async function unlock() {
+  await this.proxyCommand('/wda/unlock', 'POST');
+}
 
-    await B.delay(floatSeconds * 1000);
-    await this.proxyCommand('/wda/unlock', 'POST');
-  },
-  /**
-   * Unlock the device
-   *
-   * @this {XCUITestDriver}
-   */
-  async unlock() {
-    await this.proxyCommand('/wda/unlock', 'POST');
-  },
-  /**
-   * Determine whether the device is locked
-   *
-   * @this {XCUITestDriver}
-   * @returns {Promise<boolean>} `true` if the device is locked, `false` otherwise
-   */
-  async isLocked() {
-    return /** @type {boolean} */ (await this.proxyCommand('/wda/locked', 'GET'));
-  },
-};
+/**
+ * Determine whether the device is locked
+ *
+ * @this {XCUITestDriver}
+ * @returns {Promise<boolean>} `true` if the device is locked, `false` otherwise
+ */
+export async function isLocked() {
+  return /** @type {boolean} */ (await this.proxyCommand('/wda/locked', 'GET'));
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver

package/lib/commands/log.js

@@ -22,19 +22,6 @@ const WEBSOCKET_ENDPOINT = (sessionId) =>
 const COLOR_CODE_PATTERN = /\u001b\[(\d+(;\d+)*)?m/g; // eslint-disable-line no-control-regex
 const GET_SERVER_LOGS_FEATURE = 'get_server_logs';
 
-/**
- *
- * @param {Object} x
- * @returns {import('./types').LogEntry}
- */
-function nativeLogEntryToSeleniumEntry (x) {
-  const msg = _.isEmpty(x.prefix) ? x.message : `[${x.prefix}] ${x.message}`;
-  return toLogEntry(
-    _.replace(msg, COLOR_CODE_PATTERN, ''),
-    /** @type {any} */ (x).timestamp ?? Date.now()
-  );
-}
-
 /**
  * @type {import('@appium/types').LogDefRecord}
  * @privateRemarks The return types for these getters should be specified
@@ -78,216 +65,215 @@ const LOG_NAMES_TO_CAPABILITY_NAMES_MAP = {
   enablePerformanceLogging: 'enablePerformanceLogging',
 };
 
-export default {
-  supportedLogTypes: SUPPORTED_LOG_TYPES,
-  /**
-   *
-   * @param {XCUITestDriverLogTypes} logType
-   * @param {Partial<Record<XCUITestDriverLogTypes,{getLogs(): Promise<any>}>>} [logsContainer]
-   * @this {XCUITestDriver}
-   */
-  async extractLogs(logType, logsContainer = {}) {
-    // make sure that we have logs at all
-    // otherwise it's not been initialized
-    if (_.isEmpty(logsContainer)) {
-      throw new Error('No logs currently available. Is the device/simulator started?');
-    }
+export const supportedLogTypes = SUPPORTED_LOG_TYPES;
 
-    // If logs captured successfully send response with data, else send error
-    const logObject = logsContainer[logType];
-    if (logObject) {
-      return await logObject.getLogs();
-    }
-    if (logType in LOG_NAMES_TO_CAPABILITY_NAMES_MAP) {
-      throw new Error(
-        `${logType} logs are not enabled. Make sure you've set a proper value ` +
-        `to the 'appium:${LOG_NAMES_TO_CAPABILITY_NAMES_MAP[logType]}' capability.`
-      );
-    }
+/**
+ *
+ * @param {XCUITestDriverLogTypes} logType
+ * @param {Partial<Record<XCUITestDriverLogTypes,{getLogs(): Promise<any>}>>} [logsContainer]
+ * @this {XCUITestDriver}
+ */
+export async function extractLogs(logType, logsContainer = {}) {
+  // make sure that we have logs at all
+  // otherwise it's not been initialized
+  if (_.isEmpty(logsContainer)) {
+    throw new Error('No logs currently available. Is the device/simulator started?');
+  }
+
+  // If logs captured successfully send response with data, else send error
+  const logObject = logsContainer[logType];
+  if (logObject) {
+    return await logObject.getLogs();
+  }
+  if (logType in LOG_NAMES_TO_CAPABILITY_NAMES_MAP) {
     throw new Error(
-      `No logs of type '${logType}' found. Supported log types are: ${_.keys(SUPPORTED_LOG_TYPES)}.`
+      `${logType} logs are not enabled. Make sure you've set a proper value ` +
+      `to the 'appium:${LOG_NAMES_TO_CAPABILITY_NAMES_MAP[logType]}' capability.`
     );
-  },
+  }
+  throw new Error(
+    `No logs of type '${logType}' found. Supported log types are: ${_.keys(SUPPORTED_LOG_TYPES)}.`
+  );
+}
 
-  /**
-   * @this {XCUITestDriver}
-   */
-  async startLogCapture() {
-    this.logs = this.logs || {};
-    if (!_.isUndefined(this.logs.syslog) && this.logs.syslog.isCapturing) {
-      this.log.warn('Trying to start iOS log capture but it has already started!');
-      return true;
-    }
+/**
+ * @this {XCUITestDriver}
+ */
+export async function startLogCapture() {
+  this.logs = this.logs || {};
+  if (!_.isUndefined(this.logs.syslog) && this.logs.syslog.isCapturing) {
+    this.log.warn('Trying to start iOS log capture but it has already started!');
+    return true;
+  }
 
-    if (_.isUndefined(this.logs.syslog)) {
-      [this.logs.crashlog,] = assignBiDiLogListener.bind(this)(
-        new IOSCrashLog({
+  if (_.isUndefined(this.logs.syslog)) {
+    [this.logs.crashlog,] = assignBiDiLogListener.bind(this)(
+      new IOSCrashLog({
+        sim: /** @type {import('appium-ios-simulator').Simulator} */ (this.device),
+        udid: this.isRealDevice() ? this.opts.udid : undefined,
+        log: this.log,
+      }), {
+        type: 'crashlog',
+      }
+    );
+    [this.logs.syslog,] = assignBiDiLogListener.bind(this)(
+      this.isRealDevice()
+        ? new IOSDeviceLog({
+          udid: this.opts.udid,
+          showLogs: this.opts.showIOSLog,
+          log: this.log,
+        })
+        : new IOSSimulatorLog({
           sim: /** @type {import('appium-ios-simulator').Simulator} */ (this.device),
-          udid: this.isRealDevice() ? this.opts.udid : undefined,
+          showLogs: this.opts.showIOSLog,
+          iosSimulatorLogsPredicate: this.opts.iosSimulatorLogsPredicate,
+          simulatorLogLevel: this.opts.simulatorLogLevel,
+          log: this.log,
+          iosSyslogFile: this.opts.iosSyslogFile
+        }),
+      {
+        type: 'syslog',
+      }
+    );
+    if (_.isBoolean(this.opts.showSafariConsoleLog)) {
+      [this.logs.safariConsole,] = assignBiDiLogListener.bind(this)(
+        new SafariConsoleLog({
+          showLogs: this.opts.showSafariConsoleLog,
           log: this.log,
         }), {
-          type: 'crashlog',
+          type: 'safariConsole',
         }
       );
-      [this.logs.syslog,] = assignBiDiLogListener.bind(this)(
-        this.isRealDevice()
-          ? new IOSDeviceLog({
-            udid: this.opts.udid,
-            showLogs: this.opts.showIOSLog,
-            log: this.log,
-          })
-          : new IOSSimulatorLog({
-            sim: /** @type {import('appium-ios-simulator').Simulator} */ (this.device),
-            showLogs: this.opts.showIOSLog,
-            iosSimulatorLogsPredicate: this.opts.iosSimulatorLogsPredicate,
-            simulatorLogLevel: this.opts.simulatorLogLevel,
-            log: this.log,
-            iosSyslogFile: this.opts.iosSyslogFile
-          }),
-        {
-          type: 'syslog',
+    }
+    if (_.isBoolean(this.opts.showSafariNetworkLog)) {
+      [this.logs.safariNetwork,] = assignBiDiLogListener.bind(this)(
+        new SafariNetworkLog({
+          showLogs: this.opts.showSafariNetworkLog,
+          log: this.log,
+        }), {
+          type: 'safariNetwork',
         }
       );
-      if (_.isBoolean(this.opts.showSafariConsoleLog)) {
-        [this.logs.safariConsole,] = assignBiDiLogListener.bind(this)(
-          new SafariConsoleLog({
-            showLogs: this.opts.showSafariConsoleLog,
-            log: this.log,
-          }), {
-            type: 'safariConsole',
-          }
-        );
-      }
-      if (_.isBoolean(this.opts.showSafariNetworkLog)) {
-        [this.logs.safariNetwork,] = assignBiDiLogListener.bind(this)(
-          new SafariNetworkLog({
-            showLogs: this.opts.showSafariNetworkLog,
-            log: this.log,
-          }), {
-            type: 'safariNetwork',
-          }
-        );
-      }
-      if (this.isFeatureEnabled(GET_SERVER_LOGS_FEATURE)) {
-        [, this._bidiServerLogListener] = assignBiDiLogListener.bind(this)(
-          this.log.unwrap(), {
-            type: 'server',
-            srcEventName: 'log',
-            entryTransformer: nativeLogEntryToSeleniumEntry,
-          }
-        );
-      }
     }
-
-    let didStartSyslog = false;
-    /** @type {Promise[]} */
-    const promises = [
-      (async () => {
-        try {
-          await this.logs.syslog?.startCapture();
-          didStartSyslog = true;
-          this.eventEmitter.emit('syslogStarted', this.logs.syslog);
-        } catch (err) {
-          this.log.debug(err.stack);
-          this.log.warn(`Continuing without capturing device logs: ${err.message}`);
+    if (this.isFeatureEnabled(GET_SERVER_LOGS_FEATURE)) {
+      [, this._bidiServerLogListener] = assignBiDiLogListener.bind(this)(
+        this.log.unwrap(), {
+          type: 'server',
+          srcEventName: 'log',
+          entryTransformer: nativeLogEntryToSeleniumEntry,
         }
-      })(),
-      this.logs.crashlog?.startCapture() ?? B.resolve(),
-    ];
-    await B.all(promises);
-
-    return didStartSyslog;
-  },
-
-  /**
-   * Starts an iOS system logs broadcast websocket.
-   *
-   * The websocket listens on the same host and port as Appium.  The endpoint created is `/ws/session/:sessionId:/appium/syslog`.
-   *
-   * If the websocket is already running, this command does nothing.
-   *
-   * Each connected webcoket listener will receive syslog lines as soon as they are visible to Appium.
-   * @see https://appiumpro.com/editions/55-using-mobile-execution-commands-to-continuously-stream-device-logs-with-appium
-   * @returns {Promise<void>}
-   * @this {XCUITestDriver}
-   */
-  async mobileStartLogsBroadcast() {
-    const pathname = WEBSOCKET_ENDPOINT(/** @type {string} */ (this.sessionId));
-    if (
-      !_.isEmpty(
-        await /** @type {import('@appium/types').AppiumServer} */ (
-          this.server
-        ).getWebSocketHandlers(pathname),
-      )
-    ) {
-      this.log.debug(
-        `The system logs broadcasting web socket server is already listening at ${pathname}`,
       );
-      return;
     }
+  }
 
-    this.log.info(`Assigning system logs broadcasting web socket server to ${pathname}`);
-    // https://github.com/websockets/ws/blob/master/doc/ws.md
-    const wss = new WebSocket.Server({
-      noServer: true,
-    });
-    wss.on('connection', (ws, req) => {
-      if (req) {
-        const remoteIp = _.isEmpty(req.headers['x-forwarded-for'])
-          ? req.connection?.remoteAddress
-          : req.headers['x-forwarded-for'];
-        this.log.debug(`Established a new system logs listener web socket connection from ${remoteIp}`);
-      } else {
-        this.log.debug('Established a new system logs listener web socket connection');
+  let didStartSyslog = false;
+  /** @type {Promise[]} */
+  const promises = [
+    (async () => {
+      try {
+        await this.logs.syslog?.startCapture();
+        didStartSyslog = true;
+        this.eventEmitter.emit('syslogStarted', this.logs.syslog);
+      } catch (err) {
+        this.log.debug(err.stack);
+        this.log.warn(`Continuing without capturing device logs: ${err.message}`);
       }
+    })(),
+    this.logs.crashlog?.startCapture() ?? B.resolve(),
+  ];
+  await B.all(promises);
 
-      if (_.isEmpty(this._syslogWebsocketListener)) {
-        this._syslogWebsocketListener = (logRecord) => {
-          if (ws?.readyState === WebSocket.OPEN) {
-            ws.send(logRecord.message);
-          }
-        };
-      }
-      this.logs.syslog?.on('output', this._syslogWebsocketListener);
+  return didStartSyslog;
+}
 
-      ws.on('close', (code, reason) => {
-        if (!_.isEmpty(this._syslogWebsocketListener)) {
-          this.logs.syslog?.removeListener('output', this._syslogWebsocketListener);
-          this._syslogWebsocketListener = null;
-        }
+/**
+ * Starts an iOS system logs broadcast websocket.
+ *
+ * The websocket listens on the same host and port as Appium.  The endpoint created is `/ws/session/:sessionId:/appium/syslog`.
+ *
+ * If the websocket is already running, this command does nothing.
+ *
+ * Each connected webcoket listener will receive syslog lines as soon as they are visible to Appium.
+ * @see https://appiumpro.com/editions/55-using-mobile-execution-commands-to-continuously-stream-device-logs-with-appium
+ * @returns {Promise<void>}
+ * @this {XCUITestDriver}
+ */
+export async function mobileStartLogsBroadcast() {
+  const pathname = WEBSOCKET_ENDPOINT(/** @type {string} */ (this.sessionId));
+  if (
+    !_.isEmpty(
+      await /** @type {import('@appium/types').AppiumServer} */ (
+        this.server
+      ).getWebSocketHandlers(pathname),
+    )
+  ) {
+    this.log.debug(
+      `The system logs broadcasting web socket server is already listening at ${pathname}`,
+    );
+    return;
+  }
 
-        let closeMsg = 'System logs listener web socket is closed.';
-        if (!_.isEmpty(code)) {
-          closeMsg += ` Code: ${code}.`;
-        }
-        if (!_.isEmpty(reason)) {
-          closeMsg += ` Reason: ${reason.toString()}.`;
+  this.log.info(`Assigning system logs broadcasting web socket server to ${pathname}`);
+  // https://github.com/websockets/ws/blob/master/doc/ws.md
+  const wss = new WebSocket.Server({
+    noServer: true,
+  });
+  wss.on('connection', (ws, req) => {
+    if (req) {
+      const remoteIp = _.isEmpty(req.headers['x-forwarded-for'])
+        ? req.connection?.remoteAddress
+        : req.headers['x-forwarded-for'];
+      this.log.debug(`Established a new system logs listener web socket connection from ${remoteIp}`);
+    } else {
+      this.log.debug('Established a new system logs listener web socket connection');
+    }
+
+    if (_.isEmpty(this._syslogWebsocketListener)) {
+      this._syslogWebsocketListener = (logRecord) => {
+        if (ws?.readyState === WebSocket.OPEN) {
+          ws.send(logRecord.message);
         }
-        this.log.debug(closeMsg);
-      });
+      };
+    }
+    this.logs.syslog?.on('output', this._syslogWebsocketListener);
+
+    ws.on('close', (code, reason) => {
+      if (!_.isEmpty(this._syslogWebsocketListener)) {
+        this.logs.syslog?.removeListener('output', this._syslogWebsocketListener);
+        this._syslogWebsocketListener = null;
+      }
+
+      let closeMsg = 'System logs listener web socket is closed.';
+      if (!_.isEmpty(code)) {
+        closeMsg += ` Code: ${code}.`;
+      }
+      if (!_.isEmpty(reason)) {
+        closeMsg += ` Reason: ${reason.toString()}.`;
+      }
+      this.log.debug(closeMsg);
     });
-    await /** @type {AppiumServer} */ (this.server).addWebSocketHandler(
-      pathname,
-      /** @type {import('@appium/types').WSServer} */ (wss),
-    );
-  },
+  });
+  await /** @type {AppiumServer} */ (this.server).addWebSocketHandler(
+    pathname,
+    /** @type {import('@appium/types').WSServer} */ (wss),
+  );
+}
 
-  /**
-   * Stops the syslog broadcasting wesocket server previously started by `mobile: startLogsBroadcast`.
-   * If no websocket server is running, this command does nothing.
-   * @this {XCUITestDriver}
-   * @returns {Promise<void>}
-   */
-  async mobileStopLogsBroadcast() {
-    const pathname = WEBSOCKET_ENDPOINT(/** @type {string} */ (this.sessionId));
-    if (_.isEmpty(await /** @type {AppiumServer} */ (this.server).getWebSocketHandlers(pathname))) {
-      return;
-    }
+/**
+ * Stops the syslog broadcasting wesocket server previously started by `mobile: startLogsBroadcast`.
+ * If no websocket server is running, this command does nothing.
+ * @this {XCUITestDriver}
+ * @returns {Promise<void>}
+ */
+export async function mobileStopLogsBroadcast() {
+  const pathname = WEBSOCKET_ENDPOINT(/** @type {string} */ (this.sessionId));
+  if (_.isEmpty(await /** @type {AppiumServer} */ (this.server).getWebSocketHandlers(pathname))) {
+    return;
+  }
 
-    this.log.debug('Stopping the system logs broadcasting web socket server');
-    await /** @type {AppiumServer} */ (this.server).removeWebSocketHandler(pathname);
-  },
-};
+  this.log.debug('Stopping the system logs broadcasting web socket server');
+  await /** @type {AppiumServer} */ (this.server).removeWebSocketHandler(pathname);
+}
 
 /**
  * https://w3c.github.io/webdriver-bidi/#event-log-entryAdded
@@ -313,6 +299,19 @@ export function assignBiDiLogListener (logEmitter, properties) {
   return [logEmitter, listener];
 }
 
+/**
+ *
+ * @param {Object} x
+ * @returns {import('./types').LogEntry}
+ */
+function nativeLogEntryToSeleniumEntry (x) {
+  const msg = _.isEmpty(x.prefix) ? x.message : `[${x.prefix}] ${x.message}`;
+  return toLogEntry(
+    _.replace(msg, COLOR_CODE_PATTERN, ''),
+    /** @type {any} */ (x).timestamp ?? Date.now()
+  );
+}
+
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
  * @typedef {keyof typeof SUPPORTED_LOG_TYPES} XCUITestDriverLogTypes

package/lib/commands/memory.js

@@ -1,52 +1,50 @@
 import _ from 'lodash';
 import { errors } from 'appium/driver';
 
-export default {
-  /**
-   * Simulates Low Memory warning on the given application
-   *
-   * @since Xcode 15
-   * @param {string} bundleId - The bundle identifier of the target app. The app must be running
-   * @this {XCUITestDriver}
-   * @throws {Error} if the app is not running or is not installed
-   */
-  async mobileSendMemoryWarning(bundleId) {
-    if (!this.isRealDevice()) {
-      throw new Error('Memory warning simulation is only supported on real devices');
-    }
+/**
+ * Simulates Low Memory warning on the given application
+ *
+ * @since Xcode 15
+ * @param {string} bundleId - The bundle identifier of the target app. The app must be running
+ * @this {XCUITestDriver}
+ * @throws {Error} if the app is not running or is not installed
+ */
+export async function mobileSendMemoryWarning(bundleId) {
+  if (!this.isRealDevice()) {
+    throw new Error('Memory warning simulation is only supported on real devices');
+  }
 
-    const device = /** @type {import('../real-device').RealDevice} */ (this.device);
+  const device = /** @type {import('../real-device').RealDevice} */ (this.device);
 
-    const appInfos = await device.devicectl.listApps(bundleId);
-    if (_.isEmpty(appInfos)) {
-      throw new errors.InvalidArgumentError(
-        `The application identified by ${bundleId} cannot be found on the device. Is it installed?`
-      );
-    }
+  const appInfos = await device.devicectl.listApps(bundleId);
+  if (_.isEmpty(appInfos)) {
+    throw new errors.InvalidArgumentError(
+      `The application identified by ${bundleId} cannot be found on the device. Is it installed?`
+    );
+  }
 
-    // This regexp tries to match the process name of the main bundle executable.
-    // For example, if 'url' contains something like
-    // `file:///private/var/containers/Bundle/Application/093ACA6D-8F0B-4601-87B9-4099E43A1A20/Target.app/`
-    // and the following processes might be running:
-    // `file:///private/var/containers/Bundle/Application/093ACA6D-8F0B-4601-87B9-4099E43A1A20/Target.app/Target`
-    // `file:///private/var/containers/Bundle/Application/093ACA6D-8F0B-4601-87B9-4099E43A1A20/Target.app/PlugIns/WidgetExtension.appex/WidgetExtension`
-    // then we only want to match the first one.
-    // Unfortunately devicectl does not provide more info which would
-    // allow to connect a bundle id to a process id.
-    const pattern = new RegExp(`^${_.escapeRegExp(appInfos[0].url)}[^/]+$`);
-    /** @type {number[]} */
-    const pids = (await device.devicectl.listProcesses())
-      .filter(({executable}) => pattern.test(executable))
-      .map(({processIdentifier}) => processIdentifier);
-    if (_.isEmpty(pids)) {
-      throw new errors.InvalidArgumentError(
-        `The application identified by ${bundleId} must be running in order to simulate the Low Memory warning`
-      );
-    }
-    this.log.info(`Emulating Low Memory warning for the process id ${pids[0]}, bundle id ${bundleId}`);
-    await device.devicectl.sendMemoryWarning(pids[0]);
+  // This regexp tries to match the process name of the main bundle executable.
+  // For example, if 'url' contains something like
+  // `file:///private/var/containers/Bundle/Application/093ACA6D-8F0B-4601-87B9-4099E43A1A20/Target.app/`
+  // and the following processes might be running:
+  // `file:///private/var/containers/Bundle/Application/093ACA6D-8F0B-4601-87B9-4099E43A1A20/Target.app/Target`
+  // `file:///private/var/containers/Bundle/Application/093ACA6D-8F0B-4601-87B9-4099E43A1A20/Target.app/PlugIns/WidgetExtension.appex/WidgetExtension`
+  // then we only want to match the first one.
+  // Unfortunately devicectl does not provide more info which would
+  // allow to connect a bundle id to a process id.
+  const pattern = new RegExp(`^${_.escapeRegExp(appInfos[0].url)}[^/]+$`);
+  /** @type {number[]} */
+  const pids = (await device.devicectl.listProcesses())
+    .filter(({executable}) => pattern.test(executable))
+    .map(({processIdentifier}) => processIdentifier);
+  if (_.isEmpty(pids)) {
+    throw new errors.InvalidArgumentError(
+      `The application identified by ${bundleId} must be running in order to simulate the Low Memory warning`
+    );
   }
-};
+  this.log.info(`Emulating Low Memory warning for the process id ${pids[0]}, bundle id ${bundleId}`);
+  await device.devicectl.sendMemoryWarning(pids[0]);
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver