RanoreXPath - RanoreXPath examples | Ranorex Studio User Guide
Help CenterUser GuideRanorex Studio advanced

RanoreXPath examples

On this page, we’ve collected many detailed practical examples that show what a RanoreXPath expression for a specific scenario could look like.

In this chapter

    tipp icon

    Screencast

    The screencast “Syntax examples” walks you through the information found in this chapter:

    Watch the screencast now

    Test example definition

    All examples on this page are based on the Ranorex Studio Demo application. Most of them use the tab UI-element test area in this application.

    Ranorex demo application - UI-element test area

    Ranorex demo application – UI-element test area

    UI-element test area tab in the Ranorex Studio demo Application

    Download the Ranorex Studio Demo Application

    Follow the link below to download the file. Then unzip it and start the application.

    Download

    File: Ranorex Studio Demo Application

    Download file

    Identify a simple button and generalize its RanoreXPath

    Here we show you how to identify a simple button in a user interface and then generalize the corresponding RanoreXPath expression to match any button.

    In Ranorex Spy, track the Exit button in the UI-element test area in the demo app.

    After tracking, Spy shows the following:

    Simple button identification

    The automatically generated RanoreXPath for the Exit button.
    The tree browser shows that the Exit button is a child of the root UI element RxMainFrame.
    The Exit button is identified by the controlname attribute “RxButtonExit”.
    The Spy status bar (bottom left corner) confirms one UI element found.

    Generalize the RanoreXPath

    Generalizing a RanoreXPath expression means making it less detailed. This can increase robustness.

    In the current example, we want to generalize the RanoreXPath so that the Exit button is only identified by its “button” status. We do this by removing the button’s attribute. Since the Exit button is the only button at this level in the element tree, it will still be identified correctly and its RanoreXPath more robust against UI changes.

    In Spy, click into the RanoreXPath line, delete the attribute [@controlname=’RxButtonExit’], and press Enter.

    Spy will show the following:

    Generalization of RanoreXPath specification

    The generalized RanoreXPath with only the button role.
    The tree browser shows the Exit button as a child of the root element.
    The path editor view represents the generalized RanoreXPath specification.
    One UI element (i.e. the Exit button) has been found.

    Note icon

    Note

    If there is more than one button (or whichever type of UI element you generalized the RanoreXPath for) is present at the same level in the element tree, the RanoreXPath expression will identify all of them.

    Change the identifying attribute

    When tracking a UI element, Ranorex Studio automatically generates the RanoreXPath and therefore also determines identification attributes automatically. You can of course change the attribute by which a UI element is identified in a RanoreXPath.

    Track the Exit button in the UI-element test area in the demo app.

    Click into the RanoreXPath line, then switch to the Path Editor.

    Select the node whose attribute you want to change, e.g. the button in this example.

    On the left, check/uncheck the desired attributes, i.e. deselect controlname and select controltext instead for this example. The RanoreXPath is adjusted automatically.

    User-defined identification attribute

    The automatically determined controlname attribute was deselected and replaced with the controltext attribute.
    The RanoreXPath reflects this change.
    The path editor view also reflects this change.
    The message in the status bar indicates that one element was found for this RanoreXPath.

    Wildcards

    Wildcards can make a RanoreXPath more resistant to changes in the structure of the UI.

     

    Note icon

    Note

    The following wildcards exist:

    /* 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 optional)

    Track the entire UI-element test area in the demo application.

    'Any' wildcard example

    Ranorex Spy will show the follwing:

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

    The root element is represented in the first fixed part of the RanoreXPath expression.
    The middle UI element TabPageList is not represented. Instead, two /? wildcards replace it to make the path more robust. This is the wildcard part of the RanoreXPath.
    The final node is the target UI element, i.e. the entire UI-element test area tab page. It is the second fixed part of the RanoreXPath.

    Interpret the RanoreXPath

    Example RanoreXPath specification with /? wildcard

    The 3 target element is a descendant of the 1 root element with a total of either 2 zero, one, or two UI elements between them on two different tree levels.

    // (any descendants)

    It may often be necessary to identify elements whose “depth” in the UI we don’t know. The any descendants wildcard allows you to circumvent all the intermediate nodes between the root note and the final node.

    Enter the following RanoreXPath expression in the tree browser in Ranorex Spy:

    RanoreXPath specification with // (any descendants) wildcard

    The first part of the RanoreXPath expression represents the root node, i.e. the demo app window. This is the first fixed node.
    The second part is the any descendants wildcard. It is the wildcard node.
    The third part is the final node that represents the target UI element. In this case, this is any UI element with the role radiobutton. The expression identifies all radio buttons that are descendants of the root element.

    Spy shows the following results for this RanoreXPath:

    Search result for // (any descendant) wildcard operator

    The RanoreXPath as represented in the path editor.
    The tree browser displays seven radio buttons on two different levels (level 3 and level 4).
    The status message confirms 7 elements found.

    /* (any)

    If you know at what “depth” in the UI an element is you want to identify and the intermediate nodes are irrelevant, then the any wildcard is a good choice for making your RanoreXPath more robust.

    RanoreXPath specification with /* (any) wildcard

    The first part of the RanoreXPath expression represents the root node, i.e. the demo app window. This is the first fixed node.
    The second part consists of three any wildcards, representing any three UI elements on three different levels. This is the wildcard part of the expression.
    The third part is the final node that represents the target UI element. In this case, this is any UI element with the role radiobutton. The expression identifies all radio buttons that are exactly three levels below the root element.

    Spy shows the following results for this RanoreXPath:

    Search result for /* (any) wildcard operator

    The RanoreXPath as represented in the path editor. Each of the wildcard operators represents one level below the root element.
    The tree browser shows five radiobutton elements exactly three levels below the root element. Any radio buttons at other levels are not identified.
    The status message confirms five found UI elements.

    Make RanoreXPath expressions more detailed

    RanoreXPath expressions can often be too general, resulting in too many or incorrect UI elements being identified. In these cases, you need to make the expression more detailed.

    General RanoreXPath

    For our example, let’s first create a very general RanoreXPath. We’ll simply identify all buttons in the UI-element test area tab of the Ranorex Studio Demo Application.

    In Spy, enter the following RanoreXPath and press Enter.

    Example for initial general RanoreXPath specification

    The RanoreXPath as represented in the path editor.
    The tree browser shows 17 identified buttons.
    The status message confirms 17 found UI elements.

    Introduce more details

    Seventeen buttons are clearly too many. We need to make the RanoreXPath more detailed. We do so by adding an attribute to the button. In this case, we use the‘visible attribute to identify only buttons that are not hidden.

    Change the last part of the RanoreXPath as follows and press Enter.

    Example for narrowing RanoreXPath specification - part I

    The new RanoreXPath as represented in the path editor.

    The tree browser shows 15 buttons.

    The status message confirms 15 UI elements found.

    Even more details

    We’ve only reduced the number of buttons by two, so we need to narrow down the RanoreXPath further.  To do so, we can add another attribute and combine it with the previous one using the and operator.

    Change the last part of the RanoreXPath as follows and press Enter:

    Example for narrowing RanoreXPath specification - part II

    The RanoreXPath as represented in the path editor, now showing two attributes.

    The tree browser now shows two UI elements.
    The status message confirms two UI elements found.

    tipp icon

    Hint

    The and operator is one of several available in the ⇢ RanoreXPath syntax.

    Results

    The more detailed RanoreXPath expression now only identifies the two buttons shown below.

    Narrowed RanoreXPath search result example

    Select UI elements based on tree position

    When a RanoreXPath identifies more than one element, you can select from among them by specifying their position in the element tree.

    In Ranorex Spy, enter the following RanoreXPath and press Enter.

    Example for selecting elements in RanoreXPath specifications

    The RanoreXPath as represented in the path editor. The position operator [2] added after the predicate selects the second element from two elements identified by the preceding RanoreXPath.

    The tree browser only shows the second UI element.

    The status message confirms one found element.

    In the UI of the demo app, this identifies the button Button 1.

    RanoreXPath selection result
    Note icon

    Note

    Only the position in the element tree is relevant. In the UI itself, the position of the element may be different, as above with Button 1.

    Identify tree view items

    Tree views are a common UI element. Here we’ll explain how Ranorex Studio identifies UI elements in them.

    In Ranorex Spy, click the Track button.

    In the UI-element test area in the demo app, click the Web and mobile testing tree item.

    Tracking tree UI-elements with Ranorex Spy

    Ranorex Spy shows the following:

    Identification of a tree element with Ranorex

    The RanoreXPath for the tree item.
    Ranorex Studio automatically inserted two ‘any optional’ wildcards (/?/?) to increase robustness.
    The element tree in Spy shows the tree item Web and mobile testing as a descendant of the tree view.

    Subitems in tree views

    In Ranorex Spy, click the Track button.

    In the UI-element test area in the demo app, click the Endpoints tree item that is a child of the Web and mobile testing item.

    Tracking sub-tree UI-elements with Ranorex Spy

    Ranorex Spy shows the following:

    Identification of sub-tree elements with Ranorex Spy

    The RanoreXPath for the tree item. Note that the subtree item is identified in the same way as its parent, i.e. by its role and an attribute.
    The ancestor tree view in its entirety serves as a fixed node.
    Any tree items between the fixed node and the final node are circumvented by an any descendants operator.
    The subtree item Endpoints is identified regardless of how many ancestor tree items it has.

    Note icon

    Note

    Ranorex Studio treats all subtree items as regular tree items and identifies them with a predicate (attribute + value) in the same way. To ensure the tree structure does not interfere, it also inserts an any descendats operator. This way, it can find the tree item wherever in the tree it is.

    Identify tree siblings with axes

    When you want to identify the sibling(s) of a tree item, you can do so by using ⇢ axes. Axes allow you to specify nodes relative to a specific node. We’ll illustrate this by using the following-sibling axis.

    In Ranorex Spy, enter the following RanoreXPath and press Enter.

    Applying axis specifiers to RanoreXPath specifications

    The RanoreXPath with the added axis following-sibling::treeitem after the part that identifies the Endpoints tree item. This axis means identifies all UI elements that have the role treeitem and are below the Endpoints tree item on the same level in Spy’s element tree.
    The RanoreXPath as represented in the path editor.
    The tree browser in Spy displays the tree item Mobile testing, which is the only following sibling of the Endpoint item.

    Identification of following-sibling tree item

    The identification process illustrated in the UI of the demo app. The RanoreXPath first identifies the Endpoints item and then progresses to the Mobile testing item, which is the following sibling.

    Note icon

    Note

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

    Identify items in tables

    Here we’ll explain how identifying items in tables works with RanoreXPath.

    Test definition

    In this example we want to robustly identify the cell that contains the age of the person named Thomas Bach in the table of the UI-element test area in the demo app. This means that we need to identify both the cell that contains the name Thomas and, proceeding from it, the cell that contains the corresponding age.

    Table cell specification - test definition

    The row with the details for Thomas Bach.

    The cell that contains the age of Thomas Bach. We want to create a RanoreXPath that identifies it robustly.

    Identify the name cell with an absolute RanoreXPath

    First we’ll identify the cell that contains the name Thomas. A simple way is to just track the cell and generate an absolute RanoreXPath to it as in the image below.

    Absolute table cell specification

    Absolute RanoreXPath for the marked cell.
    The RanoreXPath identifies the cell with the accessiblename “FirstName Row3”, which reflects the cell’s position in the table. This is the cell that currently has the value Thomas.
    The identified UI element in the element tree in Spy.

    Not robust against changes

    The absolute RanoreXPath has its limitations here. When the table changes, the name in the identified cell may not be Thomas anymore, e.g. when you sort the table differently or shuffle it.

    Table cell shuffle

    Shuffling the table cell arrangment shows that…
    …the absolute RanoreXPath leads to wrong results, as it only cares about the cell position, not the name Thomas.

    Specify cell content in the RanoreXPath

    Instead of identifying the cell by its accessiblename (which is based on its position), we can use the attribute text. This attribute refers to the text in a cell.

    This is still not a robust solution, however, as there are two cells with the text Thomas.

    Cell content specification

    Using the cell content for identification makes the path robust against shuffling, but…
    …also identifies all cells with the specified content.

    Make the RanoreXPath more narrow

    We need to make sure only the Thomas cell in the FirstName column is identified. We do so by extending the predicate by another attribute that relates to the accessiblename of the cell.

    Narrowed cell specification

    The narrowed cell with two attributes forming the RanoreXPath predicate.
    Only one cell is identified – the Thomas cell in the column FirstName.

    tipp icon

    Hint

    Depending on the case, you may need to make the RanoreXPath even more detailed, e.g. by adding more attributes or with axes.

    Going from absolute to relative

    Now that we’ve robustly identified the cell containing the first name Thomas, we can now look at identifying the corresponding cell that holds Thomas’s age.

    We’ll do so by making the path relative. This means that we’ll use the parent axis (abbreviated form: ..) to navigate from an anchor point (the Thomas cell) back to the row and from there to the age cell in that row. This ensures the age cell is tied to the position of the Thomas cell and therefore always identified correctly.

    Relative cell specification

    The relative RanoreXPath with the parent axis and the age cell being identified by its accessiblename.
    This identifies the cell with the age of Thomas Bach (42) correctly.