iOS Extension Plugin

Contents:

1. Overview
2. Plugin installation
3. Usage
3.1 Start Script
3.2 Kill Script
4. Troubleshooting

1. Overview

The iOS Extension Plugin adds new features to T-Plan Robot Enterprise test scripts where Robot is hosted on a Mac OS X environment and automates an iOS device connected over the USB cable. It is typically used for automating of applications developed on the same Mac machine.

Versions 1 and 2 support:

Start an application on the iOS device
Kill the previously started iOS application

Requirements and limitations:

Robot must be running on Mac OS X with Xcode and Instruments installed.
The iOS application must be available in the Mac file system (.app or .ipa). It must be built for the target iOS device (iPhone, iPad) and it must be signed with a valid locally installed key chain.
The iOS device must be connected to the Mac machine over a USB cable and the target application must be already installed there. On iOS 8 and higher the Settings->Developer-Enable UI Automation option must be enabled.
As the plugin relies on Mac OS X technologies only its scripts (commands) can be called from Robot test scripts even if there's no iOS connected over the iOS Mirror or VNC Server (Veency) connection.

The plugin is primarily designed for test scripts written in the TPR language. To call the plugin scripts from Java either use the DefaultJavaTestScript.run() method or use the script instance approach described in the Java Script Basics document.

Should you have any questions or suggestions contact the T-Plan support. For the list of other plugins provided by T-Plan go here.

2. Plugin installation

The plugin requires T-Plan Robot 3.5.2 or higher. To install the plugin download it from:

Version 2: https://downloads.t-plan.com/releases/robot/plugins/iosextension_v2.zip

OPTION 1:

Unzip the file and copy the iosextension.jar file to the plugins/ directory under the Robot installation directory. This will make Robot load the classes on the start up. Make sure to remove any older versions of the plugin.
Start or restart Robot.

OPTION 2:

Unzip the file to a location on your hard drive.
If you plan on using the plugin in the TPR scripts put the following command to the beginning of each test script:
Include "<location>/iosextension.jar"
If you plan on using the plugin in Java test scripts put the iosextension.jar file onto the Java class path.

To uninstall the plugin simply delete the file.

3. Usage

The plugin contains two Java test scripts:

Script Name	Description
`com.tplan.ios.Start`	Start an application on the iOS device.
`com.tplan.ios.Kill`	Kill the application started previously with Start.

The plugin scripts are to be called from TPR test scripts using the Run command. The command instances may be easily created using the Command Wizard tool. To edit an existing Run command right click it and select Properties in the context menu.

EXAMPLE:

Start an application on the iOS device, perform some testing and kill it:

// Presume that iosextension.jar is in the script folder Include "iosextension.jar" // Start the MyApp.app application. You may also use the .ipa file. // We presume that there's just one iOS device attached so we don't // have to specify the UDID. Run "com.tplan.ios.Start" file="/Users/robert/Downloads/MyApp.app" // Wait for a few seconds to ensure that the application starts properly Wait 5s // Perform testing here // ... // Kill the application Run "com.tplan.ios.Kill"

3.1 Start Script

DESCRIPTION

The com.tplan.ios.Start script starts the application specified by the file parameter on the iOS device attached over the USB cable or onto the iOS simulator. The application must be already installed on the device.

Device identification:

If the Unique Device Identifier (UDID) is specified through the udid parameter the script will drive the specified device.
When the UDID is not specified:

The script will connect to the first device returned by the system (the order is not specified)
If there's no attached device the script will look for a running iOS simulator.

The script enforces one started application at a time:

If the application is already started through the Start script it gets restarted (killed and started again)
If there's another application started previously with Start it gets killed first.

Auto shut down:

Unless the Kill script gets called explicitly the application will be killed automatically after the calling script (TPR or Java) stops executing.

iOS 8 support:

iOS 8 and higher must have the Settings->Developer-Enable UI Automation option enabled. When it's disabled the app just flashes on the screen and gets terminated.

As the script receives no feedback on the application start completion it is recommended to add a delay (Wait) for a reasonable amount of time after the Start call. Should you experience a failure see the Troubleshooting section for help.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.ios.Start file=<file> [udid=<identifier>]

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.ios.Start", "<file> [, "udid", "<identifier>"] );

* Red color indicates obligatory parameters

OPTIONS

file=<file>

- Mandatory full path to the application folder (.app) or the AdHoc or Enterprise application archive (.ipa). To find the latest .app build under Xcode open Window->Organizer, select the Projects view, click the target application and open the Derived Data path in Finder. Then navigate to Build->Products and search the Debug-<target> folders for the .app. You may copy it from here to a stable location for automation purposes.

udid=<identifier>

- Optional Unique Device Identifier (UDID) of the device to work with. See instructions on how to get the UDID of your device. When the UDID is not specified the script will connect to the first device returned by the system (the order is not specified). If there's no attached device the script will look for a running iOS simulator.

RETURNS

The command returns 0 (zero) when the application gets started properly. Otherwise it returns 1 (one) or the system exit code. The failure is also logged into the execution log. See the Troubleshooting section for help.

EXAMPLES

See the Usage chapter.

3.`2` Kill Script

DESCRIPTION

The com.tplan.ios.Kill kills the application started previously with the com.tplan.ios.Start script. If there's no such application the script does nothing.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.ios.Kill

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.ios.Kill");

* Red color indicates obligatory parameters

OPTIONS:

None.

RETURNS

The command always returns 0 (zero).

EXAMPLES

See the Usage chapter.

4. Troubleshooting

This is the list of often experienced errors and their resolutions.

The Start script fails with “Failed to start Instruments daemon for ‘xxx’ on ‘xxx’ (The service is invalid.)"

Start Xcode and open Window->Organizer. This is often enough to make it work.

The Start script fails with “Instruments Trace Error: The app must be signed with a development identity (e.g. iOS Developer)”

Make sure that the app is signed with the developer certificate (“iOS Developer: <name>”) and not the distribution one (“iPhone Distribution: <name>”). This can be achieved in the Xcode project settings. Should you need to resign an Ad-Hoc or Enterprise build (.ipa) use the resigning steps.

The application flashes on the screen and disappears immediately.

This typically happens on iOS 8 when the Settings->Developer-Enable UI Automation option is disabled. Enable it.