Instrumenting iOS applications

An iOS application must be instrumented before you can use it 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 project for the application under test (AUT). If necessary, create a test 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.

    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 the test workbench. If you omit the Workbench URL, the script generates a .zip file that you can send to a tester 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.

      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 on all USB-connected devices and the iOS Simulator.

      For details about the command line arguments for rtwBuildXcode.sh, see Command line to launch the rtwBuildXcode.sh script.

  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.

Results

After you complete these steps and the instrumented app is installed on the iOS device, you can start recording tests. Testers should see Using a script to install instrumented iOS applications or Using iTunes to install instrumented iOS applications for instructions on how they can install the instrumented app on their own iOS devices.

Feedback