T-Plan Ltd Home
T-Plan Robot Enterprise 4.4.7 Doc Collection

Automating iOS Over Xcode

Last update: 24 January 2018

1. Introduction
2. Setting Up
3. Connecting From Robot
4. Troubleshooting
5. Automation

1. Introduction

NOTE: For the older document describing automation of iOS 9 devices over Xcode 7 go here.

T-Plan Robot Enterprise version 4.3.1 and higher supports automation of iOS 10+ devices over Xcode 8 and higher on Mac OS X. Main features:
As the connection is slower than the iOS Mirror one it is not suitable for testing of applications that require real time control, such as games etc. Use the iOS Mirror connection instead.

2. Setting Up


1. Download Instructions:

2. Project Setup Instructions:

3. Xcode Setup Instructions:

Xcode set up must be repeated:

The steps:

  1. Select the WebDriverAgentRunner scheme and the target device at the top bar.
  2. Select the WebDriverAgentLib target. Make sure that the "Automatically manage signing" option is on and a valid team is set.
  3. Select the WebDriverAgentRunner target. Make sure that the "Automatically manage signing" option is on and a valid team is set.
2017-10-19 15:51:28.502141+0100 WebDriverAgentRunner-Runner[785:276949] ServerURLHere-><-ServerURLHere

Robot doesn't need Xcode to run at the time of the connection. The WebDriverAgent application doesn't even have to be installed on the target iOS device. Robot will start it and eventually build it and install it on the device using the Xcode CLI tools. The manual process above is required only to ensure that the WDA project is configured properly to be built and executed using the Xcode CLI tools. It will also compile the code which shortens the connection init time.

3. Connecting From Robot

You must provide:

NOTE: Keyboard mapping may be very slow, especially on iPads where it may take up to 10 minutes. Use the stored keymap option to avoid the delay for repeated connections.

4. Troubleshooting

5. Automation

To connect to an iOS device from a test script use the Connect command (TPR scripts) or the connect() method (Java test scripts). The argument URL must be in form of  "xcode://localhost"

For example, the following command/method call will connect you to the first detected device:

TPR test scripts:     Connect xcode://localhost device="My iPhone" app="/Users/Joe/myapp.ipa"
Java test scripts:    connect("My iPhone", new File("/Users/Joe/myapp.ipa"), false, false);

Another alternative is to encode the parameters to the connect URL query. This form is also suitable for the -c/--connect CLI connection. You may copy the URL of any of your recent connections from the Tools->CLI Wizard window. Another alternative is to give your connection a name in the Desktop->Connection Manager window and then use it instead of the URL.
TPR test scripts:     Connect "xcode://localhost?device=My%20iPhone&app=/Users/Joe/myapp.ipa"

Touch Screen Support

Only  Portrait and Landscape Left screen orientations are supported. Other ones won't break the connection but the touch events (taps, ...) are likely to be misplaced. This is due to a bug in the underlying framework by Apple.

To change the screen orientation press the F4 key or make your test script press it (Press F4). This is supported since v4.4.3.

The mouse gestures are interpreted as follows:

Keyboard Support

Hardware key mappings:

iOS Hardware Key
Robot Script Key (Action)
Home, Right mouse click
Home key. Long press and double Home press is not supported.
<screen rotation>
Rotate the screen from Portrait to Landscape Left or vice versa.

Other keys are simulated through the soft keyboard. The connection acts as an end user, i.e it switches through the keyboard pages and taps individual keys (characters). Rules:
Most keys on the soft keyboard are equivalent to the PC keyboard (a-z, A-Z, 0-9 etc.). The outstanding soft keyboard mappings are summarized at the table below. Availability of the keys marked with a red asterisk may be subject to the device type and screen orientation.

iOS Keyboard Key
Robot Script Key (Action)
Enter (new line)
The Enter key.
Backspace, Delete
Backspace key. Deletes characters before the insertion point.
Up (Arrow Up)
The shift key switches the keyboard to shifted characters.
It's label and/or appearance changes depending on the keyboard page.
You don't have to press this key manually to type a shifted character
because the connection will switch it on its own.
Right (Arrow Right)
The shift key switches the keyboard to the next keyboard page.
It's label and/or appearance changes depending on the keyboard page.
You don't have to press this key manually to type a character from another page
because the connection will switch it on its own.
The key switches to the next keyboard locale. As the connection supports
(maps) just one locale you may interact with the next keyboard only through taps.
To restore the typing support you must switch back to the base keyboard locale.
Starts dictation.

Keyboard Mapping

The connection performs keyboard mapping on the start up. It is a process where it displays all pages (called "layouts") of the current keyboard and records location of its keys. As this is a slow operation it is recommended to enable storing of the map to a file. The mapping will be performed just once and the subsequent connections will reuse it. Be aware that any keyboard change will invalidate the map, namely switching to another locale (language). Update of the iOS may also introduce changes which invalidate it.

The initial keyboard mapping is performed against the keyboard displayed for the URL field of the Safari browser. As other apps may use a different set of keyboard keys or customize the keyboard the Safari map may not work properly. To fix or re-create the keyboard map manually using the Desktop -> iOS Over Xcode Keymap Editor window:

For script driven keyboard remapping check the iOS Over Xcode Extension plugin (pending).

To delete the current map file and eventually re-create the default Safari one:

WARNING: The connection forces the screen orientation change during the keyboard mapping process. As this step sets off the built-in gyroscope you won't be able to change the screen orientation by manual device rotation. To re-enable this functionality re-plug the device to the USB and avoid programmatic orientation change through reconnection using the stored keyboard.