Introduction

Ranorex Studio supports test automation for many different UI technologies. Some of these technologies must be instrumented for best automation results with Ranorex Studio. Instrumenting means that Ranorex Studio installs an add-on or inserts code so it can identify the UI elements of a particular technology.

The Ranorex Instrumentation Wizard simplifies this process for the following technologies:

  • Mozilla Firefox
  • Google Chrome
  • Microsoft Edge
  • Chromium
  • Android/iOS apps
Note icon

Note

For browsers, we recommend you use the ⇢ Open browser action to automatically instrument Mozilla Firefox or Google Chrome when you start a test.

In this chapter

    Start the Instrumentation Wizard

    There are different ways to start the Instrumentation Wizard.

    From technology limitation warnings

    Whenever you try to automate one of the above technologies without having instrumented them, a technology limitation warning will appear. It will include a button to directly run the Instrumentation Wizard.

     

    Warning for Google Chrome

    Warning for Mozilla Firefox

    Warning for Flash/Flex

    When you create a mobile test

    When you click Add app… in the mobile test creation dialog, the Instrumentation Wizard starts automatically. This is because apps need to be instrumented before you can deploy them to your mobile device. 

    Add app… button that automatically starts the Instrumentation Wizard.

    From the settings of an iOS/Android endpoint

    You can also start the Instrumentation Wizard from the settings of an Android/iOS endpoint. This works the same way as the Add app… button above.

    Instrument/deploy button in the settings of an Android endpoint

    From the menu

    You can also start the Instrumentation Wizard from Tools > Ranorex Instrumentation Wizard.

    From the Windows Start menu

    The Instrumentation Wizard is a standalone program and can therefore be started from the Windows Start menu.

    Command line instrumentation

    You can also instrument technologies from the command line. The available arguments are listed below. The image shows the Instrumentation Wizard executable in the /bin/ folder of the Ranorex Studio installation.

    Instrumentation Wizard executable

    ?|help

    Displays the general help. Add a page parameter to show the help for the respective technology.

    Possible page names: android, chrome, firefox, flex, ios.

    Android arguments (basics)

    d|device

    • Name of the mobile device to which you want to deploy an APK.
    • Not required if deploymode is set to NoDeploy.

    a|apkfile

    • Path to the APK that you want to deploy

    s|skip

    • True = no instrumentation: only deploys the APK to the device.
    • False (default) = instruments and then deploys the APK to the device.

    dm|deploymode

    • Configures how the APK is deployed.
    • Parameters: WiFi | Usb | NoDeploy | Auto (default)
    • NoDeploy = Does not deploy the APK.
    • Auto = Deploys the APK using the same mode as used for device configuration.

    o|outfile

    • Optional path or folder to save the instrumented APK.
    • You must have read and write permissions for the path/folder.
    • Adds a suffix to the saved APK to indicate that it’s been instrumented. Overwrites existing instrumented APKs.
    • If skip is set to true, does nothing.

    Android arguments (signing APKs)

    JdkBinPath

    • Complete installation path of the JDK environment.

    KeyAlias

    • Alias of the keystore entity of jarsigner.

    KeyPass

    • Password for jarsigner.
    • Attention: The password is stored as plain text.

    KeyStore

    • Complete path to the associated jarsigner keystore.

    KeyStorePass

    • Password to the jarsigner keystore.
    • Attention: The password is stored as plain text.
    Note icon

    Note

    For custom signing, KeyStore, KeyAlias, KeyStorePass, KeyPass and JDKBinPath must be set.

    Android arguments (instrumentation settings)

    RIdClass

    • Optional class name for locating resource Ids (e.g. com.ranorex.demo.R)
    • By default, Ranorex will search in .R

    EnableWebTesting

    • True (default) = shows DOM content of web views in the UI hierarchy.
    • False = does not show DOM content.
    • Important: Very high performance impact on your app when set to true.

    FullImageComparison

    • Uses more robust image comparison to determine resource IDs for images.
    • Important: Decreases startup performance.

    TreeSimplification

    • True (default) = Postprocesses the generated UI tree internally to make it simpler.
    • False = No postprocessing. False generates a larger UI tree. This can be useful for automating 3rd-party Android controls.

    Chrome arguments

    e|enable

    • True = Activates the Ranorex Chrome add-on.
    • False = Deactivates the Ranorex Chrome add-on.

    Firefox arguments

    enew|enablenew

    • True = Activates the Ranorex Firefox add-on.
    • False = Deactivates the Ranorex Firefox add-on.

    Flex arguments

    pl|preloader

    • True = Activates the Ranorex preloader.
    • False = Deactivates the Ranorex preloader.

    ie

    • True = Activates the Flex debug player for Internet Explorer.
    • False = Deactivates the Flex debug player for Internet Explorer.

    ff|firefox

    • True = Activates the NPAPI Flex debug player for Firefox/Safari.
    • False = Deactivates the NPAPI Flex debug player for Firefox/Safari.

    cr|chrome

    • True = Activates the Flex PPAPI debug player for Chrome.
    • False = Deactivates the Flex PPAPI debug player for Chrome.

    o|other

    • True = Activates cr and ff
    • False = Deactivates cr and ff

    ft|flextrace

    • True = Activates Flash tracelog.
    • False (default) = Deactivates Flash tracelog.

    iOS arguments

    u|udid

    • Unique ID of the device to which you want to deploy an app.
    • Alternative argument: dn|devicename
    Note icon

    Note

    You can find the UDID in the details of the respective endpoint.

    dn|devicename

    • Name of the mobile device to which you want to deploy an app.

    ip|inputpath

    • Complete path of the IPA file you want to instrument/deploy.

    o|outfile

    • Optional path or folder to save the instrumented IPA.
    • You must have read and write permissions for the path/folder.
    • Adds a suffix to the saved IPA to indicate that it’s been instrumented. Overwrites existing instrumented IPAs.
    • If skipinstrumentation is set to true, does nothing.

    si|skipinstrumentation

    • True = no instrumentation, only deploys the IPA to the device.
    • False (default) = instruments and then deploys the IPA to the device.

    sd|skipdeployment

    • True = Does not deploy the IPA.
    • False (default)= Deploys the IPA.

    k|keypath

    • Path to the p12 certification file (*.p12).

    pw|password

    • Password to the p12 certification file (*.p12).

    pp|provisionpath

    • Path to the embedded mobile provision profile (*.mobileprovision).

    ai|appid

    • The application ID (bundle identifier of the app).
    • Required so that an application can be uninstalled prior to installing the new archive.
    • By default, requires you to enter the ID.
    • Can also be set to auto to resolve the ID automatically during instrumentation.

    db|deploybrowser

    • True = deploys the preinstrumented Ranorex Web Browser App to the device.
    • False (default) = Does not deploy it.

    ds|deployservice

    • True = deploys the preinstrumented Ranorex Service App to the device.
    • False (default) = Does not deploy it.

    ub|uninstallbrowser

    • True = uninstalls the preinstrumented Ranorex Web Browser App before deployment.
    • False (default) = No prior uninstalling.

    ub|uninstallservice

    • True = uninstalls the preinstrumented Ranorex Service App before deployment.
    • False (default) = No prior uninstalling.

    uf|uninstallfail

    • True = Displays an error message if uninstalling an app fails.
    • False (default) = Does not display an error message.