To automate an Android application with Ranorex Studio, you must instrument the app first.
Important: As part of the instrumentation process, the app is compiled with the Ranorex automation library. This library adds additional functions and permissions to your APK. The recommendation is to NOT publish instrumented apps to the Google Play Store.
Prepare the app and the mobile device
Before you start instrumentation, make sure the following requirements are met:
- Store a copy of the APK file on the computer where Ranorex Studio is installed.
- Prepare the Android device with the required developer settings.
- Connect the device by USB if you want to instrument and deploy the app directly to the device.
- Make sure the Ranorex Service App is installed and running on the device.
Important: Starting with Ranorex 12.4.1, you do not need elevated privileges ("Run as Administrator") to run the Instrumentation Wizard. However, you must re-instrument your apps after upgrading to this version.
Instrument the app
Use the Instrumentation Wizard to instrument and deploy your Android application.
- Store the APK file on the computer where Ranorex Studio is installed.
-
Start the Instrumentation Wizard.
-
Select Android and click Next.
-
Select the device you previously added as an endpoint.
-
The instrumentation wizard checks the prerequisites. If the JRE is not found, you have to locate the JRE installation folder manually.
You can also use the Install JRE section to access the download link. After completing this step, click Save and Proceed, and then click Next. -
On the next screen, switch to the Mobile app testing tab
- Select the APK file you previously generated.
- By default, Set instrumentation parameters is set to Auto-detect. To configure the parameters manually, select Settings…
-
To start a mobile web test in Android, switch to the Mobile web testing tab. For more information, see Android mobile web test example.
-
To update Ranorex Service, Ranorex Web Testing, and Mobile app testing, switch to the Update service tab.
- Click Finish to complete the instrumentation process.
After successful instrumentation:
- The instrumented app appears in the Ranorex Service App
- The app appears on the device home screen, ready for testing
- The app is available for selection when creating a mobile test in Ranorex Studio
Note: The process can fail if you don’t apply the device settings correctly, don’t connect the device properly, or have other programs consuming too many resources. In this case, close all other programs or increase the Instrumentation timeout in the settings.
Obfuscated apps
If Ranorex Studio cannot track UI elements in an Android application, the app may use code obfuscation. Common obfuscation tools include R8, ProGuard, and DexGuard. Obfuscation can change the application structure and prevent Ranorex Studio from recognizing UI elements correctly. When possible, use a non-obfuscated APK for instrumentation and testing.
Advanced instrumentation settings
These settings allow you to configure instrumentation for special types of Android apps. These are also useful for troubleshooting.
AndroidManifest.xml addon settings
Setting |
Description |
| Change extractNativeLibs attribute to true | Changes the extractNativeLibs attribute to true if defined in AndroidManifest.xml. |
| Change testOnly attribute to false | Sets the testOnly attribute to false if defined in AndroidManifest.xml. |
| Custom R.id package name | Specifies a custom class name (for example, com.ranorex.demo.R) for locating resource IDs. By default, Ranorex Studio searches for IDs in .R. |
| Enable web testing | Shows DOM content of WebViews in the UI element tree in Ranorex Spy (enabled by default; high performance impact). |
| Full image comparison | Uses a more robust image comparison mechanism to determine resource IDs for images. Decreases startup performance. |
| Tree simplification | When 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. |
Instrumentation mode
| Setting | Description |
| Resign only | If set to True, Ranorex only changes the signature of the selected APK. Default: False. |
| Skip deployment | If set to True, Ranorex does not deploy the APK to the endpoint. This can be useful if you want to deploy the APK by other means. Default: False. |
| Skip instrumentation | If set to True, Ranorex skips the default instrumentation process, including signing the APK. This can be useful when deploying any APK without instrumenting it. Default: False. |
Instrumentation options
| Setting | Description |
| Auto-detect | Automatically adjusts instrumentation settings and reruns the instrumentation process up to four times. |
| Avoid resources decompiling | Prevents resources from being decompiled and recompiled during instrumentation. This keeps the .arsc file intact and can speed up the process. Disable this only if you need to modify resources in the instrumented APK. |
| Debug information | Adds detailed information to the instrumentation log file for troubleshooting. |
| Multidex application | If the app exceeds 65,536 methods and this setting is False, instrumentation can fail with a build error. Set it to True and try again. |
| Other instrumentation flags | Lets you add individual flags to the instrumentation process, for example -nores for Avoid resources decompiling. |
| Redistribute smali | If an error indicates issues with the number of methods in the decompiled smali code, set this option to True. Ranorex Studio then distributes the code across multiple files. |
| Static instrumentation | If you receive errors such as Register count exceeds... or Method count exceeds 65k, set this option to True. Ranorex Studio then uses a special instrumentation mechanism that reduces the amount of code added to user activities. Try Redistribute smali before enabling this option. |
Signing APK
If you want to sign the APK, specify all required options in the Signing APK section.