appium-xcuitest-driver 10.15.0 → 10.16.1

package/lib/commands/certificate.ts

@@ -7,8 +7,8 @@ import path from 'path';
 import http from 'http';
 import {exec} from 'teen_process';
 import {findAPortNotInUse, checkPortStatus} from 'portscanner';
-import {Pyidevice} from '../device/clients/py-ios-device-client';
-import {requireRealDevice} from '../utils';
+import {CertificateClient} from '../device/certificate-client';
+import {requireRealDevice, isIos18OrNewer} from '../utils';
 import type {Simulator} from 'appium-ios-simulator';
 import type {XCUITestDriver} from '../driver';
 import type {CertificateList} from './types';
@@ -119,21 +119,14 @@ export async function mobileInstallCertificate(
       );
     }
   } else {
-    if (!this.opts.udid) {
-      throw new Error('udid capability is required');
-    }
-    const client = new Pyidevice({
-      udid: this.opts.udid,
-      log: this.log,
-    });
-    if (await client.assertExists(false)) {
-      await client.installProfile({payload: Buffer.from(content, 'base64')});
+    try {
+      await withCertificateClient(this, async (client) => {
+        await client.installCertificate({payload: Buffer.from(content, 'base64')});
+      });
       return;
-    } else {
-      this.log.info(
-        'pyidevice is not installed on your system. ' +
-          'Falling back to the (slow) UI-based installation',
-      );
+    } catch (err) {
+      this.log.error(`Failed to install the certificate: ${err.message}`);
+      this.log.info('Falling back to the (slow) UI-based installation');
     }
   }
 
@@ -161,7 +154,7 @@ export async function mobileInstallCertificate(
     try {
       const host = os.hostname();
       const certUrl = `http://${host}:${tmpPort}/${configName}`;
-      await tmpServer.listen(tmpPort);
+      tmpServer.listen(tmpPort);
       try {
         await waitForCondition(
           async () => {
@@ -233,7 +226,7 @@ export async function mobileInstallCertificate(
 
     return (await util.toInMemoryBase64(configPath)).toString();
   } finally {
-    await tmpServer.close();
+    tmpServer.close();
     await fs.rimraf(tmpRoot);
   }
 }
@@ -253,15 +246,7 @@ export async function mobileInstallCertificate(
  */
 export async function mobileRemoveCertificate(this: XCUITestDriver, name: string): Promise<string> {
   requireRealDevice(this, 'Removing certificate');
-  if (!this.opts.udid) {
-    throw new Error('udid capability is required');
-  }
-  const client = new Pyidevice({
-    udid: this.opts.udid,
-    log: this.log,
-  });
-  await client.assertExists(true);
-  return await client.removeProfile(name);
+  return await withCertificateClient(this, async (client) => client.removeCertificate(name));
 }
 
 /**
@@ -275,17 +260,37 @@ export async function mobileRemoveCertificate(this: XCUITestDriver, name: string
  */
 export async function mobileListCertificates(this: XCUITestDriver): Promise<CertificateList> {
   requireRealDevice(this, 'Listing certificates');
-  if (!this.opts.udid) {
-    throw new Error('udid capability is required');
-  }
-  const client = new Pyidevice({
-    udid: this.opts.udid,
-    log: this.log,
-  });
-  await client.assertExists(true);
-  return await client.listProfiles();
+  return await withCertificateClient(this, async (client) => client.listCertificates());
 }
 
+/**
+ * Helper function to create a CertificateClient, execute an operation, and ensure cleanup.
+ *
+ * @param driver - The XCUITestDriver instance
+ * @param operation - A callback function that receives the client and performs the operation
+ * @returns The result of the operation callback
+ */
+async function withCertificateClient<T>(
+  driver: XCUITestDriver,
+  operation: (client: CertificateClient) => Promise<T>,
+): Promise<T> {
+  let client: CertificateClient | null = null;
+  try {
+    if (!driver.opts.udid) {
+      throw new Error('udid capability is required');
+    }
+    client = await CertificateClient.create(
+      driver.opts.udid,
+      driver.log,
+      isIos18OrNewer(driver.opts),
+    );
+    return await operation(client);
+  } finally {
+    if (client) {
+      await client.close();
+    }
+  }
+}
 
 /**
  * Extracts the common name of the certificate from the given buffer.
@@ -501,4 +506,3 @@ async function installPost122Certificate(driver: XCUITestDriver, name: string):
 
   return true;
 }
-

package/lib/device/certificate-client.ts

@@ -0,0 +1,195 @@
+import type {AppiumLogger} from '@appium/types';
+import {Pyidevice} from './clients/py-ios-device-client';
+import {getRemoteXPCServices} from './remotexpc-utils';
+import type {CertificateList} from '../commands/types';
+import type {
+  MobileConfigService as RemoteXPCMobileConfigService,
+  RemoteXpcConnection,
+} from 'appium-ios-remotexpc';
+
+/**
+ * Options for installing a certificate
+ */
+export interface InstallCertificateOptions {
+  payload: Buffer;
+}
+
+/**
+ * Unified Certificate Client
+ *
+ * Provides a unified interface for certificate operations on iOS devices,
+ * automatically handling the differences between iOS < 18 (py-ios-device)
+ * and iOS 18 and above (appium-ios-remotexpc MobileConfigService).
+ */
+export class CertificateClient {
+  private readonly service: RemoteXPCMobileConfigService | Pyidevice;
+  private readonly remoteXPCConnection?: RemoteXpcConnection;
+  private readonly log: AppiumLogger;
+
+  private constructor(
+    service: RemoteXPCMobileConfigService | Pyidevice,
+    log: AppiumLogger,
+    remoteXPCConnection?: RemoteXpcConnection
+  ) {
+    this.service = service;
+    this.log = log;
+    this.remoteXPCConnection = remoteXPCConnection;
+  }
+
+  //#region Public Methods
+
+  /**
+   * Create a certificate client for device
+   *
+   * @param udid - Device UDID
+   * @param log - Appium logger instance
+   * @param useRemoteXPC - Whether to use remotexpc (use isIos18OrNewer(opts) to determine)
+   * @returns Certificate client instance
+   */
+  static async create(
+    udid: string,
+    log: AppiumLogger,
+    useRemoteXPC: boolean
+  ): Promise<CertificateClient> {
+    if (useRemoteXPC) {
+      const client = await CertificateClient.withRemoteXpcConnection(async () => {
+        const Services = await getRemoteXPCServices();
+        const {mobileConfigService, remoteXPC} = await Services.startMobileConfigService(udid);
+        return {
+          service: mobileConfigService,
+          connection: remoteXPC,
+        };
+      }, log);
+      if (client) {
+        return client;
+      }
+    }
+
+    // Fallback to py-ios-device
+    const pyideviceClient = new Pyidevice({
+      udid,
+      log,
+    });
+    await pyideviceClient.assertExists(true);
+    return new CertificateClient(pyideviceClient, log);
+  }
+
+  /**
+   * Install a certificate profile
+   *
+   * @param options - Installation options containing the certificate payload
+   */
+  async installCertificate(options: InstallCertificateOptions): Promise<void> {
+    const {payload} = options;
+
+    if (this.isRemoteXPC) {
+      await this.mobileConfigService.installProfileFromBuffer(payload);
+    } else {
+      await this.pyideviceClient.installProfile({payload});
+    }
+  }
+
+  /**
+   * Remove a certificate profile by name
+   *
+   * @param name - Name of the profile to remove
+   * @returns Status message ('Acknowledged' for RemoteXPC, or pyidevice output)
+   */
+  async removeCertificate(name: string): Promise<string> {
+    if (this.isRemoteXPC) {
+      await this.mobileConfigService.removeProfile(name);
+      return 'Acknowledged';
+    } else {
+      return await this.pyideviceClient.removeProfile(name);
+    }
+  }
+
+  /**
+   * List installed certificate profiles
+   *
+   * @returns List of installed certificates
+   */
+  async listCertificates(): Promise<CertificateList> {
+    if (this.isRemoteXPC) {
+      return await this.mobileConfigService.getProfileList();
+    } else {
+      return await this.pyideviceClient.listProfiles();
+    }
+  }
+
+  /**
+   * Close the certificate service connection and remoteXPC connection if present
+   */
+  async close(): Promise<void> {
+    if (this.remoteXPCConnection) {
+      try {
+        this.log.debug(`Closing remoteXPC connection`);
+        await this.remoteXPCConnection.close();
+      } catch (err: any) {
+        this.log.debug(`Error closing remoteXPC connection: ${err.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
+   * @param log - Logger instance
+   * @returns CertificateClient on success, null on failure
+   */
+  private static async withRemoteXpcConnection<T extends RemoteXPCMobileConfigService | Pyidevice>(
+    operation: () => Promise<{service: T; connection: RemoteXpcConnection}>,
+    log: AppiumLogger
+  ): Promise<CertificateClient | null> {
+    let remoteXPCConnection: RemoteXpcConnection | undefined;
+    let succeeded = false;
+    try {
+      const {service, connection} = await operation();
+      remoteXPCConnection = connection;
+      const client = new CertificateClient(service, log, remoteXPCConnection);
+      succeeded = true;
+      return client;
+    } catch (err: any) {
+      log.error(
+        `Failed to create certificate client via RemoteXPC: ${err.message}, falling back to py-ios-device`
+      );
+      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 MobileConfigService
+   */
+  private get mobileConfigService(): RemoteXPCMobileConfigService {
+    return this.service as RemoteXPCMobileConfigService;
+  }
+
+  /**
+   * Get service as Pyidevice client
+   */
+  private get pyideviceClient(): Pyidevice {
+    return this.service as Pyidevice;
+  }
+
+  //#endregion
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-xcuitest-driver",
-  "version": "10.15.0",
+  "version": "10.16.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-xcuitest-driver",
-      "version": "10.15.0",
+      "version": "10.16.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/strongbox": "^1.0.0-rc.1",
@@ -692,9 +692,9 @@
       }
     },
     "node_modules/appium-ios-remotexpc": {
-      "version": "0.25.2",
-      "resolved": "https://registry.npmjs.org/appium-ios-remotexpc/-/appium-ios-remotexpc-0.25.2.tgz",
-      "integrity": "sha512-mRMVjorxf70Q8qsDxoF8O5tDQ5N0hBYELQ6dUDnIUNI8YljcT1/SzlBnGLLfgZYuTK6ImyJhw/jifMJKjHEkrw==",
+      "version": "0.26.0",
+      "resolved": "https://registry.npmjs.org/appium-ios-remotexpc/-/appium-ios-remotexpc-0.26.0.tgz",
+      "integrity": "sha512-9c7z05u2vlwhn6OPyY60Tfug3U5LPNw1k6Se0qTRUxnGs7ttWltk+5Dn+QUy4XDRKCtogmv/azVWHBlfIz2xKg==",
       "license": "Apache-2.0",
       "optional": true,
       "dependencies": {

package/package.json

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