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

package/lib/commands/log.js

@@ -0,0 +1,327 @@
+import _ from 'lodash';
+import B from 'bluebird';
+import {DEFAULT_WS_PATHNAME_PREFIX} from 'appium/driver';
+import {IOSCrashLog} from '../device-log/ios-crash-log';
+import {IOSSimulatorLog} from '../device-log/ios-simulator-log';
+import {IOSDeviceLog} from '../device-log/ios-device-log';
+import WebSocket from 'ws';
+import { SafariConsoleLog } from '../device-log/safari-console-log';
+import { SafariNetworkLog } from '../device-log/safari-network-log';
+import { toLogEntry } from '../device-log/helpers';
+import { NATIVE_WIN } from '../utils';
+import { BIDI_EVENT_NAME } from './bidi/constants';
+import { makeLogEntryAddedEvent } from './bidi/models';
+
+/**
+ * Determines the websocket endpoint based on the `sessionId`
+ * @param {string} sessionId
+ * @returns {string}
+ */
+const WEBSOCKET_ENDPOINT = (sessionId) =>
+  `${DEFAULT_WS_PATHNAME_PREFIX}/session/${sessionId}/appium/device/syslog`;
+const COLOR_CODE_PATTERN = /\u001b\[(\d+(;\d+)*)?m/g; // eslint-disable-line no-control-regex
+const GET_SERVER_LOGS_FEATURE = 'get_server_logs';
+
+/**
+ * @type {import('@appium/types').LogDefRecord}
+ * @privateRemarks The return types for these getters should be specified
+ */
+const SUPPORTED_LOG_TYPES = {
+  syslog: {
+    description: 'System Logs - Device logs for iOS applications on real devices and simulators',
+    getter: async (self) => await self.extractLogs('syslog', self.logs),
+  },
+  crashlog: {
+    description: 'Crash Logs - Crash reports for iOS applications on real devices and simulators',
+    getter: async (self) => await self.extractLogs('crashlog', self.logs),
+  },
+  performance: {
+    description: 'Performance Logs - Debug Timelines on real devices and simulators',
+    getter: async (self) => await self.extractLogs('performance', self.logs),
+  },
+  safariConsole: {
+    description: 'Safari Console Logs - data written to the JS console in Safari',
+    getter: async (self) => await self.extractLogs('safariConsole', self.logs),
+  },
+  safariNetwork: {
+    description: 'Safari Network Logs - information about network operations undertaken by Safari',
+    getter: async (self) => await self.extractLogs('safariNetwork', self.logs),
+  },
+  server: {
+    description: 'Appium server logs',
+    /**
+     * @returns {import('./types').LogEntry[]}
+     */
+    getter: (self) => {
+      self.assertFeatureEnabled(GET_SERVER_LOGS_FEATURE);
+      return self.log.unwrap().record.map(nativeLogEntryToSeleniumEntry);
+    },
+  },
+};
+
+const LOG_NAMES_TO_CAPABILITY_NAMES_MAP = {
+  safariConsole: 'showSafariConsoleLog',
+  safariNetwork: 'showSafariNetworkLog',
+  enablePerformanceLogging: 'enablePerformanceLogging',
+};
+
+export const supportedLogTypes = SUPPORTED_LOG_TYPES;
+
+/**
+ *
+ * @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(
+      `${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}
+ */
+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({
+        sim: /** @type {import('@limrun/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('@limrun/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.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}`);
+      }
+    })(),
+    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}
+ */
+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;
+  }
+
+  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.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),
+  );
+}
+
+/**
+ * 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);
+}
+
+/**
+ * https://w3c.github.io/webdriver-bidi/#event-log-entryAdded
+ *
+ * @template {import('node:events').EventEmitter} EE
+ * @this {XCUITestDriver}
+ * @param {EE} logEmitter
+ * @param {BiDiListenerProperties} properties
+ * @returns {[EE, import('./types').LogListener]}
+ */
+export function assignBiDiLogListener (logEmitter, properties) {
+  const {
+    type,
+    context = NATIVE_WIN,
+    srcEventName = 'output',
+    entryTransformer,
+  } = properties;
+  const listener = (/** @type {import('./types').LogEntry} */ logEntry) => {
+    const finalEntry = entryTransformer ? entryTransformer(logEntry) : logEntry;
+    this.eventEmitter.emit(BIDI_EVENT_NAME, makeLogEntryAddedEvent(finalEntry, context, type));
+  };
+  logEmitter.on(srcEventName, listener);
+  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
+ * @typedef {import('@appium/types').AppiumServer} AppiumServer
+ */
+
+/**
+ * @typedef {Object} BiDiListenerProperties
+ * @property {string} type
+ * @property {string} [srcEventName='output']
+ * @property {string} [context=NATIVE_WIN]
+ * @property {(x: Object) => import('./types').LogEntry} [entryTransformer]
+ */

package/lib/commands/memory.js

@@ -0,0 +1,51 @@
+import _ from 'lodash';
+import { errors } from 'appium/driver';
+
+/**
+ * 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 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]);
+}
+
+/**
+ * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
+ */

package/lib/commands/navigation.js

@@ -0,0 +1,125 @@
+import {errors} from 'appium/driver';
+import _ from 'lodash';
+import {waitForCondition} from 'asyncbox';
+import { isTvOs } from '../utils';
+
+// these two constitute the wait after closing a window
+const CLOSE_WINDOW_TIMEOUT = 5000;
+const CLOSE_WINDOW_INTERVAL = 100;
+
+/**
+ * @this {XCUITestDriver}
+ */
+export async function back() {
+  if (!this.isWebContext()) {
+    await this.nativeBack();
+  } else {
+    await this.mobileWebNav('back');
+  }
+}
+
+/**
+ * @this {XCUITestDriver}
+ */
+export async function forward() {
+  if (!this.isWebContext()) {
+  }
+  await this.mobileWebNav('forward');
+}
+
+/**
+ * @this {XCUITestDriver}
+ */
+export async function closeWindow() {
+  if (!this.isWebContext()) {
+    throw new errors.NotImplementedError();
+  }
+
+  // since the window will be closed and the execution context gone, return
+  // first before closing. Waiting for close will happen in the finally block
+  const script = `setTimeout(function () {window.open('','_self').close();}, 0); return true;`;
+  const context = this.curContext;
+  try {
+    return await this.executeAtom('execute_script', [script, []], true);
+  } finally {
+    // wait for the window to successfully change...
+    try {
+      await waitForCondition(() => this.curContext !== context, {
+        waitMs: CLOSE_WINDOW_TIMEOUT,
+        intervalMs: CLOSE_WINDOW_INTERVAL,
+      });
+    } catch {
+      this.log.debug('Context has not yet been changed after closing window. Continuing...');
+    }
+  }
+}
+
+/**
+ * Opens the given URL with the default application assigned to handle it based on the URL
+ * scheme, or the application provided as an optional parameter
+ *
+ * (Note: the version of Xcode must be 14.3+ and iOS must be 16.4+)
+ *
+ * @param {string} url - the URL to be opened, e.g. `myscheme://yolo`
+ * @param {string} [bundleId] - the application to open the given URL with. If not provided, then
+ * the application assigned by the operating system to handle URLs of the appropriate type
+ * @returns {Promise<void>}
+ * @since 4.17
+ * @this {XCUITestDriver}
+ */
+export async function mobileDeepLink(url, bundleId) {
+  return await this.proxyCommand('/url', 'POST', {
+    url,
+    bundleId,
+  });
+}
+
+/**
+ * @this {XCUITestDriver}
+ */
+export async function nativeBack() {
+  if (isTvOs(this.opts.platformName)) {
+    this.log.debug(`Sending Menu button as back behavior in tvOS`);
+    return await this.mobilePressButton('Menu');
+  }
+
+  try {
+    let navBar = await this.findNativeElementOrElements(
+      'class name',
+      'XCUIElementTypeNavigationBar',
+      false,
+    );
+    let buttons = await this.findNativeElementOrElements(
+      'class name',
+      'XCUIElementTypeButton',
+      true,
+      navBar,
+    );
+    if (buttons?.length === 0) {
+      throw new Error('No buttons found in navigation bar');
+    }
+
+    let backButton = _.filter(buttons, (value) => value.label === 'Back')[0];
+    if (backButton) {
+      this.log.debug(`Found navigation bar 'back' button. Clicking.`);
+    } else {
+      this.log.debug(`Unable to find 'Back' button. Trying first button in navigation bar`);
+      backButton = buttons?.[0];
+    }
+    await this.nativeClick(/** @type {string} */ (backButton));
+  } catch (err) {
+    this.log.error(`Unable to find navigation bar and back button: ${err.message}`);
+  }
+}
+
+/**
+ * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
+ */
+
+/**
+ * @typedef {Object} DeepLinkOptions
+ * @property {string} url The URL to be opened. This parameter is manadatory
+ * @property {string?} bundleId The bundle identifier of an application to open the
+ * given url with. If not provided then the default application for the given url scheme
+ * is going to be used.
+ */

package/lib/commands/notifications.js

@@ -0,0 +1,66 @@
+import {errors} from 'appium/driver';
+import _ from 'lodash';
+
+/**
+ * Simulates push notification delivery to a simulated device.
+ *
+ * **Only "remote" push notifications are supported.** VoIP, Complication, File Provider, and other types are unsupported.
+ *
+ * Supported in Xcode SDK 11.4+.
+ * @param {string} bundleId - The bundle identifier of the target application
+ * @param {import('./types').PushPayload} payload - Valid push payload.
+ * @group Simulator Only
+ * @this {XCUITestDriver}
+ */
+export async function mobilePushNotification(bundleId, payload) {
+  if (!this.isSimulator()) {
+    throw new Error('This extension only works on Simulator');
+  }
+
+  if (!bundleId) {
+    throw new errors.InvalidArgumentError(
+      `'bundleId' argument must be a valid bundle identifier string`,
+    );
+  }
+  if (!_.isPlainObject(payload)) {
+    throw new errors.InvalidArgumentError(
+      `The 'payload' argument value must be a valid dictionary. ` +
+        `Got ${JSON.stringify(payload)} instead`,
+    );
+  }
+  if (!_.isPlainObject(payload.aps)) {
+    throw new errors.InvalidArgumentError(
+      `The 'payload.aps' value must be a valid dictionary. ` +
+        `Got ${JSON.stringify(payload.aps)} instead`,
+    );
+  }
+  return await /** @type {import('../driver').Simulator} */ (this.device).pushNotification({
+    ...payload,
+    'Simulator Target Bundle': bundleId,
+  });
+}
+
+/**
+ * Blocks until the expected notification is delivered.
+ *
+ * This method is a thin wrapper over the
+ * [`XCTNSNotificationExpectation`](https://developer.apple.com/documentation/xctest/xctnsnotificationexpectation?language=objc) and
+ * [`XCTDarwinNotificationExpectation`](https://developer.apple.com/documentation/xctest/xctdarwinnotificationexpectation?language=objc) entities.
+ *
+ * @param {string} name - The name of the notification to expect
+ * @param {import('./types').NotificationType} type - Which notification type to expect.
+ * @param {number} timeoutSeconds - For how long to wait until the notification is delivered (in float seconds).
+ * @throws A [`TimeoutError`](https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/error_exports_TimeoutError.html) if the expected notification has not been delivered within the given timeout.
+ * @this {XCUITestDriver}
+ */
+export async function mobileExpectNotification(name, type = 'plain', timeoutSeconds = 60) {
+  return await this.proxyCommand('/wda/expectNotification', 'POST', {
+    name,
+    type,
+    timeout: timeoutSeconds,
+  });
+}
+
+/**
+ * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
+ */

package/lib/commands/pasteboard.js

@@ -0,0 +1,42 @@
+/**
+ * Sets the Simulator's pasteboard content to the given value.
+ *
+ * Does not work for real devices.
+ * @param {string} content - The content to set
+ * @param {string} encoding - The content's encoding
+ * @group Simulator Only
+ * @returns {Promise<void>}
+ * @this {XCUITestDriver}
+ */
+export async function mobileSetPasteboard(content, encoding = 'utf8') {
+  if (!this.isSimulator()) {
+    throw new Error('Setting pasteboard content is not supported on real devices');
+  }
+  if (!content) {
+    // can be empty string
+    throw new Error('Pasteboard content is mandatory to set');
+  }
+  return await /** @type {import('../driver').Simulator} */ (this.device).simctl.setPasteboard(
+    content, /** @type {BufferEncoding} */ (encoding)
+  );
+}
+
+/**
+ * Gets the Simulator's pasteboard content.
+ *
+ * Does not work for real devices.
+ * @param {BufferEncoding} encoding - Expected encoding of returned string
+ * @group Simulator Only
+ * @this {XCUITestDriver}
+ * @returns {Promise<string>} The pasteboard content string
+ */
+export async function mobileGetPasteboard(encoding = 'utf8') {
+  if (!this.isSimulator()) {
+    throw new Error('Getting pasteboard content is not supported on real devices');
+  }
+  return await /** @type {import('../driver').Simulator} */ (this.device).simctl.getPasteboard(encoding);
+}
+
+/**
+ * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
+ */