Working with iOS Mobile Devices
Overview
Eggplant Functional supports extensive testing of iOS mobile devices. Using Eggplant's iOS Mobile Device Connections, you can test physical iOS mobile devices which are directly connected to the machine running Eggplant Functional. Additionally, you can test cloud-hosted iOS mobile devices hosted by Sauce Labs.
This section describes the testing of physical mobile devices that are connected directly to the system running Eggplant Functional. Please refer to Connecting to Sauce Labs Real Devices and Virtual Browsers for details on working with cloud-hosted iOS mobile devices.
Mobile Device Connections only support devices which are connected directly to the machine which is running Eggplant Functional. If you have a need to host your devices from a shared network address which is not co-hosted on the same machine as Eggplant Functional, you must use Eggplant's Classic iOS Gateway application. Please refer to the user guide for the Classic iOS Gateway application for details on how to setup and use the application.
For Users of Eggplant's Classic iOS Gateway
If you have used Eggplant's Classic iOS Gateway previously, you may recognize several concepts related to the new iOS Mobile Device Connections. There are, however, several important differences that you should be aware of to ensure a seamless transition to the new iOS Mobile Device Connections. Please take some time to read this section if you are one of those users. If you have never used the Classic iOS Gateway, you can skip this section and move onto Before You Start.
These are the important behavior differences of which you need to be aware if you are migrating from the Classic iOS Gateway. The differences are as follows (you can read about the new iOS Mobile Device Connection behaviors in Before You Start):
- You must explicitly provide your Developer Certificate, a Provisioning Profile, and your Developer Disks. The new iOS Mobile Device Connections are not able to retrieve these items from XCode or from the Mac Keychain.
- Within your Provisioning Profile, instead of using a wildcard App ID of
com.testplant.*, you must use a wildcard App ID ofcom.*. - With the new iOS Mobile Device Connections, you are now able to connect to iOS devices on Windows and Linux systems. However, you must install additional software on Windows and Linux systems to enable them to support iOS Devices (see Install iTunes or
usbmuxd(Windows or Linux Only))
Unlike the Classic iOS Gateway, which only supported connections from Mac systems, the new iOS Mobile Device Connections are designed to work across all platforms that are supported by Eggplant Functional. As a result, Eggplant Functional cannot assume that XCode is installed on the machine which is running Eggplant Functional. Consequently, the tight coupling between the Classic iOS Gateway and XCode is not replicated with the new iOS Mobile Device Connections. This is the reason you must explicitly provide your Developer Certificate, Provisioning Profile, and Developer Disks.
Before You Start
Ensure You Have Your Developer Disks
To connect to your iOS mobile device, Eggplant Functional will need to be able to access your Developer Disks. If you are running Eggplant Functional on a Mac with Xcode installed, your Developer Disks are part of your Xcode installation. Within Xcode, you'll have a set of Developer Disks for each HW platform supported by Xcode (i.e. iPhone, iPad, etc). For each HW platform, there is a Developer Disk for each version of the OS supported on that platform. You'll need to know the path to the Developer Disks for the HW platform that you intend to test. Assuming you have installed Xcode in its default location, the path to your Developer Disks for an iPhone is /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport.
If you are planning to run Eggplant Functional on a Windows or Linux system and you want to connect to an iOS mobile device, you will need to copy the appropriate Developer Disks from a Mac system onto your Windows or Linux system. To copy your Developer Disks:
- Navigate to the appropriate Developer Disks location on a Mac system which has the latest version of Xcode installed (typically
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport). - Create a zip archive that contains the contents of this folder.
- Copy this zip archive to your Windows or Linux PC and unzip it. Take note of the location under which you unzipped the files. This is the location of your Developer Disks that you will need when connecting to your mobile device.
If you copy the files to Linux, you may need to check your file permissions, as they are sometimes set inappropriately after the copy. At a minimum, you need to ensure the "User" has RW permissions to all of the files and directories.
Obtain Copies of Your Provisioning Profile and Developer Certificates
To connect to an iOS mobile device, you must provide Eggplant Functional with a copy of your Developer Certificate and you must create a custom Provisioning Profile which allows Eggplant Functional to execute software on the mobile device to be tested. The custom Provisioning Profile must link your Developer Certificate to the specific device (or devices) to be tested and allow applications with a wildcard App ID of com.* to execute on the device.
Once you have them, your custom Provisioning Profile and corresponding Developer Certificate must be downloaded and available as stand-alone files on the system that is running Eggplant Functional. You will need to know the locations of these files on your system and be able to specify their paths when creating the Mobile Device Connection.
This document assumes as an iOS Developer/Tester that you are already have an Apple Developer Account and are familiar with the concepts of a Provisioning Profile and Developer Certificate. If you do not already have a Developer Account, please visit the Apple Developer Program Enrollment page for information. If you are not familiar with the concepts of a Provisioning Profile or Developer Certificate, we recommend that you read Apple's online Developer Account Help documentation, paying close attention to Create Developer ID Certificates and Create a Development Provisioning Profile. If you are working on a Mac system with XCode installed, you can also manage your Developer Certificates and Provisioning Profiles via Xcode. Please refer to the XCode documentation for details.
Install iTunes or usbmuxd (Windows or Linux Only)
If you are running Eggplant Functional on a Windows or Linux machine, you must install iTunes (Windows) or usbmuxd (Linux) before attempting to create a Mobile Device Connection to your iOS device.
Configuring Your iOS Mobile Device for Automation
In order to have the best test automation experience on your iOS mobile device, you need to configure the device appropriately. This section describes the configuration activities that you need to perform on your iOS mobile device before you try to run test automation against it for the first time.
Enable Developer Mode
On mobile devices running iOS 16 or later, you must enable developer mode on your device before connecting to device with Eggplant Functional. Please refer to Enabling Developer Mode on a device in the Apple Xcode documentation for details on how to enable developer mode.
Establish Trust
When you first connect an iOS mobile device to your system and unlock the device, you will be prompted whether or not the device should trust the system to which you are connecting. In order to use Eggplant to automate your device, you must allow your device to trust the system on which Eggplant Functional is running (and vice versa). You should only need to do this operation the first time you connect your mobile device to the system.
Getting iOS Mobile Unique Device IDs (UDID)
If you have a single iOS mobile device that you want to test, Eggplant Functional is capable of auto-discovering the device when you connect it to Eggplant Functional and create a Mobile Device Connection. Auto-discovery only works if you have a single device connected to your system. If you have more than one iOS mobile device that you want to connect to your system simultaneously, you will need to use the UDID in order to specify to which device you want Eggplant Functional to connect. This section describes how to obtain the UDID for iOS mobile devices.
There are multiple methods to locate the UDID on your iOS phone. However you obtain the UDID, please copy the information. You can specify the UDID when you create the connection in Eggplant Functional.
Finding your UDID using XCode on Mac systems
- Plug your iPhone into a USB port onto your Mac system (if prompted, acknowledge trust on both your phone and your Mac).
- Ensure that your device is not locked (i.e. sign into your device).
- Select Windows and then Devices and Simulators from the main menu.
- Under the Devices tab in the top right corner of the resulting window, you should see your device listed. Click on it.
- You should be presented with a window showing your device information. The "Identifier" field is your UDID.
- Copy the Identifier by selecting it and copying the text.
Finding your UDID using Finder on Mac systems
- Plug your iPhone into a USB port onto your Mac system (if prompted, acknowledge trust on both your phone and your Mac).
- Ensure that your device is not locked (i.e. sign into your device)
- Look for your iPhone in the Locations section of Finder Sidebar. Click on it.
- At the top of the resulting display, you should see the name of your iPhone displayed. Click on the information below the name of your iPhone. The information should cycle through multiple lines, one of which will contain your UDID.
- Copy the UDID by right-clicking on the info line and selecting "Copy UDID".
Finding your UDID using iTunes (Mac or Windows) or Apple Music
- Plug your iPhone into a USB port onto your Mac system (if prompted, acknowledge trust on both your phone and your Mac).
- Ensure that your device is not locked (i.e. sign into your device)
- Look for your iPhone in the Devices section of the left navigation pane. Click on it.
- At the top of the resulting display, you should see the name of your iPhone displayed. Click on the information below the name of your iPhone. The information should cycle through multiple lines, one of which will contain your UDID.
- Copy the UDID by right-clicking on the info line and selecting "Copy UDID".
Finding your UDID using an App
There are several Apps in the App store which will give you visibility to your UDID. Search the App store for "UDID" and install the App that works best for you.
- As a reminder, you only need the UDID if you plan to connect multiple iOS Devices simultaneously. If you only have one device connected at a time, Eggplant Functional can discover the device without needing the UDID.
- Do not confuse the UDID with the Serial Number. They are not the same. If you try to use a Serial Number in place of the UDID, your connection will fail.
Manipulating Your iOS Mobile Device
Once you connect to an iOS mobile device via Eggplant Functional's iOS Mobile Device Connection, you can manipulate your device using Eggplant's image-based commands and Eggplant's mobile WebDriver commands. Both of these capabilities are automatically available in the single Mobile Device Connection.
To use mobile WebDriver functionality on your Mobile Device Connection, simply create (or activate) a new Mobile Device Connection. Then, you can send any mobile WebDriver-based SenseTalk command to your device. You can also use several of Eggplant's mobile control and touch event commands to manipulate your mobile device. Please refer to SenseTalk Mobile Control and Touch Events for more details.
To learn how to automate your mobile device from Eggplant Functional scripts, see the following resources: