Getting Started with iOS Gateway
Introduction
iOS Gateway is a free utility to connect Eggplant Functional with iOS devices. The iOS Gateway runs on MacOS 10.14, 10.15, 11, 12, and 13 and supports connections to devices running iOS 10 through iOS 16 and iPadOS 13 through iPadOS 16.
For Mobile iOS device testing, Eggplant Functional also provides an integration with Sauce Labs. Sauce Labs makes it easy to test against a variety of cloud-hosted iOS devices with varying versions of the OS installed, making it unnecessary for you to actually own the devices. When using Sauce Labs, there is no need to use the iOS Gateway. The Sauce Labs device connections are integrated directly into Eggplant Functional.
Please refer to Connecting to Mobile Devices in the Eggplant Functional user documentation for more information.
Prior to the release of Eggplant Functional 22.5, the iOS Gateway was the only method for connecting your own iOS mobile devices to Eggplant Functional. (As noted above, you could use Sauce Labs Connections to connect to cloud-hosted devices, but the iOS Gateway was required for devices that you own.) With the release of Eggplant Functional 22.5, you are now able to connect directly to your own iOS mobile devices using Eggplant Functional's Mobile Device Connections. The Mobile Device Connections make it possible for you to connect to your iOS mobile device without having to install and use the iOS Gateway. The connections are integrated into Eggplant Functional, and are accessible from Windows, Linux, and Macintosh. They are now the preferred method to connect an iOS mobile device to Eggplant Functional. Please see Connecting to Mobile Devices in the Eggplant Functional user documentation for more details about Mobile Device Connections. Disregard the iOS Gateway and related documentation if Mobile Device Connections work for you.
Although Mobile Device Connections are the preferred method to connect your iOS mobile devices to Eggplant Functional, they only work with devices which are directly connected to the system on which Eggplant Functional is installed. This constraint means you cannot use Mobile Device Connections to share your iOS mobile devices across your network, which is a use-case supported by the iOS Gateway. If you are using the iOS Gateway to share your mobile devices, you should continue to use it in that capacity. However, Eggplant recommends that you use the Mobile Device Connections whenever possible.
Using the iOS Gateway, you create tests against iOS devices in the same manner that you would with any other SUT: by managing your connections using the Viewer window and Connection List in Eggplant Functional.
A Note About Naming Conventions
As noted above in the Introduction, the iOS Gateway pre-dated Eggplant Functional's Mobile Device Connection. To make the distinction between the two methods of connecting to iOS devices clear, the Eggplant Functional user documentation will use the term "Classic iOS Gateway" whenever it is referring to the stand-alone iOS Gateway (i.e. the application described by this document). However, within this document, we will simply refer to it as the "iOS Gateway". If you get confused, just remember the term "Gateway" refers to this stand-alone application while the term "Mobile Device Connection" refers to the new connection which is directly integrated into Eggplant Functional.
How iOS Gateway Works
The iOS Gateway works as a VNC server (from the IP address of the Mac where it is running). When you connect to that Mac from Eggplant Functional, you can see and control your iOS device.
The Mac where iOS Gateway is running does not need to be the same machine as where you have Eggplant Functional installed. However, the iOS device must be connected by USB to the Mac where iOS Gateway is installed. The diagram below shows a basic network architecture for using iOS Gateway:
System Requirements
You must install Xcode, Apple's integrated development environment (IDE), on the machine that's running iOS Gateway. Typically, when a new version of iOS comes out, Apple releases a new version of Xcode as well. You need to update Xcode to the latest version to test the companion version of iOS with iOS Gateway.
The version of iOS that you want to test determines the minimum macOS and Xcode versions that you need to have installed. In general, you need to run iOS Gateway on the latest version of macOS to test devices running the latest version of iOS.
| Minimum macOS | iOS | Recommended Xcode |
|---|---|---|
| 10.14.6 | iOS 9-13 iPadOS 13 | Xcode 11.3.1 or later |
| 10.15.7 | iOS 14 iPadOS 14 | Xcode 12.3 |
You might need a newer Mac to be able to upgrade the macOS version and the Xcode IDE. We recommend running iOS Gateway on an M1 Mac Mini or better for best results.
You can use the Diagnostics tab to check whether the active version of Xcode on your Mac is compatible with the version of iOS on the device you want to test.
Older versions of iOS Gateway are compatible with older versions of Xcode, and can be used to test devices with older versions of iOS. You can have more than one version of iOS Gateway and Xcode installed on your Mac to enable testing of older devices.
Switching the Active Xcode Version
If you're testing devices with older versions of iOS, you might need to have more than one version of Xcode installed on your Mac. You can have several versions of Xcode installed at once, but only one active version.
If you need to have more than one version of Xcode on your Mac, we recommend that you change the name of the most recent version to Xcode.app, and then change the names of older versions to include their version numbers.
To change the active version of Xcode, follow these steps:
- Open Xcode.
- Go to Xcode > Preferences > Locations.
- From the Command Line Tools drop-down menu, choose the version of Xcode you want to be active.
- Enter an administrator password when prompted.
- Close Xcode.
You must have Administrator privileges on your Mac to switch the active Xcode version.
iOS Gateway Setup
First, download and install iOS Gateway. You must have an Apple Developer ID to use iOS Gateway to test iOS devices.
Recommended Hardware
- M1 Mac Mini or better
Available Ports
The following port ranges must be available for testing with iOS Gateway:
- VNC: 5900-5950
- WebDriver: 8100-8150
Manual Provisioning
To set up provisioning manually, you must have both a development signing certificate and a development provisioning profile.
Create the signing certificate and provisioning profile on the Apple Developer portal. Download them both to your Mac.
In the General tab, manually select a profile from the Profile drop-down list. iOS Gateway automatically shows all profiles saved in the default location.
noteThe default profile location is
~/Library/MobileDevice/Provisioning Profiles.
Mobile WebDriver for iOS
You can perform object-based WebDriver testing on iOS devices using iOS Gateway and WebDriver commands and functions in Eggplant Functional. Mobile WebDriver testing requires iOS Gateway 5.1.2 and later and Eggplant Functional 18.1.2 and later.
Additional Requirements
Your testing devices must be prepared for development use. You can find this information, as well as installation instructions, in Setting Up iOS Testing.
Lastly, you need to be set up to sign apps for development use. This is an Apple requirement. Learn more in Signing Apps for Use with iOS Gateway.