node-simctl 8.0.8 → 8.1.0

package/index.js

@@ -1,4 +0,0 @@
-import { Simctl } from './lib/simctl';
-
-export { Simctl };
-export default Simctl;

package/lib/helpers.js

@@ -1,37 +0,0 @@
-import * as semver from 'semver';
-
-export const DEFAULT_EXEC_TIMEOUT = 10 * 60 * 1000; // ms
-export const SIM_RUNTIME_NAME = 'com.apple.CoreSimulator.SimRuntime.';
-
-/**
- * "Normalize" the version, since iOS uses 'major.minor' but the runtimes can
- * be 'major.minor.patch'
- *
- * @param {string} version - the string version
- * @return {string} The version in 'major.minor' form
- * @throws {Error} If the version not parseable by the `semver` package
- */
-export function normalizeVersion (version) {
-  const semverVersion = semver.coerce(version);
-  if (!semverVersion) {
-    throw new Error(`Unable to parse version '${version}'`);
-  }
-  return `${semverVersion.major}.${semverVersion.minor}`;
-}
-
-/**
- * @returns {string}
- */
-export function getXcrunBinary () {
-  return process.env.XCRUN_BINARY || 'xcrun';
-}
-
-/**
- * Generate a UUID v4
- *
- * @returns {Promise<string>}
- */
-export async function uuidV4 () {
-  const uuidLib = await import('uuid');
-  return uuidLib.v4();
-}

package/lib/simctl.js

