Mobile gateway for iOS
With the Mobile Gateway for iOS, you can run Xcode UI Tests, such as Appium's WebDriverAgent, on iOS devices, using a Windows or Linux machine.
The Mobile Gateway for iOS can integrate with Appium, enabling you to run Appium's tests on real, physical iOS devices using a Linux machine.
Prequisites
Before you can use the Mobile Gateway for iOS, 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
- On a Mac machine, make sure the latest version of XCode is installed
- 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. - Copy this zip archive to your PC.
- 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 calledusbmuxd
- 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 the Mobile Gateway for iOS on Windows, make sure:
- You have installed iTunes
Ubuntu Linux
To run the Mobile Gateway for iOS 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 usbmuxd libturbojpeg libgdiplus
We recommend you uninstall the gvfs-backends
package when running a desktop edition of Ubuntu 20.04 or later.
CentOS Linux
To run the Mobile Gateway for iOS 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 usbmuxd libturbojpeg libgdiplus
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
:
- Run
lsusb -v
to check whether the Linux USB stack has correctly detected your device. - Run
idevice_id -l
to check whetherusbmuxd
has correctly detected your device. You should see the UDID of your device in the system output. - 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:
- Unplug the USB cable of your device, and then re-connect the cable.
- 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.
- Run
systemctl status usbmuxd
to check the status of theusbmuxd
agent on your device. - Run
journalctl -u usbmuxd
to get the log output of theusbmuxd
service.
Using the Mobile Gateway for iOS
To use the Mobile Gateway for iOS, 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 license file>
The available options are:
Short Name | Long Name | Value |
---|---|---|
-u | --udid <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 <path> | The path to your iOS Developer Profile. |
-p | --developerProfilePassword <password> | The password for your developer profile. |
-s | --keepSignature <password> | Keep the current signature on the Xcode UI Test bundle. Do not resign the test bundle. |
-l | --license <path> | The path to the license file |
-k | --developerDiskDir <path> | The path to a folder which contains the iOS developer disks |
-t | --testBundle <path> | 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 <ID> | 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 <name> | 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. |