4.8.3. Setting up an iOS AUT for testing

If you want to test an iOS application, you have to prepare the AUT in order to make it testable.

This preparation is designed to be undertaken by a developer who has access to the AUT’s source code as well as knowledge of developing for iOS using Objective-C and Xcode. These instructions assume you are using Xcode 5. For other Xcode versions please adapt the instructions accordingly.

4.8.3.1. Create a Testing Target

We strongly recommend that you create a separate target which contains and uses all the necessary modifications for your AUT to be testable. Once you have created a second target for the testing-enabled version of your AUT to test, you can begin testing simply by running this second target. Having a separate target also ensures that no testing code will be released into the productive version of your app.

The new target will start as a duplicate of your old target. To create the duplicated target:

  1. Select the project file for your app in the Project Navigator.

  2. In the project setting page, click on the black arrow icon ”Show project and targets list” in the main content area in the very top left that hides/shows the project and tar- gets list. To duplicate your target select it and press »COMMAND KEY+D«, or right+click the target and choose ”Duplicate” entry of the context menu.

  3. The new target will be created. We suggest renaming it, e.g. to Jubula Tests. by double-clicking the target in the list of project targets and changing the value to a new name.

  4. You can also (optionally) rename your iOS application to something more meaningful e.g. MyApp (Jubula Tests) by selecting the ”Build Settings” tab and searching for ”Product Name”, then changing the value to a new name. After target name change the product name will also have this new name if you give the next name to ”Product Name” in build settings:

    ${TARGET_NAME}

    Making the AUT testable can be achieved more easily and quickly by using a CocoaPods, however its usage is not obligatory. CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries in your projects. You can find more details about CocoaPods at
    http://cocoapods.org.

    Below, two ways to configure the Testing Target are described: with and without the CocoaPods usage.

4.8.3.2. Configure the Testing Target without CocoaPods

Now that you have a target for your tests, add the tests to that target.

  1. The first step is to link/add the librc.mobile.ios.nativ static library and UIRemoteControl.h file directly into your iOS application. Locate the development/iOS-support.zip file in the installation directory in Finder. Unzip it and drag all of its content into the Project Navigator. In the dialog to choose options for adding these files use ”Add to target” option by checking a checkbox of the target you want to work with from the target list. This lets your project and thereby your iOS application be run as a testable AUT.

  2. With the project settings still selected in the Project Navigator, and the new integration tests target selected in the project settings, select the ”Build Phases” tab.

  3. Under the ”Link Binary With Libraries” section, press the ”+” button.

  4. In the sheet that appears, select CFNetwork.framework and SenTestingKit.framework and click ”Add”.

  5. Then click ”Add other...” in the lower left corner and locate and select the library librc.mobile.ios.nativ.a and click ”Open”.

  6. Next, make sure that the UIRemoteControl.h header file can be accessed. To do this, add the UIRemoteControl.h to the ”Header Search Paths” build setting. Start by selecting the ”Build Settings” tab of the project settings, and from there, use the filter control to find the ”Header Search Paths” setting.

  7. Double click the value, and add the file UIRemoteControl.h to the list. If it’s not there already, you should add the $(inherited) entry as the first entry in this list.

  8. The iOS support takes advantage of Objective C’s ability to add categories to an object, but this isn’t enabled for static libraries by default. To enable this, add the -ObjC and -all_load flags to the ”Other Linker Flags” build settings.

  9. If you build for iOS Simulator, but linking against dylib built, build error with linker command failed might occur. To avoid this, add to the ”Framework Search Paths” build setting the line ”$(SDKROOT)/Developer/Library/Frameworks” right after the $(inherited) entry.

  10. Finally, add a preprocessor flag to the testing target so that you can conditionally include code. This will help to make sure that none of the testing code makes it into the production app. Call the flag RUN_FUNCTIONAL_TESTS and add it under the ”Preprocessor Macros”. Again, make sure the $(inherited) entry is first in the list.

4.8.3.3. Configure the Testing Target

You need to have CocoaPods installed on your machine before you start making your AUT testable with its help.

To configure the Testing Target with CocoaPods, you need a specification - .podspec file. It describes a version of the Pod library and includes details about where the source should be fetched from, what files to use, the build settings to apply, and other general metadata such as its name, version, and description. We provide two types of such files. The rcmobile.podspec file will add a static library, while the rcmobile-debug.podspec file will import all source files to the project dynamically, which allows you to change code for testing and to debug more deeply.

  1. In the installation directory you will find a development folder and an iOS-support zip archive inside it which you have to unzip. There you will see a rcmobile.podspec. rcmobile-debug.podspec is located in a ”development/git/com.bredexsw.jubula.core/com.bredexsw.jubula.rc.mobile.ios.nativ” folder of the installation directory.

  2. In a directory of your AUT XCode project location create a Podfile by running this command in a terminal:

    $ pod init

  3. Open the newly created Podfile and add ”rcmobile” static library (as a local source) or dynamically linked source files with help of ”rcmobile-debug” by entering the following line inside the ”do ... end” block for each target you want to make testable:

    target "TargetName" do
    pod ’rcmobile’, :path => ’iOS-support-path’
    end
    
    or
    
    target "TargetName" do
    pod ’rcmobile-debug’, :path => ’sources-path’
    end
    

    ”iOS-support-path” is the path where rcmobile.podspec file is located. ”sources-path” is the path where rcmobile-debug.podspec file and folder with sources are located. By default both of them are located in the ”development/git/com.bredexsw.jubula.core/com.bredexsw.jubula.rc.mobile.ios.nativ” folder of the installation directory. Other Podfile content may remain as it is.

  4. Install the Podfile to add the library to the AUT by running this command in the terminal:

    $ pod install

    You must use the »’« (apostrophe) symbol around the library name and the path in the Podfile to install it, otherwise you will receive the error "Invalid ’Podfile’ file".

  5. From now on the project-name.xcworkspace file must be used instead of the project file.

  6. If you have used the rcmobile.podspec, the static library is now added to the project. If you used the rcmobile-debug.podspec file all source files are dynamically linked to the project through the alias and you can find them under the Development Pods library in the XCode workspace of your project.

4.8.3.4. Add hook into the AUT

Finally, the app needs a hook so that it actually allows the attachment and running of the tests when executing the Tests target. This is achieved by using the RUN_FUNCTIONAL_TESTS macro that was defined in the preceding section. This ”preprocessor macro” is only defined in the testing target, so the remote controlling won’t be possible in the regular target. To allow your AUT to be remote controlled, add the following code to your application delegate:

...
#if RUN_FUNCTIONAL_TESTS
#import "UIRemoteControl.h"
#endif
...

and the following code to the end of its - (void)applicationDidFinishLaunching[withOptions]: method

...
#if RUN_FUNCTIONAL_TESTS
    [UIRemoteControl attach];
    // alternatively you can
    // allow the UIRemoteControl 
    // to use a specific port number 
    // on the iOS device 
    // by using:
    // 
    // [UIRemoteControl attach:<portNo>];
    // 
    // this is necessary
    // e.g. when you're running 
    // different AUTs in parallel on 
    // the same iOS device
#endif
...

Everything should now be configured. When you run the AUT tests target it will launch your app and allow the ITE to remotely attach (on the port specified, or on 11022 if none is entered) and execute tests.

If you do not follow the above steps, the AUT Agent will not be able to communicate with your AUT!

This documentation is derived from the KIF installation documentation (http://github.com/square/KIF) as we make use of KIF internally.



Copyright BREDEX GmbH 2015. Made available under the Eclipse Public License v1.0.