Registry / testing / appium-ios-device

appium-ios-device

library3.1.11jsnpmunverified

appium-ios-device is a robust Node.js library providing a comprehensive API for advanced, low-level programmatic interaction with iOS devices. It acts as a direct, pure JavaScript/TypeScript rewrite of the `libimobiledevice` C library, enabling Appium and other tools to communicate with iPhones, iPads, and iPods over `usbmuxd` without relying on macOS-specific tools like Xcode for basic operations. This package facilitates a wide array of functionalities, including retrieving detailed device information (OS version, name, device time), establishing secure port connections, and managing various iOS services such as syslog monitoring, web inspector sessions, app installation proxying, and location simulation. A key differentiator is its `Xctest` class, which allows invoking pre-installed XCUITest applications on devices without needing a full Xcode environment on the host machine. Currently at version 3.1.11, the library undergoes active development with frequent patch and minor releases, reflecting ongoing maintenance and adaptation to new iOS versions and underlying dependencies. While primarily used and tested within the `appium-xcuitest-driver` on macOS, it offers partial functionality on other platforms, though full capabilities often necessitate specific developer image mounts or a macOS host with Xcode.

testing

npm install appium-ios-device

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · APPIUM-IOS-DEVICE

appium-ios-device

testingjavascriptv3.1.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

utilities

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

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

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

services

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

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

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

Xctest

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

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

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

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();

Debug

Known issues

breakingThis 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`).

affects: >=3.0.0

gotchaThe 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.

affects: >=3.0.0

gotchaAdvanced 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.

affects: >=3.0.0

Errors

Common errors & fixes

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

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.

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.

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.

Upgrade

Version history

3.1.11latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/appium/appium-ios-device ↗

packagehttps://www.npmjs.com/package/appium-ios-device ↗

homepagehttps://appium.io ↗