@appium/coresim 1.0.0

package/src/commands/media.ts

@@ -0,0 +1,38 @@
+import type {NativeSimctl} from '../native-simctl.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    addMedia(udid: string, filePaths: string[]): Promise<void>;
+    addPhoto(udid: string, filePath: string): Promise<void>;
+    addVideo(udid: string, filePath: string): Promise<void>;
+  }
+}
+
+/**
+ * Adds one or more photo/video files to the device's Photos library — the native equivalent of
+ * `simctl addmedia`. Each file's type is auto-detected; use {@link addPhoto}/{@link addVideo}
+ * instead when the file's kind is already known.
+ *
+ * @param udid — UDID of the target device
+ * @param filePaths — paths to the media files on the local filesystem
+ */
+export async function addMedia(this: NativeSimctl, udid: string, filePaths: string[]): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).addMedia(filePaths));
+}
+
+/**
+ * @param udid — UDID of the target device
+ * @param filePath — path to a photo file on the local filesystem
+ */
+export async function addPhoto(this: NativeSimctl, udid: string, filePath: string): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).addPhoto(filePath));
+}
+
+/**
+ * @param udid — UDID of the target device
+ * @param filePath — path to a video file on the local filesystem
+ */
+export async function addVideo(this: NativeSimctl, udid: string, filePath: string): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).addVideo(filePath));
+}

package/src/commands/misc.ts

@@ -0,0 +1,20 @@
+import type {NativeSimctl} from '../native-simctl.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    shake(udid: string): Promise<void>;
+  }
+}
+
+const SHAKE_NOTIFICATION_NAME = 'com.apple.UIKit.SimulatorShake';
+
+/**
+ * Simulates a shake gesture (e.g. to trigger "Shake to Undo" or a shake-triggered debug menu) —
+ * the same Darwin notification (see darwin-notification.ts) Simulator.app's own Device > Shake
+ * menu item posts.
+ *
+ * @param udid — UDID of the target device
+ */
+export async function shake(this: NativeSimctl, udid: string): Promise<void> {
+  await this.postDarwinNotification(udid, SHAKE_NOTIFICATION_NAME);
+}

package/src/commands/pasteboard.ts

@@ -0,0 +1,31 @@
+import type {NativeSimctl} from '../native-simctl.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    getPasteboard(udid: string): Promise<string>;
+    setPasteboard(udid: string, content: string): Promise<void>;
+  }
+}
+
+/**
+ * Reads the device's current pasteboard content — the native equivalent of `simctl pbpaste`
+ * (see native/sim_pasteboard.mm for which private CoreSimulator API this uses). Rejects with
+ * `NativeSimUnavailableError` if neither is present.
+ *
+ * @param udid — UDID of the device to read from; must be booted
+ * @returns the pasteboard's string content, or `""` if it holds no string-typed content
+ */
+export async function getPasteboard(this: NativeSimctl, udid: string): Promise<string> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).getPasteboard());
+}
+
+/**
+ * Sets the device's pasteboard content — the native equivalent of `simctl pbcopy`.
+ *
+ * @param udid — UDID of the target device; must be booted
+ * @param content — string content to set
+ */
+export async function setPasteboard(this: NativeSimctl, udid: string, content: string): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).setPasteboard(content));
+}

package/src/commands/permissions.ts

