appium-ios-simulator 8.1.2 → 8.2.0

package/build/lib/utils/xcode.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDeveloperRoot = getDeveloperRoot;
+exports.getUiClientAppPath = getUiClientAppPath;
+exports.assertXcodeVersion = assertXcodeVersion;
+exports.readBundleIdFromPlist = readBundleIdFromPlist;
+const support_1 = require("@appium/support");
+const teen_process_1 = require("teen_process");
+const node_path_1 = __importDefault(require("node:path"));
+const constants_1 = require("./constants");
+/**
+ * @returns Promise that resolves to the developer root path.
+ */
+async function getDeveloperRoot() {
+    const { stdout } = await (0, teen_process_1.exec)('xcode-select', ['-p']);
+    return stdout.trim();
+}
+/**
+ * @param bundleId - The bundle identifier of the Simulator UI client.
+ * @param xcodeVersion - The active Xcode version.
+ * @returns The full path to the UI client app in the active Xcode installation.
+ * @throws {Error} If no matching app is found in the active Xcode folder.
+ */
+async function getUiClientAppPath(bundleId, xcodeVersion) {
+    const devRoot = await getDeveloperRoot();
+    const applicationsDir = xcodeVersion.major >= constants_1.MIN_DEVICE_HUB_XCODE_VERSION
+        ? node_path_1.default.resolve(devRoot, '..', 'Applications')
+        : node_path_1.default.resolve(devRoot, 'Applications');
+    if (await support_1.fs.exists(applicationsDir)) {
+        const appPaths = (await support_1.fs.readdir(applicationsDir))
+            .filter((entry) => entry.endsWith('.app'))
+            .map((entry) => node_path_1.default.resolve(applicationsDir, entry));
+        const apps = await Promise.all(appPaths.map(async (appPath) => ({
+            appPath,
+            bundleId: await readBundleIdFromPlist(node_path_1.default.resolve(appPath, 'Contents', 'Info.plist')),
+        })));
+        const match = apps.find((app) => app.bundleId === bundleId);
+        if (match) {
+            return match.appPath;
+        }
+    }
+    throw new Error(`Could not find UI client app with bundle id '${bundleId}' under '${applicationsDir}' ` +
+        `(active Xcode developer root: ${devRoot})`);
+}
+/**
+ * Asserts that the Xcode version meets the minimum supported version requirement.
+ *
+ * @template V - The Xcode version type.
+ * @param xcodeVersion - The Xcode version to check.
+ * @returns The same Xcode version if it meets the requirement.
+ * @throws {Error} If the Xcode version is below the minimum supported version.
+ */
+function assertXcodeVersion(xcodeVersion) {
+    if (xcodeVersion.major < constants_1.MIN_SUPPORTED_XCODE_VERSION) {
+        throw new Error(`Tried to use an iOS simulator with xcode version ${xcodeVersion.versionString} but only Xcode version ` +
+            `${constants_1.MIN_SUPPORTED_XCODE_VERSION} and up are supported`);
+    }
+    return xcodeVersion;
+}
+/**
+ * @param infoPlistPath - The full path to an Info.plist file.
+ * @returns The bundle identifier or null if it cannot be read.
+ */
+async function readBundleIdFromPlist(infoPlistPath) {
+    try {
+        const { stdout } = await (0, teen_process_1.exec)('/usr/libexec/PlistBuddy', [
+            '-c',
+            'print CFBundleIdentifier',
+            infoPlistPath,
+        ]);
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=xcode.js.map

package/build/lib/utils/xcode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xcode.js","sourceRoot":"","sources":["../../../lib/utils/xcode.ts"],"names":[],"mappings":";;;;;AASA,4CAGC;AAQD,gDA8BC;AAUD,gDAQC;AAMD,sDAWC;AArFD,6CAAmC;AACnC,+CAAkC;AAClC,0DAA6B;AAE7B,2CAAsF;AAEtF;;GAEG;AACI,KAAK,UAAU,gBAAgB;IACpC,MAAM,EAAC,MAAM,EAAC,GAAG,MAAM,IAAA,mBAAI,EAAC,cAAc,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACvB,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,kBAAkB,CACtC,QAAgB,EAChB,YAA0B;IAE1B,MAAM,OAAO,GAAG,MAAM,gBAAgB,EAAE,CAAC;IACzC,MAAM,eAAe,GACnB,YAAY,CAAC,KAAK,IAAI,wCAA4B;QAChD,CAAC,CAAC,mBAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,cAAc,CAAC;QAC7C,CAAC,CAAC,mBAAI,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IAE5C,IAAI,MAAM,YAAE,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,CAAC,MAAM,YAAE,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;aACjD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;aACzC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAI,CAAC,OAAO,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAC5B,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;YAC/B,OAAO;YACP,QAAQ,EAAE,MAAM,qBAAqB,CAAC,mBAAI,CAAC,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;SACvF,CAAC,CAAC,CACJ,CAAC;QACF,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;QAC5D,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,KAAK,CAAC,OAAO,CAAC;QACvB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,gDAAgD,QAAQ,YAAY,eAAe,IAAI;QACrF,iCAAiC,OAAO,GAAG,CAC9C,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAAyB,YAAe;IACxE,IAAI,YAAY,CAAC,KAAK,GAAG,uCAA2B,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CACb,oDAAoD,YAAY,CAAC,aAAa,0BAA0B;YACtG,GAAG,uCAA2B,uBAAuB,CACxD,CAAC;IACJ,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,qBAAqB,CAAC,aAAqB;IAC/D,IAAI,CAAC;QACH,MAAM,EAAC,MAAM,EAAC,GAAG,MAAM,IAAA,mBAAI,EAAC,yBAAyB,EAAE;YACrD,IAAI;YACJ,0BAA0B;YAC1B,aAAa;SACd,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/lib/extensions/applications.ts

@@ -1,7 +1,6 @@
 import path from 'node:path';
 import {fs, plist, util} from '@appium/support';
 import {waitForCondition} from 'asyncbox';
-import {isPlainObject} from '../utils';
 import type {CoreSimulator, InteractsWithApps, LaunchAppOptions} from '../types';
 
 type CoreSimulatorWithApps = CoreSimulator & InteractsWithApps;
@@ -47,10 +46,15 @@ export async function getUserInstalledBundleIdsByBundleName(
       })(),
     );
   }
