iOS Devices

Eggplant Gateway can be used to test against iOS devices from Windows, Linux, and macOS machines, and supports testing on real, physical iOS devices over Wi-Fi and USB.

info

Supported iOS versions:

• Eggplant Gateway supports all major iOS versions except versions between 17 and 17.3 on Windows, Linux, and macOS.

Prerequisites

Before you can use the Eggplant Gateway to connect to iOS, you must:

1. Have access to an iOS Provisioning Profile, which allows you to sign iOS applications and run iOS applications signed with your developer certificate on your devices.
2. Have a copy of the relevant developer disk images on the system where you are running Eggplant Gateway as described in Developer Disk Images below.
3. Install the appropriate connection enabling software for your operating system as follows:
   • On Windows, install iTunes.
   • On Linux, install usbmuxd. And, in a shell install net-tools (for example, sudo apt install net-tools.)

Developer Disk Images

You need to have a copy of the relevant developer disk images on the system where Eggplant Gateway is running depending on your device and its operating system as follows:

Device	Notes
For devices running iOS 16 and earlier	For Eggplant Gateway on Mac: - Make sure the latest version of Xcode is installed. - When Xcode is installed, you can use the default folder /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport as the --developerDiskLocation. For Eggplant Gateway on Windows or Linux: You need to copy the appropriate developer disks from a macOS machine with Xcode installed. - Navigate to the folder /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport on a Mac machine. - Create a zip archive that contains the contents of this folder. - Copy this zip archive to your Windows or Linux machine and unzip it.
For devices (for iPhone 16 see next row) running iOS 17.4 or later	The developer disks are mounted automatically. Note that this requires an internet connection. Eggplant Gateway automatically fetches the personalized developer disk.
For devices manufactured iPhone 16 and running iOS 17.4 and later	You can also use these steps to provide your custom path for a personalized disc image. For Eggplant Gateway on Mac: Make sure the latest version of Xcode is installed. Or, if you have a custom path, provide it to the --developerDiskLocation argument. For Eggplant Gateway on Windows or Linux: - If you have the latest Xcode installed on your Mac, then the location of the Personalized Developer Disk on your Mac is in ~/Library/Developer/DeveloperDiskImages/iOS_DDI.dmg. - Open a terminal and run the command below. You can choose any directory for <TMP_DIR> hdiutil attach ~/Library/Developer/DeveloperDiskImages/iOS_DDI.dmg -mountpoint <TMP_DIR> - Copy the Restore folder from <TMP_DIR> to your Windows/Linux pc from the Mac machine. - On your target Windows/Linux machine, the Restore folder path will be used as path to --developerDiskLocation argument - Note: An internet connection is still required because Apple must verify the signature when mounting the personalized disk image.

Enabling Automation on Your iOS Device

Follow the steps below to enable automation on your iOS device:

1. Establish trust between your Eggplant Gateway machine (on Mac, Windows, or Linux) and your device.
   • Connect your iOS device to your PC using an USB cable.
   • The pop-up Trust this Device will appear on your iOS device, tap Trust. It can take up to one minute for your iOS device and your machine to initiate the pairing process.
2. Enable Developer mode on your device (iOS 16 and later).
   • In the Settings app on your iOS device select Privacy & Security then scroll down and tap Developer Mode.
   • Turn on the Developer Mode toggle at the top.
   • A prompt will appear at the bottom asking you to reboot your iOS device for enabling the feature. Tap Restart to proceed. Your iOS device will now reboot.
   • Once the device is restarted and unlocked, a prompt should appear on the screen asking you whether you wish to turn on Developer Mode on your device. Tap Turn On. When you do that, iOS will enable Developer Mode on your iOS device and you should be able to connect.

Creating a Connection

To create an Eggplant Gateway connection to an iOS device, run the following command:

epgw add ios
--name <name> (REQUIRED)
--udid <udid>
--provisioningProfile <path> (REQUIRED)
--developerCertificate <path> (REQUIRED) 
--developerCertificatePassword <password> (REQUIRED)
--developerDiskLocation <path> (Required on iOS <17.4 or iPhone 16, optional on iOS 17.4+ with internet)

For example, for iOS 16 or earlier devices:

epgw add ios --name ios --provisioningProfile "C:\" --developerCertificate "C:\" --developerCertificatePassword "****" --developerDiskLocation "C:\"

Or for iOS 17.4 or later devices (--developerDiskLocation is optional, please refer to Developer Disk Images section):

epgw add ios --name ios --provisioningProfile "C:\" --developerCertificate "C:\" --developerCertificatePassword "****"

The available options are:

Key	Description
name	The connection name.
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.
provisioningProfile	The path to the provisioning profile to use when installing WebDriverAgent.
developerCertificate	The path to the developer certificate to use to resign WebDriverAgent.
developerCertificatePassword	The password to use to retrieve the private key of the developer certificate.
developerDiskLocation	The path to the directory which stores the developer disk images (see Developer Disk Images for details on obtaining developer disk images).
help	Show help and usage information.

Start a Connection

Open a new terminal window and run epgw vnc <name>, where name is the name of your Gateway connection. For example, epgw vnc ios.

• Eggplant Gateway will start:
  • A VNC server at port 5900
  • A WebDriver server at port 5000

Known Issues

• Currently we do support a limited set of VNC extensions. To have a full overview please refer to the Supported SenseTalk Commands.

• On rare occasions tiny lines may appear on the screen or the SUT window may blink.

Connecting to Eggplant Functional

Start Eggplant Functional and manually add your device to the connection list.