Instrument apps

Before you can use test automation with a mobile app, you must instrument the app. Instrumenting an app means configuring the app so that Ranorex Studio can access the GUI and functions of the app to create and run an automated test.

Instrumenting apps work differently for Android and iOS, which is why the procedures are explained separately in this chapter.

Attention
Whenever you update Ranorex Studio (i.e. use newer automation libraries/Ranorex Service App), reinstrument your apps. Otherwise, automation may not work as intended.

Attention
For iOS developers: As part of the instrumentation process, the app will be compiled with the Ranorex automation library. This library adds additional functions and permissions to your IPA.
Do NOT publish instrumented apps to the App Store.
Instrumented apps do not work with TestFlight.

For web tests on Android devices, the pre-instrumented Ranorex web browser for Android is required.

Download and install the Ranorex Web Browser

1. Go to Mobile Download to download the Ranorex Web Browser for Android.

2. Select the pre-instrumented browser in the mobile download archive:
   

3. Install it as you would any other app on your mobile device.
   

1. 1. Opened Ranorex Web Browser.

   2. The app is also listed in the Ranorex Service App, which indicates that it has been instrumented correctly.

For web tests on iOS devices, the preinstrumented Ranorex web browser for iOS is required.

Download and install the Ranorex web browser

1. Go to Mobile downloads to download the Ranorex Web Browser for iOS.

2. Select the pre-instrumented browser in the mobile download archive:
   

3. Install it as you would any other app on your mobile device.
   

1. 1. Opened Ranorex Web Browser.

   2. The app is also listed in the Ranorex Service App, which indicates that it has been instrumented correctly.

You need to instrument Android apps before you can use them for mobile tests with Ranorex Studio.

Note
It’s not possible to instrument apps that have been downloaded from Google Play.

Reference
Instrumenting Android apps is explained in the following chapter Interfaces and connectivity > Ranorex Instrumentation Wizard > Android apps.

You need to instrument iOS apps before you can use them for mobile tests with Ranorex Studio.

Attention Instrumenting iOS apps is challenging and not self-explanatory. It’s best done by experienced iOS developers. To allow you to evaluate iOS testing with Ranorex Studio without the hassle of instrumenting your app, we provide the pre-instrumented KeePass app for your use.

Attention For iOS developers: As part of the instrumentation process, the app will be compiled with the Ranorex automation library. This library adds additional functions and permissions to your IPA.
Do NOT publish instrumented apps to the App Store.
Instrumented apps do not work with TestFlight.

Note
It’s not possible to instrument apps that have been downloaded from the App Store, as they are subject to DRM restrictions.

Instrumenting an iOS app means integrating a special Ranorex library (Ranorex libs) into the source code of the app and then compiling it. Afterward, the app needs to be signed with a P12 certificate and the proper provisioning profile.

For more information on iOS development and release procedures, please refer to the official Apple documentation.

There are two ways to instrument iOS apps:

• With the Ranorex Instrumentation Wizard (recommended)

  Instrumenting iOS apps using the Instrumentation Wizard is explained in Interfaces and connectivity > Ranorex Instrumentation Wizard > iOS apps

• Manual instrumentation of the source code in iOS with Xcode iOS developers can integrate the Ranorex library, compile it, and sign the app manually using Xcode.
  Manual instrumentation is explained in the following chapter Web and mobile testing > Advanced mobile testing > iOS source-code instrumentation

Attention
After instrumenting and deploying the iOS app for the first time, start the app manually once! Otherwise, it will not be visible within the Ranorex Service App.

Ranorex provides a preinstrumented iOS sample app for evaluation and learning purposes. The app is KeyPass for iOS, distributed under the GNU General Publice License. For information regarding the copyright holder and the license agreement, go to https://keepass.info/help/v1/license.html.

Download and install the sample app

1. Go to https://support.ranorex.com/rxApp.

2. The mobile download archive is categorized according to Ranorex Studio versions and mobile OS. Download the RxMiniKeePass app for iOS devices for your Ranorex Studio version.

3. Next, install the sample app as you would any other app on your device.
   

1. The RxMiniKeypass app appears on your home screen.

2. Since the app is already instrumented, it also automatically appears in the Ranorex Service App.