-  const bundleInfos = (await Promise.all(bundleInfoPromises)).filter(isPlainObject);
+  const bundleInfos = (await Promise.all(bundleInfoPromises)).filter((info) =>
+    util.isPlainObject(info),
+  );
   const bundleIds = bundleInfos
-    .filter(({CFBundleName}) => CFBundleName === bundleName)
-    .map(({CFBundleIdentifier}) => CFBundleIdentifier);
+    .filter(
+      ({CFBundleName, CFBundleIdentifier}) =>
+        CFBundleName === bundleName && typeof CFBundleIdentifier === 'string',
+    )
+    .map(({CFBundleIdentifier}) => CFBundleIdentifier as string);
   if (bundleIds.length === 0) {
     return [];
   }

package/lib/extensions/biometric.ts

@@ -1,5 +1,5 @@
 import type {CoreSimulator, SupportsBiometric} from '../types';
-import {escapeRegExp} from '../utils';
+import {util} from '@appium/support';
 
 type CoreSimulatorWithBiometric = CoreSimulator & SupportsBiometric;
 
@@ -18,7 +18,7 @@ export async function isBiometricEnrolled(this: CoreSimulatorWithBiometric): Pro
     '-g',
     ENROLLMENT_NOTIFICATION_RECEIVER,
   ]);
