T-Plan Robot Enterprise Doc Collection

12/09/14

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:

1. 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.
2. Right click the Frameworks folder in the Xcode project view, select "Add Files To ..." and add the libTPlanTestLib.a file.
3. 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:

1. 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.]

2. 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.

3. 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>
}

4. Once you have everything setup, the code should look like the screenshot below:
   
   

4. Select the name of the project in the project navigator.
   • The project editor appears in the editor area of the Xcode workspace window.
     
     
1. 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.



2. Click 'Build Phases' at the top of the project editor.
3. Navigate to 'Link Binary With Libraries'.
4. Using the '+' symbol click to 'Add items'.
5. Search or scroll navigate in the list to the item named 'MediaPlayer.framework'.
6. 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.
     
     
5. 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:

1. The application archive is unzipped and the library is copied in there.
2. 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.
3. 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:

1. 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:

1. Start Xcode and select Xcode->Preferences in the menu.
2. Switch to the Downloads tab.
3. Select Install next to the Command Line Tools package.



2. Get the dynamic library package from the T-Plan Support. Once you have it:
   1. Unzip it to your hard drive to a path with no spaces in its name.
      
   2. Open a terminal and change to the package directory.
   3. 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.
     

3. 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

   1. Sign in to the Apple Developer Center using your Apple ID.
   2. Navigate to the Certificates, Identifiers & Profiles section.
   3. Then navigate to the Provisioning Profiles section.
   4. Click the "+" button to create a new profile:
   1. Select the "Ad Hoc" profile type.
   2. Select the Xcode iOS Wildcard App ID.
   3. Select the appropriate distribution certificate.
   4. Select the devices you wish to allow to run the server on. You must add at least one device.
      
   5. Provide the profile name, for example "T-Plan Server" and select Generate.
   6. Select Download to download the "T-Plan Server.mobileprovision" file to your local file system.

   Step 2: Get the certificate

   1. Go to Member Center->Certificates, Identifiers & Profiles and select the Certificates link in the iOS Apps group.
   2. Download the iOS (iPhone) distribution certificate.
   3. 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>".

   

4. 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.

5. 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:

1. Navigate to your "Keychain Access" application in the "Utilities" application folder.
2. As per the screenshot below, navigate to the "My Certificates" section.
   
   
   
   
3. 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)"
4. 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".
5. 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:

1. 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.
2. Find out the IP address of your device:
1. Tap Settings in the iOS home screen
2. 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.
3. Start mirroring between the device and the Robot machine using Reflector or Airserver.
4. 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.