node-simctl 8.0.9 → 8.1.0

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

@@ -1,13 +1,12 @@
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Grants the given permission on the app with the given bundle identifier
  *
  * @since Xcode 11.4 SDK
- * @this {import('../simctl').Simctl}
- * @param {string} bundleId the identifier of the application whose
+ * @param bundleId the identifier of the application whose
  * privacy settings are going to be changed
- * @param {string} perm one of possible permission values:
+ * @param perm one of possible permission values:
  * - all: Apply the action to all services.
  * - calendar: Allow access to calendar.
  * - contacts-limited: Allow access to basic contact info.
@@ -25,48 +24,45 @@ const commands = {};
  * or there was an error while granting the permission
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.grantPermission = async function grantPermission (bundleId, perm) {
+export async function grantPermission (this: Simctl, bundleId: string, perm: string): Promise<void> {
   await this.exec('privacy', {
     args: [this.requireUdid('privacy grant'), 'grant', perm, bundleId],
   });
-};
+}
 
 /**
  * Revokes the given permission on the app with the given bundle identifier
  * after it has been granted
  *
  * @since Xcode 11.4 SDK
- * @this {import('../simctl').Simctl}
- * @param {string} bundleId the identifier of the application whose
+ * @param bundleId the identifier of the application whose
  * privacy settings are going to be changed
- * @param {string} perm one of possible permission values (see `grantPermission`)
+ * @param perm one of possible permission values (see `grantPermission`)
  * @throws {Error} if the current SDK version does not support the command
  * or there was an error while revoking the permission
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.revokePermission = async function revokePermission (bundleId, perm) {
+export async function revokePermission (this: Simctl, bundleId: string, perm: string): Promise<void> {
   await this.exec('privacy', {
     args: [this.requireUdid('privacy revoke'), 'revoke', perm, bundleId],
   });
-};
+}
 
 /**
  * Resets the given permission on the app with the given bundle identifier
  * to its default state
  *
  * @since Xcode 11.4 SDK
- * @this {import('../simctl').Simctl}
- * @param {string} bundleId the identifier of the application whose
+ * @param bundleId the identifier of the application whose
  * privacy settings are going to be changed
- * @param {string} perm one of possible permission values (see `grantPermission`)
+ * @param perm one of possible permission values (see `grantPermission`)
  * @throws {Error} if the current SDK version does not support the command
  * or there was an error while resetting the permission
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.resetPermission = async function resetPermission (bundleId, perm) {
+export async function resetPermission (this: Simctl, bundleId: string, perm: string): Promise<void> {
   await this.exec('privacy', {
     args: [this.requireUdid('private reset'), 'reset', perm, bundleId],
   });
-};
+}
 
-export default commands;

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

@@ -3,17 +3,15 @@ import { uuidV4 } from '../helpers';
 import path from 'path';
 import os from 'os';
 import fs from 'fs/promises';
-
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Send a simulated push notification
  *
  * @since Xcode 11.4 SDK
- * @this {import('../simctl').Simctl}
- * @param {Object} payload - The object that describes Apple push notification content.
+ * @param payload The object that describes Apple push notification content.
  * It must contain a top-level "Simulator Target Bundle" key with a string value matching
- * the target application‘s bundle identifier and "aps" key with valid Apple Push Notification values.
+ * the target application's bundle identifier and "aps" key with valid Apple Push Notification values.
  * For example:
  * {
  *   "Simulator Target Bundle": "com.apple.Preferences",
@@ -27,7 +25,7 @@ const commands = {};
  * or there was an error while pushing the notification
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.pushNotification = async function pushNotification (payload) {
+export async function pushNotification (this: Simctl, payload: Record<string, any>): Promise<void> {
   const dstPath = path.resolve(os.tmpdir(), `${await uuidV4()}.json`);
   try {
     await fs.writeFile(dstPath, JSON.stringify(payload), 'utf8');
@@ -37,6 +35,5 @@ commands.pushNotification = async function pushNotification (payload) {
   } finally {
     await rimraf(dstPath);
   }
-};
+}
 
-export default commands;

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

@@ -1,27 +1,24 @@
 import _ from 'lodash';
-import log, { LOG_PREFIX } from '../logger';
-
-const commands = {};
+import { log, LOG_PREFIX } from '../logger';
+import type { Simctl } from '../simctl';
 
 /**
  * Shutdown the given Simulator if it is 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.shutdownDevice = async function shutdownDevice () {
+export async function shutdownDevice (this: Simctl): Promise<void> {
   try {
     await this.exec('shutdown', {
       args: [this.requireUdid('shutdown')],
     });
-  } catch (e) {
+  } catch (e: any) {
     if (!_.includes(e.message, 'current state: Shutdown')) {
       throw e;
     }
     log.debug(LOG_PREFIX, `Simulator already in 'Shutdown' state. Continuing`);
   }
-};
+}
 
-export default commands;

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

@@ -1,21 +1,23 @@
 import _ from 'lodash';
-
-
-const commands = {};
+import type { Simctl } from '../simctl';
+import type { TeenProcessExecResult, SubProcess } from 'teen_process';
 
 /**
  * Spawn the particular process on Simulator.
  * It is required that Simulator is in _booted_ state.
  *
- * @this {import('../simctl').Simctl}
- * @param {string|string[]} args - Spawn arguments
- * @param {object} [env={}] - Additional environment variables mapping.
- * @return {Promise<import('teen_process').TeenProcessExecResult>} Command execution result.
+ * @param args - Spawn arguments
+ * @param env - Additional environment variables mapping.
+ * @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.spawnProcess = async function spawnProcess (args, env = {}) {
+export async function spawnProcess (
+  this: Simctl,
+  args: string | string[],
+  env: Record<string, any> = {}
+): Promise<TeenProcessExecResult<string>> {
   if (_.isEmpty(args)) {
     throw new Error('Spawn arguments are required');
   }
@@ -24,19 +26,22 @@ commands.spawnProcess = async function spawnProcess (args, env = {}) {
     args: [this.requireUdid('spawn'), ...(_.isArray(args) ? args : [args])],
     env,
   });
-};
+}
 
 /**
  * Prepare SubProcess instance for a new process, which is going to be spawned
  * on Simulator.
  *
- * @this {import('../simctl').Simctl}
- * @param {string|string[]} args - Spawn arguments
- * @param {object} [env={}] - Additional environment variables mapping.
- * @return {Promise<import('teen_process').SubProcess>} The instance of the process to be spawned.
+ * @param args - Spawn arguments
+ * @param env - Additional environment variables mapping.
+ * @return The instance of the process to be spawned.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.spawnSubProcess = async function spawnSubProcess (args, env = {}) {
+export async function spawnSubProcess (
+  this: Simctl,
+  args: string | string[],
+  env: Record<string, any> = {}
+): Promise<SubProcess> {
   if (_.isEmpty(args)) {
     throw new Error('Spawn arguments are required');
   }
@@ -45,7 +50,6 @@ commands.spawnSubProcess = async function spawnSubProcess (args, env = {}) {
     args: [this.requireUdid('spawn'), ...(_.isArray(args) ? args : [args])],
     env,
     asynchronous: true,
-  });
-};
+  }) as SubProcess;
+}
 
-export default commands;

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

@@ -1,20 +1,18 @@
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Terminate the given running application on Simulator.
  * It is required that Simulator is in _booted_ state.
  *
- * @this {import('../simctl').Simctl}
- * @param {string} bundleId - Bundle identifier of the application,
+ * @param bundleId - Bundle identifier of the application,
  *                            which is going to be terminated.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.terminateApp = async function terminateApp (bundleId) {
+export async function terminateApp (this: Simctl, bundleId: string): Promise<void> {
   await this.exec('terminate', {
     args: [this.requireUdid('terminate'), bundleId],
   });
-};
+}
 
-export default commands;

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

@@ -1,40 +1,36 @@
 import _ from 'lodash';
-
-
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Retrieves the current UI appearance value from the given simulator
  *
  * @since Xcode 11.4 SDK
- * @this {import('../simctl').Simctl}
- * @return {Promise<string>} the appearance value, for example 'light' or 'dark'
+ * @return the appearance value, for example 'light' or 'dark'
  * @throws {Error} if the current SDK version does not support the command
  * or there was an error while getting the value
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.getAppearance = async function getAppearance () {
+export async function getAppearance (this: Simctl): Promise<string> {
   const {stdout} = await this.exec('ui', {
     args: [this.requireUdid('ui'), 'appearance'],
   });
   return _.trim(stdout);
-};
+}
 
 /**
  * Sets the UI appearance to the given style
  *
  * @since Xcode 11.4 SDK
- * @this {import('../simctl').Simctl}
- * @param {string} appearance valid appearance value, for example 'light' or 'dark'
+ * @param appearance valid appearance value, for example 'light' or 'dark'
  * @throws {Error} if the current SDK version does not support the command
  * or there was an error while getting the value
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.setAppearance = async function setAppearance (appearance) {
+export async function setAppearance (this: Simctl, appearance: string): Promise<void> {
   await this.exec('ui', {
     args: [this.requireUdid('ui'), 'appearance', appearance],
   });
-};
+}
 
 /**
  * Retrieves the current increase contrast configuration value from the given simulator.
@@ -45,20 +41,19 @@ commands.setAppearance = async function setAppearance (appearance) {
  *   - unknown: The current setting is unknown or there was an error detecting it.
  *
  * @since Xcode 15 (but lower xcode could have this command)
- * @this {import('../simctl').Simctl}
- * @return {Promise<string>} the contrast configuration value.
+ * @return the contrast configuration value.
  *                           Possible return value is 'enabled', 'disabled',
  *                           'unsupported' or 'unknown' with Xcode 16.2.
  * @throws {Error} if the current SDK version does not support the command
  * or there was an error while getting the value.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.getIncreaseContrast = async function getIncreaseContrast () {
+export async function getIncreaseContrast (this: Simctl): Promise<string> {
   const {stdout} = await this.exec('ui', {
     args: [this.requireUdid('ui'), 'increase_contrast'],
   });
   return _.trim(stdout);
-};
+}
 
 /**
  * Sets the increase constrast configuration for the given simulator.
@@ -67,18 +62,17 @@ commands.getIncreaseContrast = async function getIncreaseContrast () {
  * in the caller side.
  *
  * @since Xcode 15 (but lower xcode could have this command)
- * @this {import('../simctl').Simctl}
- * @param {string} increaseContrast valid increase constrast configuration value.
+ * @param increaseContrast valid increase constrast configuration value.
  *                                  Acceptable value is 'enabled' or 'disabled' with Xcode 16.2.
  * @throws {Error} if the current SDK version does not support the command
  * or the given value was invalid for the command.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.setIncreaseContrast = async function setIncreaseContrast (increaseContrast) {
+export async function setIncreaseContrast (this: Simctl, increaseContrast: string): Promise<void> {
   await this.exec('ui', {
     args: [this.requireUdid('ui'), 'increase_contrast', increaseContrast],
   });
-};
+}
 
 /**
  * Retrieves the current content size value from the given simulator.
@@ -91,8 +85,7 @@ commands.setIncreaseContrast = async function setIncreaseContrast (increaseContr
  *   Other values: unknown, unsupported.
  *
  * @since Xcode 15 (but lower xcode could have this command)
- * @this {import('../simctl').Simctl}
- * @return {Promise<string>} the content size value. Possible return value is
+ * @return the content size value. Possible return value is
  *                           extra-small, small, medium, large, extra-large, extra-extra-large,
  *                           extra-extra-extra-large, accessibility-medium, accessibility-large,
  *                           accessibility-extra-large, accessibility-extra-extra-large,
@@ -102,12 +95,12 @@ commands.setIncreaseContrast = async function setIncreaseContrast (increaseContr
  * or there was an error while getting the value.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.getContentSize = async function getContentSize () {
+export async function getContentSize (this: Simctl): Promise<string> {
   const {stdout} = await this.exec('ui', {
     args: [this.requireUdid('ui'), 'content_size'],
   });
   return _.trim(stdout);
-};
+}
 
 /**
  * Sets content size for the given simulator.
@@ -122,8 +115,7 @@ commands.getContentSize = async function getContentSize () {
  * in the caller side.
  *
  * @since Xcode 15 (but lower xcode could have this command)
- * @this {import('../simctl').Simctl}
- * @param {string} contentSizeAction valid content size or action value. Acceptable value is
+ * @param contentSizeAction valid content size or action value. Acceptable value is
  *                                   extra-small, small, medium, large, extra-large, extra-extra-large,
  *                                   extra-extra-extra-large, accessibility-medium, accessibility-large,
  *                                   accessibility-extra-large, accessibility-extra-extra-large,
@@ -132,10 +124,9 @@ commands.getContentSize = async function getContentSize () {
  * or the given value was invalid for the command.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.setContentSize = async function setContentSize (contentSizeAction) {
+export async function setContentSize (this: Simctl, contentSizeAction: string): Promise<void> {
   await this.exec('ui', {
     args: [this.requireUdid('ui'), 'content_size', contentSizeAction],
   });
-};
+}
 
-export default commands;

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

@@ -1,21 +1,19 @@
-const commands = {};
+import type { Simctl } from '../simctl';
 
 /**
  * Remove the particular application package from Simulator.
  * It is required that Simulator is in _booted_ state and
  * the application with given bundle identifier is already installed.
  *
- * @this {import('../simctl').Simctl}
- * @param {string} bundleId - Bundle identifier of the application,
+ * @param bundleId - Bundle identifier of the application,
  *                            which is going to be removed.
  * @throws {Error} If the corresponding simctl subcommand command
  *                 returns non-zero return code.
  * @throws {Error} If the `udid` instance property is unset
  */
