Appium iOS Device API

Common errors

• Error: The current Node.js version (vX.Y.Z) is not supported. Please upgrade Node.js.

  cause Attempting to use the package with an incompatible Node.js version as specified in its `engines` field.
  fix Update your Node.js environment to version 20.19.0+, 22.12.0+, or 24.0.0+ using a tool like `nvm` (`nvm install 20 && nvm use 20`).

• No iOS devices found connected via USB.

  cause No physical iOS devices are connected, or the connected device is not recognized by `usbmuxd` (e.g., not trusted, locked, or usbmuxd service not running).
  fix Ensure the iOS device is connected via USB, unlocked, has 'trusted' the computer, and verify `usbmuxd` is running on your host system.

• Mismatched Xcode/iOS version or missing developer image.

  cause Attempting to use a service or feature (like XCUITest) that requires a developer image to be mounted on the device, but it's missing or incompatible.
  fix Ensure your Xcode version is compatible with the connected iOS device's OS. If not, manually download and mount the correct `DeveloperDiskImage.dmg` and `DeveloperDiskImage.dmg.signature` files.

Warnings

• breaking This package strictly requires Node.js versions ^20.19.0, ^22.12.0, or >=24.0.0. Older Node.js versions are not supported and will lead to installation or runtime failures.
  Fix: Upgrade your Node.js environment to a compatible version (e.g., using `nvm install 20` or `nvm install 22`).
• gotcha The module is primarily developed and tested on macOS with Xcode installed. While some features may work on other platforms, full functionality and stability are best achieved on a macOS host.
  Fix: For optimal experience and full feature set, use this module on a macOS host with a recent version of Xcode installed.
• gotcha Advanced services (e.g., `services.startSyslogService`, `Xctest` class) may require a mounted developer image on the iOS device, especially when using a higher iOS version with an older Xcode, or on non-macOS hosts.
  Fix: Manually download the appropriate DeveloperDiskImage.dmg for your iOS version from Apple Developer Downloads and mount it to the device, or ensure your Xcode version matches the iOS version.

Install

• npm install appium-ios-device npm
• yarn add appium-ios-device yarn
• pnpm add appium-ios-device pnpm

Imports

• utilities
  wrong:

  const utilities = require('appium-ios-device').utilities;

  correct:

  import { utilities } from 'appium-ios-device';

  The 'utilities' object provides general device information and control methods. This library is ESM-first for modern Node.js versions.
• services
  wrong:

  const services = require('appium-ios-device').services;

  correct:

  import { services } from 'appium-ios-device';

  The 'services' object exposes methods to start various iOS services like syslog or web inspector. This library prefers ESM imports.
• Xctest
  wrong:

  const { Xctest } = require('appium-ios-device');

  correct:

  import { Xctest } from 'appium-ios-device';

  The 'Xctest' class allows direct invocation of XCUITest bundles on iOS devices. Use named import for the class and prefer ESM.

Quickstart

Demonstrates how to discover and retrieve basic information for all currently connected iOS devices via USB.

import { utilities } from 'appium-ios-device';

async function getAndDisplayConnectedDevices() {
  console.log('Attempting to discover connected iOS devices...');
  try {
    const devices = await utilities.getConnectedDevices();

    if (devices.length === 0) {
      console.log('No iOS devices found connected via USB.');
      console.log('Please ensure your device is connected, unlocked, and trusted the computer.');
      return;
    }

    console.log(`Successfully found ${devices.length} iOS device(s):`);
    for (const udid of devices) {
      console.log(`\n  Device UDID: ${udid}`);
      const deviceInfo = await utilities.getDeviceInfo(udid);
      console.log(`  Name: ${deviceInfo.deviceName}`);
      console.log(`  iOS Version: ${deviceInfo.productVersion}`);
      console.log(`  Product Type: ${deviceInfo.productType}`);
      console.log(`  Build Version: ${deviceInfo.buildVersion}`);
      // More properties are available in deviceInfo object
      // e.g., deviceInfo.modelNumber, deviceInfo.serialNumber
    }
    console.log('\nDiscovery complete.');

  } catch (error) {
    console.error('Failed to communicate with iOS devices. Ensure usbmuxd is running and devices are connected.', error);
    console.error('Common issues: Older Node.js version, unmounted developer image (for advanced services).');
  }
}

getAndDisplayConnectedDevices();