quamotion/xcuitrunner repository overview

The xcuitrunner (short for Xcode UI Test Runner) allows you to run Xcode UI Tests, such as Facebook's WebDriverAgent (used by Appium) on real, physical iOS devices using a standard Linux PC.

⁠Prerequisites

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 access to the Developer Disk Images for your iOS device

⁠Overview

You'll need to start two Docker containers:

• One Docker container runs usbmuxd, the USB multiplexer for iOS devices. usbmuxd allows Linux programs to communicate with iOS devices. It acts as a daemon. We’ll run usbmuxd in a single container, which runs in the background.
• One Docker container runs xcuitrunner, the command-line utility that will actually launch the Xcode UI Test. If you want to run multiple Xcode UI Tests in parallel, you can run start multiple containers running xcuitrunner.

⁠Launching usbmuxd

You can run usbmuxd using the following commands. This command will launch a Dcoker container running usbmuxd in the background, which will automatically start when the system reboots.

sudo docker run \
  --privileged \
  -v /dev/bus/usb:/dev/bus/usb \
  -v /var/lib/lockdown:/var/lib/lockdown \
  -v /var/run:/var/run \
  --name usbmuxd \
  --restart always \
  quamotion/usbmuxd \
  usbmuxd -f -v

To test the connectivity with your iPhone, connect your iPhone using an USB cable. You should see a Trust pop up on the device. Trust the computer.

Then, run sudo docker exec -it usbmuxd idevice_id -l to list all iOS devices, or sudo docker exec -it usbmuxd idevicesyslog to show the system log for your iOS device.

⁠Running an Xcode UI Test

You’ll want to share some files between your host (the computer on which you run Docker) and the container (which is running xcuitrunner). For example, you may want to save your Quamotion license file, the Developer Disk images, and your developer profile.

We recommend you store these files in /var/lib/xcuitrunner, and then make that folder available inside your container by mounting it as a volume.

Then, use the following command to launch the xcuitrunner:

sudo docker run \
  -it \
  --net host \
  -v /var/run:/var/run \
  -v /var/lib/xcuitrunner:/var/lib/xcuitrunner \
  quamotion/xcuitrunner \
  /app/xcuitrunner \
  run \
  -l /var/lib/xcuitrunner/.license \
  -d /var/lib/xcuitrunner/quamotion.developerprofile \
  -p [PASSWORD] \

See the Quamotion website⁠ for more information.