Getting Started

Try Xcode UI Test Runner on Windows or Linux!

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.

Prequisites

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:

Windows

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 Quamotion xcuitrunner

To use Quamotion xcuitrunner, run the following command:

xcuitrunner
run 
--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.
-tbi –testBundleId The bundle ID of the test bundle containing your Xcode UI Tests. Use this option if the test bundle is installed on your device.
-tbp –testBundlePlugin The ID of the test bundle plugin. Use this option if the test bundle is installed on your device.
-nf –noforward Disables port forwarding.
-f –forward Defines the local port for the WebDriverAgent.
–vnc Starts a VNC server. Requires the WebDriverAgent. You can connect to the VNC server using TightVNC. Specify the UDID of your device as password. This allows you to remotely control your device using a mouse and keyboard.
–vncPort The port on which the VNC server should listen.
-v –verbose Enables diagnostic logging to a log file.

Download

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.


Last modified October 30, 2019: Fix duplicate page description (2e3b328)