appium-ios-simulator

A Node.js API for controlling iOS simulators, used internally by Appium's XCUITest driver. It talks to CoreSimulator.framework directly through @appium/coresim, rather than shelling out to xcrun simctl, so most operations are faster and return typed, catchable errors instead of parsed CLI output.

With it you can:

• boot, shut down, erase, and otherwise manage the lifecycle of a simulator
• install, launch, terminate, and inspect apps
• grant, revoke, and query app permissions (contacts, camera, photos, and more)
• control biometrics, geolocation, the pasteboard, and keychain
• change UI settings (appearance, content size, contrast, localization, ...)
• rotate the device to a specific orientation, or read its current one
• capture screenshots, record the display to a file, or stream it as encoded H.264/HEVC or a live sequence of JPEG frames — optionally muxing/interleaving the device's own audio into the video paths (Xcode 26+)
• add media to the Photos library, and spawn guest processes
• look up Simulator-specific directories, apps, and settings on disk

Requirements

• macOS, with Xcode 15 or newer installed
• Node.js ^20.19.0 || ^22.12.0 || >=24.0.0

Installation

npm install appium-ios-simulator

Usage

The main entry point is getSimulator(udid), which returns a Simulator instance for an existing simulator (identified by its UDID, e.g. as reported by xcrun simctl list devices). To create a new device first, use @appium/coresim's NativeSimctl#createDevice().

import { getSimulator } from 'appium-ios-simulator';
import assert from 'node:assert/strict';

const sim = await getSimulator('DAE95172-0788-4A85-8D0D-5C85509109E1');
await sim.run();
assert.equal('Booted', (await sim.stat()).state);

await sim.installApp('/path/to/MyApp.app');
await sim.launchApp('com.example.MyApp');
await sim.setPermission('com.example.MyApp', 'photos', 'yes');

await sim.shutdown();
assert.equal('Shutdown', (await sim.stat()).state);

See lib/types.ts for the full Simulator API surface, and test/functional/simulator-e2e.spec.ts for more end-to-end examples of most of it in action.

getSimulator() also accepts a devicesSetPath option to target an isolated, non-default device set instead of the default one under ~/Library/Developer/CoreSimulator/Devices.

Pasteboard synchronization

sim.run({pasteboardAutomaticSync: 'off'}) disables synchronization with the macOS clipboard. On Xcode 27 and newer, this sets DeviceHub's Use Shared Clipboard preference for the selected simulator. Use on to enable synchronization or system to leave the existing preference unchanged.

DeviceHub caches these preferences. Close DeviceHub before starting sessions when changing this setting so its next launch reads the updated preferences. The library does not restart an already-running DeviceHub, which could disrupt other sessions. Disable synchronization on every simulator used for parallel clipboard tests.

Hardware keyboard

sim.run({connectHardwareKeyboard: true}) enables hardware keyboard simulation; false (the default) disables it. On Xcode 27 and newer, this sets DeviceHub's Simulate Hardware Keyboard preference via alwaysSimulateHardwareKeyboard. This is a global DeviceHub setting, shared by all devices and sessions. Parallel sessions must use the same value; different values per device are not supported. Close DeviceHub before starting sessions when changing this setting so its next launch reads the updated preference. The library does not restart DeviceHub automatically.

Xcode and iOS versions

Check the Xcode Wikipedia page for the mapping between Xcode and iOS versions. Only Xcode 15 and newer are supported.

Development

Check out the repository and run:

npm install
npm run dev # tsc --watch

npm run lint    # static analysis
npm run format  # code formatting

Use the following commands to run tests:

npm run test      # unit tests, no simulator required
npm run e2e-test  # functional tests against real simulators