-  const match = new RegExp(`${escapeRegExp(ENROLLMENT_NOTIFICATION_RECEIVER)}\\s+([01])`).exec(
+  const match = new RegExp(`${util.escapeRegExp(ENROLLMENT_NOTIFICATION_RECEIVER)}\\s+([01])`).exec(
     stdout,
   );
   if (!match) {

package/lib/extensions/keychain.ts

@@ -44,6 +44,7 @@ export async function backupKeychains(this: CoreSimulatorWithKeychain): Promise<
     throw new Error(
       `Cannot create keychains backup from '${this.keychainPath}'. ` +
         `Original error: ${err.stderr || err.stdout || err.message}`,
+      {cause: err},
     );
   }
   await resetBackupPath(dstPath);
@@ -75,12 +76,10 @@ export async function restoreKeychains(
     );
   }
 
-  let patterns: string[] = [];
-  if (typeof excludePatterns === 'string') {
-    patterns = excludePatterns.split(',').map((x) => x.trim());
-  } else {
-    patterns = excludePatterns;
-  }
+  const patterns =
+    typeof excludePatterns === 'string'
+      ? excludePatterns.split(',').map((x) => x.trim())
+      : excludePatterns;
   const isServerRunning = await this.isRunning();
   let plistPath: string | undefined;
   if (isServerRunning) {
@@ -111,6 +110,7 @@ export async function restoreKeychains(
       throw new Error(
         `Cannot restore keychains from '${backupPath}'. ` +
           `Original error: ${err.stderr || err.stdout || err.message}`,
+        {cause: err},
       );
     }
     await fs.unlink(backupPath);

package/lib/extensions/permissions.ts

@@ -128,6 +128,7 @@ async function execSQLiteQuery(
   } catch (err: any) {
     throw new Error(
       `Cannot execute SQLite query "${query}" to '${db}'. Original error: ${err.stderr}`,
+      {cause: err},
     );
   }
 }
@@ -155,6 +156,7 @@ async function execWix(this: CoreSimulatorWithAppPermissions, args: string[]): P
   } catch (e: any) {
     throw new Error(
       `Cannot execute "${WIX_SIM_UTILS} ${util.quote(args)}". Original error: ${e.stderr || e.message}`,
+      {cause: e},
     );
   }
 }

package/lib/extensions/settings.ts

@@ -1,9 +1,8 @@
-import {NSUserDefaults, generateDefaultsCommandArgs} from '../defaults-utils';
+import {NSUserDefaults, generateDefaultsCommandArgs} from '../utils';
 import path from 'node:path';
 import {exec} from 'teen_process';
 import AsyncLock from 'async-lock';
