Skip to main content

Troubleshooting Issues in iOS Testing

Test automation with iOS devices offers some unique challenges. Following are tips and instructions to help you configure iOS devices and your computer for testing, and to avoid issues in that testing.

Mobile Device Automation Overview

Much of your automation control of iOS devices with Eggplant Functional is done the same as for any other type of system under test (SUT). However, some control options are unique to mobile environments and to iOS specifically.

To learn how to automate your mobile device from Eggplant Functional scripts, see the following resources:

High CPU Usage

High CPU usage during automation of iOS devices is expected, as the processing for that automation happens on the computer running iOS Gateway, not on the iOS device.

The quickest way to reduce CPU usage is to stop automation when you're finished testing.

To reduce CPU usage during testing:

  • Reduce the frame rate using the Max Frames Per Second dialog box in the main iOS Gateway interface.
  • Enable Faster Screen Updates using the checkbox in the main iOS Gateway interface.

App States

When you work with an iOS app, it is useful to know the state of that app. For our purposes, we work with three iOS app states: Frontmost, Suspended, and Terminated.

App states diagram

Frontmost: The Frontmost app is the app you are currently looking at. If you are multitasking in iOS 9 or later, only the left-side app is Frontmost. The right-side app is considered Suspended.

Suspended: An app that has been Frontmost since it was last Terminated (or since the last device reboot), but that is not currently Terminated.

Terminated: A terminated app is an app that is completely unloaded from memory. This happens in the following circumstances:

  • The app is successfully killed via iOS Gateway or Eggplant Functional
  • The app crashes on its own
  • The app is closed from the Recent Apps list

Multiple Xcode Versions

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. Not all versions of iOS are compatible with all versions of Xcode.

You can have more than one version of Xcode installed on your Mac, though only one version can be active at a given time. The easiest way to see if your active version of Xcode works with the version of iOS on the device you want to test is by using the iOS Gateway Diagnostics tab.

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.

You must have Administrator privileges on your Mac to switch the active Xcode version.

Killing Apps

You can use the KillApp command in Eggplant Functional. For more about this command, see the KillApp Command.


You should be able to kill any developer-signed app in any iOS version.

iOS-Specific Commands

Double-Press the Home Button

On iOS 9 and later devices, you can access the recently used apps list by double-pressing the home button. In Eggplant Functional, you can use the TypeText command to automate the action in your SUT by using the following code:

TypeText homeButton, homeButton


This command must be entered as one line. If you use two separate lines, the device registers two separate home button presses, not a double-press.

Disabling iOS Features that Can Interfere with Testing

In order to successfully test iOS devices in Eggplant Functional, it is necessary to properly configure those devices. Certain features in iOS need to be disabled to prevent test interruptions. Listed below are instructions for disabling iOS features that can interfere with testing.

Updates and Pop-ups

Automated software update notifications and pop-ups in iOS 8 and later can disrupt your testing. If you don’t want to update iOS, or if you want to prevent update notifications from occurring, try one of these methods:

  • Block and through your router. If you maintain a large group of iOS testing devices that you don’t want to update, consider placing those devices on a separate Wi-Fi network from other devices that should take iOS updates.
  • Delete any existing over-the-air (OTA) updates that have already been downloaded to the iOS device:
    1. Open Settings > General > Storage & iCloud usage on the iOS device.
    2. Under Storage, tap Manage Storage.
    3. Find and select the iOS download from the list.
    4. Tap Delete Update, then confirm that you want to delete the update.

Note that iOS Gateway automation can't begin if there are any pop-up notifications displayed on the iOS device.

Screen Effects

In iOS 9 and later, icons in the user interface move as the device is physically moved. This motion can cause problems with matching images in tests. Icon motion effects can be disabled in Settings. Go to General, then Accessibility, then set Reduce Motion to On.

Text Correction

If you are entering text on an iOS device, auto-correct suggestions are typically accepted by default, which can cause text to appear incorrectly. You can work around this problem by disabling automatic keyboard options on your test devices.

In the iOS Settings app, select General, then Keyboard. Turn off the settings for Auto-Capitalization, Auto-Correction, and Predictive, and any other setting that adversely affects the display of your text.

Special Instructions

File Transfer Commands

When you transfer files using iOS Gateway, the files are not transferred to the actual iOS device, but instead to and from the machine that is running iOS Gateway.

Swapping Apps

Eggplant recommends swapping between apps using the LaunchApp command in Eggplant Functional instead of pressing the home button and navigating the home screen. There are several reasons for this:

  • The home screen is particularly "active", making image matching harder and slower.
  • It can be difficult to know where an app gets installed, as Apple has sophisticated rules for managing app placement (especially when uninstalling and installing apps). LaunchApp is faster, more maintainable, and less error-prone.
  • There is a known bug in Apple's XCTest framework that causes failures after multiple home button presses. To work around that, iOS Gateway will restart automation every 150 times the home button is pressed. That can make user scripts less resilient. LaunchApp can be used to avoid the Apple bug entirely.