Xcode UI Test Runner on Docker

Running Xcode UI Tests from Linux, using Docker

This tutorial describes how to run Xcode UI Tests, such as the Facebook WebDriverAgent (or the Appium fork), using the xcuitrunner command-line utility, running in a Docker container on Linux.

This setup consists of two Docker containers:

  1. 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. usbmuxd runs in a background container.
  2. One Docker container runs xcuitrunner, the command-line utility that launches the Xcode UI Test. If you want to run multiple Xcode UI Tests in parallel, you can run start multiple containers running xcuitrunner.

This document describes how to run the xcuitrunner on CentOS Linux using Docker. Instructions for other Linux distributions are similar.

Install Docker

You need to install Docker before you can run Docker containers. You can use the Community Edition, Docker CE.

  1. Install the required packages

    sudo yum install -y yum-utils device-mapper-persistent-data lvm2
  2. Add the Docker repository

    sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
  3. Install Docker

    sudo yum install docker-ce docker-ce-cli containerd.io
  4. Start Docker

    sudo systemctl start docker

Launch the usbmuxd daemon

Run the following commands to download and launch the usbmuxd Docker image. This command launches a background Docker container running usbmuxd, which automatically starts 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 check whether the Docker container is running, you can run:

sudo docker ps

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, open a Bash shell inside the usbmuxd Docker container:

sudo docker exec -it usbmuxd /bin/bash

You can now run various commands, such as idevice_id -l to list all iOS devices, or idevicesyslog to show the system logs.

To exit the Bash shell inside your usbmuxd container, simply type exit.

Launch an Xcode UI Test

You need to share some files between your host (the computer on which you run Docker) and the container (which is running xcuitrunner). This includes your Quamotion license file, the Developer Disk images, and your developer profile.

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

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] \

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

Last modified October 30, 2019: Move Docker guide to Tutorial (7f1dd71)