@@ -0,0 +1,122 @@
+import type {NativeSimctl} from '../native-simctl.js';
+import type {SimPermissionService, SimPermissionStatus} from '../types.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    grantPermission(udid: string, service: SimPermissionService, bundleId: string): Promise<void>;
+    revokePermission(udid: string, service: SimPermissionService, bundleId: string): Promise<void>;
+    resetPermission(udid: string, service: SimPermissionService, bundleId: string): Promise<void>;
+    getPermission(udid: string, service: SimPermissionService, bundleId: string): Promise<SimPermissionStatus>;
+  }
+}
+
+/**
+ * Grants a privacy permission to the given app on the given device, by writing directly to the
+ * simulator's own TCC (privacy) database — see CLAUDE.md for why this bypasses CoreSimulator's own
+ * privacy API.
+ *
+ * @param udid — UDID of the target device
+ * @param service — permission to grant, e.g. `"camera"`, `"contacts"`, `"photos"`
+ * @param bundleId — bundle identifier of the app the permission applies to
+ */
+export async function grantPermission(
+  this: NativeSimctl,
+  udid: string,
+  service: SimPermissionService,
+  bundleId: string,
+): Promise<void> {
+  return runCatchingAsync(async () => {
+    const tccIdentifier = toTCCIdentifier(service);
+    return (await this._findDevice(udid)).grantPermission(tccIdentifier, bundleId);
+  });
+}
+
+/**
+ * Revokes a previously granted privacy permission from the given app.
+ *
+ * @param udid — UDID of the target device
+ * @param service — permission to revoke (see {@link grantPermission})
+ * @param bundleId — bundle identifier of the app the permission applies to
+ */
+export async function revokePermission(
+  this: NativeSimctl,
+  udid: string,
+  service: SimPermissionService,
+  bundleId: string,
+): Promise<void> {
+  return runCatchingAsync(async () => {
+    const tccIdentifier = toTCCIdentifier(service);
+    return (await this._findDevice(udid)).revokePermission(tccIdentifier, bundleId);
+  });
+}
+
+/**
+ * Resets a privacy permission for the given app to its default (unprompted) state.
+ *
+ * @param udid — UDID of the target device
+ * @param service — permission to reset (see {@link grantPermission})
+ * @param bundleId — bundle identifier of the app the permission applies to
+ */
+export async function resetPermission(
+  this: NativeSimctl,
+  udid: string,
+  service: SimPermissionService,
+  bundleId: string,
+): Promise<void> {
+  return runCatchingAsync(async () => {
+    const tccIdentifier = toTCCIdentifier(service);
+    return (await this._findDevice(udid)).resetPermission(tccIdentifier, bundleId);
+  });
+}
+
+/**
+ * Reads a privacy permission's current status directly from the simulator's own TCC database —
+ * there's no CoreSimulator getter for this, only the setters {@link grantPermission}/
+ * {@link revokePermission}/{@link resetPermission} write to (see CLAUDE.md).
+ *
+ * @param udid — UDID of the device to read from
+ * @param service — permission to check (see {@link grantPermission})
+ * @param bundleId — bundle identifier of the app the permission applies to
+ * @returns `'unset'` if the app has never been prompted/decided for this permission
+ */
+export async function getPermission(
+  this: NativeSimctl,
+  udid: string,
+  service: SimPermissionService,
+  bundleId: string,
+): Promise<SimPermissionStatus> {
+  return runCatchingAsync(async () => {
+    const tccIdentifier = toTCCIdentifier(service);
+    return (await this._findDevice(udid)).getPermission(tccIdentifier, bundleId);
+  });
+}
+
+// Maps a friendly service name to the internal TCC service identifier its row in the simulator's
+// own TCC.db is keyed on (see native/tcc_privacy.h). `location` is deliberately absent: it isn't a
+// plain TCC row (CoreLocation simulation has its own subsystem), so it isn't supported by this
+// TCC.db-based implementation.
+const SERVICE_TO_TCC_IDENTIFIER: Record<SimPermissionService, string> = {
+  calendar: 'kTCCServiceCalendar',
+  camera: 'kTCCServiceCamera',
+  contacts: 'kTCCServiceAddressBook',
+  health: 'kTCCServiceMSO',
+  homekit: 'kTCCServiceWillow',
+  medialibrary: 'kTCCServiceMediaLibrary',
+  microphone: 'kTCCServiceMicrophone',
+  motion: 'kTCCServiceMotion',
+  photos: 'kTCCServicePhotos',
+  reminders: 'kTCCServiceReminders',
+  siri: 'kTCCServiceSiri',
+  speech: 'kTCCServiceSpeechRecognition',
+};
+
+function toTCCIdentifier(service: SimPermissionService): string {
+  const identifier = SERVICE_TO_TCC_IDENTIFIER[service];
+  if (!identifier) {
+    throw new Error(
+      `'${service}' is not a supported permission. Supported: ${Object.keys(SERVICE_TO_TCC_IDENTIFIER).join(', ')}`,
+    );
+  }
+  return identifier;
+}

package/src/commands/process.ts

