feat: add testmanagerd DTX service for XCTest (#148)

Author: navin772

package.json

@@ -54,6 +54,7 @@
     "test:dvt:notification": "mocha test/integration/dvt_instruments/notifications-test.ts --exit --timeout 1m",
     "test:dvt:network-monitor": "mocha test/integration/dvt_instruments/network-monitor-test.ts --exit --timeout 1m",
     "test:dvt:process-control": "mocha test/integration/process-control-test.ts --exit --timeout 1m",
+    "test:testmanagerd": "mocha test/integration/testmanagerd-test.ts --exit --timeout 2m",
     "test:tunnel-creation": "sudo tsx scripts/test-tunnel-creation.ts",
     "test:tunnel-creation:lsof": "sudo tsx scripts/test-tunnel-creation.ts --keep-open"
   },

src/index.ts

@@ -71,6 +71,9 @@ export type {
   ProcessControlService,
   ProcessLaunchOptions,
   OutputReceivedEvent,
+  SendMessageOptions,
+  TestmanagerdService,
+  TestmanagerdServiceWithConnection,
 } from './lib/types.js';
 export { PowerAssertionType } from './lib/types.js';
 export { NetworkMessageType } from './services/ios/dvt/instruments/network-monitor.js';

src/lib/types.ts

@@ -1755,3 +1755,85 @@ export interface InstallationProxyServiceWithConnection {
   /** The RemoteXPC connection for service management */
   remoteXPC: RemoteXpcConnection;
 }
+
+/**
+ * Options for sending a DTX message
+ */
+export interface SendMessageOptions {
+  /** Optional message arguments */
+  args?: any | null;
+  /** Whether a reply is expected (default: true) */
+  expectsReply?: boolean;
+}
+
+/**
+ * Testmanagerd DTX service interface for XCTest session management
+ */
+export interface TestmanagerdService extends BaseService {
+  /**
+   * Connect to the testmanagerd service and perform DTX handshake
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Create a communication channel for a specific identifier
+   * @param identifier The channel identifier
+   * @returns The created channel
+   */
+  makeChannel(identifier: string): Promise<any>;
+
+  /**
+   * Send a DTX message on a channel
+   * @param channel The channel code
+   * @param selector The ObjectiveC method selector
+   * @param options Optional message options
+   */
+  sendMessage(
+    channel: number,
+    selector: string | null,
+    options?: SendMessageOptions,
+  ): Promise<void>;
+
+  /**
+   * Receive a plist message from a channel
+   * @param channel The channel to receive from
+   * @param signal Optional AbortSignal for cancellation
+   * @returns Tuple of [decoded data, auxiliary values]
+   */
+  recvPlist(channel?: number, signal?: AbortSignal): Promise<[any, any[]]>;
+
+  /**
+   * Receive a plist message with a timeout. Returns null on timeout instead
+   * of throwing, and properly cleans up socket listeners to prevent leaks.
+   * @param channel The channel to receive from
+   * @param timeoutMs Timeout in milliseconds
+   * @returns Tuple of [decoded data, auxiliary values], or null on timeout
+   */
+  recvPlistWithTimeout(
+    channel?: number,
+    timeoutMs?: number,
+  ): Promise<[any, any[]] | null>;
+
+  /**
+   * Send a DTX reply message for the last received message on a channel.
+   * Used for responding to callbacks like _XCT_testRunnerReadyWithCapabilities:.
+   * @param channel The channel code
+   * @param payload Optional archived payload to include in the reply
+   */
+  sendReply(channel: number, payload?: Buffer | null): Promise<void>;
+
+  /**
+   * Close the testmanagerd service connection
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * Represents a TestmanagerdService instance with its associated RemoteXPC connection
+ */
+export interface TestmanagerdServiceWithConnection {
+  /** The testmanagerd service instance */
+  testmanagerdService: TestmanagerdService;
+  /** The RemoteXPC connection for service management */
+  remoteXPC: RemoteXpcConnection;
+}

src/services.ts

@@ -16,6 +16,7 @@ import type {
   PowerAssertionServiceWithConnection,
   SpringboardServiceWithConnection,
   SyslogService as SyslogServiceType,
+  TestmanagerdServiceWithConnection,
   WebInspectorServiceWithConnection,
 } from './lib/types.js';
 import AfcService from './services/ios/afc/index.js';
@@ -40,6 +41,7 @@ import { NotificationProxyService } from './services/ios/notification-proxy/inde
 import { PowerAssertionService } from './services/ios/power-assertion/index.js';
 import { SpringBoardService } from './services/ios/springboard-service/index.js';
 import SyslogService from './services/ios/syslog-service/index.js';
+import { DvtTestmanagedProxyService } from './services/ios/testmanagerd/index.js';
 import { WebInspectorService } from './services/ios/webinspector/index.js';
 
 const APPIUM_XCUITEST_DRIVER_NAME = 'appium-xcuitest-driver';
@@ -293,6 +295,27 @@ export async function startDVTService(
   };
 }
 
