T-Plan Home
T-Plan Robot Enterprise 4.3.1 Doc Collection

Automating iOS Over Xcode

Last update: 18 August 2016

1. Introduction
2. Setting Up
3. Installing The T-Plan Application
4. Troubleshooting
5. Automation

1. Introduction

T-Plan Robot Enterprise version 4.2 and higher supports automation of iOS 9 devices over Xcode 7 (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. Install Robot on Mac OS X.
  2. Connect the iOS device through the Lightning USB cable to the Mac machine.
  3. Install Xcode 7 on Mac OS X or make sure it's up to date if already installed.
  4. Start Xcode and select Window -> Devices. Make sure you see your device in there. This step will enable the device for development. You will have to repeat it after every device restart. You may close Xcode after this step. It's not needed for the connection to succeed.
Xcode Devices
  1. Start Robot and select the "iOS Over Xcode" connection. It requires two parameters:
T-Plan Robot Logon for Xcode
NOTE: Though the connection requires a locally stored iOS application it will NOT install the app on your iOS device. You must install it beforehand. The local copy is used to verify the application properties and signature. It doesn't even have to be the same app build (version) as the one installed on the device.

The connection capabilities are subject to which application you specify:
  1. Make sure that the iOS device is not locked or in the sleep mode. Select Connect to establish the connection.

3. Installing The T-Plan Application

The T-Plan application delivers a framework for full iOS control. As the application must be signed with your certificate chain we distribute it as an Xcode project. You must compile it under Xcode, install it onto the target device and create the .ipa file. This is a one time process which takes about 10 minutes.


: Download the application project archive. Double click the DMG to mount it. Open Finder and copy the project from the "TPlanApp" drive to a folder on your Mac OS X.

Build the app in Xcode and install it on the device:

  1. Start Xcode. In the welcome screen click "Open another project" and select the TPlanApp.xcodeproj file from the app folder. 
  2. Set the active scheme to your device name.
Xcode scheme
  1. Select the Run button. This will compile the application, install it on the device and start it. The application will appear for a short moment and disappear (suspend). This is expected.
Xcode Run button

Create the IPA build

  1. Select Product -> Archive in the Xcode's main menu.
  2. The Archives window will pop up. Click the Export... button.
Xcode Export
  1. Select the "Save for Ad-Hoc Deployment" option.
  2. Use the provisioning and device support defaults. Xcode will finally save a folder with the TPlanApp.ipa file to your desktop.
  3. Close Xcode. It is not needed any more.

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"
System Pop Ups

System pop ups can not by handled and freeze the connection. Avoid them.

Touch Screen Support

The mouse clicks and drags are mapped onto the touch screen event taps and swipes. Mouse wheel events are not supported and they are ignored.

Keyboard Support

Hardware key mappings:

iOS Hardware Key
Robot Script Key (Action)
Home, Right mouse click
Home key. The key is emulated through the T-Plan Application and it is not available
in the application mode. Double Home press is not supported.

Keys are simulated through the soft keyboard. For this reason the connection supports only keys that are on the currently displayed keyboard.
Soft keyboard mappings follow. 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.
The Next Keyboard key switches the keyboard layout.
Backspace, Delete
Backspace key. Deletes characters before the insertion point.
Hides the keyboard. 
RIGHT* Right
The Arrow Right button goes to the next character. 
LEFT* Left
The Arrow Left button goes to the previous character.  
UNDO* Ctrl+Z
Cancels the typed text.
Set on the Emoji keyboard. Once switched it must be operated with mouse (touch screen).
Typing of keys is disabled until the keyboard gets switched using the mouse back to the key one.