RanoreXPath blueprint | Ranorex
Help CenterUser GuideRanorex Studio advanced

RanoreXPath blueprint

The purpose of this chapter is to introduce and explain the basic RanoreXPath syntax and its application with respect to automated testing with Ranorex. The target audience for this chapter are beginners with little or no knowledge of XPath or RanoreXPath. This chapter outlines the basic concept for a fundamental understanding.

In this chapter


    RanoreXPath specification builds on the W3C XPath language specification. Basically, RanoreXPath is a subset of the XPath specification – and – in some topics, it extends it. As with any other mathematical syntax, RanoreXPath implements a defined (expanded) syntax and an abbreviated syntax.

    While advanced and experienced users usually apply the abbreviated syntax notation, this introductory chapter mainly makes use of the defined and expanded language notation. We recommend learning RanoreXPath syntax by starting with this chapter. As you make progress and gain experience you may find yourself applying abbreviated language notation automatically.

    Where necessary and useful we give hint to syntax options and possible abbreviations.


    UI-element description

    This section introduces and explains the syntax description of one single UI-element with RanoreXPath notation.

    RanoreXPath specification for a button

    RanoreXPath specification for a button

    Basic RanoreXPath element: A basic RanoreXPath consists of three elements – an axis specifier, a node, and zero or more predicate(s) to uniquely identify and describe UI-element(s)
    RanoreXPath button description: The Exit button of the demo application is described with the role button and a predicate which consists of an attribute-value pair that uniquely identifies the button


    Axis specifiers indicate navigation direction within the tree representation of the UI-elements. Examples for axis specifiers are /, //, .., ancestor, and others. They will be described in more detail later in this section.

    Role (node)

    • The formal XPath syntax defines this specification part as a node, whereas in Ranorex, this is known as a role (aka adapter-type)
    • Ranorex uses the role of the referenced UI-element as primary description header in RanoreXPath notation
    • If a predicate is needed to specify the UI-element, it is nested within [ ]

    Attribute/value pair (predicate)

    • Attribute-value pairs are optionally used to identify & describe UI-elements within XPath notation
    • If necessary, two or more attribute-value pairs can be combined to form a predicate
    • Introducing the attribute with a preceding @ is a convention
    • Attribute-value syntax can be fairly complex, therefore, the notation
      @attribute = 'value' is of common convention
    • Attribute-value pairs do not only apply the = operator. There are other operators as well which will be introduced and explained later
    • Attribute-value pairs are not the only options to specify a UI-element. Predicates may be formed of rather complex mathematical constructs
    Note icon


    Ranorex automatically selects the most suitable attribute-value pair(s) among the list of available attributes to identify & describe a UI-element. Most suitable means the attribute(s) with the highest weight(s) are chosen – a property which can be altered by the user. Therefore, the automatic identification of UI-elements can be influenced.

    Further reading

    The expert topic of mapping dynamic UI-elements by means of changing path weights is introduced and explained in > Ranorex Studio expert > ⇢ Mapping dynamic UI-elements.

    RanoreXPath construction

    This section introduces the composition of a RanoreXPath to completely and uniquely describe a UI-element within the GUI of the application under test. The RanoreXPath, therefore, describes the position of the UI-element within the abstract tree representation of Ranorex.

    Basic concept

    The basic concept of RanoreXPath construction is to simply chain UI-element descriptions together.

    RanoreXPath construction

    RanoreXPath construction

    Root element: defines the root of the current UI-element tree, i.e. the beginning of the RanoreXPath specification
    Path from root to node: optional (zero, or more) branch elements which define the path from the root element to the designated node element(s)
    Node element: one, or more UI-elements which is(are) to be identified by the current RanoreXPath specification

    Example RanoreXPath description

    Assume the example of the previous section – the Exit button has been tracked and described in RanoreXPath syntax.

    Simple RanoreXPath example

    Simple RanoreXPath example

    Tracking the Exit of the demo application
    See the RanoreXPath specification being automatically generated by Ranorex

    Example for RanoreXPath in Spy

    Example for RanoreXPath in Spy

    See the UI-element tree browser with the UI-elements being organized in a tree-like data-structure.

    • The root element is the program window (=form) of the demo application,
    • being identified by its controlname RxMainFrame
    • The node element is the Exit button,
    • being identified by its controlname RxButtonExit
    • There are no additional path elements

    See the RanoreXPath elements of the path editor. They represent the RanoreXPath elements in a hierarchical form


    The final RanoreXPath specification of the Exit button looks like:

    Resulting example RanoreXPath specification

    Resulting example RanoreXPath specification

    RanoreXPath characteristics

    There are two main ways of how to use and apply RanoreXPath specifications.

    RanoreXPath main applications

    RanoreXPath main applications

    The purpose of the RanoreXPath description of UI-elements can be the identification of one single UI-element as well as the identification of a set of UI-elements based on defined grouping characteristics.

    Important to know:

    Independent from the application purpose, a RanoreXPath specification is always:

    RanoreXPath principle

    RanoreXPath principle


    • Level of detail vs. flexibility have their impact on robustness and execution speed
    • A very detailed RanoreXPath leads to less robust declarations but may speed up with respect to execution time.
    • A very flexible RanoreXPath becomes more robust and immune against changes in GUI architecture but becomes more time consuming during processing. 

    RanoreXPath robustness

    One outstanding characteristic of Ranorex is its robustness of test cases against dynamic changes in the graphical user interface. This robustness has its origin in the maximum flexibility of RanoreXPath definitions.

    The automatic generation of RanoreXPath specifications tries to find a good compromise between detail and flexibility. This is usually achieved by trying to include suitable container elements into the path specification. The underlying concept is based on wildcard operators.

    Example definition

    RanoreXPath robustness example definition

    RanoreXPath robustness example definition

    Use the Track function of Spy
    and track the Female radio button of the test database in the demo application


    See the tracking result in Ranorex Spy with the RanoreXPath, the UI-element tree browser and the item tree view of the path editor.

    RanoreXPath robustness example result

    RanoreXPath robustness example result

    RanoreXPath specification:

    • See the RanoreXPath specification with its components and compare them with the views in Spy and in the path editor

    Spy UI-element tree browser view

    • See the UI-elements of the demo application GUI with
    • 5 different UI-elements structured in the UI-elements tree

    Path editor

    • See the RanoreXPath items in the tree view of the path editor
    • There are 7 RanoreXPath items from the root to the node element
    • Together they form the RanoreXPath specification

    Detailed RanoreXPath specification

    Let’s have a closer look at the automatically generated RanoreXPath specification:

    RanoreXPath robustness through wildcards

    RanoreXPath robustness through wildcards

    Root element RxMainFrame:
    This UI-element represents the program window of the application under test (i.e. the demo application) and is a fixed part of the RanoreXPath specification

    Wildcards: By making the RanoreXPath specification as flexible as possible, Ranorex inserts two wildcards /? (i.e. any optional) until the next fixed RanoreXPath item
    Fixed RanoreXPath item RxTabStandard: Ranorex classifies this UI-element to be a fixed necessary part of the RanoreXPath specification to be able to robustly identify the node UI-element
    Wildcards: Again, the next two RanoreXPath items are declared to be /? wildcards in order to increase flexibility in UI-element identification
    Finally, the node element rdbFemale is the final fixed part of the RanoreXPath specification for successful and robust UI-element identification


    • With respect to wildcards, Ranorex is able to doubtlessly identify a UI-element even if the underlying GUI structure changes
    • In the current example, Ranorex specifies the path with three (3) fixed UI-elements which are essential for the UI-element identification of the radio button
    • Four (4) wildcards give way for GUI changes and a robust identification regardless of these changes
    • There are three different wildcard operators which will be explained in the next section

    Wildcard operators

    Flexibility in RanoreXPath specification is based on wildcards. Three different wildcard operators are distinguished:

    /* (any) Any UI-element, exactly one (1) tree level
    /? (any optional) Any UI-element, exactly zero (0) or one (1)  tree level
    // (any descendants) Any UI-element, in any number of tree levels

    Current example summary

    Referring to the current example, let’s have a look at the wildcard implementation.

    Wildcard application in test example

    Wildcard application in test example

    See the UI-element RxTabControl being replaced by two /?/? wildcards. This means that the next fixed RanoreXPath item can be directly in the root UI-element, or one (1), or two (2) levels below it whereas the levels are not further specified
    See the UI-element grpGender being replaced by two /?/? wildcards. This means that the node UI-element can be in the previous fixed UI-element, or one (1), or two (2) levels below whereas these levels are not specified further

    Therefore, there is a level flexibility of up to four (4) levels whereas the levels are not specified any further which gives room for major changes in GUI structure and content. The target UI-element is found based on two fixed path parts and with its attributecontrolname.