node-simctl

What is node-simctl?

The node-simctl package is a Node.js wrapper for simctl, a command-line utility used to control the iOS Simulator. It allows developers to manage iOS simulators programmatically, including creating, deleting, booting, and shutting down simulators, as well as installing and uninstalling apps.

What are node-simctl's main functionalities?

Create a new simulator

This feature allows you to create a new iOS simulator with a specified name, device type, and iOS version. The code sample demonstrates how to create an iPhone 8 simulator running iOS 13.3.

const simctl = require('node-simctl');

async function createSimulator() {
  const udid = await simctl.createDevice('My Simulator', 'iPhone 8', '13.3');
  console.log('Created simulator with UDID:', udid);
}

createSimulator();

Boot a simulator

This feature allows you to boot an existing iOS simulator using its UDID. The code sample demonstrates how to boot a simulator by providing its UDID.

const simctl = require('node-simctl');

async function bootSimulator(udid) {
  await simctl.bootDevice(udid);
  console.log('Booted simulator with UDID:', udid);
}

bootSimulator('your-simulator-udid');

Install an app on a simulator

This feature allows you to install an app on a specified iOS simulator. The code sample demonstrates how to install an app by providing the simulator's UDID and the path to the app.

const simctl = require('node-simctl');

async function installApp(udid, appPath) {
  await simctl.installApp(udid, appPath);
  console.log('Installed app on simulator with UDID:', udid);
}

installApp('your-simulator-udid', '/path/to/your/app.app');

Shutdown a simulator

This feature allows you to shut down an existing iOS simulator using its UDID. The code sample demonstrates how to shut down a simulator by providing its UDID.

const simctl = require('node-simctl');

async function shutdownSimulator(udid) {
  await simctl.shutdownDevice(udid);
  console.log('Shutdown simulator with UDID:', udid);
}

shutdownSimulator('your-simulator-udid');

Other packages similar to node-simctl

ios-sim

The ios-sim package is a command-line utility that launches an iOS application on the iOS Simulator. It provides functionalities to start the simulator, install apps, and launch apps. Compared to node-simctl, ios-sim is more focused on launching and managing apps on the simulator rather than managing the simulators themselves.

appium

Appium is an open-source tool for automating mobile applications. It supports iOS and Android platforms and allows you to write tests using various programming languages. While Appium provides broader functionality for mobile automation, including interacting with simulators, node-simctl is more specialized in managing iOS simulators.

detox

Detox is an end-to-end testing library for mobile apps. It supports both iOS and Android and allows you to write tests that run on simulators and real devices. Detox includes functionalities to manage simulators, but its primary focus is on testing and automation, whereas node-simctl is specifically designed for simulator management.

README

node-simctl

ES6/7 Node wrapper around Apple's simctl binary, the "Command line utility to control the iOS Simulator". simctl is run as a sub-command of xcrun

Installation

Install through npm.

npm install node-simctl

API

The module exports single class Simctl. This class contains methods which wrap the following simctl subcommands:

create (Create a new device)

• createDevice *

clone (Clone an existing device)

None

upgrade (Upgrade a device to a newer runtime)

None

delete (Delete specified devices, unavailable devices, or all devices)

• deleteDevice

pair (Create a new watch and phone pair)

None

unpair (Unpair a watch and phone pair)

None

pair_activate (Set a given pair as active)

None

erase (Erase a device's contents and settings)

• eraseDevice

boot (Boot a device)

• bootDevice

shutdown (Shutdown a device)

• shutdownDevice

rename (Rename a device)

None

getenv (Print an environment variable from a running device)

• getEnv

openurl (Open a URL in a device)

• openUrl

addmedia (Add photos, live photos, videos, or contacts to the library of a device)

• addMedia

install (Install an app on a device)

• installApp

uninstall (Uninstall an app from a device)

• uninstallApp

get_app_container (Print the path of the installed app's container)

• getAppContainer

launch (Launch an application by identifier on a device)

• launchApp

terminate (Terminate an application by identifier on a device)

• terminateApp

spawn (Spawn a process by executing a given executable on a device)

• spawnProcess
• spawnSubProcess

list (List available devices, device types, runtimes, or device pairs)

• getDevicesByParsing *
• getDevices *
• getRuntimeForPlatformVersionViaJson *
• getRuntimeForPlatformVersion *
• getDeviceTypes *
• list *

icloud_sync (Trigger iCloud sync on a device)

None

pbsync (Sync the pasteboard content from one pasteboard to another)

None

pbcopy (Copy standard input onto the device pasteboard)

• setPasteboard

pbpaste (Print the contents of the device's pasteboard to standard output)

• getPasteboard

help (Prints the usage for a given subcommand)

None

io (Set up a device IO operation)

• getScreeenshot

diagnose (Collect diagnostic information and logs)

None

logverbose (enable or disable verbose logging for a device)

None

status_bar (Set or clear status bar overrides)

None

ui (Get or Set UI options)

• getAppearance
• setAppearance

push (Send a simulated push notification)

• pushNotification

privacy (Grant, revoke, or reset privacy and permissions)

• grantPermission
• revokePermission
• resetPermission

keychain (Manipulate a device's keychain)

• addRootCertificate
• addCertificate
• resetKeychain

appinfo (Undocumented)

• appInfo

bootstatus (Undocumented)

• startBootMonitor

Methods marked with the star (*) character do not require the udid property to be set on the Simctl instance upon their invocation. All other methods will throw an error if the udid property is unset while they are being invoked.

All public methods are supplied with docstrings that describe their arguments and returned values.

The Simctl class constructor supports the following options:

• xcrun (Object): 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.
• execTimeout (number[600000]): The maximum number of milliseconds to wait for a single synchronous xcrun command.
• logErrors (boolean[true]): Whether to write xcrun error messages into the debug log before throwing them as errors.
• udid (string[null]): The unique identifier of the current device, which is going to be implicitly passed to all methods, which require it (see above). It can either be set upon instance creation if it is already known or later when/if needed via the corresponding setter.
• devicesSetPath (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. This option has a getter and a setter which allows to switch between multiple device sets during the Simctl instance life cycle.

Advanced Usage

Any simctl subcommand could be called via exec method, which accepts the subcommand itself as the first argument and the set of options, which may contain additional command args, environment variables, encoding, etc. For example:

import Simctl from 'node-simctl';

const simctl = new Simctl();
const name = 'My Device Name';
simctl.udid = await simctl.createDevice(name, 'iPhone X', '13.3');
await simctl.bootDevice();
await simctl.startBootMonitor({timeout: 120000});
await simctl.exec('pbsync');
console.log(`Pasteboard content: ${await simctl.getPasteboard()}`);
const {stdout} = await simctl.exec('status_bar', {
  args: [simctl.udid, 'list']
});
console.log(output);
simctl.udid = void(await simctl.deleteDevice());

See specs for examples of usage.

Running Multiple Simulator SDKs On a Single Computer

It is possible to run multiple simulators using different Xcode SDKs on a single machine. Simply set a proper value to DEVELOPER_DIR environment variable for each process.

Read this MacOps article for more details.

Changelog

7.1.14 (2023-05-02)

Miscellaneous Chores

• deps: bump rimraf from 4.4.1 to 5.0.0 (#178) (5c40d7d)