RanoreXPath syntax examples | Ranorex
Help CenterUser GuideRanorex Studio advanced

RanoreXPath syntax examples

This chapter shows a number of RanoreXPath syntax examples in order to deepen your understanding of the powerful options to apply RanoreXPath specifications in your test environment.

In this chapter

    Test example definition

    All RanoreXPath explanation examples are created using the Ranorex demo application. Most of the herein presented examples are done with the UI-element test area of the demo application.

    Ranorex demo application - UI-element test area

    Ranorex demo application – UI-element test area

    UI-element test area of Ranorex demo application

    Ranorex demo application

    The demo application can be downloaded following the below-displayed link. Download the file, unzip it and start the demo application.

    Download

    Theme: Ranorex demo application
    Time: Less than 10 min

    Download sample file

    Simple button identification

    This section shows how to identify a simple button of a user interface and analyzes the corresponding RanoreXPath specification.

    Simple button identification

    Simple button identification

    See the RanoreXPath specification for the Exit button of the demo application
    The tree browser shows that the Exit button is a direct child of the root UI-element RxMainFrame
    The Exit button is identified by its controlname
    The Spy status information (lower left window corner) confirms one UI-element found

    Generalization of RanoreXPath specification

    As the Exit button is the only button in the current GUI layer of the demo application, it is possible to generalize the RanoreXPath specification without losing track of the button. Here is how to do this.

    Generalization of RanoreXPath specification

    Generalization of RanoreXPath specification

    See the generalized RanoreXPath specification with the role button and with removed predicate specification
    The tree browser still shows the UI-element Exit button as a direct child of the root element
    The path editor tree view shows the generalized RanoreXPath specification
    Still, one UI-element (i.e. the Exit button) is identified

    Note icon

    Note

    This example succeeds because there is only one button at the designated level. If an additional button is added, the current example is not able to track & identify one single button.

    User-defined identification attribute

    Ranorex chooses identification attributes automatically. This choice can be changed at will. Here is how to select a user-defined identification attribute.

    User-defined identification attribute

    User-defined identification attribute

    See the selection of the attribute-value pair controltext='Exit' in the path editor of Spy
    The predicate has been added to the RanoreXPath specification
    which is also displayed in the tree view of the path editor
    As a result, the Exit button is still identified

    tipp icon

    Hint

    The Spy status line shows if a RanoreXPath specification is unique and if and how many UI-elements have been identified with the current RanoreXPath specification.

    /? (any optional) wildcard example

    Wildcards add flexibility and robustness to RanoreXPath specifications. The identification of UI-elements becomes more resistant against structural changes in the graphical user interface. The objective is to design a UI-element identification – ideally – independent from the structure of the underlying GUI.

    Note icon

    Note

    Remember the wildcard definitions from the previous section:

    /* Any UI-element, exactly one (1) tree level
    /? Any UI-element, exactly zero (0), or one (1) tree level
    // Any UI-element, any number of tree levels
    'Any' wildcard example

    ‘Any’ wildcard example

    Track the pane of the UI-element test area of the demo application

    Result(s):

    The result can be seen in the Spy tree browser and the path editor.

    Spy tree browser and path editor of '/?' example

    Spy tree browser and path editor of ‘/?’ example

    The root element represents the beginning of the RanoreXPath specification
    The middle UI-element TabPageList is replaced by two /? wildcards to make the path specification robust. The path will still be valid even if the TabPage element moves down or up one level
    The node UI-element is the target UI-element of the RanoreXPath specification and is defined through its role and the controlname attribute

    RanoreXPath interpretation:

    Example RanoreXPath specification with /? wildcard

    Example RanoreXPath specification with /? wildcard

    The target element 3 is a descendant element of the root element 1 with up to two (0,1, or 2) non-necessarily specified UI-elements 2 in between.

    // (any descendants) wildcard example

    It is often necessary to find & track elements from within a GUI where we do not know the ‘depth’ of the elements. Therefore, an ‘all path descendants’ operator allows searching ‘all’ descendant levels of an element to track specific UI-element(s). Here is how to do this.

    RanoreXPath specification with // (any descendants) wildcard

    RanoreXPath specification with // (any descendants) wildcard

    See the demo application program window, specified with its role /form to be the root element of the RanoreXPath specification
    The wildcard operator specifies any element at any level below
    The target UI-element is restricted to the role radiobutton, i.e. any radio button in and below the root element is searched

    Result(s):

    The result can be seen in Ranorex Spy.

    Search result for // (any descendant) wildcard operator

    Search result for // (any descendant) wildcard operator

    See the path editor of Spy with RanoreXPath specification displayed as tree elements
    The UI-element tree browser displays all found UI-elements, i.e. 7 radio buttons in two different levels (level 3 and level 4)
    The status message in the lower left corner of Spy confirms 7 found radio buttons

    RanoreXPath interpretation:

    Search and identify any radio button 3 in and below 2 the root element 1.

    /* (any) wildcard example

    If you want to find UI-elements with an exactly known ‘depth’, the ‘any’ wildcard operator might be the tool of your choice. See a simple example of its application.

    RanoreXPath specification with /* (any) wildcard

    RanoreXPath specification with /* (any) wildcard

    Program windows of demo application as root element of RanoreXPath specification
    Three /* (any) wildcard operators searching for elements three levels down of the root element
    Specification of the node element with role radiobutton

    Result(s):

    The search & identification result can be seen in Ranorex Spy:

    Search result for /* (any) wildcard operator

    Search result for /* (any) wildcard operator

    See the path editor with the elements of the RanoreXPath specification in tree-like structure. Each of the wildcard operators represents one search level below the root element
    See the UI-element tree browser with five (5) found UI-elements of role radiobutton exactly three (3) levels down from the root element
    The lower left status line confirms the 5 found UI-elements

    RanoreXPath interpretation:

    Search & identify any radio button 3 which is located exactly three levels 2
    below the root element 1

    Narrowing RanoreXPath specifications

    In many cases, it is necessary to narrow a general RanoreXPath specification to a more specific one to find & identify the selected UI-elements within the GUI. The most common methods for narrowing a RanoreXPath specification are introduced herein.

    General RanoreXPath specification

    Let’s start to track & identify all buttons from within the UI-element test area pane of the demo application

    Start Spy and the demo application and specify the RanoreXPath as follows:

    Example for initial general RanoreXPath specification

    Example for initial general RanoreXPath specification

    See the path editor with all elements of the RanoreXPath specification in tree-like form searching for any button in and below the UI-elements test area pane
    See the UI-element tree browser with 17 buttons found in the demo application
    The lower left status message confirms 17 found buttons

    Narrowing RanoreXPath specification – part I

    In a first step, the RanoreXPath specification is narrowed to ‘visible’ buttons, i.e. buttons which are not hidden within the GUI.

    Change the RanoreXPath specification with a predicate as follows:

    Example for narrowing RanoreXPath specification - part I

    Example for narrowing RanoreXPath specification – part I

    See the path editor with the node element further specified with the attribute visible='True'
    See the UI-element tree browser with 15 resulting buttons found based on the current RanoreXPath specification
    The lower left status information confirms 15 buttons found

    Narrowing RanoreXPath specification – part II

    If narrowing a RanoreXPath specification is not sufficient, continued narrowing by means of combined attributes as the predicate may be a solution. See how this is done.

    Add the below listed attribute specification to the predicate of the current RanoreXPath definition

    Example for narrowing RanoreXPath specification - part II

    Example for narrowing RanoreXPath specification – part II

    See the narrowed RanoreXPath specification with a second attribute/value pair as predicate.

    • The search is set to all visible buttons which…
    • … have a controlname attribute starting with the letters btn

    See the UI-element tree browser with two found UI-elements correlating with the RanoreXPath search specification
    The lower-left status information confirms two found UI-elements

    tipp icon

    Hint

    The > operator is one of several different operators which can be used in RanoreXpath specifications.

    Narrowing result(s):

    The search result of the narrowed RanoreXPath specification can be seen in the below-displayed image – two buttons in the ‘UI-element test area‘ pane are identified matching UI-elements.

    Narrowed RanoreXPath search result example

    Narrowed RanoreXPath search result example

    Selecting UI-elements within RanoreXPath specification

    Single elements within a set of tracked and identified elements can be selected directly by using the element selection operator of RanoreXPath syntax. Here is how to do this.

    Insert the below-listed RanoreXPath specification to the current example

    Example for selecting elements in RanoreXPath specifications

    Example for selecting elements in RanoreXPath specifications

    See the path editor with the selection [2] operator added to the predicate, selecting the second element from the list of elements identified by the current RanoreXPath specification
    See the UI-element tree browser identifying the second UI-element as search result of the RanoreXPath specification
    See the confirmation of the search result in the lower-left Spy status information

    Selection result(s):

    The selection result is the second of the two identified buttons of the ‘UI-element test area‘ pane:

    RanoreXPath selection result

    RanoreXPath selection result

    tipp icon

    Hint

    The sort order is just the order the UI-element appears in the element tree. This order is the result of the preceding predicate definition and may have nothing in common with UI-element naming (i.e. ‘Button 1’).

    Tree element specification

    This section introduces and explains the tracking and identification of tree elements.

    Tracking tree UI-elements with Ranorex Spy

    Tracking tree UI-elements with Ranorex Spy

    Click the Track button of Ranorex Spy and track
    a tree element of the UI-element test area in the demo application

    Result(s):

    Ranorex identifies the tree element as follows:

    Identification of a tree element with Ranorex

    Identification of a tree element with Ranorex

    See the RanoreXPath specification of the tracking result with the tree-item Web and mobile testing
    Ranorex inserts two ‘any optional’ wildcards (/?/?) to add path robustness and flexibility to the tracking result
    The tree item Web and mobile testing is identified as descendant of the tree. The path flexibility allows successful identification if the tree item is in and below one or two levels of the tree item

    Subtree item specification

    The concept of tracking and identification of tree items within a tree is revealed by specifying a tree node down of any top node.

    Tracking sub-tree UI-elements with Ranorex Spy

    Tracking sub-tree UI-elements with Ranorex Spy

    Use the Track button of Ranorex Spy and
    track the sub-tree item Endpoints in the UI-element test area of the demo application

    Result(s):

    Ranorex identifies the sub-tree item as follows:

    Identification of sub-tree elements with Ranorex Spy

    Identification of sub-tree elements with Ranorex Spy

    See the resulting RanoreXPath specification with the sub-tree item Endpoints identified as normal tree item
    Ranorex keeps the tree as anchor element of the RanoreXPath specification
    All sub-tree items are identified as simple tree items , independent from their position within the tree through an any descendants wildcard operator
    See the sub-tree item being identified as regular tree item and its accessiblename as predicate

    Note icon

    Note

    Ranorex treats all sub-tree items as regular tree items and identifies them by a unique predicate specification. The position within the tree is not of importance, therefore, a change in tree structure does not change the identification success.

    Specification of tree-siblings

    A simple modification of the RanoreXPath specification by means of axis specifiers allows to track and identify the following and preceding-sibling tree item of the current tree item.

    Applying axis specifiers to RanoreXPath specifications

    Applying axis specifiers to RanoreXPath specifications

    See the RanoreXPath specification with the added axis specifier tracking the following tree item sibling
    The path editor displays the RanroeXPath specification in tree-like structure
    The UI-element tree browser displays the identification result, the tree item Mobile testing as following sibling tree item of the Endpoint tree item

    Identification of following-sibling tree item

    Identification of following-sibling tree item

    See the UI-element test area of the application under test where the tree element Mobile testing is displayed as the following sibling element of the Endpoint tree item
    Note icon

    Note

    The axis specifier following-sibling returns all following sibling elements if more than one exists.

    Table item specification

    Tracking and identifying elements within a table are an advanced specification method and require some fundamental knowledge which is introduced and explained herein.

    Basic table orientation

    The addressing of table cells follows a system which is important to be understood and which is displayed in the below image.

    Basic table orientation

    Basic table orientation

    Important to know:

    • Table columns are identified by their header names
    • Table rows are numbered, beginning with ‘0’ in the first row below the header
    • Table cells are usually identified by a combination of column name and row number

    Example for absolute cell specification: The cell ‘Thomas’ is absolutely specified by a combination of column name and row number
    Example for relative cell specification: The cell ‘Development’ is relatively specified as 6th cell after an absolutely specified anchor cell by means of the axis specifier /..

    Test definition

    The purpose of the current test example is to uniquely identify the age of the person named Thomas Bach in the table of the UI-element test area in the demo application.

    Table cell specification - test definition

    Table cell specification – test definition

    See the table entry (line) with firstname, lastname, age, gender and department affiliation
    The age of Thomas Bach is to be selected robustly by means of the RanoreXPath specification

    Absolute cell position specification

    In a first and simple approach, the cell with the person ‘Thomas Bach’ may be identified by an absolute cell position specification:

    Absolute table cell specification

    Absolute table cell specification

    See the RanoreXPath specification with the table cell absolutely specified
    The RanoreXPath specification refers to the cell in column ‘FirstName’ and row no. 3 which – in our current example – contains the name Thomas
    See the identified UI-element in the tree browser view of Spy

    Missing robustness against table cell change

    The absolute cell specification lacks robustness against a change in table cell arrangement.

    Table cell shuffle

    Table cell shuffle

    Shuffling the table cell arrangment shows that …
    … the absolute cell specification leads to wrong results, as the specification clings to the cell position rather than to the desired cell content

    Cell content specification

    An improvement to the specification of the cell position is the specification of the cell content, where we identify a cell based on its contents.

    Cell content specification

    Cell content specification

    Specifying the cell content gains robustness against table shuffling, but…
    … leads to the identification of all cells with the specified content, independent from the column

    Narrowed cell specification

    It is further necessary to restrict the cell specification to first names ‘Thomas’ (and last name ‘Bach’). This is done by a narrowed cell specification.

    Narrowed cell specification

    Narrowed cell specification

    See the narrowed cell specification with two attributes forming the RanoreXPath predicate…
    … and as a result, the uniquely identified cell of the current example

    tipp icon

    Hint

    It may be necessary to further specify a cell by additional attributes and/or other axis specifiers in order to uniquely specify a defined cell. In the current example, two attributes are sufficient.

    Relative cell specification

    Finally, to specify the cell which holds the age of the person named ‘Thomas Bach’, a relative cell specification is necessary.

    Relative cell specification

    Relative cell specification

    The relative cell specification of the RanoreXPath with the cell of accessiblename ‘Age’ delivers
    the content Age=42 of the table row with ‘Thomas Bach’