Instrumenting iOS applications

Native and hybrid iOS applications must be instrumented before you can use them to record or play back a test. The application can be instrumented for testing on an iOS device or an iOS Simulator. To instrument an application, you must have the Xcode project for the application under test (AUT) on a Macintosh computer.

Before you begin

Procedure

  1. From the test workbench, select a Test Workbench project for the application under test (AUT) or create a project by clicking File > New > Test Workbench Project.
  2. In the test workbench, click the Display Workbench URL icon Workbench URL and make note of the Workbench URL.

    You need the Workbench URL to connect the Macintosh computer and mobile devices to the test workbench.

  3. Download the RTW-iOS-Build-Archive.zip build archive.

    The build archive contains scripts that are needed to prepare the app for testing.

    1. Open a browser on the Macintosh computer and enter the Workbench URL in the following format:

      http://Workbench_URL:port/mobile

      For example, http://192.0.2.24:7878/mobile

    2. In the Rational Test Workbench - Mac OS Welcome page, follow the online instructions to download the archive.
    3. When the download finishes, unpack the build archive.

      The following folders are included in the build archive: browser, build-script, client, runtime, runtime-bundle.

  4. Attach an iOS device to a USB port on the Macintosh computer.

    Attaching the iOS device via USB allows you to install the instrumented application on an iOS device at the end of the instrumentation process. You can attach multiple, compatible iOS devices to the USB ports.

  5. Instrument the AUT by running the rtwBuildXcode.sh script.

    Instrumentation augments the AUT with code that allows you to record and play back a test. You can install the instrumented AUT on the device automatically by running the script with the device option.

    You can also replace the device option with simu to install the instrumented AUT in an iOS Simulator, or use the both option to install the AUT on all USB-connected devices and the iOS Simulator.

    The rtwBuildXcode.sh script provides support for both Xcode projects, which are described here, and Xcode workspaces. For details about the syntax for Xcode workspaces, see the rtwBuildXcode.sh reference topic.

    Note: You must have the appropriate permissions to run the script. If necessary, run the chmod command to change permissions.
    1. On the Macintosh computer, open the Macintosh Terminal application.
    2. Type the following command to instrument the AUT and send it to the test workbench as an incoming application.
      unpack_dir/build-script/rtwBuildXcode.sh .xcodeproj file Workbench URL options

      where options include device, simu, and both.

      Here is an example of the command line syntax to instrument an AUT named UICatalog and send it to the test workbench and to all USB-connected devices:

      ./rtwBuildXcode.sh /Users/mario/iOSApps/UICatalog/UICatalog.xcodeproj/ http://9.54.119.136:7878 device

      If you specify the Workbench URL in the command line, the instrumented application is automatically pushed to your test workbench or the test workbench of another user.

      You can also send the .zip file that is generated by the script to the test team for testing. The tester can add the AUT to the test workbench by clicking the Add applications to list icon Add applications to list in the Mobile Applications editor.

  6. Add the instrumented version of the AUT to a project in the test workbench.

    Incoming applications must be managed to be used in a test. After you run the rtwBuildXcode.sh shell-script, do one of the following actions to manage the application:

    • Click the incoming application button in the test workbench.
    • In the Test Navigator, right-click an incoming application under Mobile Incoming Applications and click Generate Managed Application.
    Note: If you do not add the AUT as a managed app at this time, it will be done for you automatically when you generate a test at the end of the recording process for the AUT.

    For details, see Importing applications to test in the workbench.

  7. If you did not use the device or both option with the rtwBuildXcode.sh script, you can still add the instrumented version of the AUT to a mobile device later. For details, see Installing instrumented iOS applications.
    Important: When you instrument the app, the output is a file named Rmotapp_name.zip. If the instrumentation process fails, you can troubleshoot the failure by examining the build process traces, which are saved in the log folder inside this ZIP file.

Results

After you complete these steps and the instrumented app is installed on the iOS device, you can start recording tests. For details, see Creating mobile tests.

Feedback