@limrun/appium-xcuitest-driver 10.11.0-lim.3 → 10.14.6-lim.1

package/lib/commands/{log.js → log.ts}

@@ -11,22 +11,33 @@ import { toLogEntry } from '../device/log/helpers';
 import { NATIVE_WIN } from '../utils';
 import { BIDI_EVENT_NAME } from './bidi/constants';
 import { makeLogEntryAddedEvent } from './bidi/models';
+import type {XCUITestDriver} from '../driver';
+import type {LogEntry, LogListener} from './types';
+import type {LogDefRecord, AppiumServer, WSServer} from '@appium/types';
+import type {Simulator} from 'appium-ios-simulator';
+import type {EventEmitter} from 'node:events';
 
 /**
  * Determines the websocket endpoint based on the `sessionId`
- * @param {string} sessionId
- * @returns {string}
  */
-const WEBSOCKET_ENDPOINT = (sessionId) =>
+const WEBSOCKET_ENDPOINT = (sessionId: string): string =>
   `${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 XCUITestDriverLogTypes = keyof typeof SUPPORTED_LOG_TYPES;
+
+interface BiDiListenerProperties {
+  type: string;
+  srcEventName?: string;
+  context?: string;
+  entryTransformer?: (x: any) => LogEntry;
+}
+
 /**
- * @type {import('@appium/types').LogDefRecord}
  * @privateRemarks The return types for these getters should be specified
  */
-const SUPPORTED_LOG_TYPES = {
+const SUPPORTED_LOG_TYPES: LogDefRecord = {
   syslog: {
     description: 'System Logs - Device logs for iOS applications on real devices and simulators',
     getter: async (self) => await self.extractLogs('syslog', self.logs),
@@ -49,9 +60,6 @@ const SUPPORTED_LOG_TYPES = {
   },
   server: {
     description: 'Appium server logs',
-    /**
-     * @returns {import('./types').LogEntry[]}
-     */
     getter: (self) => {
       self.assertFeatureEnabled(GET_SERVER_LOGS_FEATURE);
       return self.log.unwrap().record.map(nativeLogEntryToSeleniumEntry);
@@ -59,7 +67,7 @@ const SUPPORTED_LOG_TYPES = {
   },
 };
 
-const LOG_NAMES_TO_CAPABILITY_NAMES_MAP = {
+const LOG_NAMES_TO_CAPABILITY_NAMES_MAP: Record<string, string> = {
   safariConsole: 'showSafariConsoleLog',
   safariNetwork: 'showSafariNetworkLog',
   enablePerformanceLogging: 'enablePerformanceLogging',
@@ -68,12 +76,18 @@ const LOG_NAMES_TO_CAPABILITY_NAMES_MAP = {
 export const supportedLogTypes = SUPPORTED_LOG_TYPES;
 
 /**
+ * Extracts logs of the specified type from the logs container.
  *
- * @param {XCUITestDriverLogTypes} logType
- * @param {Partial<Record<XCUITestDriverLogTypes,{getLogs(): Promise<any>}>>} [logsContainer]
- * @this {XCUITestDriver}
+ * @param logType - The type of log to extract
+ * @param logsContainer - Container holding log objects
+ * @returns The extracted logs
+ * @throws {Error} If logs are not available or the log type is not found
  */
-export async function extractLogs(logType, logsContainer = {}) {
+export async function extractLogs(
+  this: XCUITestDriver,
+  logType: XCUITestDriverLogTypes,
+  logsContainer: Partial<Record<XCUITestDriverLogTypes, {getLogs(): Promise<any>}>> = {},
+): Promise<any> {
   // make sure that we have logs at all
   // otherwise it's not been initialized
   if (_.isEmpty(logsContainer)) {
@@ -97,9 +111,14 @@ export async function extractLogs(logType, logsContainer = {}) {
 }
 
 /**
- * @this {XCUITestDriver}
+ * Starts capturing iOS system logs.
+ *
+ * Initializes and starts capturing syslog and crashlog. Optionally starts Safari console and network logs
+ * if the corresponding capabilities are enabled.
+ *
+ * @returns `true` if syslog capture started successfully; `false` otherwise
  */
-export async function startLogCapture() {
+export async function startLogCapture(this: XCUITestDriver): Promise<boolean> {
   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!');
@@ -109,7 +128,7 @@ export async function startLogCapture() {
   if (_.isUndefined(this.logs.syslog)) {
     [this.logs.crashlog,] = assignBiDiLogListener.bind(this)(
       new IOSCrashLog({
-        sim: /** @type {import('appium-ios-simulator').Simulator} */ (this.device),
+        sim: this.device as Simulator,
         udid: this.isRealDevice() ? this.opts.udid : undefined,
         log: this.log,
       }), {
@@ -119,12 +138,12 @@ export async function startLogCapture() {
     [this.logs.syslog,] = assignBiDiLogListener.bind(this)(
       this.isRealDevice()
         ? new IOSDeviceLog({
-          udid: /** @type {string} */ (this.opts.udid),
+          udid: this.opts.udid as string,
           showLogs: this.opts.showIOSLog,
           log: this.log,
         })
         : new IOSSimulatorLog({
-          sim: /** @type {import('appium-ios-simulator').Simulator} */ (this.device),
+          sim: this.device as Simulator,
           showLogs: this.opts.showIOSLog,
           iosSimulatorLogsPredicate: this.opts.iosSimulatorLogsPredicate,
           simulatorLogLevel: this.opts.simulatorLogLevel,
@@ -167,14 +186,13 @@ export async function startLogCapture() {
   }
 
   let didStartSyslog = false;
-  /** @type {Promise[]} */
-  const promises = [
+  const promises: Promise<any>[] = [
     (async () => {
       try {
         await this.logs.syslog?.startCapture();
         didStartSyslog = true;
         this.eventEmitter.emit('syslogStarted', this.logs.syslog);
-      } catch (err) {
+      } catch (err: any) {
         this.log.debug(err.stack);
         this.log.warn(`Continuing without capturing device logs: ${err.message}`);
       }
@@ -189,22 +207,18 @@ export async function startLogCapture() {
 /**
  * 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`.
