Setup and execution | Ranorex
Help CenterUser GuideWeb and mobile testing

Setup and execution

Learn how to automate your Android app testing for different devices and languages. The following sections will explain how to set up an environment for Android testing, how to generate and execute a test and what to do if any problems occur. The Android app KeePassDroid is taken as an example how to automate mobile applications using Ranorex.
For more general information on mobile testing, feel free to refer to our mobile testing wiki.

In this chapter


    Before getting started with Android test automation, it’s necessary to choose the connection type that suits your needs. The following overview helps you to find out which connection type will work best for you.

     USB  Wi-Fi
    Create tests
    Start/Stop App
    Install APK
    Deploy (unattended)
    Automate System Apps

    Even if automating via Wi-Fi it is recommended to have your system under test plugged into a power supply during test creation and execution.

    Getting Started

    This quick start guide will show you how easy it is to create your Android test and execute the test on different devices and Android languages.

    Prepare your Android device

    In order to ensure that the device connection is as stable as possible, it is recommended to enable the ‘Developer Mode’ on your Android device. This mode grants access to some advanced settings which are responsible for a stable connection. On Android 4.2 and higher, ‘Developer Mode’ is hidden by default. You can unhide it by navigating to ‘Settings’ -> ‘About Phone’ and tapping ‘Build Number’ for seven times. Now return to the previous screen and find ‘Developer options’ in the main menu:

    Enter ‘Developer options’

    Inside the ‘Developer options’ menu, please enable the following settings:

    • ‘Stay awake’ which prevents your device from going to Standby during test automation.
    Note icon


    Although you might be automating via Wi-Fi, your devices should always be connected to a power supply to ensure both letting this setting work as well as ensuring to not run out of battery during your tests. Furthermore it disables any energy saving mechanisms for your Wi-Fi interface and makes the Wi-Fi connection more stable.

    • ‘USB debugging’ (only when automating via USB)

    Additionally, enable installing from unknown sources in the Security menu.

    To start creating your test, click RECORD in Ranorex Recorder.

    The following dialog will appear.

    Click Create mobile test to proceed. You will see a short introduction how creating mobile tests works in Ranorex Studio. Once you’ve clicked through it, you will be prompted to choose a device and app:

    Add Device

    Follow the instructions on how to add an Android endpoint.

    Instrument and Deploy your Android App

    After setting up the Android device, the app which should be automated has to be instrumented and deployed to the device.  The Instrumentation wizard for instrumenting and deploying an APK file can be started in the ⇢endpoint options, the ‘Create a mobile test’ dialog, or directly by starting the instrumentation wizard as described in the chapter ⇢Instrumentation Wizard – Android.

    Note icon


    As mentioned before, the Android app KeePassDroid is taken as an example how to automate mobile applications using Ranorex. The APK file can be downloaded at

    Next to instrumenting and deploying your Android app, the Instrumentation Wizard allows you to update the Ranorex Service on your device as well as deploy the RXBrowser app, which enables web testing for Android.

    After choosing a device to deploy and an APK file to instrument, the process will be started by pressing the ‘Next’ button.

    Android Instrumentation Wizard

    Note icon


    Open the Advanced Instrumentation Settings dialog by clicking the Advanced button. Here you can change the APK signing as well as some instrumentation options. When enabling “Full image comparison”, a more robust image comparison mechanism will be used. Enabling this option decreases the apps startup performance but might be useful when having problems with determining resource id’s for images. When disabling “Tree simplification”, UI-trees will remain unchanged. This means no post processing will take place, resulting in larger UI-trees. Disabling this option decreases the apps startup performance but might be useful when automating 3rd party controls.

    After the instrumentation of the APK file, it will be automatically deployed to the selected device.

    Successfully finished instrumenting and deploying APK

    To finish the instrumentation and deployment process, the installation has to be confirmed on the mobile device.

    Confirm installation of instrumented APK

    Note icon


    Because the Ranorex automation lib uses non-public API and adds additional permissions to your APK, make sure you do not release automated APKs to an app store to avoid biased user experience.

    Create and Run an Android Test

    After preparing the device and instrumenting the APK, you can start creating your test by choosing the device on which the test should be executed and the app which should be tested.

    Creating a mobile test with chosen device and app

    By pressing the ‘Create’ button, the instrumented app will be automatically started on the mobile device and Ranorex Spy will be started on the desktop.

    To fill your repository with items and your recording with actions, two separate steps are necessary.

    Step 1: Track and add

    In this step, you will use Ranorex Spy to identify elements in your AUT and add them to your repository so you can assign actions to them.

    Click on a node in the element browser on the left to bring up a live preview of the associated UI in the bottom right.

    Mouse over the desired UI element in the preview, make sure it is covered with a red overlay, and click it. It’s now tracked and highlighted in the element tree.
    Alternatively, you can also browse through the element tree until you find the desired UI element.

    In the element tree, right-click the selected UI element and select one of the available ⇢Add to repository options from the context menu.

    The element is now available for use in your repository.

    Step 2: Drag and drop

    In this step, you will fill your recording with actions.

    Drag and drop the UI element you want to perform an action on from the repository to the action table.

    In the context menu that opens, select the desired action.

    Configure the action in the action table.

    Note icon


    You can also drag UI elements from the element tree to the action table directly. This works the same way as adding them to the repository beforehand and then dragging them to the action table.

    After you’ve filled the recording module with actions as described above, the action table may look something like this:

    Action table

    Action #1 is a ‘Run Mobile App’ action which starts the instrumented APK file on the selected device.

    Note icon


    You can add a launcher activity to your “Run Mobile App” action by simply adding the activity name to the “Startup Arguments” using the following syntax: <fullpackagename>/<fullpackagename.activityname>

    Action # 2 is a Touch Event on a button. There are 5 different kinds of touch events recognized by Ranorex:

    • a normal ‘Touch’ which is equivalent to a mouse click on a desktop machine,
    • a ‘Long Touch’ which typically opens a context menu
    • and ‘Touch Start’, ‘Touch Move’ and ‘Touch End’ for simulating a drag gesture.
    Note icon


    The duration for both, ‘Touch’ and ‘Long Touch’ can be defined int the properties pane. You can open this pane by clicking the context menu item ‘Properties’ on the ‘Touch Event’ action item.

    Action # 4 is a ‘Set Value’ action, which is typically used for keyboard input.

    Action # 6 is a ‘Wait For Not Exists’ action, which is useful when having for example an item indicating a loading process and the automation should go ahead when the item has disappeared.

    Action # 7 is a ‘Validate’ action as described before.

    Action # 8 is a ‘Get Value’ action, which can be used to write back an attribute value of a control to a variable for further processing.

    Action # 9 is a ‘Report’ action, which is used to add information to the test report.

    Action # 10 is a ‘Invoke Action’ which performs a scroll action on a list control to its index ‘0’. ‘Invoke Actions’ directly call the corresponding method of the selected control.

    You can use the invoke action to call user defined methods or get and set user defined members.
    To call such a user defined method

    1. type ‘CallMethod’ to the action name field of the invoke action
    2. add the method name to the first argument field
    3. add a value or a variable you want to pass to the method to the argument field or fields

    To get or set a member use ‘GetMember’ or ‘SetMember’ instead of ‘CallMethod’ as action name.
    For further details about invoke action have a look at ⇢Invoking actions.

    User defined methods can also be invoked from code the same way. Here is a short example:

    string text = (string) repo.App.Text.Element.InvokeAction("CallMethod", "myCustomGetTextMethod");
    Dim text As String = DirectCast(repo.App.Text.Element.InvokeAction("CallMethod", "myCustomGetTextMethod"), String)

    Action # 11 is a ‘Mobile Key Press’ action. ‘Mobile Key Press’ actions simulate the physical buttons ‘Back’ and ‘Menu’ of the mobile device.

    Action # 12 is a ‘Close Application’ action. ‘Close Application’ actions stop the selected application on the mobile device.

    Note icon


    Make sure to add a ‘Close Application’ action, when running your test on different devices, because if the app will not be closed on the devices, the app on the first identified device will be automated.

    Run Test

    Simply run your test as usual by pressing the ‘Run’ button. It will then be performed on your mobile device.