Xcode UI Test Runner

Running Xcode UI Tests from Linux, using Docker

Quamotion provides software which allows you to run Xcode UI Tests from Windows and Linux-based PCs. Quamotion provides you with xcuitrunner, a stand-alone command-line utility.


Before you can use Quamotion xcuitrunner, you need to make sure you meet the following prerequisites:

  • You have an iOS Developer Profile which allows you to sign iOS applications and run iOS applications signed with your developer certificate on your devices.
  • You have a copy of the relevant Developer Disk images on your local PC
    1. On a Mac machine, make sure the latest version of XCode is installed
    2. Navigate to the /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport folder and create a zip archive that contains the contents of this folder.
    3. Copy this zip archive to your PC.
    4. Unzip this archive on your PC.
  • A system service (or daemon) which manages the connectivity with all iOS devices on your PC. This system service (or daemon) is conceptually similar to adb which enables connectivity to your Android devices. It exposes an endpoint to which applications can connect, and then forwards the communication to the correct iOS device over USB. In other words, it “multiplexes” all connections to iOS devices through the USB stack. This system service (or daemon) is called usbmuxd - short for USB multiplexor daemon. On Windows, the Apple Mobile Device Service is installed as part of iTunes. On Linux, you can install this package from the Quamotion Ubuntu and CentOS package repositories.

Depending on your operating system (Linux or Windows) you need also the following:


To run Quamotion xcuitrunner on Windows, make sure:

Ubuntu Linux

To run Quamotion xcuitrunner on Ubuntu Linux, you need to install a couple of packages.

Run the following commands to install these packages:

sudo add-apt-repository ppa:quamotion/ppa
sudo apt-get update
sudo apt-get install -y libusbmuxd-tools libplist-dev libusbmuxd-dev libimobiledevice-dev usbmuxd

CentOS Linux

To run Quamotion xcuitrunner on CentOS Linux, you need to install a couple of packages.

Run the following commands to install these packages:

sudo yum install -y yum-utils libicu
sudo yum-config-manager -y --add-repo https://download.opensuse.org/repositories/home:/qmfrederik/CentOS_7/home:qmfrederik.repo
sudo yum install -y libplist-devel libusbmuxd-devel libimobiledevice-devel usbmuxd

Verifying usbmuxd (Linux only)

Execute the following steps to make sure your iOS device is connected to your PC over USB and has been detected correctly by usbmuxd:

  1. Run lsusb -v to check whether the Linux USB stack has correctly detected your device.
  2. Run idevice_id -l to check whether usbmuxd has correctly detected your device. You should see the UDID of your device in the system output.
  3. Run idevicesyslog to make sure you can connect to system services running on your device. This command should show the system log of your USB device.

Try the following steps if your device is not being detected correctly:

  1. Unplug the USB cable of your device, and then re-connect the cable.
  2. If a pop up message appears on your device, click the Trust button to establish a secure connection between your iOS device and your PC.
  3. Run systemctl status usbmuxd to check the status of the usbmuxd agent on your device.
  4. Run journalctl -u usbmuxd to get the log output of the usbmuxd service.

Using the Quamotion xcuitrunner

To use the Quamotion xcuitrunner, run the following command:

--udid <udid>
--developerProfile <path to your developer profile>
--developerProfilePassword <password for your developer profile>
--developerDiskDir <path to your developer disk folder>
--license <path your Quamotion license file>

The available options are:

Short Name Long Name Value
-u –udid The UDID of the device on which to run the Xcode UI Test. You can omit this parameter if exactly one iOS device is connected to your computer.
-d –developerProfile The path to your iOS Developer Profile.
-p –developerProfilePassword The password for your developer profile.
-s –keepSignature Keep the current signature on the Xcode UI Test bundle. Do not resign the test bundle.
-l –license The path to the Quamotion license file
-k –developerDiskDir The path to a folder which contains the iOS developer disks
-t –testBundle The path to the test bundle containing your Xcode UI Tests. This must be an .ipa file. Launches Facebook WebDriverAgent if not specified.
-v –verbose Enables diagnostic logging to a log file.


You can download Xcode UI Test Runner for the following platforms:

For more information about the Quamotion xcuitrunner command-line utility, contact us at info@quamotion.mobi.