+ * 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.
+ * Each connected websocket 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));
+export async function mobileStartLogsBroadcast(this: XCUITestDriver): Promise<void> {
+  const pathname = WEBSOCKET_ENDPOINT(this.sessionId as string);
   if (
     !_.isEmpty(
-      await /** @type {import('@appium/types').AppiumServer} */ (
-        this.server
-      ).getWebSocketHandlers(pathname),
+      await (this.server as AppiumServer).getWebSocketHandlers(pathname),
     )
   ) {
     this.log.debug(
@@ -229,7 +243,7 @@ export async function mobileStartLogsBroadcast() {
     }
 
     if (_.isEmpty(this._syslogWebsocketListener)) {
-      this._syslogWebsocketListener = (logRecord) => {
+      this._syslogWebsocketListener = (logRecord: {message: string}) => {
         if (ws?.readyState === WebSocket.OPEN) {
           ws.send(logRecord.message);
         }
@@ -237,7 +251,7 @@ export async function mobileStartLogsBroadcast() {
     }
     this.logs.syslog?.on('output', this._syslogWebsocketListener);
 
-    ws.on('close', (code, reason) => {
+    ws.on('close', (code: number, reason: Buffer) => {
       if (!_.isEmpty(this._syslogWebsocketListener)) {
         this.logs.syslog?.removeListener('output', this._syslogWebsocketListener);
         this._syslogWebsocketListener = null;
@@ -253,45 +267,49 @@ export async function mobileStartLogsBroadcast() {
       this.log.debug(closeMsg);
     });
   });
-  await /** @type {AppiumServer} */ (this.server).addWebSocketHandler(
+  await (this.server as AppiumServer).addWebSocketHandler(
     pathname,
-    /** @type {import('@appium/types').WSServer} */ (wss),
+    wss as WSServer,
   );
 }
 
 /**
- * Stops the syslog broadcasting wesocket server previously started by `mobile: startLogsBroadcast`.
+ * Stops the syslog broadcasting websocket 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))) {
+export async function mobileStopLogsBroadcast(this: XCUITestDriver): Promise<void> {
+  const pathname = WEBSOCKET_ENDPOINT(this.sessionId as string);
+  if (_.isEmpty(await (this.server as AppiumServer).getWebSocketHandlers(pathname))) {
     return;
   }
 
   this.log.debug('Stopping the system logs broadcasting web socket server');
-  await /** @type {AppiumServer} */ (this.server).removeWebSocketHandler(pathname);
+  await (this.server as AppiumServer).removeWebSocketHandler(pathname);
 }
 
 /**
+ * Assigns a BiDi log listener to the given log emitter.
+ *
  * 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]}
+ * @template EE extends EventEmitter
+ * @param logEmitter - The event emitter to attach the listener to
+ * @param properties - Configuration for the BiDi listener
+ * @returns A tuple containing the log emitter and the listener function
  */
-export function assignBiDiLogListener (logEmitter, properties) {
+export function assignBiDiLogListener<EE extends EventEmitter>(
+  this: XCUITestDriver,
+  logEmitter: EE,
+  properties: BiDiListenerProperties,
+): [EE, LogListener] {
   const {
     type,
     context = NATIVE_WIN,
     srcEventName = 'output',
     entryTransformer,
   } = properties;
-  const listener = (/** @type {import('./types').LogEntry} */ logEntry) => {
+  const listener: LogListener = (logEntry: LogEntry) => {
     const finalEntry = entryTransformer ? entryTransformer(logEntry) : logEntry;
     this.eventEmitter.emit(BIDI_EVENT_NAME, makeLogEntryAddedEvent(finalEntry, context, type));
   };
@@ -299,29 +317,11 @@ export function assignBiDiLogListener (logEmitter, properties) {
   return [logEmitter, listener];
 }
 
-/**
- *
- * @param {Object} x
- * @returns {import('./types').LogEntry}
- */
-function nativeLogEntryToSeleniumEntry (x) {
+function nativeLogEntryToSeleniumEntry(x: any): LogEntry {
   const msg = _.isEmpty(x.prefix) ? x.message : `[${x.prefix}] ${x.message}`;
   return toLogEntry(
     _.replace(msg, COLOR_CODE_PATTERN, ''),
-    /** @type {any} */ (x).timestamp ?? Date.now()
+    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 → memory.ts}

@@ -1,20 +1,24 @@
 import _ from 'lodash';
 import { errors } from 'appium/driver';
+import type {XCUITestDriver} from '../driver';
+import type {RealDevice} from '../device/real-device-management';
 
 /**
  * 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
+ * @param bundleId - The bundle identifier of the target app. The app must be running
+ * @throws If the app is not running or is not installed
  */
-export async function mobileSendMemoryWarning(bundleId) {
+export async function mobileSendMemoryWarning(
+  this: XCUITestDriver,
+  bundleId: string,
+): Promise<void> {
   if (!this.isRealDevice()) {
     throw new Error('Memory warning simulation is only supported on real devices');
   }
 
-  const device = /** @type {import('../device/real-device-management').RealDevice} */ (this.device);
+  const device = this.device as RealDevice;
 
   const appInfos = await device.devicectl.listApps(bundleId);
   if (_.isEmpty(appInfos)) {
@@ -33,7 +37,6 @@ export async function mobileSendMemoryWarning(bundleId) {
   // 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);
@@ -46,6 +49,3 @@ export async function mobileSendMemoryWarning(bundleId) {
   await device.devicectl.sendMemoryWarning(pids[0]);
 }
 
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

package/lib/commands/{navigation.js → navigation.ts}

@@ -1,16 +1,17 @@
 import {errors} from 'appium/driver';
-import _ from 'lodash';
 import {waitForCondition} from 'asyncbox';
 import { isTvOs } from '../utils';
+import type {XCUITestDriver} from '../driver';
+import type {Element} from '@appium/types';
 
 // these two constitute the wait after closing a window
 const CLOSE_WINDOW_TIMEOUT = 5000;
 const CLOSE_WINDOW_INTERVAL = 100;
 
 /**
- * @this {XCUITestDriver}
+ * Navigate back in the browser history or native app navigation.
  */
-export async function back() {
+export async function back(this: XCUITestDriver): Promise<void> {
   if (!this.isWebContext()) {
     await this.nativeBack();
   } else {
@@ -19,18 +20,22 @@ export async function back() {
 }
 
 /**
- * @this {XCUITestDriver}
+ * Navigate forward in the browser history.
  */
-export async function forward() {
+export async function forward(this: XCUITestDriver): Promise<void> {
   if (!this.isWebContext()) {
+    // No-op for native context
+    return;
   }
   await this.mobileWebNav('forward');
 }
 
 /**
- * @this {XCUITestDriver}
+ * Closes the current window in a web context.
+ *
+ * @returns Promise that resolves when the window is closed
  */
-export async function closeWindow() {
+export async function closeWindow(this: XCUITestDriver): Promise<any> {
   if (!this.isWebContext()) {
     throw new errors.NotImplementedError();
   }
@@ -60,14 +65,16 @@ export async function closeWindow() {
  *
  * (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
+ * @param url - the URL to be opened, e.g. `myscheme://yolo`
+ * @param 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) {
+export async function mobileDeepLink(
+  this: XCUITestDriver,
+  url: string,
+  bundleId?: string,
+): Promise<void> {
   return await this.proxyCommand('/url', 'POST', {
     url,
     bundleId,
@@ -75,51 +82,47 @@ export async function mobileDeepLink(url, bundleId) {
 }
 
 /**
- * @this {XCUITestDriver}
+ * Navigate back in native app navigation by finding and clicking the back button.
  */
-export async function nativeBack() {
+export async function nativeBack(this: XCUITestDriver): Promise<void> {
   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(
+    const navBar = await this.findNativeElementOrElements(
       'class name',
       'XCUIElementTypeNavigationBar',
       false,
     );
-    let buttons = await this.findNativeElementOrElements(
-      'class name',
-      'XCUIElementTypeButton',
+    let dstButton: Element<string>;
+    const backButtons = await this.findNativeElementOrElements(
+      '-ios predicate string',
+      'type == "XCUIElementTypeButton" AND label == "Back"',
       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) {
+    if (backButtons.length === 0) {
+      const buttons = await this.findNativeElementOrElements(
+        '-ios predicate string',
+        'type == "XCUIElementTypeButton"',
+        true,
+        navBar,
+      );
+      if (buttons.length === 0) {
+        throw new Error('No buttons found in navigation bar');
+      }
       this.log.debug(`Found navigation bar 'back' button. Clicking.`);
+      dstButton = buttons[0];
     } else {
-      this.log.debug(`Unable to find 'Back' button. Trying first button in navigation bar`);
-      backButton = buttons?.[0];
+      this.log.debug(`Did not find any navigation bar 'back' button. Clicking the first one.`);
+      dstButton = backButtons[0];
     }
-    await this.nativeClick(/** @type {string} */ (backButton));
-  } catch (err) {
+
+    await this.nativeClick(dstButton);
+  } catch (err: any) {
     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 → notifications.ts}

@@ -1,5 +1,8 @@
 import {errors} from 'appium/driver';
 import _ from 'lodash';
+import type {XCUITestDriver} from '../driver';
+import type {PushPayload, NotificationType} from './types';
+import type {Simulator} from 'appium-ios-simulator';
 
 /**
  * Simulates push notification delivery to a simulated device.
@@ -7,12 +10,16 @@ import _ from 'lodash';
  * **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.
+ *
+ * @param bundleId - The bundle identifier of the target application
+ * @param payload - Valid push payload.
  * @group Simulator Only
- * @this {XCUITestDriver}
  */
-export async function mobilePushNotification(bundleId, payload) {
+export async function mobilePushNotification(
+  this: XCUITestDriver,
+  bundleId: string,
+  payload: PushPayload,
+): Promise<void> {
   if (!this.isSimulator()) {
     throw new Error('This extension only works on Simulator');
   }
@@ -34,7 +41,7 @@ export async function mobilePushNotification(bundleId, payload) {
         `Got ${JSON.stringify(payload.aps)} instead`,
     );
   }
-  return await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).pushNotification({
+  await (this.device as Simulator).pushNotification({
     ...payload,
     'Simulator Target Bundle': bundleId,
   });
@@ -47,20 +54,21 @@ export async function mobilePushNotification(bundleId, payload) {
  * [`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).
+ * @param name - The name of the notification to expect
+ * @param type - Which notification type to expect.
+ * @param 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', {
+export async function mobileExpectNotification(
+  this: XCUITestDriver,
+  name: string,
+  type: NotificationType = 'plain',
+  timeoutSeconds: number = 60,
+): Promise<void> {
+  await this.proxyCommand('/wda/expectNotification', 'POST', {
     name,
     type,
     timeout: timeoutSeconds,
   });
 }
 
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

package/lib/commands/pasteboard.ts

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