Appium

The Eggplant Gateway for Appium supports automating iOS physical devices and iOS simulators by connecting to an Appium server. This gateway is only supported on macOS.

info

The Eggplant Gateway for Appium is designed to work with Appium 2.0 (W3C WebDriver protocol).

Prerequisites

1. Install the latest supported Xcode version on your Mac pc.
2. Install Node.js and npm.
3. Install Appium server.
4. Install the iOS driver: appium driver install xcuitest.
5. Configure a developer certificate and Provisioning Profile, which allow you to sign iOS applications and run iOS applications on your devices. The Appium gateway supports the basic (automatic) configuration using xcodeOrgId and xcodeSigningId.

Getting started

Enabling automation on your iOS physical device

1. Establish trust between your PC and your device as follows:
   • Connect your iOS device to your PC using a USB cable. The pop-up Trust this Device will appear on your iOS device.
   • Click 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, 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 restarts, and should prompt you to enable Developer Mode. Tap Turn On to enable Developer Mode. iOS enables Developer Mode and you should be able to connect.
3. Download the Apple iOS 17 platform in case you want to automate iOS 17 devices.
   • Display the XCode menu and press Settings.
   • Open the Platform pane in Settings.
   • Locate the iOS 17 item and press Get next to it. (Consider upgrading XCode when this item is not available.)

Running automation on an iOS simulator

The Eggplant Gateway for Appium connection can automatically start the iOS simulator. You can also manually pre-start an iOS simulator from Xcode as follows:

1. Launch Xcode, then choose Xcode > Open Developer Tool > Simulator or Control-click the Xcode icon in the Dock, and from the shortcut menu, choose Open Developer Tool > Simulator.
2. Click File > Open Simulator. A list of available simulators will be displayed. You can then choose one.

Creating a connection

To create an Eggplant Gateway for Appium connection to a physical iOS device, run the following command:

epgw add appium
--name <name> (REQUIRED)
--deviceId <udid> (REQUIRED)
--platformName "iOS"
--xcodeSigningId <signingId> (REQUIRED)
--xcodeOrgId <teamId> (REQUIRED)

For example,

epgw add appium --name appium-ios17 --platformName "iOS" --deviceId "" --xcodeOrgId "Q73Y67F7ET" --xcodeSigningId "iPhone Developer"

The available options are:

Key	Description
name	The connection name.
platformName	The platform name (currently only iOS is supported).
deviceId	The UDID of the physical iOS device or the UDID of the iOS simulator 1 you want to automate.
xcodeSigningId	The signing id, usually Apple Developer or iPhone Developer. It can be left blank for simulator.
xcodeOrgId	The team identifier. It can be left blank for simulator.
help	Show help and usage information.

Connecting to Eggplant Functional

Follow these steps to start an emulator through Eggplant Functional:

1. Start Appium server: appium.
2. Run epgw vnc <name>, where name is the name of your Gateway connection. For example, epgw vnc appium-ios17.
   • The Eggplant Gateway will start:
     • A VNC server at port 5900
     • A WebDriver server at port 5000
3. Start Eggplant Functional and manually add your device to the connection list.

Footnotes

1. The UDID of the iOS simulator can be retrieved using xcrun simctl list in the terminal. ↩