appium-ios-device
Advanced tools
The appium-ios-device npm package provides a set of utilities for interacting with iOS devices. It is primarily used in the context of Appium, a popular automation framework for mobile applications, to facilitate communication with iOS devices for tasks such as file management, process control, and device information retrieval.
File Management
This feature allows you to manage files on the iOS device. The code sample demonstrates how to list files in the Documents directory of a specific app on the device.
const { services } = require('appium-ios-device');
(async () => {
const udid = 'your-device-udid';
const service = await services.startHouseArrestService(udid, 'your-app-bundle-id');
const files = await service.listDirectory('/Documents');
console.log(files);
})();Process Control
This feature allows you to control and monitor processes running on the iOS device. The code sample shows how to list all running processes on the device.
const { services } = require('appium-ios-device');
(async () => {
const udid = 'your-device-udid';
const service = await services.startLockdownService(udid);
const processes = await service.listProcesses();
console.log(processes);
})();Device Information
This feature allows you to retrieve various pieces of information about the iOS device. The code sample demonstrates how to get the iOS version of the device.
const { services } = require('appium-ios-device');
(async () => {
const udid = 'your-device-udid';
const service = await services.startLockdownService(udid);
const info = await service.getValue('ProductVersion');
console.log(info);
})();The node-ios-device package provides similar functionalities for interacting with iOS devices, such as listing connected devices and retrieving device information. However, it is more focused on basic device management and lacks some of the advanced features provided by appium-ios-device, such as file management and process control.
The ios-deploy package is primarily used for deploying iOS apps to devices from the command line. While it offers some device interaction capabilities, its main focus is on app deployment rather than the broader range of device management features provided by appium-ios-device.
Appium API for dealing with iOS devices. This is mainly a rewrite of libimobiledevice in Node.js. The APIs allow Appium to talk directly to the phone over usbmuxd.
More information can be found at the links below:
Note This module is used and tested by appium-xcuitest-driver, which expects macOS as the host paltform with Xcode. Some features may only work partially on other platforms.
This module should be used over the utilities and services modules or exported classes in documents due to the complexity of iOS communication. When a new services is implemented, it should be added and made available over the services module.
utilities.getConnectedDevicesutilities.getOSVersionutilities.getDeviceTimeutilities.getDeviceNameutilities.getDeviceInfoutilities.startLockdownSessionutilities.connectPortutilities.connectPortSSLutilities.fetchImageFromGithubReposervices.startSyslogServiceservices.startWebInspectorServiceservices.startInstallationProxyServiceservices.startSimulateLocationServiceservices.startAfcServiceservices.startNotificationProxyServiceservices.startHouseArrestServiceservices.startInstrumentServiceservices.startTestmanagerdServiceservices.startMCInstallServiceservices.startImageMounterServiceXctest
new Xctest(udid, xctestBundleId, targetBundleId, opts)
udid - string Device udid.xctestBundleId - string - Bundle Id of xctest app on device. The app must be installed on device.targetBundleId - string - Test target bundle id. null by default.opts - optional addition options to specific XCTestConfiguration and app launch env.
conf - properties to override in XCTestConfiguration.
productModuleName - string | nulltargetApplicationArguments - string[] | nulltestsToRun - string[] | nulltestsToSkip - string[] | nullenv - object - key-value pairs to append in xctest app environmentxctest.start()
stop() method has not been called, calling this again would return directly.xctest.stop()
When using a higher version of iOS devices with a lower version of Xcode or other non-macOS operating systems, most of the functions in services or Xctest may not be available because the developer image is not mounted. Sometimes it can be solved automatically by opening Xcode and waiting for a while. But more often you need to manually download and mount the developer image as follows：
(New Xcode.app)/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport. A DeveloperDiskImage.dmg and a DeveloperDiskImage.dmg.signature should be inside that folder.(Old Xcode.app)/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport.(Xcode.app)/Contents/Developer/Platforms/AppleTVOS.platform/DeviceSupport.ideviceimagemounter binary file compiled by libimobiledevice project on your operating system.These operations are very cumbersome. Fortunately there are many repositories of these developer images in the open source community. The folders mentioned in the above process are zipped and uploaded into open source repositories according to different versions. You can also make your own mirror repository on GitHub in a similar way. With services.startImageMounterService and utilities.fetchImageFromGithubRepo, you can automate the whole process cross-platform.
As an example, assuming we are using a repo from https://github/example/iOSDeviceSupport. All the .zip files are inside DeviceSupportFiles/iOS folder of root. We can check the mount status, download and mount the image using following code:
import { services, utilities } from 'appium-ios-device';
import _ from 'lodash';
const { startImageMounterService } = services;
...
async function checkAndMountDeveloperImage(udid) {
const imageMountService = await startImageMounterService(udid);
try {
const mountStatus = await imageMountService.isDeveloperImageMounted();
if (!mountStatus) {
const { fetchImageFromGithubRepo } = utilities;
const repoOpts = {
githubRepo: 'example/iOSDeviceSupport',
subFolderList: ['DeviceSupportFiles', 'iOS']
}
const downloadedImagePath = await fetchImageFromGithubRepo(udid, repoOpts);
if (!_.isEmpty(downloadedImagePath)) {
const {developerImage, developerImageSignature} = downloadedImagePath;
await imageMountService.mount(developerImage, developerImageSignature);
}
}
} catch(e) {
// Failed to mount, do something...
} finally {
imageMountService.close();
}
}
USBMUXD_SOCKET_ADDRESS is used to get usbmuxd socket address. Mostly useful in cases where the usbmuxd is run by a non-root user.npm test
FAQs
Appium API for dealing with iOS devices
The npm package appium-ios-device receives a total of 326,703 weekly downloads. As such, appium-ios-device popularity was classified as popular.
We found that appium-ios-device demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ECMAScript 2025 introduces Iterator Helpers, Set methods, JSON modules, and more in its latest spec update approved by Ecma in June 2025.
Security News
A new Node.js homepage button linking to paid support for EOL versions has sparked a heated discussion among contributors and the wider community.
Research
North Korean threat actors linked to the Contagious Interview campaign return with 35 new malicious npm packages using a stealthy multi-stage malware loader.