Android apps

In this chapter, you’ll learn how to instrument an Android app.

Attention
For Android 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 APK. This is why we recommend you do NOT publish instrumented apps to Google Play.

Before you can instrument and deploy an app for automation with Ranorex, complete the following preparations:

Prepare the app

Make sure you can access the APK from the computer on which Ranorex Studio is installed. We recommend that you store a copy of the APK in a folder on that computer.

Prepare the mobile device

• Apply the device settings.
• Connect your device to the computer on which Ranorex Studio is installed.
• Start the Ranorex Service App on the device.

Note
You can instrument and then immediately deploy the app to your mobile device with the Instrumentation Wizard. If you want to do so, you must connect the mobile device to your computer via USB (recommended).

Instrumentation example

For our example, we’ll instrument the Dropbox app. The app is a product of Dropbox, Inc., whose terms and conditions for downloading and using the app apply.

In preparation for instrumentation, we’ve stored the app in the folder Android app testing on the computer Ranorex Studio is installed on.

1. Start the Instrumentation Wizard and confirm the Windows security dialog.

2. Select Android 

3. Click Next.

Add APK file

1. Click Browse… to select the APK.

2. The APK is loaded in the Instrumentation Wizard.
   
   
   

3. Select Manually Configure the parameters and click Settings… to apply your selected advanced settings. These are explained at the end of this page under Advanced Android instrumentation settings.
4. Auto-detect is selected by default. This option automatically adjusts instrumentation settings and re-runs the instrumentation process a couple of times.
5. Click Next to start the Instrumentation process.
6. When the instrumentation process completes the Operation successful message displays, note that this screen details settings changes that were auto-detected during the instrumentation wizard. Click Finish to close the wizard.
   

Note
If the process fails, please first check you’ve applied the device settings correctly and connected the device properly. A common problem is also that another program is consuming too many resources, slowing down instrumentation to the point of a timeout error. Either close all other programs or increase the Instrumentation timeout in the settings.

If the app has been instrumented and deployed correctly, you will see the following on your device:

1. The instrumented app appears in the Ranorex Service App.

2. The instrumented app appears on your device’s home screen.

In Ranorex Studio, you can see the app has been instrumented correctly if it appears for selection when creating a mobile test.

These settings are available as part of the instrumentation dialog, as explained on this page under Specify APK and settings. They contain options for configuring instrumentation for special types of Android apps and are also useful for troubleshooting.

1. AndroidManifest.xml addon settings
   

   • Change extractNativeLibs attribute to true: When set to True, Ranorex changes the extractNativeLibs attribute to true if it is defined in AndroidManifest.xml.
   • Change testOnly attribute to false: When set to True, Ranorex sets the testOnly attribute to false if it is defined in AndroidManifest.xml
   • Custom R.id package name: Allows you to specify a custom class name for locating resource IDs (e.g. com.ranorex.demo.R). By default, Ranorex Studio will search for IDs in .R.
   • Enable web testing: When set to True (by default), show DOM content of WebViews in the UI element tree in Ranorex Spy. Has a significant performance impact.
   • Full image comparison: When set to True, uses a more robust image comparison mechanism to determine resource IDs for images. Decreases startup performance.
   • Tree simplification: When set to False, no postprocessing of the UI element tree takes place. This means a more complex element tree is displayed in Ranorex Spy, which may be useful for automating third-party Android controls.

    

2. Instrumentation mode
   
• Resign only: When set to True, Ranorex will perform only changing the signature of the chosen APK file. By default, should be set to False.
• Skip deployment: When set to True, Ranorex will not perform the deployment process. It means that Ranorex will not attempt to upload the chosen IPA file to the chosen endpoint. It may be useful if one wants to deploy the IPA using another device. By default, this option is set to False.
• Skip instrumentation: When set to True, Ranorex will not perform the default instrumentation process for the chosen APK file, including the signing of the APK. This option may be useful for deploying any APK. By default, this option is set to False.
3. Instrumentation options
   
   • Auto-detect: When set to True (by default), automatically adjusts instrumentation settings and re-runs the instrumentation process up to four times.
   • Avoid resources decompiling: If set to True (by default), resources are not decompiled and recompiled during instrumentation. This means the following:
   • • Resources will not be decompiled and the arsc is kept intact without any decoding.
     • The AndroidManifest.xml is decoded by Ranorex Studio and not by the default Android tools embedded in the APK.
   • When enabled, speeds up the instrumentation process significantly. Only set to False if you need to make changes to the resources in the instrumented APK.
   • Debug information: When set to True, add additional information to the instrumentation log file. Useful for troubleshooting instrumentation issues.
   • Multidex application: If your mobile app and the libraries it references exceed 65,536 methods and this option is set to False, you will encounter a build error during instrumentation. This is because your app has reached the limit of the Android build architecture. To resolve this, set this option to True and retry instrumenting.
   • Other instrumentation flags: Here you can add individual flags to apply to the instrumentation process. These are simply the settings you find here, except in parameter form, e.g. -nores for the option Avoid resources decompiling.
   • Redistribute smali: If you receive an error message that indicates issues with the number of methods in the decompiled smali code, set this option to True. Ranorex Studio will then distribute the code across multiple files.
   • Static instrumentation: If you receive an error message of the type “Register count exceeds…” or “Method count exceeds 65k”, set this option to True. Ranorex Studio will then use a special instrumentation mechanism that highly reduces the amount of code that needs to be added to user activities.
     Try the option “Redistribute smali” before activating this option!
4. Signing APK
   
• If you want to sign your APK, you need to specify all of these options.