iOS Extension Plugin For T-Plan Robot Enterprise
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 Test
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:
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:
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
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
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.
