node-simctl 8.0.9 → 8.1.0

package/lib/simctl.ts

@@ -0,0 +1,221 @@
+import _ from 'lodash';
+import which from 'which';
+import { log, LOG_PREFIX } from './logger';
+import {
+  DEFAULT_EXEC_TIMEOUT, getXcrunBinary,
+} from './helpers';
+import { exec as tpExec, SubProcess } from 'teen_process';
+import * as addmediaCommands from './subcommands/addmedia';
+import * as appinfoCommands from './subcommands/appinfo';
+import * as bootCommands from './subcommands/boot';
+import * as bootstatusCommands from './subcommands/bootstatus';
+import * as createCommands from './subcommands/create';
+import * as deleteCommands from './subcommands/delete';
+import * as eraseCommands from './subcommands/erase';
+import * as getappcontainerCommands from './subcommands/get_app_container';
+import * as installCommands from './subcommands/install';
+import * as ioCommands from './subcommands/io';
+import * as keychainCommands from './subcommands/keychain';
+import * as launchCommands from './subcommands/launch';
+import * as listCommands from './subcommands/list';
+import * as openurlCommands from './subcommands/openurl';
+import * as pbcopyCommands from './subcommands/pbcopy';
+import * as pbpasteCommands from './subcommands/pbpaste';
+import * as privacyCommands from './subcommands/privacy';
+import * as pushCommands from './subcommands/push';
+import * as envCommands from './subcommands/getenv';
+import * as shutdownCommands from './subcommands/shutdown';
+import * as spawnCommands from './subcommands/spawn';
+import * as terminateCommands from './subcommands/terminate';
+import * as uiCommands from './subcommands/ui';
+import * as uninstallCommands from './subcommands/uninstall';
+import * as locationCommands from './subcommands/location';
+import type {
+  XCRun, ExecOpts, SimctlOpts, ExecResult,
+} from './types';
+
+const SIMCTL_ENV_PREFIX = 'SIMCTL_CHILD_';
+
+export class Simctl {
+  private xcrun: XCRun;
+  private execTimeout: number;
+  private logErrors: boolean;
+  private _udid: string | null;
+  private _devicesSetPath: string | null;
+
+  constructor (opts: SimctlOpts = {}) {
+    this.xcrun = _.cloneDeep(opts.xcrun ?? { path: null });
+    this.execTimeout = opts.execTimeout ?? DEFAULT_EXEC_TIMEOUT;
+    this.logErrors = opts.logErrors ?? true;
+    this._udid = opts.udid ?? null;
+    this._devicesSetPath = opts.devicesSetPath ?? null;
+  }
+
+  set udid (value: string | null) {
+    this._udid = value;
+  }
+
+  get udid (): string | null {
+    return this._udid;
+  }
+
+  set devicesSetPath (value: string | null) {
+    this._devicesSetPath = value;
+  }
+
+  get devicesSetPath (): string | null {
+    return this._devicesSetPath;
+  }
+
+  /**
+   * @param commandName - Optional command name for error message
+   * @returns The UDID string
+   * @throws {Error} If UDID is not set
+   */
+  requireUdid (commandName: string | null = null): string {
+    if (!this.udid) {
+      throw new Error(`udid is required to be set for ` +
+        (commandName ? `the '${commandName}' command` : 'this simctl command'));
+    }
+    return this.udid;
+  }
+
+  /**
+   * @returns Promise resolving to the xcrun binary path
+   */
+  async requireXcrun (): Promise<string> {
+    const xcrunBinary = getXcrunBinary();
+
+    if (!this.xcrun.path) {
+      try {
+        this.xcrun.path = await which(xcrunBinary);
+      } catch {
+        throw new Error(`${xcrunBinary} tool has not been found in PATH. ` +
+          `Are Xcode developers tools installed?`);
+      }
+    }
+    if (!this.xcrun.path) {
+      throw new Error(`${xcrunBinary} tool path is not set`);
+    }
+    return this.xcrun.path;
+  }
+
+  /**
+   * Execute the particular simctl command.
+   *
+   * @param subcommand - One of available simctl subcommands.
+   * Execute `xcrun simctl` in Terminal to see the full list  of available subcommands.
+   * @param opts - Execution options
+   * @return Either the result of teen process's `exec` or
+   * `SubProcess` instance depending of `opts.asynchronous` value.
+   * @throws {Error} If the simctl subcommand command returns non-zero return code.
+   */
+  async exec<T extends ExecOpts> (
+    subcommand: string,
+    opts?: T
+  ): Promise<ExecResult<T>> {
+    const {
+      args: initialArgs = [],
+      env: initialEnv = {},
+      asynchronous = false,
+      encoding,
+      logErrors = true,
+      architectures,
+      timeout,
+    } = opts ?? {} as T;
+    // run a particular simctl command
+    const args = [
+      'simctl',
+      ...(this.devicesSetPath ? ['--set', this.devicesSetPath] : []),
+      subcommand,
+      ...initialArgs
+    ];
+    // Prefix all passed in environment variables with 'SIMCTL_CHILD_', simctl
+    // will then pass these to the child (spawned) process.
+    const env = _.defaults(
+      _.mapKeys(initialEnv,
+        (value, key) => _.startsWith(key, SIMCTL_ENV_PREFIX) ? key : `${SIMCTL_ENV_PREFIX}${key}`),
+      process.env
+    );
+
+    const execOpts: any = {
+      env,
+      encoding,
+    };
+    if (!asynchronous) {
+      execOpts.timeout = timeout || this.execTimeout;
+    }
+    const xcrun = await this.requireXcrun();
+    try {
+      let execArgs: [string, string[], any];
+      if (architectures?.length) {
+        const archArgs = _.flatMap(
+          (_.isArray(architectures) ? architectures : [architectures]).map((arch) => ['-arch', arch])
+        );
+        execArgs = ['arch', [...archArgs, xcrun, ...args], execOpts];
+      } else {
+        execArgs = [xcrun, args, execOpts];
+      }
+      // We know what we are doing here - the type system can't handle the dynamic nature
+      return (asynchronous ? new SubProcess(...execArgs) : await tpExec(...execArgs)) as ExecResult<T>;
+    } catch (e: any) {
+      if (!this.logErrors || !logErrors) {
+        // if we don't want to see the errors, just throw and allow the calling
+        // code do what it wants
+      } else if (e.stderr) {
+        const msg = `Error running '${subcommand}': ${e.stderr.trim()}`;
+        log.debug(LOG_PREFIX, msg);
+        e.message = msg;
+      } else {
+        log.debug(LOG_PREFIX, e.message);
+      }
+      throw e;
+    }
+  }
+
+  // Extension methods
+  addMedia = addmediaCommands.addMedia;
+  appInfo = appinfoCommands.appInfo;
+  bootDevice = bootCommands.bootDevice;
+  startBootMonitor = bootstatusCommands.startBootMonitor;
+  createDevice = createCommands.createDevice;
+  deleteDevice = deleteCommands.deleteDevice;
+  eraseDevice = eraseCommands.eraseDevice;
+  getAppContainer = getappcontainerCommands.getAppContainer;
+  getEnv = envCommands.getEnv;
+  installApp = installCommands.installApp;
+  getScreenshot = ioCommands.getScreenshot;
+  addRootCertificate = keychainCommands.addRootCertificate;
+  addCertificate = keychainCommands.addCertificate;
+  resetKeychain = keychainCommands.resetKeychain;
+  launchApp = launchCommands.launchApp;
+  getDevicesByParsing = listCommands.getDevicesByParsing;
+  getDevices = listCommands.getDevices;
+  getRuntimeForPlatformVersionViaJson = listCommands.getRuntimeForPlatformVersionViaJson;
+  getRuntimeForPlatformVersion = listCommands.getRuntimeForPlatformVersion;
+  getDeviceTypes = listCommands.getDeviceTypes;
+  list = listCommands.list;
+  setLocation = locationCommands.setLocation;
+  clearLocation = locationCommands.clearLocation;
+  openUrl = openurlCommands.openUrl;
+  setPasteboard = pbcopyCommands.setPasteboard;
+  getPasteboard = pbpasteCommands.getPasteboard;
+  grantPermission = privacyCommands.grantPermission;
+  revokePermission = privacyCommands.revokePermission;
+  resetPermission = privacyCommands.resetPermission;
+  pushNotification = pushCommands.pushNotification;
+  shutdownDevice = shutdownCommands.shutdownDevice;
+  spawnProcess = spawnCommands.spawnProcess;
+  spawnSubProcess = spawnCommands.spawnSubProcess;
+  terminateApp = terminateCommands.terminateApp;
+  getAppearance = uiCommands.getAppearance;
+  setAppearance = uiCommands.setAppearance;
+  getIncreaseContrast = uiCommands.getIncreaseContrast;
+  setIncreaseContrast = uiCommands.setIncreaseContrast;
+  getContentSize = uiCommands.getContentSize;
+  setContentSize = uiCommands.setContentSize;
+  removeApp = uninstallCommands.removeApp;
+}
+
+export default Simctl;
+

