T-Plan Robot Enterprise iOS 7, 8 & 9 Plugin
Contents:
1. Overview
2. Static Library Linking
3. Dynamic Library Linking
4. Application Automation
1. Overview
The T-Plan iOS 7, 8 & 9 Plugin enables testing of iOS applications
on iOS version 7 and higher, using the iOS Mirror connection.
- For testing on iOS version 5 & 6 use the iOS6 Server
application. This will give you control over the whole OS.
- As Apple tightened the security in iOS
version 7, it is not possible to control the touch screen
and keyboard at the OS level, like for iOS 6. The only known way of
automation is to add the automation capability (the T-Plan
library) to the application under test (AUT). This will
allow you to automate the application after it gets started.
- I.e. Currently Robot cannot control the whole iOS, or any other
functionality outside of the application, like it did using the iOS6 Server method.
- Unfortunately for iOS 8, the same restrictions on full device control are still in place. Apart from including the plugin into your application, there is no invasive source instrumentation compile time code required, like in competitive products. As our solution works at the UI level, we are unique in not requiring code hooks and other testing specific code to be included in your application by developers.
The library plugin is delivered both in the static and dynamic
form:
- The static library (.a format) must be added to the
Xcode project and the application source code must be updated
with two lines of code. This approach is suitable for QA
organizations which have access to the application source code
and are allowed to build the AUT on their own. This way is also
recommended for applications relying on the key chain APIs. For
details see the the Static Library Linking
chapter.
- The dynamic library (.dylib
format) may be injected to an existing Ad-Hoc or Enterprise
application in the .ipa format. This approach is suitable where
the QA organizations which don't have access to the application
source code and/or the build process. For details see the the Dynamic Library Linking chapter.
From the point of T-Plan Robot Enterprise, applications with the iOS
Plugin can be automated the same way as iOS 5 & 6 with the
T-Plan Server. The existing automation test scripts designed against
iOS 5/6 can be reused, as long as they don't rely on any
functionality outside of the application. For example, if your iOS
5/6 test script taps the application icon on the home screen to
start, it this will not work any more and you will have to start the
app manually.
2. Static Library Linking
The static library is easy to use:
- Get the static library package from the T-Plan Support
and unzip it to your Mac OS X machine with Xcode 5 and your
application project.
- Right click the Frameworks
folder in the Xcode project view, select "Add Files
To ..." and add the
libTPlanTestLib.a
file.
- Locate your application delegate
class. If you are not familiar with the code right click the
topmost project node, select "Find in Selected Groups"
and search for a class containing "didFinishLaunchingWithOptions" or "AppDelegate".
Please notice that your project will have an 'AppDelegate'.h, as well as another file with a '.m' extension.
The .h extension denotes the Header file and the .m denotes the Implementation file. Together, they form the AppDelegate class.
[Note: If you are unfamiliar with Xcode etc. you most likely will be adding the code in points 2&3 below, into the '.m' implementation file.]
Once you have
it:
- Right click its parent folder in
the project view, select "Add Files To ..." and
add the
TPlanTestLib.h
file.

[Note: Select the 'Copy items if needed' checkbox to include the files into your project directory.]
- Open the app delegate class in the
editor and insert the import clause to the header section of the '.m' implementation file:
#import
"TPlanTestLib.h"
*Note: Depending on your project settings etc. you may wish to add the above code into the header ('.h') AppDelegate class file instead.
- Locate the
didFinishLaunchingWithOptions
method and add a call of the setup_tplan()
function to the very beginning of its body:
- (
BOOL
)application:(
UIApplication *
)application
didFinishLaunchingWithOptions:(
NSDictionary
*)launchOptions
{
setup_tplan();
<...other code>
}
- Once you have everything setup, the code should look like the screenshot below:

- Select the name of the project in the project navigator.
- The project editor appears in the editor area of the Xcode workspace window.
- Select the name of a target from the list in the left column of the project editor.
- The screenshot below shows the T-Plan WebViewer project selected in the project navigator. The T-Plan WebViewer iOS target is selected in the project editor.

- Click 'Build Phases' at the top of the project editor.
- Navigate to 'Link Binary With Libraries'.
- Using the '+' symbol click to 'Add items'.
- Search or scroll navigate in the list to the item named 'MediaPlayer.framework'.
- Select 'Add' and your new item should be displayed in the list as per the screenshot above.
- Note: This framework is required for the automatic starting and stopping of the AirPlay Mirroring slider on the device.
- Build the application and start it on the device in the
standard way. See the Application
Automation chapter for further instructions.
3. Dynamic Library Linking
The dynamic library package consists of the library
binary (.dylib) and the injector script. It adds the
library to your iOS7 ad-hoc application (*.ipa) without having to
modify the source code or rebuild it in Xcode. It works as
follows:
- The application archive is unzipped
and the library is copied in there.
- The script adds the library to the
Mach-O header of your application executable. This ensures that
the library gets loaded on the application start up. As this
operation doesn't touch the part of the executable that contains
your application code, it is generally considered safe and low
invasive.
- As any modification of the
application package invalidates its signature, the application
gets re-signed with your distribution certificate and packed
back to the .ipa format.
To enable dynamic linking get a Mac OS X machine (10.8+
recommended) and configure it as follows:
- Make sure to have the latest Xcode 5 and Command Line Tools. To verify:
- Start Xcode, select Xcode->About Xcode, version must be 5+
- Select Xcode->Preferences
and click the Downloads button. If you see "Command Line Tools" available in the Components
section then install it.
Requirements:
- Mac OS X 10.7 (Mountain Lion) or later.
- An Apple Developer Account.
- Xcode installed (v5.x or higher required) with the Command
Line Tools package. To install the tools:
- Start Xcode and select Xcode->Preferences in the menu.
- Switch to the Downloads tab.
- Select Install next to the Command
Line Tools package.