@@ -0,0 +1,80 @@
+import {once} from 'node:events';
+
+import type {NativeSimctl} from '../native-simctl.js';
+import type {SimProcessInfo} from '../types.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    listProcesses(udid: string): Promise<SimProcessInfo[]>;
+  }
+}
+
+/**
+ * Lists currently-running processes/launchd jobs on the given (booted) device, by spawning
+ * `launchctl list` inside it and parsing its `PID / Status / Label` output. A `-` PID column
+ * (registered but not running) is dropped; an app process's `name` is its bundle identifier.
+ *
+ * @param udid — UDID of the device to inspect; must be booted
+ */
+export async function listProcesses(this: NativeSimctl, udid: string): Promise<SimProcessInfo[]> {
+  return runCatchingAsync(async () => {
+    const device = await this._findDevice(udid);
+    // The guest runtime ships its own launchctl, distinct from the host's /bin/launchctl (see
+    // CLAUDE.md) — spawn() takes a literal path, so resolve it via RuntimeRoot ourselves.
+    const launchctlPath = `${device.runtimeRootPath()}/bin/launchctl`;
+    const proc = await this.spawnProcess(udid, launchctlPath, {arguments: [launchctlPath, 'list']});
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (chunk: Buffer) => {
+      stdout += chunk;
+    });
+    proc.stderr.on('data', (chunk: Buffer) => {
+      stderr += chunk;
+    });
+    // stdout/stderr are plain net.Sockets over raw fds — an unhandled 'error' on either would
+    // crash the whole process, not just reject this promise, so race it in as a real rejection.
+    const streamError = Promise.race([once(proc.stdout, 'error'), once(proc.stderr, 'error')]).then(([err]) => {
+      throw err;
+    });
+    // 'exit' can fire before the stdout stream has finished delivering its buffered data (see
+    // spawnProcess's own integration test) — wait for both before parsing.
+    const [[code, signal]] = await Promise.race([
+      Promise.all([once(proc, 'exit'), once(proc.stdout, 'end')]),
+      streamError,
+    ]);
+    if (code !== 0) {
+      const reason = signal ? `signal ${signal}` : `exit code ${code}`;
+      throw new Error(`'launchctl list' failed with ${reason}${stderr.trim() ? `: ${stderr.trim()}` : ''}`);
+    }
+
+    const result: SimProcessInfo[] = [];
+    for (const line of stdout.split('\n')) {
+      const trimmedLine = line.trim();
+      if (!trimmedLine) {
+        continue;
+      }
+      const [pidText, , label] = trimmedLine.split(/\s+/);
+      const pid = Number.parseInt(pidText, 10);
+      if (!pid || !label) {
+        continue;
+      }
+      result.push({pid, group: extractGroup(label), name: extractName(label)});
+    }
+    return result;
+  });
+}
+
+function extractGroup(label: string): string | null {
+  const colonIdx = label.indexOf(':');
+  return colonIdx >= 0 ? label.slice(0, colonIdx) : null;
+}
+
+function extractName(label: string): string {
+  let name = label.includes(':') ? label.slice(label.indexOf(':') + 1) : label;
+  const bracketIdx = name.indexOf('[');
+  if (bracketIdx >= 0) {
+    name = name.slice(0, bracketIdx);
+  }
+  return name;
+}

package/src/commands/screenshot.ts

@@ -0,0 +1,46 @@
+import type {NativeSimctl} from '../native-simctl.js';
+import type {ScreenshotOptions, SimDisplayInfo} from '../types.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    getScreenshot(udid: string, options?: ScreenshotOptions): Promise<Buffer>;
+    getDisplays(udid: string): Promise<SimDisplayInfo[]>;
+  }
+}
+
+/**
+ * Captures a device display as an image — the native equivalent of `simctl io <udid> screenshot`
+ * (see native/sim_screenshot.mm for how this reads the framebuffer directly, with no temp file or
+ * subprocess). Rejects if the resolved display has no renderable surface yet (e.g. not booted), or
+ * if `options.displayId` doesn't match any display from {@link getDisplays}.
+ *
+ * @param udid — UDID of the device to capture; must be booted
+ * @param options — `format` (defaults to `'png'`), `displayId` (defaults to the primary display),
+ * and `quality` (JPEG only, 0-100 percent)
+ * @returns image data encoded as `options.format`
+ */
+export async function getScreenshot(
+  this: NativeSimctl,
+  udid: string,
+  options: ScreenshotOptions = {},
+): Promise<Buffer> {
+  if (
+    options.quality !== undefined &&
+    (!Number.isFinite(options.quality) || options.quality < 0 || options.quality > 100)
+  ) {
+    throw new RangeError(`quality must be a number between 0 and 100, got ${options.quality}`);
+  }
+  return runCatchingAsync(async () => (await this._findDevice(udid)).screenshot(options));
+}
+
+/**
+ * Lists the device's renderable displays — the same information `simctl io <udid> enumerate`
+ * reports for its own `--display` selection. Most devices report exactly one (the primary
+ * display); a device with a secondary display (e.g. tvOS's TVOut) reports more than one.
+ *
+ * @param udid — UDID of the device to inspect; must be booted
+ */
+export async function getDisplays(this: NativeSimctl, udid: string): Promise<SimDisplayInfo[]> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).getDisplays());
+}

package/src/commands/spawn.ts

