Xcode UI Test Runner on Docker

Running Xcode UI Tests from Linux, using Docker

This document describes how you can run Xcode UI Tests, such as the Facebook WebDriverAgent (or the Appium fork), using the xcuitrunner command-line utility, using Docker containers on Linux.

To make this work, we’ll use 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. We’ll run usbmuxd in a single container, which runs in the background.
  2. One Docker container runs xcuitrunner, the command-line utility that will actually launc 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 should be similar.

Install Docker

Before you can run Docker images, you’ll first need to install Docker itself. 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

You can download the usbmuxd Docker image and run it 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 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 execit the Bash shell inside your usbmuxd container, simply type exit.

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