-commands.removeApp = async function removeApp (bundleId) {
+export async function removeApp (this: Simctl, bundleId: string): Promise<void> {
   await this.exec('uninstall', {
     args: [this.requireUdid('uninstall'), bundleId],
   });
-};
+}
 
-export default commands;

package/lib/types.ts

@@ -0,0 +1,243 @@
+import type { SubProcess, TeenProcessExecResult } from 'teen_process';
+
+/**
+ * XCRun configuration
+ */
+export interface XCRun {
+  /**
+   * Full path to the xcrun script
+   */
+  path: string | null;
+}
+
+/**
+ * Options for asynchronous execution
+ */
+export interface AsyncExecOpts {
+  asynchronous: true;
+}
+
+/**
+ * Execution options for simctl commands
+ */
+export interface ExecOpts {
+  /**
+   * The list of additional subcommand arguments.
+   * It's empty by default.
+   */
+  args?: string[];
+  /**
+   * Environment variables mapping. All these variables
+   * will be passed Simulator and used in the executing function.
+   */
+  env?: Record<string, any>;
+  /**
+   * Set it to _false_ to throw execution errors
+   * immediately without logging any additional information.
+   */
+  logErrors?: boolean;
+  /**
+   * Whether to execute the given command
+   * 'synchronously' or 'asynchronously'. Affects the returned result of the function.
+   */
+  asynchronous?: boolean;
+  /**
+   * Explicitly sets streams encoding for the executed
+   * command input and outputs.
+   */
+  encoding?: string;
+  /**
+   * One or more architecture names to be enforced while
+   * executing xcrun. See https://github.com/appium/appium/issues/18966 for more details.
+   */
+  architectures?: string | string[];
+  /**
+   * 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.
+   */
+  timeout?: number;
+}
+
+/**
+ * Simctl instance options
+ */
+export interface SimctlOpts {
+  /**
+   * 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.
+   */
+  xcrun?: XCRun;
+  /**
+   * The default maximum number of milliseconds
+   * to wait for single synchronous xcrun command.
+   */
+  execTimeout?: number;
+  /**
+   * Whether to wire xcrun error messages
+   * into debug log before throwing them.
+   */
+  logErrors?: boolean;
+  /**
+   * 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.
+   */
+  udid?: string | null;
+  /**
+   * Full path to the set of devices that you want to manage.
+   * By default this path usually equals to ~/Library/Developer/CoreSimulator/Devices
+   */
+  devicesSetPath?: string | null;
+}
+
+/**
+ * Device information
+ */
+export interface DeviceInfo {
+  /**
+   * The device name.
+   */
+  name: string;
+  /**
+   * The device UDID.
+   */
+  udid: string;
+  /**
+   * The current Simulator state, for example 'booted' or 'shutdown'.
+   */
+  state: string;
+  /**
+   * The SDK version, for example '10.3'.
+   */
+  sdk: string;
+  /**
+   * The platform name, for example 'iOS'.
+   */
+  platform: string;
+}
+
+/**
+ * Simulator creation options
+ */
+export interface SimCreationOpts {
+  /**
+   * Platform name in order to specify runtime such as 'iOS', 'tvOS', 'watchOS'
+   */
+  platform?: string;
+  /**
+   * The maximum number of milliseconds to wait
+   * unit device creation is completed.
+   */
+  timeout?: number;
+}
+
+/**
+ * Result type for exec method - either SubProcess for async or TeenProcessExecResult for sync
+ */
+export type ExecResult<T extends ExecOpts> = T extends AsyncExecOpts
+  ? SubProcess
+  : TeenProcessExecResult<string>;
+
+/**
+ * Boot monitor options
+ */
+export interface BootMonitorOptions {
+  /**
+   * Simulator booting timeout in ms.
+   */
+  timeout?: number;
+  /**
+   * This event is fired when data migration stage starts.
+   */
+  onWaitingDataMigration?: () => void;
+  /**
+   * This event is fired when system app wait stage starts.
+   */
+  onWaitingSystemApp?: () => void;
+  /**
+   * This event is fired when Simulator is fully booted.
+   */
+  onFinished?: () => void;
+  /**
+   * This event is fired when there was an error while monitoring the booting process
+   * or when the timeout has expired.
+   */
+  onError?: (error: Error) => void;
+  /**
+   * Whether to preboot the Simulator
+   * if this command is called and it is not already in booted or booting state.
+   */
+  shouldPreboot?: boolean;
+}
+
+/**
+ * Certificate options
+ */
+export interface CertOptions {
+  /**
+   * whether the `cert` argument
+   * is the path to the certificate on the local file system or
+   * a raw certificate content
+   */
+  raw?: boolean;
+}
+
+/**
+ * App information returned by simctl appinfo when the app is found
+ */
+export interface AppInfo {
+  /**
+   * Application type (e.g., "Hidden")
+   */
+  ApplicationType: string;
+  /**
+   * Bundle URL (file:// URL)
+   */
+  Bundle?: string;
+  /**
+   * Bundle container URL (file:// URL)
+   */
+  BundleContainer?: string;
+  /**
+   * Display name of the application
+   */
+  CFBundleDisplayName: string;
+  /**
+   * Executable name
+   */
+  CFBundleExecutable: string;
+  /**
+   * Bundle identifier
+   */
+  CFBundleIdentifier: string;
+  /**
+   * Bundle name
+   */
+  CFBundleName: string;
+  /**
+   * Bundle version
+   */
+  CFBundleVersion: string | number;
+  /**
+   * Data container URL (file:// URL)
+   */
+  DataContainer?: string;
+  /**
+   * Group containers dictionary
+   */
+  GroupContainers?: Record<string, any>;
+  /**
+   * Path to the app bundle
+   */
+  Path: string;
+  /**
+   * SpringBoard app tags
+   */
+  SBAppTags?: string[];
+}
+

package/package.json

@@ -6,7 +6,7 @@
     "ios",
     "simctl"
   ],
-  "version": "8.0.9",
+  "version": "8.1.0",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -26,7 +26,7 @@
     "lib": "./lib"
   },
   "files": [
-    "index.js",
+    "index.ts",
     "lib",
     "build/index.*",
     "build/lib",

package/index.js

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