@@ -0,0 +1,133 @@
+import {EventEmitter} from 'node:events';
+import {Socket} from 'node:net';
+import {constants as osConstants} from 'node:os';
+
+import type {NativeSimctl} from '../native-simctl.js';
+import type {SpawnOptions} from '../types.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    spawnProcess(udid: string, path: string, options?: SpawnOptions): Promise<SpawnedProcess>;
+  }
+}
+
+// Some signal numbers have more than one name (e.g. SIGABRT/SIGIOT are both 6) — built with a
+// for-of rather than Object.fromEntries so the *first* name Node lists for a number wins instead
+// of whichever happens to be last, which would otherwise make an aborted process unpredictably
+// report as the obscure historical alias (confirmed: this reversed Object.fromEntries reported a
+// real SIGABRT as 'SIGIOT').
+const SIGNAL_NAME_BY_NUMBER: Record<number, NodeJS.Signals> = {};
+for (const [name, num] of Object.entries(osConstants.signals)) {
+  SIGNAL_NAME_BY_NUMBER[num] ??= name as NodeJS.Signals;
+}
+
+interface SpawnedProcessEvents {
+  exit: [code: number | null, signal: NodeJS.Signals | null];
+}
+
+/**
+ * A process spawned on a simulator device via `NativeSimctl.spawnProcess`. The simulator shares
+ * the host kernel and filesystem, so `pid` is a real host OS process id — {@link kill} just calls
+ * Node's own `process.kill()`, no native call needed. `stdout`/`stderr` stream live output as the
+ * process runs; `'exit'` fires exactly once, with a decoded `(code, signal)` pair mirroring
+ * `child_process.ChildProcess`'s own semantics (exactly one of the two is non-null).
+ */
+export class SpawnedProcess extends EventEmitter<SpawnedProcessEvents> {
+  readonly stdout: Socket;
+  readonly stderr: Socket;
+  exitCode: number | null = null;
+  signalCode: NodeJS.Signals | null = null;
+
+  constructor(
+    readonly pid: number,
+    stdoutFd: number,
+    stderrFd: number,
+  ) {
+    super();
+    // `net.Socket` (not `fs.createReadStream`) deliberately: these fds are blocking NSPipe read
+    // ends, and fs's reads always run as blocking syscalls on the shared libuv threadpool (default
+    // size 4) regardless of the fd's actual type — a single quiet process's idle stdout+stderr
+    // reads permanently occupy 2 of those 4 workers until output or EOF arrives, and two quiet
+    // processes exhaust the pool entirely, stalling unrelated fs work *and* this addon's own
+    // AsyncWorkers (confirmed empirically: an unrelated fs.readFile took 8+ seconds instead of
+    // ~1ms while two quiet spawned processes' output was being read this way). A pipe fd is
+    // recognized by libuv as a named-pipe handle regardless of whether it's an anonymous pipe(2),
+    // so wrapping it in a Socket gets real event-driven (kqueue/epoll) I/O instead, exactly like
+    // Node's own child_process does for a child's stdio pipes.
+    this.stdout = new Socket({fd: stdoutFd, readable: true, writable: false});
+    this.stderr = new Socket({fd: stderrFd, readable: true, writable: false});
+  }
+
+  /** Whether the process has neither exited nor been killed yet. */
+  get running(): boolean {
+    return this.exitCode === null && this.signalCode === null;
+  }
+
+  /**
+   * Sends a signal to the process — a thin wrapper over `process.kill()`. A no-op returning
+   * `false` once exit has already been observed, rather than risking `process.kill()` throwing
+   * `ESRCH` on an already-reaped pid or, worse, hitting an unrelated process if the pid has since
+   * been recycled by the OS.
+   */
+  kill(signal: NodeJS.Signals | number = 'SIGTERM'): boolean {
+    if (!this.running) {
+      return false;
+    }
+    return process.kill(this.pid, signal);
+  }
+
+  /** @internal Invoked once by NativeSimctl when the native termination callback fires. */
+  _handleExit(code: number | null, signal: number | null): void {
+    this.exitCode = code;
+    this.signalCode = signal === null ? null : (SIGNAL_NAME_BY_NUMBER[signal] ?? null);
+    this.emit('exit', this.exitCode, this.signalCode);
+  }
+}
+
+/**
+ * Native equivalent of `simctl spawn`. Streams live stdout/stderr and eventually reports an
+ * exit code/signal — see {@link SpawnedProcess}.
+ *
+ * @param udid — UDID of the target device
+ * @param path — path to the executable to spawn; not auto-prepended to `options.arguments`
+ * @param options — see {@link SpawnOptions}
+ * @returns a handle to the spawned process
+ */
+export async function spawnProcess(
+  this: NativeSimctl,
+  udid: string,
+  path: string,
+  options: SpawnOptions = {},
+): Promise<SpawnedProcess> {
+  return runCatchingAsync(async () => {
+    const device = await this._findDevice(udid);
+    // The native termination callback (delivered via a ThreadSafeFunction/GCD path) and
+    // device.spawn()'s own promise resolution (an AsyncWorker completion) are independent async
+    // signals with no guaranteed relative order — a process that exits almost immediately can have
+    // its termination callback fire before the promise below resolves and `proc` exists. Buffer the
+    // exit args in that case and deliver them once the handle is constructed, rather than assuming
+    // the callback always arrives second.
+    let proc: SpawnedProcess | undefined;
+    let pendingExit: [code: number | null, signal: number | null] | undefined;
+    const {pid, stdoutFd, stderrFd} = await device.spawn(path, options, (code, signal) => {
+      if (proc) {
+        proc._handleExit(code, signal);
+      } else {
+        pendingExit = [code, signal];
+      }
+    });
+    proc = new SpawnedProcess(pid, stdoutFd, stderrFd);
+    if (pendingExit) {
+      // Delivering this synchronously would emit 'exit' before spawnProcess()'s own promise has
+      // even resolved — a caller doing `const proc = await sim.spawnProcess(...); proc.on('exit', ...)`
+      // would never see it, since its listener can't be attached until after that await returns.
+      // setImmediate defers past both promise-resolution microtasks and any synchronous listener
+      // setup that runs right after them, guaranteeing the listener is attached first.
+      const exitArgs = pendingExit;
+      const deliverTo = proc;
+      setImmediate(() => deliverTo._handleExit(...exitArgs));
+    }
+    return proc;
+  });
+}

