Skip to main content

Getting Started with iOS Gateway

iOS Gateway is a free utility to connect Eggplant Functional with iOS devices. It lets you control any iOS device running iOS 10, iOS 11, iOS 12, iOS 13, or iOS14. iOS Gateway also works with iPadOS 13, iPadOS 14, and Apple TV (4th generation).

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:

The iOS Gateway machine connects to the device via USB; eggPlant Functional can run on the same machine or a different one.

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 macOSiOSRecommended Xcode
10.14.6iOS 9-13

iPadOS 13
Xcode 11.3.1 or later
10.15.7iOS 14

iPadOS 14
Xcode 12.3
Important

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.

note

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.

note

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:

  1. Open Xcode.
  2. Go to Xcode > Preferences > Locations.
  3. From the Command Line Tools drop-down menu, choose the version of Xcode you want to be active.
  4. Enter an administrator password when prompted.
  5. Close Xcode.
note

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.

  • 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.

  1. Create the signing certificate and provisioning profile on the Apple Developer portal. Download them both to your Mac.

  2. 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.

    note

    The 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.