appium-xcuitest-driver 10.16.2 → 10.17.0

package/lib/commands/log.ts

@@ -8,7 +8,7 @@ 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 { NATIVE_WIN, isIos18OrNewer } from '../utils';
 import { BIDI_EVENT_NAME } from './bidi/constants';
 import { makeLogEntryAddedEvent } from './bidi/models';
 import type {XCUITestDriver} from '../driver';
@@ -131,6 +131,7 @@ export async function startLogCapture(this: XCUITestDriver): Promise<boolean> {
         sim: this.device as Simulator,
         udid: this.isRealDevice() ? this.opts.udid : undefined,
         log: this.log,
+        useRemoteXPC: this.isRealDevice() && isIos18OrNewer(this.opts),
       }), {
         type: 'crashlog',
       }

package/lib/device/crash-reports-client.ts

@@ -0,0 +1,216 @@
+import {getRemoteXPCServices} from './remotexpc-utils';
+import {log} from '../logger';
+import type {
+  CrashReportsService as RemoteXPCCrashReportsService,
+  RemoteXpcConnection,
+} from 'appium-ios-remotexpc';
+import type {Pyidevice as PyideviceClient} from './clients/py-ios-device-client';
+import {Pyidevice} from './clients/py-ios-device-client';
+
+const CRASH_REPORT_EXTENSIONS = ['.ips'];
+const MAX_FILES_IN_ERROR = 10;
+
+/**
+ * Unified Crash Reports Client
+ *
+ * Provides a unified interface for crash report operations on iOS devices,
+ * automatically handling the differences between iOS < 18 (py-ios-device via Pyidevice)
+ * and iOS 18+ (appium-ios-remotexpc).
+ */
+export class CrashReportsClient {
+  private readonly service: RemoteXPCCrashReportsService | PyideviceClient;
+  private readonly remoteXPCConnection?: RemoteXpcConnection;
+
+  private constructor(
+    service: RemoteXPCCrashReportsService | PyideviceClient,
+    remoteXPCConnection?: RemoteXpcConnection
+  ) {
+    this.service = service;
+    this.remoteXPCConnection = remoteXPCConnection;
+  }
+
+  //#region Public Static Methods
+
+  /**
+   * Create a crash reports client for device
+   *
+   * @param udid - Device UDID
+   * @param useRemoteXPC - Whether to use remotexpc
+   * @returns CrashReportsClient instance
+   */
+  static async create(udid: string, useRemoteXPC: boolean): Promise<CrashReportsClient> {
+    if (useRemoteXPC) {
+      const client = await CrashReportsClient.withRemoteXpcConnection(async () => {
+        const Services = await getRemoteXPCServices();
+        const {crashReportsService, remoteXPC} = await Services.startCrashReportsService(udid);
+        return {
+          service: crashReportsService,
+          connection: remoteXPC,
+        };
+      });
+      if (client) {
+        return client;
+      }
+    }
+
+    // Fallback to Pyidevice
+    const pyideviceClient = new Pyidevice({udid, log});
+    return new CrashReportsClient(pyideviceClient);
+  }
+
+  //#endregion
+
+  //#region Public Instance Methods
+
+  /**
+   * Check if the crash reports tool exists
+   *
+   * @param isStrict - If true, throws an error when tool is not found
+   * @returns True if the tool exists, false otherwise
+   */
+  async assertExists(isStrict: boolean = true): Promise<boolean> {
+    if (this.isRemoteXPC) {
+      // RemoteXPC is already connected, so it exists
+      return true;
+    }
+
+    // Pyidevice: check if binary exists
+    return await this.pyideviceClient.assertExists(isStrict);
+  }
+
+  /**
+   * List crash report files on the device
+   *
+   * @returns Array of crash report file names (e.g., ['crash1.ips', 'crash2.crash'])
+   */
+  async listCrashes(): Promise<string[]> {
+    if (!this.isRemoteXPC) {
+      return await this.pyideviceClient.listCrashes();
+    }
+
+    // RemoteXPC: ls returns full paths, filter and extract filenames
+    const allFiles = await this.remoteXPCCrashReportsService.ls('/', -1);
+    return allFiles
+      .filter((filePath) =>
+        CRASH_REPORT_EXTENSIONS.some((ext) => filePath.endsWith(ext))
+      )
+      .map((filePath) => {
+        const parts = filePath.split('/');
+        return parts[parts.length - 1];
+      });
+  }
+
+  /**
+   * Export a crash report file from the device to local directory
+   *
+   * @param name - Name of the crash report file (e.g., 'crash.ips')
+   * @param dstFolder - Local destination folder path
+   */
+  async exportCrash(name: string, dstFolder: string): Promise<void> {
+    if (!this.isRemoteXPC) {
+      return await this.pyideviceClient.exportCrash(name, dstFolder);
+    }
+
+    // RemoteXPC: need to find full path first, then pull
+    const allFiles = await this.remoteXPCCrashReportsService.ls('/', -1);
+    const fullPath = allFiles.find((p) => p.endsWith(`/${name}`) || p === `/${name}`);
+
+    if (!fullPath) {
+      const filesList = allFiles.slice(0, MAX_FILES_IN_ERROR).join(', ');
+      const hasMore = allFiles.length > MAX_FILES_IN_ERROR;
+      throw new Error(
+        `Crash report '${name}' not found on device. ` +
+          `Available files: ${filesList}${hasMore ? `, ... and ${allFiles.length - MAX_FILES_IN_ERROR} more` : ''}`
+      );
+    }
+
+    await this.remoteXPCCrashReportsService.pull(dstFolder, fullPath);
+  }
+
+  /**
+   * Close the crash reports service and release resources
+   *
+   * Only RemoteXPC clients need explicit cleanup; Pyidevice is stateless
+   */
+  async close(): Promise<void> {
+    if (!this.isRemoteXPC) {
+      return;
+    }
+
+    this.remoteXPCCrashReportsService.close();
+
+    if (this.remoteXPCConnection) {
+      try {
+        await this.remoteXPCConnection.close();
+      } catch (err) {
+        log.warn(
+          `Error closing RemoteXPC connection for crash reports: ${(err as Error).message}`
+        );
+      }
+    }
+  }
+
+  //#endregion
+
+  //#region Private Methods
+
+  /**
+   * Check if this client is using RemoteXPC
+   */
+  private get isRemoteXPC(): boolean {
+    return !!this.remoteXPCConnection;
+  }
+
+  /**
+   * Helper to safely execute remoteXPC operations with connection cleanup
+   * @param operation - Async operation that returns service and connection
+   * @returns CrashReportsClient on success, null on failure
+   */
+  private static async withRemoteXpcConnection(
+    operation: () => Promise<{
+      service: RemoteXPCCrashReportsService;
+      connection: RemoteXpcConnection;
+    }>
+  ): Promise<CrashReportsClient | null> {
+    let remoteXPCConnection: RemoteXpcConnection | undefined;
+    let succeeded = false;
+    try {
+      const {service, connection} = await operation();
+      remoteXPCConnection = connection;
+      const client = new CrashReportsClient(service, remoteXPCConnection);
+      succeeded = true;
+      return client;
+    } catch (err: any) {
+      log.error(
+        `Failed to create crash reports client via RemoteXPC: ${err.message}. ` +
+          `Falling back to py-ios-device (pyidevice)`
+      );
+      return null;
+    } finally {
+      // Only close connection if we failed (if succeeded, the client owns it)
+      if (remoteXPCConnection && !succeeded) {
+        try {
+          await remoteXPCConnection.close();
+        } catch {
+          // Ignore cleanup errors
+        }
+      }
+    }
+  }
+
+  /**
+   * Get service as RemoteXPC crash reports service
+   */
+  private get remoteXPCCrashReportsService(): RemoteXPCCrashReportsService {
+    return this.service as RemoteXPCCrashReportsService;
+  }
+
+  /**
+   * Get service as Pyidevice client
+   */
+  private get pyideviceClient(): PyideviceClient {
+    return this.service as PyideviceClient;
+  }
+
+  //#endregion
+}