+export async function startTestmanagerdService(
+  udid: string,
+): Promise<TestmanagerdServiceWithConnection> {
+  const { remoteXPC, tunnelConnection } = await createRemoteXPCConnection(udid);
+  const testmanagerdDescriptor = remoteXPC.findService(
+    DvtTestmanagedProxyService.RSD_SERVICE_NAME,
+  );
+
+  const testmanagerdService = new DvtTestmanagedProxyService([
+    tunnelConnection.host,
+    parseInt(testmanagerdDescriptor.port, 10),
+  ]);
+
+  await testmanagerdService.connect();
+
+  return {
+    remoteXPC: remoteXPC as RemoteXpcConnection,
+    testmanagerdService,
+  };
+}
+
 export async function createRemoteXPCConnection(udid: string) {
   const tunnelConnection = await getTunnelInformation(udid);
   const remoteXPC = await startService(

src/services/ios/base-service.ts

@@ -1,3 +1,5 @@
+import type net from 'node:net';
+
 import { getLogger } from '../../lib/logger.js';
 import { ServiceConnection } from '../../service-connection.js';
 
@@ -77,4 +79,14 @@ export class BaseService {
   }
 }
 
+/**
+ * Remove any SSL wrapper from the socket so raw binary protocols (DTX)
+ * can read/write directly. Both DVT and testmanagerd services require this.
+ */
+export function stripSSL(socket: net.Socket): void {
+  if ('_sslobj' in socket) {
+    (socket as any)._sslobj = null;
+  }
+}
+
 export default BaseService;

src/services/ios/dvt/channel.ts

@@ -1,5 +1,18 @@
+import type { SendMessageOptions } from '../../../lib/types.js';
 import type { MessageAux } from './dtx-message.js';
-import type { DVTSecureSocketProxyService } from './index.js';
+
+/**
+ * Interface for DTX services that can be used with Channel.
+ * Both DVTSecureSocketProxyService and DvtTestmanagedProxyService implement this.
+ */
+export interface DTXServiceProvider {
+  recvPlist(channel: number, signal?: AbortSignal): Promise<[any, any[]]>;
+  sendMessage(
+    channel: number,
+    selector: string | null,
+    options?: SendMessageOptions,
+  ): Promise<void>;
+}
 
 export type ChannelMethodCall = (
   args?: MessageAux,
@@ -12,9 +25,16 @@ export type ChannelMethodCall = (
 export class Channel {
   constructor(
     private readonly channelCode: number,
-    private readonly service: DVTSecureSocketProxyService,
+    private readonly service: DTXServiceProvider,
   ) {}
 
+  /**
+   * Get the channel code
+   */
+  getCode(): number {
+    return this.channelCode;
+  }
+
   /**
    * Receive a plist response from the channel
    */
@@ -45,12 +65,10 @@ export class Channel {
   call(methodName: string): ChannelMethodCall {
     const selector = this.convertToSelector(methodName);
     return (async (args, expectsReply = true) => {
-      await this.service.sendMessage(
-        this.channelCode,
-        selector,
+      await this.service.sendMessage(this.channelCode, selector, {
         args,
         expectsReply,
-      );
+      });
     }) as ChannelMethodCall;
   }
 

src/services/ios/dvt/dtx-message.ts

@@ -42,12 +42,24 @@ export const DTX_CONSTANTS = {
 
   // Message types
   INSTRUMENTS_MESSAGE_TYPE: 2,
+  REPLY_TYPE: 3,
   EXPECTS_REPLY_MASK: 0x1000,
 
+  // Compression
+  COMPRESSION_MASK: 0xff000,
+  COMPRESSION_SHIFT: 12,
+
   // Auxiliary value types
   AUX_TYPE_OBJECT: 2,
   AUX_TYPE_INT32: 3,
   AUX_TYPE_INT64: 6,
+
+  // PrimitiveDictionary value types
+  PRIMITIVE_TYPE_STRING: 0x01,
+  PRIMITIVE_TYPE_BYTEARRAY: 0x02,
+  PRIMITIVE_TYPE_UINT32: 0x03,
+  PRIMITIVE_TYPE_INT64: 0x06,
+  PRIMITIVE_TYPE_NULL: 0x0a,
 } as const;
 
 /**

src/services/ios/dvt/index.ts

@@ -1,14 +1,17 @@
-import net from 'node:net';
+import type net from 'node:net';
 
 import { getLogger } from '../../../lib/logger.js';
 import {
   PlistUID,
   createBinaryPlist,
   parseBinaryPlist,
 } from '../../../lib/plist/index.js';
-import type { PlistDictionary } from '../../../lib/types.js';
+import type {
+  PlistDictionary,
+  SendMessageOptions,
+} from '../../../lib/types.js';
 import { ServiceConnection } from '../../../service-connection.js';
-import { BaseService, type Service } from '../base-service.js';
+import { BaseService, type Service, stripSSL } from '../base-service.js';
 import { ChannelFragmenter } from './channel-fragmenter.js';
 import { Channel } from './channel.js';
 import { DTXMessage, DTX_CONSTANTS, MessageAux } from './dtx-message.js';
@@ -68,11 +71,7 @@ export class DVTSecureSocketProxyService extends BaseService {
     // DVT uses DTX binary protocol, connect without plist-based RSDCheckin
     this.connection = await this.startLockdownWithoutCheckin(service);
     this.socket = this.connection.getSocket();
-
-    // Remove SSL context if present for raw DTX communication
-    if ('_sslobj' in this.socket) {
-      (this.socket as any)._sslobj = null;
-    }
+    stripSSL(this.socket);
 
     await this.performHandshake();
   }
@@ -105,7 +104,7 @@ export class DVTSecureSocketProxyService extends BaseService {
     args.appendInt(channelCode);
     args.appendObj(identifier);
 
-    await this.sendMessage(0, '_requestChannelWithCode:identifier:', args);
+    await this.sendMessage(0, '_requestChannelWithCode:identifier:', { args });
 
     const [ret] = await this.recvPlist();
 
@@ -123,15 +122,14 @@ export class DVTSecureSocketProxyService extends BaseService {
    * Send a DTX message on a channel
    * @param channel The channel code
    * @param selector The ObjectiveC method selector
-   * @param args Optional message arguments
-   * @param expectsReply Whether a reply is expected
+   * @param options Optional message options
    */
   async sendMessage(
     channel: number,
     selector: string | null = null,
-    args: MessageAux | null = null,
-    expectsReply: boolean = true,
+    options: SendMessageOptions = {},
   ): Promise<void> {
+    const { args = null, expectsReply = true } = options;
     if (!this.socket) {
       throw new Error('Not connected to DVT service');
     }
@@ -273,8 +271,7 @@ export class DVTSecureSocketProxyService extends BaseService {
         await this.sendMessage(
           DVTSecureSocketProxyService.BROADCAST_CHANNEL,
           '_channelCanceled:',
-          args,
-          false,
+          { args, expectsReply: false },
         );
       } catch (error) {
         log.debug('Error sending channel canceled message:', error);
@@ -302,7 +299,10 @@ export class DVTSecureSocketProxyService extends BaseService {
       'com.apple.private.DTXBlockCompression': 0,
       'com.apple.private.DTXConnection': 1,
     });
-    await this.sendMessage(0, '_notifyOfPublishedCapabilities:', args, false);
+    await this.sendMessage(0, '_notifyOfPublishedCapabilities:', {
+      args,
+      expectsReply: false,
+    });
 
     const [retData, aux] = await this.recvMessage();
     const ret = retData ? parseBinaryPlist(retData) : null;

src/services/ios/dvt/nskeyedarchiver-encoder.ts

@@ -8,9 +8,9 @@ const log = getLogger('NSKeyedArchiverEncoder');
  * capable of satisfying NSSecureCoding requirements.
  */
 export class NSKeyedArchiverEncoder {
-  private objects: any[] = ['$null'];
-  private objectCache = new Map<any, number>(); // Cache for object identity/deduplication
-  private classes = new Map<string, number>(); // Cache for class definitions
+  protected objects: any[] = ['$null'];
+  protected objectCache = new Map<any, number>(); // Cache for object identity/deduplication
+  protected classes = new Map<string, number>(); // Cache for class definitions
 
   /**
    * Encode the root value into NSKeyedArchiver format
@@ -26,7 +26,7 @@ export class NSKeyedArchiverEncoder {
     };
   }
 
-  private archiveObject(value: any): number {
+  protected archiveObject(value: any): number {
     if (value === null || value === undefined) {
       return 0; // $null is always at index 0
     }
@@ -75,7 +75,7 @@ export class NSKeyedArchiverEncoder {
     return index;
   }
 
-  private archiveArray(array: any[]): number {
+  protected archiveArray(array: any[]): number {
     const index = this.objects.length;
     this.objects.push(null); // Placeholder
     this.objectCache.set(array, index);
@@ -97,7 +97,7 @@ export class NSKeyedArchiverEncoder {
     return index;
   }
 
-  private archiveDictionary(dict: Record<string, any>): number {
+  protected archiveDictionary(dict: Record<string, any>): number {
     const index = this.objects.length;
     this.objects.push(null); // Placeholder
     this.objectCache.set(dict, index);
@@ -117,7 +117,7 @@ export class NSKeyedArchiverEncoder {
     return index;
   }
 
-  private archiveBuffer(buffer: Buffer): number {
+  protected archiveBuffer(buffer: Buffer): number {
     const index = this.objects.length;
     this.objects.push(null);
     this.objectCache.set(buffer, index);
@@ -132,7 +132,7 @@ export class NSKeyedArchiverEncoder {
     return index;
   }
 
-  private getClassUid(classname: string, ...superclasses: string[]): number {
+  protected getClassUid(classname: string, ...superclasses: string[]): number {
     if (this.classes.has(classname)) {
       return this.classes.get(classname)!;
     }