- Get the dynamic library package from the T-Plan Support.
Once you have it:
- Unzip it to your hard drive to a
path with no spaces in its name.
- Open a terminal and change to the
package directory.
- To verify whether your Python is
configured properly execute:
./test_python.sh
- The injector script relies on Python 2.7.6. If your
version is lower then install v2.7.6. Install it also if the version you have is 3.x
because the injector doesn't work with Python 3 (this may be
fixed later).
- If Python fails with an error
like: "ImportError: No module named pkg_resources"
then install setuptools:
sudo curl
https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
| python
- If Python fails with an error like: "pkg_resources.DistributionNotFound:
altgraph>=0.10" or "pkg_resources.VersionConflict:
altgraph 0.9" then upgrade the altgraph
library:
/Library/Frameworks/Python.framework/Versions/2.7/bin/easy_install
--upgrade altgraph
- Should you wish to call another Python instance edit
test_python.sh
and set the PYTHON
variable to the target
python command.
- Get the provisioning profile and import the distribution
certificate into your local keychain as is described in Step
1 and 2 below.
Note:
Remember the distribution certificate
name because you will need it later. You may also get it through
the Applications->Utilities->Keychain Access
tool of the Mac OS.
Step 1: Create the
provisioning profile
- Sign in to the Apple
Developer Center using your Apple ID.
- Navigate to the Certificates, Identifiers & Profiles section.
- Then navigate to the Provisioning Profiles section.
- Click the "+" button to create a new profile:
- Select the "Ad Hoc" profile type.
- Select the Xcode iOS Wildcard App ID.
- Select the appropriate distribution certificate.
- Select the devices you wish to allow to run the server on.
You must add at least one device.
- Provide the profile name, for example "T-Plan Server" and select Generate.
- Select Download to download the
"T-Plan
Server.mobileprovision"
file to your
local file system.
Step 2: Get the certificate
- Go to Member Center->Certificates, Identifiers &
Profiles and select the Certificates link in the iOS Apps group.
- Download the iOS (iPhone) distribution certificate.
- Open the certificate from Downloads or Finder.
This will import it into your key chain. Then look at the
certificate under the My Certificates screen of
the Keychain Access window and jot down the name.
It should look like "iPhone Distribution: <name>".

- Once your environment is set up you may modify your application
through:
./add_dylib_and_resign.sh <application>.ipa
<profile>.mobileprovision
"<distribution_certificate_name>" "<team_ID>"
where
"<distribution_certificate_name>"
is the certificate name. For example, for the certificate on the above picture it is "iPhone Distribution: Company XYZ"
,
"<team_ID>"
is the team ID assigned by Apple. For example, for the certificate on the above picture it is "ABCDE12345"
. This option is required if the target iOS version is 8.2 or higher. Resigning without the team ID will work only on iOS 8.1 and lower.
- If the script executes correctly it will create a new package called
<application>-modified.ipa
. See the Application Automation chapter for further
instructions.
IMPORTANT: This process will only work for applications that
have been built for Ad-Hoc or Enterprise distribution. Applications
downloaded from the Apple Store can not be modified because they are
signed by Apple and protected through DRM. The script will reject
them.
Troubleshooting
1. Loading application onto device using iTunes stays at "Installing..." after resigning the application process
This issue as per the image below, is a direct consequence of the changes in the "Entitlements" signing process; introduced by Apple since iOS 8.2.

To get a better understanding of the issue, please navigate to the "Devices" section in Xcode 6.x and install the application using the recognised developer method, as per the below image.

If you install the application through this method, and you signed with invalid entitlements, you will most likely receive the error as per the below image.

If this error occurs please follow the instructions below:
- Navigate to your "Keychain Access" application in the "Utilities" application folder.
- As per the screenshot below, navigate to the "My Certificates" section.

- As per the screenshot above, make a note of your "Developer" key name, and the "Distribution" id in brackets.
E.g. in the example above, my "Developer" key is: "iPhone Developer: Charlie Wheeler (T-Plan Limited)"
- IMPORTANT! For the correct command to be run when injecting the dynamic libraries, it is very important to note the name in brackets. In the above example and screenshot this is "T-Plan Limited".
The key team id name for the query string to be used is therefore my "Distribution" key, NOT my "Developer" id.
I.e. The
key team id name to be used is "ABCDE12345", NOT "12345ABCDE".
- The Terminal command string to run for my example is:
./add_dylib_and_resign.sh <application>.ipa XC_Ad_Hoc_.mobileprovision "iPhone Developer: Charlie Wheeler" "ABCDE12345"
Note: Running the command with the wrong team id will result in the entitlements error.
4. Application Automation
To automate the application use T-Plan Robot Enterprise 3.5 or
higher running on a Windows or Mac OS X machine with Java 1.7
installed.
Steps:
- Install the application on your iOS device. If you are using
the .ipa format see the Installation from Mac OS
and Installation from Windows paragraphs of our iOS Mirror
document.
- Find out the IP address of your
device:
- Tap Settings in the
iOS home screen
- Navigate to Wi-Fi
and tap the blue
"(i)"
icon to the right from
the name of the wi-fi network you are connected to.
- Start mirroring between the device
and the Robot machine using Reflector or Airserver.
- Start the tested application on the
device, and while it is in the foreground connect to it from
Robot:
- Connection Type:
iOS
Mirror
- Server:
<device_IP_address>:5909
For more informaiton please view
the Automation Tips section of our iOS Mirror document.