package/lib/device/log/ios-crash-log.ts

@@ -2,11 +2,10 @@ import {fs, tempDir, util} from 'appium/support';
 import B from 'bluebird';
 import path from 'path';
 import _ from 'lodash';
-import {Pyidevice} from '../clients/py-ios-device-client';
+import {CrashReportsClient} from '../crash-reports-client';
 import {IOSLog} from './ios-log';
 import { toLogEntry, grepFile } from './helpers';
 import type { AppiumLogger } from '@appium/types';
-import type { BaseDeviceClient } from '../clients/base-device-client';
 import type { Simulator } from 'appium-ios-simulator';
 import type { LogEntry } from '../../commands/types';
 
@@ -24,11 +23,14 @@ export interface IOSCrashLogOptions {
   /** Simulator instance */
   sim?: Simulator;
   log: AppiumLogger;
+  /** Whether to use RemoteXPC for crash reports (iOS 18+). */
+  useRemoteXPC?: boolean;
 }
 
 export class IOSCrashLog extends IOSLog<TSerializedEntry, TSerializedEntry> {
   private readonly _udid: string | undefined;
-  private readonly _realDeviceClient: BaseDeviceClient | null;
+  private readonly _useRemoteXPC: boolean;
+  private _realDeviceClient: CrashReportsClient | null;
   private readonly _logDir: string | null;
   private readonly _sim: Simulator | undefined;
   private _recentCrashFiles: string[];
@@ -41,12 +43,8 @@ export class IOSCrashLog extends IOSLog<TSerializedEntry, TSerializedEntry> {
     });
     this._udid = opts.udid;
     this._sim = opts.sim;