package/src/commands/ui.ts

@@ -0,0 +1,61 @@
+import type {NativeSimctl} from '../native-simctl.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    getAppearance(udid: string): Promise<number>;
+    setAppearance(udid: string, style: number): Promise<void>;
+    getIncreaseContrast(udid: string): Promise<number>;
+    setIncreaseContrast(udid: string, enabled: boolean): Promise<void>;
+    getContentSize(udid: string): Promise<number>;
+    setContentSize(udid: string, category: number): Promise<void>;
+  }
+}
+
+/**
+ * @param udid — UDID of the device to read from
+ * @returns the device's current UI appearance style, as a raw `UIUserInterfaceStyle` value
+ */
+export async function getAppearance(this: NativeSimctl, udid: string): Promise<number> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).getUIAppearance());
+}
+
+/**
+ * @param udid — UDID of the target device
+ * @param style — a raw `UIUserInterfaceStyle` value to apply
+ */
+export async function setAppearance(this: NativeSimctl, udid: string, style: number): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).setUIAppearance(style));
+}
+
+/**
+ * @param udid — UDID of the device to read from
+ * @returns the device's current Increase Contrast accessibility setting
+ */
+export async function getIncreaseContrast(this: NativeSimctl, udid: string): Promise<number> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).getIncreaseContrast());
+}
+
+/**
+ * @param udid — UDID of the target device
+ * @param enabled — whether Increase Contrast should be enabled
+ */
+export async function setIncreaseContrast(this: NativeSimctl, udid: string, enabled: boolean): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).setIncreaseContrast(enabled));
+}
+
+/**
+ * @param udid — UDID of the device to read from
+ * @returns the device's current Dynamic Type content size category
+ */
+export async function getContentSize(this: NativeSimctl, udid: string): Promise<number> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).getContentSize());
+}
+
+/**
+ * @param udid — UDID of the target device
+ * @param category — the Dynamic Type content size category to apply
+ */
+export async function setContentSize(this: NativeSimctl, udid: string, category: number): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).setContentSize(category));
+}

package/src/commands/webinspector.ts

@@ -0,0 +1,23 @@
+import type {NativeSimctl} from '../native-simctl.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    getWebInspectorSocket(udid: string): Promise<string>;
+  }
+}
+
+/**
+ * Locates the Unix-domain socket a booted device's WebInspector service listens on, for WebKit
+ * remote-debugging tools to connect to directly.
+ *
+ * @example
+ * const socketPath = await sim.getWebInspectorSocket(udid);
+ * const socket = net.connect(socketPath); // speak the WebInspector wire protocol from here
+ *
+ * @param udid — UDID of the device to inspect; must be booted
+ * @returns the socket's filesystem path
+ */
+export async function getWebInspectorSocket(this: NativeSimctl, udid: string): Promise<string> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).getWebInspectorSocket());
+}