# @appium/coresim

> Native bindings to CoreSimulator.framework for Apple platform simulator control

Latest version **1.11.1** (published 2026-10-05) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @appium/coresim
pnpm add @appium/coresim
yarn add @appium/coresim
bun add @appium/coresim
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.11.1 |
| Published | 2026-10-05 |
| First published | 2026-09-16 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^20.19.0 \|\| ^22.12.0 \|\| >=24.0.0 |
| Dependencies | 4 |
| Unpacked size | 1.4 MB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 3 |
| Author | Appium Contributors |
| Maintainers | jlipps, nick.mokhnach, kazucocoa |

## Links

- npm: https://www.npmjs.com/package/@appium/coresim
- Repository: https://github.com/appium/appium-ios
- Homepage: https://github.com/appium/appium-ios#readme
- Issues: https://github.com/appium/appium-ios/issues
- npm.io page: https://npm.io/package/@appium/coresim

## Dependencies (4)

- [asyncbox](https://npm.io/package/asyncbox.md) ^6.4.3
- [node-addon-api](https://npm.io/package/node-addon-api.md) ^8.5.0
- [node-gyp-build](https://npm.io/package/node-gyp-build.md) ^4.8.4
- [@appium/support](https://npm.io/package/@appium/support.md) ^7.2.0

## Recent versions

- 1.11.1 (latest) — 2026-10-05
- 1.11.0 — 2026-10-03
- 1.10.2 — 2026-10-02
- 1.10.1 — 2026-09-30
- 1.10.0 — 2026-09-29
- 1.9.0 — 2026-09-27
- 1.8.0 — 2026-09-25
- 1.7.0 — 2026-09-23
- 1.6.0 — 2026-09-23
- 1.5.0 — 2026-09-22
- 1.4.0 — 2026-09-19
- 1.3.0 — 2026-09-19
- 1.2.1 — 2026-09-18
- 1.2.0 — 2026-09-17
- 1.1.1 — 2026-09-16
- … 3 more at https://npm.io/package/@appium/coresim/versions

## README

# @appium/coresim

Fast, native control of the iOS/tvOS/watchOS/visionOS Simulator from Node.js — no `simctl`
subprocess, no CLI output to parse.

## Why

Most tools drive the Simulator by shelling out to `simctl` and parsing its text output.
`@appium/coresim` talks to the same underlying system directly, in-process. That means:

- **Faster** — no process spawn per call.
- **More reliable** — real errors instead of scraped stderr strings.
- **Async by design** — every call returns a `Promise` and never blocks your app.

## Install

```sh
npm install @appium/coresim
```

Works on any platform to install, but simulator control requires **macOS**. On other platforms
(or when the Simulator isn't available), calls reject with a clear `NativeSimUnavailableError`
instead of crashing.

## Usage

```ts
import {NativeSimctl} from '@appium/coresim';

const sim = new NativeSimctl();

const devices = await sim.getDevices();
console.log(devices.map((d) => `${d.name} (${d.state})`));

const device = await sim.createDevice(
  'My Test Device',
  'com.apple.CoreSimulator.SimDeviceType.iPhone-15',
  'com.apple.CoreSimulator.SimRuntime.iOS-17-4',
);

await sim.bootDevice(device.udid);
await sim.waitForBoot(device.udid); // waits until the simulator is fully ready, not just "booted"

await sim.installApp(device.udid, '/path/to/MyApp.app');
await sim.launchApp(device.udid, 'com.example.MyApp');

await sim.shutdownDevice(device.udid);
await sim.deleteDevice(device.udid);
```

## What it can do

- **Devices** — list, create, delete, boot, shut down, and erase simulators; check real boot
  readiness with `getBootStatus()`/`waitForBoot()`.
- **Apps** — install, remove, launch, terminate, and inspect apps.
- **Processes** — spawn a process on the simulator and stream its stdout/stderr live.
- **Screen capture** — screenshots, video recording to a file, a real-time encoded video stream,
  and a real-time JPEG frame stream (`startJpegStream` — configurable fps/quality, no video codec
  involved, meant for callers building their own MJPEG stream out of the frame sequence) —
  optionally with the device's own audio, muxed into the recording or interleaved into the video
  stream (`audio: true` on `startVideoRecording`/`startVideoStream`). Audio capture requires:
  - **macOS 14.2+** on the host (Core Audio process taps).
  - The host's **"System Audio Recording Only"** privacy permission (System Settings > Privacy &
    Security > Screen & System Audio Recording). This can't be granted programmatically, and a
    denial isn't a thrown error — it silently produces an audio-less/near-silent track.
  - A default audio output device on the host, and a booted simulator that has produced audio at
    least once (e.g. a foreground app that plays sound) — an empty guest process set throws.
  - Uses a host-side Core Audio API, not anything iOS-version-specific, so it's expected to work
    on any simulator runtime; only Xcode 26.x has actually been exercised so far.

  On some CI/headless hosts, starting an audio capture can block for a while before failing —
  see [`CLAUDE.md`](./CLAUDE.md) for the known root cause and current workaround.
- **Simulator settings** — appearance (light/dark), accessibility (increase contrast, content
  size), location, and permissions.
- **Extras** — keychain certificates, push notifications, and Darwin notifications.

## Status

Early stage: core device and app lifecycle is implemented and tested; broader coverage is in
progress.

See [`CLAUDE.md`](./CLAUDE.md) for architecture details.

---
_Source: https://npm.io/package/@appium/coresim · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._