-    this._realDeviceClient = this._isRealDevice()
-      ? new Pyidevice({
-        udid: this._udid as string,
-        log: opts.log,
-      })
-      : null;
+    this._useRemoteXPC = opts.useRemoteXPC ?? false;
+    this._realDeviceClient = null;
     this._logDir = this._isRealDevice()
       ? null
       : path.resolve(process.env.HOME || '/', 'Library', 'Logs', 'DiagnosticReports');
@@ -61,6 +59,11 @@ export class IOSCrashLog extends IOSLog<TSerializedEntry, TSerializedEntry> {
 
   override async stopCapture(): Promise<void> {
     this._started = false;
+    // Clean up the client connection
+    if (this._realDeviceClient) {
+      await this._realDeviceClient.close();
+      this._realDeviceClient = null;
+    }
   }
 
   override get isCapturing(): boolean {
@@ -97,11 +100,11 @@ export class IOSCrashLog extends IOSLog<TSerializedEntry, TSerializedEntry> {
         if (this._isRealDevice()) {
           const fileName = filePath;
           try {
-            await (this._realDeviceClient as BaseDeviceClient).exportCrash(fileName, tmpRoot);
+            await (this._realDeviceClient as CrashReportsClient).exportCrash(fileName, tmpRoot);
           } catch (e) {
             this.log.warn(
               `Cannot export the crash report '${fileName}'. Skipping it. ` +
-              `Original error: ${e.message}`,
+              `Original error: ${(e as Error).message}`,
             );
             return;
           }
@@ -117,8 +120,20 @@ export class IOSCrashLog extends IOSLog<TSerializedEntry, TSerializedEntry> {
 
   private async _gatherFromRealDevice(strict: boolean): Promise<string[]> {
     if (!this._realDeviceClient) {
-      return [];
+      try {
+        this._realDeviceClient = await CrashReportsClient.create(
+          this._udid as string,
+          this._useRemoteXPC
+        );
+      } catch (err) {
+        this.log.error(
+          `Failed to create crash reports client: ${(err as Error).message}. ` +
+          `Skipping crash logs collection for real devices.`
+        );
+        return [];
+      }
     }
+
     if (!await this._realDeviceClient.assertExists(strict)) {
       this.log.info(
         `The ${_.toLower(this._realDeviceClient.constructor.name)} tool is not present in PATH. ` +

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-xcuitest-driver",
-  "version": "10.16.2",
+  "version": "10.17.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-xcuitest-driver",
-      "version": "10.16.2",
+      "version": "10.17.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/strongbox": "^1.0.0-rc.1",
@@ -752,9 +752,9 @@
       }
     },
     "node_modules/appium-remote-debugger": {
-      "version": "15.2.9",
-      "resolved": "https://registry.npmjs.org/appium-remote-debugger/-/appium-remote-debugger-15.2.9.tgz",
-      "integrity": "sha512-yscA+KsxDF0gTSy3fo8pa9kxa+to/PIL428+khDqUTNGjmDssgD0fD2/JH0bcQ5+j1BzlEk6avW7U+O3jvzXmA==",
+      "version": "15.2.10",
+      "resolved": "https://registry.npmjs.org/appium-remote-debugger/-/appium-remote-debugger-15.2.10.tgz",
+      "integrity": "sha512-1Ez76NmzuiyF8tWMTgczgTidAF0HIV8PvWVjaxxjnQTuuwqAMpZ9bPv+iWwETAhPlC5vL/SSb7dU73HEki1vGw==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/base-driver": "^10.0.0-rc.1",
@@ -1022,9 +1022,9 @@
       "license": "MIT"
     },
     "node_modules/asyncbox": {
-      "version": "4.0.1",
-      "resolved": "https://registry.npmjs.org/asyncbox/-/asyncbox-4.0.1.tgz",
-      "integrity": "sha512-JtbRZ6JWq1eT0mq/Eg2yObjnX9+80QcYQXDYyLxeNcbu2jHjbV18De2eyn69GTWbbLvDm52Pp/4SFDtte3q/bQ==",
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/asyncbox/-/asyncbox-4.1.1.tgz",
+      "integrity": "sha512-j2O7uJ2UmPM9ok++6nVcGC+w1KreiAM2Cjw4IKpX0cgKV621sZeftfGxzPBWGfOsit+hIKIjpAHvppGdXxfDcg==",
       "license": "Apache-2.0",
       "dependencies": {
         "bluebird": "^3.5.1",

package/package.json

@@ -8,7 +8,7 @@
     "xcuitest",
     "xctest"
   ],
-  "version": "10.16.2",
+  "version": "10.17.0",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {