Lesson 9 - Ranorex Spy

As a stand-alone tool the Ranorex Spy provides all the functionality needed to explore and analyze desktop and mobile applications or websites under test - including their controls and UI elements. After starting Ranorex Spy, the element browser contains all currently running applications from your Windows desktop and mobile devices.

The element browser tree shown on the left side represents the computer's desktop with all currently opened applications. The name of the root node is set to the machine's host name. By selecting one of the elements from the browser tree, the Spy provides more detailed information about the selected item in the tabs 'Overview', 'Detail' and 'Screenshot' shown on the right. Ranorex recognizes over 30 of the most commonly known types of UI elements. In Ranorex vocabulary they are called 'adapters'. Every element shown within the element tree of Ranorex Spy is represented by an adapter as described in Ranorex UI adapter. If Ranorex is not able to specify the type of adapter of a UI element, it will be displayed as 'Unknown'.

The 'Overview' tab provides the most important view into the details of a UI element. The available attributes and their values are divided into the following sections:

  • 'General'
  • Logical adapters like 'Form', 'Button' or 'Text'
  • Technology related adapters like 'Control', 'Accessible' or 'NativeWindow'
Ranorex Spy 'Overview' tab divided into three attribute sections

Ranorex Spy 'Overview' tab divided into three attribute sections


Regardless of what type of UI element is currently selected the 'General' section provides information about whether the element is enabled, valid or visible.

Logical adapters like 'Form', 'Button' or 'Text'

Regardless of what technology is used from the application under test, Ranorex tries to abstract it with logical adapters as explained in Ranorex UI Adapter. These adapters are also used within repositories and provide class specific attribute values like the text value or the state of a checkbox.

Technology related adapters like 'Control', 'Accessible' or 'NativeWindow'

This type of adapter is used to group technology related information like the 'ControlName' of a .NET WinForms button or the process name of an application.

All attributes shown within this tab are accessible during an automated test for validation. Depending on the type of a UI element, they may also be used to set values. Learn more about how to use different adapters to read and set attribute values at  Code Examples - Create Adapters to Access More Properties and Methods.

In addition all attributes can be used within the RanoreXPath. By default the attribute in the overview tab written in bold is automatically used to identify the UI element.

Attribute 'controlname' is used to identify the button

Attribute 'controlname' is used to identify the button

The RanoreXPath expression shown in the figure above can be seen as a navigation path through the element browser tree used to identify a UI element. You can use the path editor to change element identification or edit the path expression directly within the text box's RanoreXPath edit mode.

Note You are able to access common text functionality like 'Select All' (<CTRL>+A), 'Copy' (<CTRL>+C), 'Cut' (<CTRL>+X), 'Paste' (<CTRL>+V), 'Undo' (<CTRL>+Z) or 'Delete' (<DEL>) in RanoreXPath.

Another way to navigate through the element tree is to use the image navigator which can be found at the bottom of the Overview/Detail tab.

Image navigator

Image navigator

At the top of the image navigator you can see the adapter type and the name of the currently selected UI element. By moving the mouse over a specific child element of the currently selected element, you will see the adapter type and its name. Clicking a UI element selects it, double-clicking outside the selected element selects the parent.

Short Introduction to the Structure of RanoreXPath

The RanoreXPath is built up in a hierarchical way where all the UI levels are separated with a 'forward slash' (/). The following figure shows an abstract illustration of how UI levels are represented by so called adapters (e.g. form, button, etc.). Since there may be more than one UI element of a specific type (adapters) on the current level of the path, the desired adapter itself is commonly specified in more detail; this is done using one or more predicate expressions. You can also specify the intended adapter with the use of an index (e.g. button[2]). As already mentioned, search specification is commonly done with one or more attributes, where the attribute is prefixed with an @ sign followed by a comparison operator (=, !=, ~, > as well as >, >=, <, <=) and an attribute.
Abstract illustration of the structure of RanoreXPath

Abstract illustration of the structure of RanoreXPath

Attribute comparisons may also be combined with 'and' and 'or' operators (e.g. button[@text='OK' and @enabled='true']).

Capture Screenshot Files for Image-Based Search

Use the context menu item 'Capture Screenshot' to create an image file (PNG format) which can be used to search for images in test automation code as explained in  Code Examples - How to find and compare images.

Capture a screenshot from a UI element to save as PNG file

Capture a screenshot from a UI element to save as PNG file

Specify the image region using the toolbar button 'Select Image Region' and click the 'Save' button to save the selected region as a PNG file.
Select an image region to save

Select an image region to save

Toolbar shortcuts

Browse Endpoint

Browse Endpoint Shows currently running applications on the active endpoint (set as automation root)


Endpoints Opens the endpoints pad


Refresh Updates the current state of applications

Load from Snapshot

Load from Snapshot Loads an existing Ranorex snapshot file

Save as Snapshot

Save as Snapshot Saves the currently selected node and all its descendants to a Ranorex snapshot file

Highlight Elements

Highlight Elements When switched on, highlights selected UI elements on the users desktop

Update Path

Update Path Sets the path from the currently selected element

Context menu

Update Path

Update Path Sets the path from the currently selected element

Set Element as Root

Set Element as Root Sets the currently selected element as root element

Highlight Element

Highlight Element Highlights the current element

Add to Repository

Add to Repository Adds the current element to a Ranorex Repository

Add to Repository (incl. Children)

Add to Repository (incl. Children)

Adds the current element and the element's children to a Ranorex Repository

Add Matching Children to Repository

Add Matching Children to Repository

Adds all UI elements matching the given RanoreXPath to the Repository

Update Element Data

Update Element Data Updates all attributes of the specified UI element

Save as Snapshot...

Save as Snapshot... Saves the current UI element including the child structure to a Ranorex snapshot file

Capture Screenshot...

Capture Screenshot... Captures a screenshot from the current element to be used for further image-based validation

Expand All Expands all child elements of the selected UI element in the element browser

Collapse All Collapses all child elements of the selected UI element in the element browser

Add Class or Process Name
to GDI Capture List
Specifies whether the element's class or process name should use the GDI plug-In to turn on text-based object recognition

Actions to perform Based on the type of the UI element a list of different actions to perform on the UI element is available

Note Saved screenshots can also be used for image comparison in code, for example for finding and comparing images or image-based automation. For more information about this, please have a look at Code Examples - How to do image based automation and Code Examples - How to find and compare images.