@@ -1,299 +0,0 @@
-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 addmediaCommands from './subcommands/addmedia';
-import appinfoCommands from './subcommands/appinfo';
-import bootCommands from './subcommands/boot';
-import bootstatusCommands from './subcommands/bootstatus';
-import createCommands from './subcommands/create';
-import deleteCommands from './subcommands/delete';
-import eraseCommands from './subcommands/erase';
-import getappcontainerCommands from './subcommands/get_app_container';
-import installCommands from './subcommands/install';
-import ioCommands from './subcommands/io';
-import keychainCommands from './subcommands/keychain';
-import launchCommands from './subcommands/launch';
-import listCommands from './subcommands/list';
-import openurlCommands from './subcommands/openurl';
-import pbcopyCommands from './subcommands/pbcopy';
-import pbpasteCommands from './subcommands/pbpaste';
-import privacyCommands from './subcommands/privacy';
-import pushCommands from './subcommands/push';
-import envCommands from './subcommands/getenv';
-import shutdownCommands from './subcommands/shutdown';
-import spawnCommands from './subcommands/spawn';
-import terminateCommands from './subcommands/terminate';
-import uiCommands from './subcommands/ui';
-import uninstallCommands from './subcommands/uninstall';
-import locationCommands from './subcommands/location';
-
-const SIMCTL_ENV_PREFIX = 'SIMCTL_CHILD_';
-const DEFAULT_OPTS = {
-  xcrun: {
-    path: null,
-  },
-  execTimeout: DEFAULT_EXEC_TIMEOUT,
-  logErrors: true,
-};
-
-/**
- * @typedef {Object} XCRun
- * @property {string?} path Full path to the xcrun script
- */
-
-/**
- * @typedef {{asynchronous: true}} TAsyncOpts
- */
-
-/**
- * @typedef {Object} ExecOpts
- * @property {string[]} [args=[]] - The list of additional subcommand arguments.
- * It's empty by default.
- * @property {Record<string, any>} [env={}] - Environment variables mapping. All these variables
- * will be passed Simulator and used in the executing function.
- * @property {boolean} [logErrors=true] - Set it to _false_ to throw execution errors
- * immediately without logging any additional information.
- * @property {boolean} [asynchronous=false] - Whether to execute the given command
- * 'synchronously' or 'asynchronously'. Affects the returned result of the function.
- * @property {string} [encoding] - Explicitly sets streams encoding for the executed
- * command input and outputs.
- * @property {string|string[]} [architectures] - One or more architecture names to be enforced while
- * executing xcrun. See https://github.com/appium/appium/issues/18966 for more details.
- * @property {number} [timeout] - The maximum number of milliseconds
- * to wait for single synchronous xcrun command. If not provided explicitly, then
- * the value of execTimeout property is used by default.
- */
-
-/**
- * @typedef {Object} SimctlOpts
- * @property {XCRun} [xcrun] - The xcrun properties. Currently only one property
- * is supported, which is `path` and it by default contains `null`, which enforces
- * the instance to automatically detect the full path to `xcrun` tool and to throw
- * an exception if it cannot be detected. If the path is set upon instance creation
- * then it is going to be used by `exec` and no autodetection will happen.
- * @property {number} [execTimeout=600000] - The default maximum number of milliseconds
- * to wait for single synchronous xcrun command.
- * @property {boolean} [logErrors=true] - Whether to wire xcrun error messages
- * into debug log before throwing them.
- * @property {string?} [udid] - The unique identifier of the current device, which is
- * going to be implicitly passed to all methods, which require it. It can either be set
- * upon instance creation if it is already known in advance or later when/if needed via the
- * corresponding instance setter.
- * @property {string?} [devicesSetPath] - Full path to the set of devices that you want to manage.
- * By default this path usually equals to ~/Library/Developer/CoreSimulator/Devices
- */
-
-
-class Simctl {
-  /** @type {XCRun} */
-  xcrun;
-
-  /** @type {number} */
-  execTimeout;
-
-  /** @type {boolean} */
-  logErrors;
-
-  /**
-   * @param {SimctlOpts} [opts={}]
-   */
-  constructor (opts = {}) {
-    opts = _.cloneDeep(opts);
-    _.defaultsDeep(opts, DEFAULT_OPTS);
-    for (const key of _.keys(DEFAULT_OPTS)) {
-      this[key] = opts[key];
-    }
-    /** @type {string?} */
-    this._udid = _.isNil(opts.udid) ? null : opts.udid;
-    /** @type {string?} */
-    this._devicesSetPath = _.isNil(opts.devicesSetPath) ? null : opts.devicesSetPath;
-  }
-
-  set udid (value) {
-    this._udid = value;
-  }
-
-  get udid () {
-    return this._udid;
-  }
-
-  set devicesSetPath (value) {
-    this._devicesSetPath = value;
-  }
-
-  get devicesSetPath () {
-    return this._devicesSetPath;
-  }
-
-  /**
-   * @param {string?} [commandName=null]
-   * @returns {string}
-   */
-  requireUdid (commandName = null) {
-    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<string>}
-   */
-  async requireXcrun () {
-    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?`);
-      }
-    }
-    return /** @type {string} */ (this.xcrun.path);
-  }
-
-  /**
-   * Execute the particular simctl command.
-   *
-   * @template {ExecOpts} TExecOpts
-   * @param {string} subcommand - One of available simctl subcommands.
-   * Execute `xcrun simctl` in Terminal to see the full list  of available subcommands.
-   * @param {TExecOpts} [opts]
-   * @return {Promise<TExecOpts extends TAsyncOpts ? import('teen_process').SubProcess : import('teen_process').TeenProcessExecResult>}
-   * 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 (subcommand, opts) {
-    let {
-      args = [],
-      env = {},
-      asynchronous = false,
-      encoding,
-      logErrors = true,
-      architectures,
-      timeout,
-    } = opts ?? {};
-    // run a particular simctl command
-    args = [
-      'simctl',
-      ...(this.devicesSetPath ? ['--set', this.devicesSetPath] : []),
-      subcommand,
-      ...args
-    ];
-    // Prefix all passed in environment variables with 'SIMCTL_CHILD_', simctl
-    // will then pass these to the child (spawned) process.
-    env = _.defaults(
-      _.mapKeys(env,
-        (value, key) => _.startsWith(key, SIMCTL_ENV_PREFIX) ? key : `${SIMCTL_ENV_PREFIX}${key}`),
-      process.env
-    );
-
-    const execOpts = {
-      env,
-      encoding,
-    };
-    if (!asynchronous) {
-      execOpts.timeout = timeout || this.execTimeout;
-    }
-    const xcrun = await this.requireXcrun();
-    try {
-      let execArgs = [xcrun, args, execOpts];
-      if (architectures?.length) {
-        const archArgs = _.flatMap(
-          (_.isArray(architectures) ? architectures : [architectures]).map((arch) => ['-arch', arch])
-        );
-        execArgs = ['arch', [...archArgs, xcrun, ...args], execOpts];
-      }
-      // @ts-ignore We know what we are doing here
-      return asynchronous ? new SubProcess(...execArgs) : await tpExec(...execArgs);
-    } catch (e) {
-      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;
-    }
-  }
-
-  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;
-export { Simctl };

package/lib/subcommands/appinfo.js

@@ -1,51 +0,0 @@
-const commands = {};
-
-/**
- * Invoke hidden appinfo subcommand to get the information
- * about applications installed on Simulator, including
- * system applications ({@link getAppContainer} does not "see" such apps).
- * Simulator server should be in 'booted' state for this call to work properly.
- * The tool is only available since Xcode SDK 8.1
- *
- * @this {import('../simctl').Simctl}
- * @param {string} bundleId - The bundle identifier of the target application.
- * @return {Promise<string>} The information about installed application.
- *
- * Example output for non-existing application container:
- * <pre>
- * {
- *   CFBundleIdentifier = "com.apple.MobileSafari";
- *   GroupContainers =     {
- *   };
- *   SBAppTags =     (
- *   );
- * }
- * </pre>
- *
- * Example output for an existing system application container:
- * <pre>
- * {
- *   ApplicationType = Hidden;
- *   Bundle = "file:///Applications/Xcode-beta.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/CoreSimulator/Profiles/Runtimes/iOS.simruntime/Contents/Resources/RuntimeRoot/System/Library/CoreServices/SpringBoard.app";
- *   CFBundleDisplayName = SpringBoard;
- *   CFBundleExecutable = SpringBoard;
- *   CFBundleIdentifier = "com.apple.springboard";
- *   CFBundleName = SpringBoard;
- *   CFBundleVersion = 50;
- *   GroupContainers =     {
- *   };
- *   Path = "/Applications/Xcode-beta.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/CoreSimulator/Profiles/Runtimes/iOS.simruntime/Contents/Resources/RuntimeRoot/System/Library/CoreServices/SpringBoard.app";
- *   SBAppTags =     (
- *   );
- * }
- * </pre>
- * @throws {Error} If the `udid` instance property is unset
- */
-commands.appInfo = async function appInfo (bundleId) {
-  const {stdout} = await this.exec('appinfo', {
-    args: [this.requireUdid('appinfo'), bundleId],
-  });
-  return (stdout || '').trim();
-};
-
-export default commands;

package/lib/subcommands/bootstatus.js

@@ -1,119 +0,0 @@
-import log from '../logger';
-import { waitForCondition } from 'asyncbox';
-import _ from 'lodash';
-
-const commands = {};
-
-/**
- * @typedef {Object} BootMonitorOptions
- * @property {number} [timeout=240000] - Simulator booting timeout in ms.
- * @property {Function} [onWaitingDataMigration] - This event is fired when data migration stage starts.
- * @property {Function} [onWaitingSystemApp] - This event is fired when system app wait stage starts.
- * @property {Function} [onFinished] - This event is fired when Simulator is fully booted.
- * @property {Function} [onError] - This event is fired when there was an error while monitoring the booting process
- * or when the timeout has expired.
- * @property {boolean} [shouldPreboot=false] Whether to preboot the Simulator
- * if this command is called and it is not already in booted or booting state.
- */
-
-/**
- * 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.
- *
- * @this {import('../simctl').Simctl}
- * @param {BootMonitorOptions} [opts={}] - Monitoring options.
- * @returns {Promise<import('teen_process').SubProcess>} 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
- */
-commands.startBootMonitor = async function startBootMonitor (opts = {}) {
-  const {
-    timeout = 240000,
-    onWaitingDataMigration,
-    onWaitingSystemApp,
-    onFinished,
-    onError,
-    shouldPreboot,
-  } = opts;
-  const udid = this.requireUdid('bootstatus');
-
-  /** @type {string[]} */
-  const status = [];
-  let isBootingFinished = false;
-  let error = null;
-  let timeoutHandler = null;
-  const args = [udid];
-  if (shouldPreboot) {
-    args.push('-b');
-  }
-  const bootMonitor = await this.exec('bootstatus', {
-    args,
-    asynchronous: true,
-  });
-  const onStreamLine = (/** @type {string} */ line) => {
-    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) {
-        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;
-};
-
-export default commands;