simctl - Xcode Simulator Utility Wrapper

Common errors

• TypeError: output.toString is not a function

  cause Attempting to call `toString()` on a `Buffer` object, but `simctl` v3.0.0+ now returns strings directly, not Buffers.
  fix Remove `.toString()` calls from the output of `simctl` methods, as the output is already a UTF-8 string.

• Error: Command failed: xcrun simctl ... Error Domain=NSPOSIXErrorDomain Code=2 "No such file or directory"

  cause `xcrun simctl` command failed, often due to an incorrect path, missing Xcode components, or an Xcode version older than the required 8+.
  fix Verify Xcode is installed and up-to-date (Xcode 8+). Ensure `xcode-select --install` has been run for command line tools. Check if `xcrun simctl` works from the terminal.

• TypeError: simctl.spawn is not a function or signature mismatch

  cause This error can occur if `spawn` is not correctly imported (e.g., using a default import instead of a named import) or if the arguments passed to `spawn` do not match its updated signature in `simctl` v3.0.0.
  fix Ensure `import { spawn } from 'simctl';` is used. Review the library's documentation for the correct `spawn` method signature in `simctl` v3.0.0+ and adjust your code accordingly.

Warnings

• breaking In `simctl` v3.0.0, all methods that call `spawnSync` now exclusively return UTF-8 encoded strings for `stdout`, `stderr`, and within `output`. Buffer output is no longer supported.
  Fix: Update any code relying on `Buffer` operations or raw binary data from `simctl` method outputs to handle string input directly. Parse string output as needed.
• breaking The `spawn` method signature was updated in `simctl` v3.0.0. Code using the old signature will break.
  Fix: Refer to the official documentation or source code for the correct `spawn` method signature and adjust calls accordingly.
• breaking Starting with `simctl` v2.0.0, the `start` behavior changed: the simulator is now re-used if it has already been started, instead of being killed and restarted each time. This impacts workflows expecting a fresh simulator instance.
  Fix: If a fresh simulator instance is required, explicitly use `shutdown` or `erase` commands before `start` to ensure the desired state, or adjust testing/development workflows to account for simulator re-use.
• gotcha `simctl` requires Xcode 8 or greater to be installed on macOS, and NodeJS 14.17.0 or greater.
  Fix: Ensure your development environment meets the minimum Xcode and Node.js version requirements. Upgrade Xcode via the Mac App Store or developer portal, and Node.js using `nvm` or a similar tool.

Install

• npm install simctl npm
• yarn add simctl yarn
• pnpm add simctl pnpm

Imports

• list
  wrong:

  const { list } = require('simctl');

  correct:

  import { list } from 'simctl';

  While CommonJS `require` might work in older Node.js environments, the library's evolution (Node.js >=14.17.0) indicates a preference for ESM. Use named import for `list`.
• spawn
  wrong:

  const { spawn } = require('simctl');

  correct:

  import { spawn } from 'simctl';

  `spawn` method signature changed significantly in v3.0.0, returning UTF-8 strings instead of Buffers. Ensure you are using the correct signature and handling string output.
• simctl
  wrong:

  import simctl from 'simctl';

  correct:

  import * as simctl from 'simctl';

  The library primarily exposes named exports for its functionalities. While you can import all as a namespace object, a default import is generally not provided or recommended for this module's structure.

Quickstart

This quickstart code demonstrates how to use the `list` function from `simctl` to asynchronously retrieve and display information about all available iOS Simulator devices, runtimes, and device types configured on the macOS system.

import { list } from 'simctl';

async function getSimulatorInfo() {
  console.log('Fetching available Simulators and runtimes...');
  try {
    const info = await list();
    console.log('Devices:');
    for (const runtimeId in info.devices) {
      console.log(`  Runtime: ${runtimeId}`);
      info.devices[runtimeId].forEach(device => {
        console.log(`    - ${device.name} (${device.udid}) - ${device.state}`);
      });
    }

    console.log('\nRuntimes:');
    info.runtimes.forEach(runtime => {
      console.log(`  - ${runtime.name} (${runtime.identifier})`);
    });

    console.log('\nDevice Types:');
    info.devicetypes.forEach(type => {
      console.log(`  - ${type.name} (${type.identifier})`);
    });

  } catch (error) {
    console.error('Failed to retrieve simulator info:', error);
    process.exit(1);
  }
}

getSimulatorInfo();