-import {fs} from '@appium/support';
-import {isPlainObject} from '../utils';
+import {fs, util} from '@appium/support';
 import type {
   CoreSimulator,
   HasSettings,
@@ -209,7 +208,7 @@ export async function configureLocalization(
   const {language, locale, keyboard} = opts;
   const globalPrefs: Record<string, any> = {};
   let keyboardId: string | null = null;
-  if (isPlainObject(keyboard)) {
+  if (util.isPlainObject(keyboard)) {
     const {name, layout, hardware} = keyboard;
     if (!name) {
       throw new Error(`The 'keyboard' field must have a valid name set`);
@@ -223,14 +222,14 @@ export async function configureLocalization(
     }
     globalPrefs.AppleKeyboards = [keyboardId];
   }
-  if (isPlainObject(language)) {
+  if (util.isPlainObject(language)) {
     const {name} = language;
     if (!name) {
       throw new Error(`The 'language' field must have a valid name set`);
     }
     globalPrefs.AppleLanguages = [name];
   }
-  if (isPlainObject(locale)) {
+  if (util.isPlainObject(locale)) {
     const {name, calendar} = locale;
     if (!name) {
       throw new Error(`The 'locale' field must have a valid name set`);
@@ -375,8 +374,8 @@ export async function updatePreferences(
         if (await fs.exists(plistPath)) {
           const currentPlistContent = await defaults.asJson();
           if (
-            isPlainObject(currentPlistContent.DevicePreferences) &&
-            isPlainObject(currentPlistContent.DevicePreferences[udidKey])
+            util.isPlainObject(currentPlistContent.DevicePreferences) &&
+            util.isPlainObject(currentPlistContent.DevicePreferences[udidKey])
           ) {
             existingDevicePrefs = currentPlistContent.DevicePreferences[udidKey];
           }

package/lib/simulator-xcode-14.ts

@@ -1,12 +1,16 @@
 import {fs, timing, util} from '@appium/support';
 import {waitForCondition, retryInterval} from 'asyncbox';
-import {getDeveloperRoot, SIMULATOR_APP_NAME} from './utils';
+import {
+  getDeveloperRoot,
+  getMacAppPidByBundleId,
+  getUiClientAppPath,
+  SIMULATOR_UI_CLIENT_BUNDLE_ID,
+} from './utils';
 import {exec} from 'teen_process';
 import {log as defaultLog} from './logger';
 import EventEmitter from 'node:events';
 import AsyncLock from 'async-lock';
 import path from 'node:path';
-import {getPath as getXcodePath} from 'appium-xcode';
 import {Simctl} from 'node-simctl';
 import * as appExtensions from './extensions/applications';
 import * as biometricExtensions from './extensions/biometric';
@@ -37,7 +41,6 @@ import type {AppiumLogger, StringRecord} from '@appium/types';
 
 const SIMULATOR_SHUTDOWN_TIMEOUT = 15 * 1000;
 const STARTUP_LOCK = new AsyncLock();
-const UI_CLIENT_BUNDLE_ID = 'com.apple.iphonesimulator';
 const STARTUP_TIMEOUT_MS = 120 * 1000;
 
 export class SimulatorXcode14
@@ -110,6 +113,7 @@ export class SimulatorXcode14
   private readonly _simctl: Simctl;
   private readonly _xcodeVersion: XcodeVersion;
   private readonly _log: AppiumLogger;
+  private _uiClientAppPath: Promise<string> | undefined;
 
   /**
    * Constructs the object with the `udid` and version of Xcode.
@@ -174,7 +178,7 @@ export class SimulatorXcode14
    * @returns The bundle identifier of the Simulator UI client.
    */
   get uiClientBundleId(): string {
-    return UI_CLIENT_BUNDLE_ID;
+    return SIMULATOR_UI_CLIENT_BUNDLE_ID;
   }
 
   /**
@@ -305,18 +309,11 @@ export class SimulatorXcode14
    * @returns The process ID or null if the UI client is not running.
    */
   async getUIClientPid(): Promise<string | null> {
-    let stdout: string;
-    try {
-      ({stdout} = await exec('pgrep', ['-fn', `${SIMULATOR_APP_NAME}/Contents/MacOS/`]));
-    } catch {
-      return null;
+    const pid = await getMacAppPidByBundleId(this.uiClientBundleId);
+    if (pid) {
+      this.log.debug(`Got UI client PID: ${pid}`);
     }
-    if (isNaN(parseInt(stdout, 10))) {
-      return null;
-    }
-    stdout = stdout.trim();
-    this.log.debug(`Got Simulator UI client PID: ${stdout}`);
-    return stdout;
+    return pid;
   }
 
   /**
@@ -456,16 +453,15 @@ export class SimulatorXcode14
       ...opts,
     };
 
-    const simulatorApp = path.resolve(await getXcodePath(), 'Applications', SIMULATOR_APP_NAME);
-    const args = ['-Fn', simulatorApp];
-    this.log.info(`Starting Simulator UI: ${util.quote(['open', ...args])}`);
+    const uiClientApp = await this._getUiClientAppPath();
+    const args = ['-Fn', uiClientApp];
+    this.log.info(`Starting UI client: ${util.quote(['open', ...args])}`);
     try {
       await exec('open', args, {timeout: startUiOpts.startupTimeout});
     } catch (err: any) {
       throw new Error(
-        `Got an unexpected error while opening Simulator UI: ` + err.stderr ||
-          err.stdout ||
-          err.message,
+        `Got an unexpected error while opening UI client: ${err.stderr || err.stdout || err.message}`,
+        {cause: err},
       );
     }
   }
@@ -580,7 +576,9 @@ export class SimulatorXcode14
       if (e.code === 1) {
         return false;
       }
-      throw new Error(`Cannot kill the Simulator UI client. Original error: ${e.message}`);
+      throw new Error(`Cannot kill the Simulator UI client. Original error: ${e.message}`, {
+        cause: e,
+      });
     }
   }
 
@@ -665,4 +663,11 @@ export class SimulatorXcode14
       'LaunchDaemons',
     );
   }
+
+  private async _getUiClientAppPath(): Promise<string> {
+    if (!this._uiClientAppPath) {
+      this._uiClientAppPath = getUiClientAppPath(this.uiClientBundleId, this.xcodeVersion);
+    }
+    return this._uiClientAppPath;
+  }
 }

package/lib/simulator-xcode-15.ts

@@ -1,6 +1,6 @@
 import {fs} from '@appium/support';
-import {exec} from 'teen_process';
 import path from 'node:path';
+import {readBundleIdFromPlist} from './utils';
 import {SimulatorXcode14} from './simulator-xcode-14';
 
 export class SimulatorXcode15 extends SimulatorXcode14 {
@@ -114,23 +114,12 @@ export class SimulatorXcode15 extends SimulatorXcode14 {
     }
 
     const appsRoot = path.resolve(await this._getSystemRoot(), 'Applications');
-    const fetchBundleId = async (appRoot: string): Promise<string | null> => {
-      const infoPlistPath = path.resolve(appRoot, 'Info.plist');
-      try {
-        const {stdout} = await exec('/usr/libexec/PlistBuddy', [
-          '-c',
-          'print CFBundleIdentifier',
-          infoPlistPath,
-        ]);
-        return stdout.trim();
-      } catch {
-        return null;
-      }
-    };
     const allApps = (await fs.readdir(appsRoot))
       .filter((x) => x.endsWith('.app'))
       .map((x) => path.join(appsRoot, x));
-    const bundleIds = await Promise.all(allApps.map(fetchBundleId));
+    const bundleIds = await Promise.all(
+      allApps.map((appRoot) => readBundleIdFromPlist(path.resolve(appRoot, 'Info.plist'))),
+    );
     this._systemAppBundleIds = new Set(bundleIds.filter((x): x is string => x !== null));
     return this._systemAppBundleIds;
   }

package/lib/simulator-xcode-27.ts

@@ -0,0 +1,9 @@
+import {DEVICE_HUB_UI_CLIENT_BUNDLE_ID} from './utils';
+import {SimulatorXcode15} from './simulator-xcode-15';
+
+export class SimulatorXcode27 extends SimulatorXcode15 {
+  /** @inheritdoc */
+  override get uiClientBundleId(): string {
+    return DEVICE_HUB_UI_CLIENT_BUNDLE_ID;
+  }
+}

package/lib/simulator.ts

@@ -1,6 +1,12 @@
 import {SimulatorXcode14} from './simulator-xcode-14';
 import {SimulatorXcode15} from './simulator-xcode-15';
-import {getSimulatorInfo, assertXcodeVersion, MIN_SUPPORTED_XCODE_VERSION} from './utils';
+import {SimulatorXcode27} from './simulator-xcode-27';
+import {
+  assertXcodeVersion,
+  getSimulatorInfo,
+  MIN_DEVICE_HUB_XCODE_VERSION,
+  MIN_SUPPORTED_XCODE_VERSION,
+} from './utils';
 import * as xcode from 'appium-xcode';
 import {log} from './logger';
 import type {Simulator, SimulatorLookupOptions} from './types';
@@ -38,15 +44,13 @@ export async function getSimulator(
   (logger ?? log).info(
     `Constructing ${platform} simulator for Xcode version ${xcodeVersion.versionString} with udid '${udid}'`,
   );
-  let SimClass: typeof SimulatorXcode14 | typeof SimulatorXcode15;
-  switch (xcodeVersion.major) {
-    case MIN_SUPPORTED_XCODE_VERSION:
-      SimClass = SimulatorXcode14;
-      break;
-    case 15:
-    default:
-      SimClass = SimulatorXcode15;
-      break;
+  let SimClass: typeof SimulatorXcode14 | typeof SimulatorXcode15 | typeof SimulatorXcode27;
+  if (xcodeVersion.major === MIN_SUPPORTED_XCODE_VERSION) {
+    SimClass = SimulatorXcode14;
+  } else if (xcodeVersion.major >= MIN_DEVICE_HUB_XCODE_VERSION) {
+    SimClass = SimulatorXcode27;
+  } else {
+    SimClass = SimulatorXcode15;
   }
 
   const result = new SimClass(udid, xcodeVersion, logger);

package/lib/utils/constants.ts

@@ -0,0 +1,6 @@
+export const SAFARI_STARTUP_TIMEOUT_MS = 25 * 1000;
+export const MOBILE_SAFARI_BUNDLE_ID = 'com.apple.mobilesafari';
+export const SIMULATOR_UI_CLIENT_BUNDLE_ID = 'com.apple.iphonesimulator';
+export const DEVICE_HUB_UI_CLIENT_BUNDLE_ID = 'com.apple.dt.Devices';
+export const MIN_SUPPORTED_XCODE_VERSION = 14;
+export const MIN_DEVICE_HUB_XCODE_VERSION = 27;

package/lib/{defaults-utils.ts → utils/defaults.ts}

@@ -1,7 +1,7 @@
 import {DOMParser, XMLSerializer, type Document, type Element} from '@xmldom/xmldom';
 import {exec} from 'teen_process';
-import {log} from './logger';
-import {isPlainObject} from './utils';
+import {log} from '../logger';
+import {util} from '@appium/support';
 
 export class NSUserDefaults {
   plist: string;
@@ -24,6 +24,7 @@ export class NSUserDefaults {
     } catch (e: any) {
       throw new Error(
         `'${this.plist}' cannot be converted to JSON. Original error: ${e.stderr || e.message}`,
+        {cause: e},
       );
     }
   }
@@ -40,7 +41,7 @@ export class NSUserDefaults {
    * @throws {Error} If there was an error while updating the plist
    */
   async update(valuesMap: Record<string, any>): Promise<void> {
-    if (!isPlainObject(valuesMap)) {
+    if (!util.isPlainObject(valuesMap)) {
       throw new TypeError(`plist values must be a map. '${valuesMap}' is given instead`);
     }
     if (Object.keys(valuesMap).length === 0) {
@@ -55,6 +56,7 @@ export class NSUserDefaults {
     } catch (e: any) {
       throw new Error(
         `Could not write defaults into '${this.plist}'. Original error: ${e.stderr || e.message}`,
+        {cause: e},
       );
     }
   }
@@ -75,7 +77,7 @@ export class NSUserDefaults {
 export function toXmlArg(value: any, serialize: boolean = true): string | Element {
   let xmlDoc: Document | null = null;
 
-  if (isPlainObject(value)) {
+  if (util.isPlainObject(value)) {
     xmlDoc = new DOMParser().parseFromString('<dict></dict>', 'text/xml');
     const documentElement = requireDocumentElement(xmlDoc);
     for (const [subKey, subValue] of Object.entries(value)) {
@@ -136,7 +138,7 @@ export function generateDefaultsCommandArgs(
   const resultArgs: string[][] = [];
   for (const [key, value] of Object.entries(valuesMap)) {
     try {
-      if (!replace && isPlainObject(value)) {
+      if (!replace && util.isPlainObject(value)) {
         const dictArgs = [key, '-dict-add'];
         for (const [subKey, subValue] of Object.entries(value)) {
           dictArgs.push(subKey, toXmlArg(subValue) as string);

package/lib/utils/devices.ts

@@ -0,0 +1,25 @@
+import type {SimulatorInfoOptions} from './types';
+import {getDevices} from './get-devices';
+
+/**
+ * @param udid - The simulator UDID.
+ * @param opts - Options including devicesSetPath.
+ * @returns Promise that resolves to simulator info or undefined if not found.
+ */
+export async function getSimulatorInfo(
+  udid: string,
+  opts: SimulatorInfoOptions = {},
+): Promise<any> {
+  const {devicesSetPath} = opts;
+  // see the README for github.com/appium/node-simctl for example output of getDevices()
+  const devices = Object.values(await getDevices({devicesSetPath})).flat();
+  return devices.find((sim: any) => sim.udid === udid);
+}
+
+/**
+ * @param udid - The simulator UDID.
+ * @returns Promise that resolves to true if simulator exists, false otherwise.
+ */
+export async function simExists(udid: string): Promise<boolean> {
+  return !!(await getSimulatorInfo(udid));
+}

package/lib/utils/get-devices.ts

@@ -0,0 +1,10 @@
+import {Simctl} from 'node-simctl';
+import type {StringRecord} from '@appium/types';
+
+/**
+ * @param simctlOpts - Optional simctl options
+ * @returns Promise that resolves to a record of devices grouped by SDK version
+ */
+export async function getDevices(simctlOpts?: StringRecord): Promise<Record<string, any[]>> {
+  return await new Simctl(simctlOpts).getDevices();
+}

package/lib/utils/index.ts

@@ -0,0 +1,20 @@
+export {
+  SAFARI_STARTUP_TIMEOUT_MS,
+  MOBILE_SAFARI_BUNDLE_ID,
+  SIMULATOR_UI_CLIENT_BUNDLE_ID,
+  DEVICE_HUB_UI_CLIENT_BUNDLE_ID,
+  MIN_SUPPORTED_XCODE_VERSION,
+  MIN_DEVICE_HUB_XCODE_VERSION,
+} from './constants';
+export type {SimulatorInfoOptions} from './types';
+export {NSUserDefaults, toXmlArg, generateDefaultsCommandArgs} from './defaults';
+export {getDevices} from './get-devices';
+export {getSimulatorInfo, simExists} from './devices';
+export {getMacAppPidByBundleId} from './process';
+export {
+  assertXcodeVersion,
+  getDeveloperRoot,
+  getUiClientAppPath,
+  readBundleIdFromPlist,
+} from './xcode';
+export {killAllSimulators} from './lifecycle';

package/lib/utils/lifecycle.ts

@@ -0,0 +1,78 @@
+import {log} from '../logger';
+import {exec, type ExecError} from 'teen_process';
+import {waitForCondition} from 'asyncbox';
+import {getVersion} from 'appium-xcode';
+import {
+  DEVICE_HUB_UI_CLIENT_BUNDLE_ID,
+  MIN_DEVICE_HUB_XCODE_VERSION,
+  SIMULATOR_UI_CLIENT_BUNDLE_ID,
+} from './constants';
+import {getDevices} from './get-devices';
+import {getMacAppPidByBundleId, killMacAppByBundleId} from './process';
+
+const DEFAULT_SIM_SHUTDOWN_TIMEOUT_MS = 60000;
+
+/**
+ * @param timeout - Timeout in milliseconds (default: DEFAULT_SIM_SHUTDOWN_TIMEOUT_MS).
+ * @returns Promise that resolves when all simulators are killed.
+ */
+export async function killAllSimulators(
+  timeout: number = DEFAULT_SIM_SHUTDOWN_TIMEOUT_MS,
+): Promise<void> {
+  log.debug('Killing all iOS Simulators');
+  const xcodeVersion = await getVersion(true);
+  const uiClientBundleId =
+    xcodeVersion.major >= MIN_DEVICE_HUB_XCODE_VERSION
+      ? DEVICE_HUB_UI_CLIENT_BUNDLE_ID
+      : SIMULATOR_UI_CLIENT_BUNDLE_ID;
+
+  const startedMs = performance.now();
+  try {
+    await exec('xcrun', ['simctl', 'shutdown', 'all'], {timeout});
+  } catch (err: unknown) {
+    log.debug(
+      `Failed to shutdown all simulators: ${(err as ExecError).stderr || (err as Error).message}`,
+    );
+  }
+
+  const uiClientPid = await getMacAppPidByBundleId(uiClientBundleId);
+  if (uiClientPid) {
+    log.debug(`Killing UI client '${uiClientBundleId}' (pid ${uiClientPid})`);
+    await killMacAppByBundleId(uiClientBundleId);
+  } else {
+    log.debug(`UI client '${uiClientBundleId}' is not running`);
+  }
+
+  try {
+    await waitForCondition(allSimsAreDown, {
+      waitMs: Math.max(1000, startedMs + timeout - performance.now()),
+      intervalMs: 200,
+    });
+  } catch (err) {
+    const remainingDevices = await getNonShutdownDeviceDescriptions();
+    const message =
+      remainingDevices.length > 0
+        ? `The following devices are still not in the correct state after ${timeout} ms:\n` +
+          remainingDevices.map((device) => `    ${device}`).join('\n')
+        : `Timed out after ${timeout} ms waiting for all simulators to shut down`;
+    throw new Error(message, {cause: err});
+  }
+}
+
+async function allSimsAreDown(): Promise<boolean> {
+  try {
+    return (await getNonShutdownDeviceDescriptions()).length === 0;
+  } catch {
+    return false;
+  }
+}
+
+async function getNonShutdownDeviceDescriptions(): Promise<string[]> {
+  const devices = Object.values(await getDevices()).flat();
+  return devices
+    .filter((sim) => !['shutdown', 'unavailable', 'disconnected'].includes(sim.state.toLowerCase()))
+    .map(
+      (sim) =>
+        `${sim.name} (${sim.sdk}, udid: ${sim.udid}) is still in state '${sim.state.toLowerCase()}'`,
+    );
+}

package/lib/utils/process.ts

@@ -0,0 +1,31 @@
+import {log} from '../logger';
+import {exec} from 'teen_process';
+
+/**
+ * @param bundleId - The bundle identifier of a running macOS application.
+ * @returns The process ID or null if the application is not running.
+ */
+export async function getMacAppPidByBundleId(bundleId: string): Promise<string | null> {
+  let stdout: string;
+  try {
+    ({stdout} = await exec('lsappinfo', ['info', '-only', 'pid', bundleId]));
+  } catch {
+    return null;
+  }
+  const match = stdout.trim().match(/"pid"=(\d+)/);
+  return match?.[1] ?? null;
+}
+
+/**
+ * @param bundleId - The bundle identifier of a running macOS application.
+ * @returns True if the kill command succeeded.
+ */
+export async function killMacAppByBundleId(bundleId: string): Promise<boolean> {
+  try {
+    await exec('lsappinfo', ['kill', '-hard', bundleId]);
+    return true;
+  } catch (e: any) {
+    log.debug(`Could not kill '${bundleId}' via lsappinfo: ${e.stderr || e.message}`);
+    return false;
+  }
+}

package/lib/utils/types.ts

@@ -0,0 +1,3 @@
+export interface SimulatorInfoOptions {
+  devicesSetPath?: string | null;
+}