package/lib/subcommands/{addmedia.js → addmedia.ts}

@@ -1,21 +1,19 @@
-const commands = {};
+import type { Simctl } from '../simctl';
+import type { TeenProcessExecResult } from 'teen_process';
 
 /**
  * Add the particular media file to Simulator's library.
  * It is required that Simulator is in _booted_ state.
  *
- * @this {import('../simctl').Simctl}
- * @param {string} filePath - Full path to a media file on the local
+ * @param filePath - Full path to a media file on the local
  *                            file system.
- * @return {Promise<import('teen_process').TeenProcessExecResult>} Command execution result.
+ * @return Command execution result.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.addMedia = async function addMedia (filePath) {
+export async function addMedia (this: Simctl, filePath: string): Promise<TeenProcessExecResult<string>> {
   return await this.exec('addmedia', {
     args: [this.requireUdid('addmedia'), filePath],
   });
-};
-
-export default commands;
+}

package/lib/subcommands/appinfo.ts

@@ -0,0 +1,39 @@
+import type { Simctl } from '../simctl';
+import type { AppInfo } from '../types';
+import { convertPlistToJson } from '../helpers';
+import _ from 'lodash';
+
+/**
+ * Get information about an app installed on the simulator
+ *
+ * @param bundleId - Bundle identifier of the application
+ * @return App info object
+ * @throws {Error} If the app is not found
+ * @throws {Error} If the corresponding simctl subcommand command
+ *                 returns non-zero return code.
+ * @throws {Error} If the `udid` instance property is unset
+ */
+export async function appInfo (this: Simctl, bundleId: string): Promise<AppInfo> {
+  const {stdout} = await this.exec('appinfo', {
+    args: [this.requireUdid('appinfo'), bundleId],
+  });
+  let result: any;
+  try {
+    result = JSON.parse(stdout);
+  } catch {
+    // If JSON parsing fails, use plutil to convert plist-style output to JSON
+    try {
+      result = await convertPlistToJson(stdout);
+    } catch (err) {
+      throw new Error(
+        `Cannot retrieve app info for ${bundleId}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+
+  if (!_.isPlainObject(result) || !('ApplicationType' in result)) {
+    throw new Error(`App with bundle identifier "${bundleId}" not found. Is it installed?`);
+  }
+
+  return result as AppInfo;
+}

package/lib/subcommands/{boot.js → boot.ts}

@@ -1,28 +1,23 @@
 import _ from 'lodash';
-import log, { LOG_PREFIX } from '../logger';
-
-
-const commands = {};
+import { log, LOG_PREFIX } from '../logger';
+import type { Simctl } from '../simctl';
 
 /**
  * Boot the particular Simulator if it is not running.
  *
- * @this {import('../simctl').Simctl}
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.bootDevice = async function bootDevice () {
+export async function bootDevice (this: Simctl): Promise<void> {
   try {
     await this.exec('boot', {
       args: [this.requireUdid('boot')]
     });
-  } catch (e) {
+  } catch (e: any) {
     if (_.includes(e.message, 'Unable to boot device in current state: Booted')) {
       throw e;
     }
     log.debug(LOG_PREFIX, `Simulator already in 'Booted' state. Continuing`);
   }
-};
-
-export default commands;
+}

package/lib/subcommands/bootstatus.ts

@@ -0,0 +1,108 @@
+import { log } from '../logger';
+import { waitForCondition } from 'asyncbox';
+import _ from 'lodash';
+import type { Simctl } from '../simctl';
+import type { BootMonitorOptions } from '../types';
+import type { SubProcess } from 'teen_process';
+
+/**
+ * Start monitoring for boot status of the particular Simulator.
+ * If onFinished property is not set then the method will block
+ * until Simulator booting is completed.
+ * The method is only available since Xcode8.
+ *
+ * @param opts - Monitoring options.
+ * @returns The instance of the corresponding monitoring process.
+ * @throws {Error} If the Simulator fails to finish booting within the given timeout and onFinished
+ * property is not set.
+ * @throws {Error} If the `udid` instance property is unset
+ */
+export async function startBootMonitor (
+  this: Simctl,
+  opts: BootMonitorOptions = {}
+): Promise<SubProcess> {
+    const {
+      timeout = 240000,
+      onWaitingDataMigration,
+      onWaitingSystemApp,
+      onFinished,
+      onError,
+      shouldPreboot,
+    } = opts;
+    const udid = this.requireUdid('bootstatus');
+
+    const status: string[] = [];
+    let isBootingFinished = false;
+    let error: Error | null = null;
+    let timeoutHandler: NodeJS.Timeout | null = null;
+    const args = [udid];
+    if (shouldPreboot) {
+      args.push('-b');
+    }
+    const bootMonitor = await this.exec('bootstatus', {
+      args,
+      asynchronous: true,
+    });
+    const onStreamLine = (line: string) => {
+      status.push(line);
+      if (onWaitingDataMigration && line.includes('Waiting on Data Migration')) {
+        onWaitingDataMigration();
+      } else if (onWaitingSystemApp && line.includes('Waiting on System App')) {
+        onWaitingSystemApp();
+      }
+    };
+    for (const streamName of ['stdout', 'stderr']) {
+      bootMonitor.on(`line-${streamName}`, onStreamLine);
+    }
+    bootMonitor.once('exit', (code, signal) => {
+      if (timeoutHandler) {
+        clearTimeout(timeoutHandler);
+      }
+      if (code === 0) {
+        if (onFinished) {
+          onFinished();
+        }
+        isBootingFinished = true;
+      } else {
+        const errMessage = _.isEmpty(status)
+          ? `The simulator booting process has exited with code ${code} by signal ${signal}`
+          : status.join('\n');
+        error = new Error(errMessage);
+        if (onError) {
+          onError(error);
+        }
+      }
+    });
+    await bootMonitor.start(0);
+    const stopMonitor = async () => {
+      if (bootMonitor.isRunning) {
+        try {
+          await bootMonitor.stop();
+        } catch (e: any) {
+          log.warn(e.message);
+        }
+      }
+    };
+    const start = process.hrtime();
+    if (onFinished) {
+      timeoutHandler = setTimeout(stopMonitor, timeout);
+    } else {
+      try {
+        await waitForCondition(() => {
+          if (error) {
+            throw error;
+          }
+          return isBootingFinished;
+        }, {waitMs: timeout, intervalMs: 500});
+      } catch {
+        await stopMonitor();
+        const [seconds] = process.hrtime(start);
+        throw new Error(
+          `The simulator ${udid} has failed to finish booting after ${seconds}s. ` +
+          `Original status: ${status.join('\n')}`
+        );
+      }
+    }
+    return bootMonitor;
+}
+

package/lib/subcommands/{create.js → create.ts}

@@ -1,41 +1,38 @@
 import _ from 'lodash';
-import log, { LOG_PREFIX } from '../logger';
+import { log, LOG_PREFIX } from '../logger';
 import { retryInterval } from 'asyncbox';
 import { SIM_RUNTIME_NAME, normalizeVersion } from '../helpers';
-
+import type { Simctl } from '../simctl';
+import type { SimCreationOpts } from '../types';
 
 const SIM_RUNTIME_NAME_SUFFIX_IOS = 'iOS';
 const DEFAULT_CREATE_SIMULATOR_TIMEOUT = 10000;
 
-const commands = {};
-
-/**
- * @typedef {Object} SimCreationOpts
- * @property {string} [platform='iOS'] - Platform name in order to specify runtime such as 'iOS', 'tvOS', 'watchOS'
- * @property {number} [timeout=10000] - The maximum number of milliseconds to wait
- *                                      unit device creation is completed.
- */
-
 /**
  * Create Simulator device with given name for the particular
  * platform type and version.
  *
- * @this {import('../simctl').Simctl}
- * @param {string} name - The device name to be created.
- * @param {string} deviceTypeId - Device type, for example 'iPhone 6'.
- * @param {string} platformVersion - Platform version, for example '10.3'.
- * @param {SimCreationOpts} [opts={}] - Simulator options for creating devices.
- * @return {Promise<string>} The UDID of the newly created device.
+ * @param name - The device name to be created.
+ * @param deviceTypeId - Device type, for example 'iPhone 6'.
+ * @param platformVersion - Platform version, for example '10.3'.
+ * @param opts - Simulator options for creating devices.
+ * @return The UDID of the newly created device.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  */
-commands.createDevice = async function createDevice (name, deviceTypeId, platformVersion, opts = {}) {
+export async function createDevice (
+  this: Simctl,
+  name: string,
+  deviceTypeId: string,
+  platformVersion: string,
+  opts: SimCreationOpts = {}
+): Promise<string> {
   const {
     platform = SIM_RUNTIME_NAME_SUFFIX_IOS,
     timeout = DEFAULT_CREATE_SIMULATOR_TIMEOUT
   } = opts;
 
-  let runtimeIds = [];
+  const runtimeIds: string[] = [];
 
   // Try getting runtimeId using JSON flag
   try {
@@ -45,7 +42,7 @@ commands.createDevice = async function createDevice (name, deviceTypeId, platfor
   if (_.isEmpty(runtimeIds)) {
     // at first make sure that the runtime id is the right one
     // in some versions of Xcode it will be a patch version
-    let runtimeId;
+    let runtimeId: string;
     try {
       runtimeId = await this.getRuntimeForPlatformVersion(platformVersion, platform);
     } catch {
@@ -56,7 +53,7 @@ commands.createDevice = async function createDevice (name, deviceTypeId, platfor
     // get the possible runtimes, which will be iterated over
 
     // start with major-minor version
-    let potentialRuntimeIds = [normalizeVersion(runtimeId)];
+    const potentialRuntimeIds = [normalizeVersion(runtimeId)];
     if (runtimeId.split('.').length === 3) {
       // add patch version if it exists
       potentialRuntimeIds.push(runtimeId);
@@ -71,7 +68,7 @@ commands.createDevice = async function createDevice (name, deviceTypeId, platfor
   }
 
   // go through the runtime ids and try to create a simulator with each
-  let udid;
+  let udid: string | undefined;
   for (const runtimeId of runtimeIds) {
     log.debug(LOG_PREFIX,
       `Creating simulator with name '${name}', device type id '${deviceTypeId}' and runtime id '${runtimeId}'`);
@@ -95,17 +92,15 @@ commands.createDevice = async function createDevice (name, deviceTypeId, platfor
   // make sure that it gets out of the "Creating" state
   const retries = parseInt(`${timeout / 1000}`, 10);
   await retryInterval(retries, 1000, async () => {
-    const devices = _.values(await this.getDevices());
-    for (const deviceArr of _.values(devices)) {
-      for (const device of deviceArr) {
-        if (device.udid === udid) {
-          if (device.state === 'Creating') {
-            // need to retry
-            throw new Error(`Device with udid '${udid}' still being created`);
-          } else {
-            // stop looking, we're done
-            return;
-          }
+    const devices = _.flatMap(_.values(await this.getDevices()));
+    for (const device of devices) {
+      if (device.udid === udid) {
+        if (device.state === 'Creating') {
+          // need to retry
+          throw new Error(`Device with udid '${udid}' still being created`);
+        } else {
+          // stop looking, we're done
+          return;
         }
       }
     }
@@ -113,6 +108,5 @@ commands.createDevice = async function createDevice (name, deviceTypeId, platfor
   });
 
   return udid;
-};
+}
 
-export default commands;

package/lib/subcommands/{delete.js → delete.ts}

@@ -1,17 +1,15 @@
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Delete the particular Simulator from available devices list.
  *
- * @this {import('../simctl').Simctl}
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.deleteDevice = async function deleteDevice () {
+export async function deleteDevice (this: Simctl): Promise<void> {
   await this.exec('delete', {
     args: [this.requireUdid('delete')]
   });
-};
+}
 
-export default commands;

package/lib/subcommands/{erase.js → erase.ts}

@@ -1,19 +1,17 @@
 import { retryInterval } from 'asyncbox';
-
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Reset the content and settings of the particular Simulator.
  * It is required that Simulator is in _shutdown_ state.
  *
- * @this {import('../simctl').Simctl}
- * @param {number} [timeout=10000] - The maximum number of milliseconds to wait
+ * @param timeout - The maximum number of milliseconds to wait
  *                                   unit device reset is completed.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.eraseDevice = async function eraseDevice (timeout = 1000) {
+export async function eraseDevice (this: Simctl, timeout: number = 1000): Promise<void> {
   // retry erase with a sleep in between because it's flakey
   const retries = parseInt(`${timeout / 200}`, 10);
   await retryInterval(retries, 200,
@@ -21,6 +19,5 @@ commands.eraseDevice = async function eraseDevice (timeout = 1000) {
       args: [this.requireUdid('erase')]
     })
   );
-};
+}
 
-export default commands;

package/lib/subcommands/{get_app_container.js → get_app_container.ts}

@@ -1,4 +1,4 @@
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Get the full path to the particular application container
@@ -7,24 +7,26 @@ const commands = {};
  * like 'com.apple.springboard'.
  * It is required that Simulator is in _booted_ state.
  *
-* @this {import('../simctl').Simctl}
- * @param {string} bundleId - Bundle identifier of an application.
- * @param {string?} [containerType=null] - Which container type to return. Possible values
+ * @param bundleId - Bundle identifier of an application.
+ * @param containerType - Which container type to return. Possible values
  *                                  are 'app', 'data', 'groups', '<A specific App Group container>'.
  *                                  The default value is 'app'.
- * @return {Promise<string>} Full path to the given application container on the local
+ * @return Full path to the given application container on the local
  *                  file system.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.getAppContainer = async function getAppContainer (bundleId, containerType = null) {
+export async function getAppContainer (
+  this: Simctl,
+  bundleId: string,
+  containerType: string | null = null
+): Promise<string> {
   const args = [this.requireUdid('get_app_container'), bundleId];
   if (containerType) {
     args.push(containerType);
   }
   const {stdout} = await this.exec('get_app_container', {args});
   return (stdout || '').trim();
-};
+}
 
-export default commands;

package/lib/subcommands/{getenv.js → getenv.ts}

@@ -1,21 +1,19 @@
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Retrieves the value of a Simulator environment variable
  *
- * @this {import('../simctl').Simctl}
- * @param {string} varName - The name of the variable to be retrieved
- * @returns {Promise<string|null>} The value of the variable or null if the given variable
+ * @param varName - The name of the variable to be retrieved
+ * @returns The value of the variable or null if the given variable
  * is not present in the Simulator environment
  * @throws {Error} If there was an error while running the command
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.getEnv = async function getEnv (varName) {
+export async function getEnv (this: Simctl, varName: string): Promise<string | null> {
   const {stdout, stderr} = await this.exec('getenv', {
     args: [this.requireUdid('getenv'), varName],
     logErrors: false,
   });
   return stderr ? null : stdout;
-};
+}
 
-export default commands;