Ranorex Help Center

How can we help you?

The Path Editor

In this section you will learn about

As you might know, the RanoreXPath expression is a powerful identifier of UI elements for desktop and Web applications.  To learn more about the RanoreXPath have a look at the section 'RanoreXPath'.

How to Access the Path Editor

It's this easy: Everywhere a RanoreXPath is visible in a Ranorex Tool you can edit this RanoreXPath with the path editor.

You can access the path editor by choosing any UI Element in the repository and then clicking the 'Edit button' on the left of the RanoreXPath, or alternatively by pressing the key shortcut <CTRL><E>.

Click the 'Edit' button to open the path editor

Click the 'Edit' button to open the path editor

In Ranorex Spy, the path editor can be accessed by simply switching to the 'PATH EDITOR' tab.
Switch to path editor tab

Switch to path editor tab

Layout of the Path Editor

The editor can be broken down into two main areas: the RanoreXPath shown in a tree view on the left (marked in green) and the attribute comparison list of the selected tree item on the right (marked in red).
Overview of path editor

Overview of path editor

Additionally you can see the number of identified UI elements using the given RanoreXPath in the status bar. Buttons to refresh and to highlight the identified elements can be found right above the tree view and the original RanoreXPath can be found at the top of Ranorex Spy, right below the modified one.

As you can see, the whole path is shown in this tree structure with each path element being a node of the tree. In the left section of the editor, you can access each of these path elements to alter the attribute comparisons in the right section on which the path is based.

After altering the RanoreXPath, you can review the effects by pressing the refresh and highlight buttons and apply the changes using the 'Apply' button next to the RanoreXPath at the top of Ranorex Spy.

Of course you can change the RanoreXPath by using the 'Track' button, too. To simplify tracking, the tracking area is limited to the parent folder of the selected repository item (grayed out in RanoreXPath at the top of Ranorex Spy), which will be indicated with a yellow border.

Tracking area limited to the KeePass application

Tracking area limited to the KeePass application

The Tree View Section

As described above you can see the whole RanoreXPath you want to edit mapped as a tree structure. For example if you start KeePass and add two entries, one called 'WordPressDemo' and the other called 'GMail' and you track the cell holding the username of 'GMail', you will get the following tree structure in the path editor:

KeePass with one cell being tracked by Ranorex Spy

KeePass with one cell being tracked by Ranorex Spy

RanoreXPath structure in path editor for a cell in second row

RanoreXPath structure in path editor for a cell in second row

The Attribute Comparison Section

In the attribute comparison section of the path editor you can define the attribute value comparison which the RanoreXPath is based on. If you want to define the adapter being accessed with different attributes than the ones being suggested by Ranorex, you are free to change the method of object identification here by simply checking and unchecking attributes.

Concerning KeePass and the data-driven approach (see Lesson 3: Data-Driven Testing ) we validated the success of 'Adding an entry' with the validation of the existence of the entry in the grid. Thus we add two sample entries (WordPressDemo and GMail) to KeePass. When Ranorex Spy is used to track the username of the GMail entry (second cell in the second row), the following structure of RanoreXPath results in the path editor window:

/form[@controlname='MainForm']/container[@controlname='m_splitHorizontal'] //table[@controlname='m_lvEntries']/row[@index='1']/cell[@text='Ranorex']

What we can see in the RanoreXPath structure (in path editor) as well as in the RanoreXPath itself is that the row (adapter) is identified by its 'index' attribute (row[@index='1']). This means that the cell 'Ranorex' is only recognized if it is located in the second row. This cell would not be found if an additional row was inserted above and the index was changed. Sorting by a column (e.g. column username) could easily lead to another row index. To avoid a problem concerning the row index, you could change the path with the use of the path editor to be row independent by unchecking the index attribute checkbox in the row node.
Uncheck the index attribute in the row node

Uncheck the index attribute in the row node

/form[@controlname='MainForm']/container[@controlname='m_splitHorizontal'] //table[@controlname='m_lvEntries']/row/cell[@text='Ranorex']

This path leads to any cell in any row containing the text 'Ranorex'. Concerning our validation of the success of adding an entry, it would be more meaningful if the path would lead to the text value 'Ranorex' in any row but only in the column 'UserName'. Therefore add the 'column index attribute' by checking it.
Check the column index attribute

Check the column index attribute

/form[@controlname='MainForm']/container[@controlname='m_splitHorizontal'] //table[@controlname='m_lvEntries']/row/cell[@text='Ranorex' and @columnindex='1']

If another KeePass entry is added which has the same username ('Ranorex'), this path would lead to multiple results. You can easily check the result of your RanoreXPath in path editor by having a look at the text in the bottom left corner.
The current path leads to two elements

The current path leads to two elements

To find out which elements are found with the current RanoreXPath, simply click on the 'Highlight' button on the bottom of path editor.
The underlying path leads to two elements in KeePass

The underlying path leads to two elements in KeePass

As you can see, building up a robust and unique path is a crucial task which always depends on the characteristics of your application.

Types of Comparisons

Ranorex provides a set of comparisons which can be used to build up or to modify a RanoreXPath. These comparison operators can be accessed via a drop-down in path editor.


Textual Comparisons

The following types of comparisons are defined for textual comparisons (case sensitive):

  • '=': The value of the attribute must be equal to the given value
  • '~': The value of the attribute must match the given regular expression
  • '!~': The value of the attribute must not match the given regular expression
  • ' !=': The value of the attribute must not be equal to the given value
  • '>': The value of the attribute must start with the given string 


Numerical Comparisons

The following types of comparisons are defined for numerical comparisons (starting with Ranorex Version 3.3):

  • '>': The (numerical) value of the attribute must be greater than the given value
  • '>=': The (numerical) value of the attribute must be greater than or equal to the given value
  • '<': The (numerical) value of the attribute must be less than the given value
  • '<=': The (numerical) value of the attribute must be less than or equal to the given value


Note Since the > operator is used for textual and for numerical comparisons as well, it depends on the type of the values you are trying to compare; i.e. whether the textual 'Starts with' or the numerical 'Greater than' functionality is used.

Example for Regular Expression

The following example shows how to use a 'regular expression' operator (~).

Matches all entries ending with the text fragment 'rex' using a regular expression

Matches all entries ending with the text fragment 'rex' using a regular expression

Result from the comparison above

Result from the comparison above

Note For more details about regular expressions, see RanoreXPath - RanoreXPath with Regular Expressions.


Example for Not Equal

The following example shows how to use the 'not equal' operator (!=).

Matches all entries that are not equal to 'Ranorex'

Matches all entries that are not equal to 'Ranorex'

Result from the comparison above

Result from the comparison above

Example for Starts With

The following example shows how to use the 'starts with' operator (>).

Matches all entries that start with 'adm'

Matches all entries that start with 'adm'

Result from the comparison above

Result from the comparison above

Example for Numerical Comparisons

The following examples demonstrates how numerical operators (>, >=, < and <=) can be used in the path Editor.


Matches all rows matching index > 2 and index <= 3

Result from the comparison above

Result from the comparison above

Relationship Operators

After exploring the comparison operators, you are going to learn more about the relationship operators. Relationship operators define the relationship between the nodes (elements of the path). It is therefore not necessary to always use a directed path. One element in the path can also be defined by using another relationship to its 'parent' other than being the child of a parent node.

The following relationship operators are available in the context menu of a node.

Available relationship operators in path editor

Available relationship operators in path editor

  • child: Refers to all children of the current node
  • descendant-or-self: Refers to all descendants (children, grandchildren, etc.) of the current node and the node itself
  • ancestor: Refers to all ancestors (parents, grandparents, etc.) of the current node
  • self: Refers to the current node
  • descendant: Refers to all descendants (children, grandchildren, etc.) of the current node
  • parent: Refers to the parent of the current node
  • ancestor-or-self: Refers to all ancestors (parents, grandparents, etc.) of the current node and the current node itself
  • preceding-sibling: Refers to all siblings before the current node 
  • following-sibling: Refers to all siblings after the current node

The following example describes,how to change the common parent-child relationship  in the path using relationship operators ('Axis'), e.g. if you want to refer to a table row containing any cell with the text 'Amazon'. Using the common, directed way of building up a path, this wouldn't be possible. We start with the path referring to the cell:

/form[@controlname='MainForm']/container[@controlname='m_splitHorizontal'] //table[@controlname='m_lvEntries']/row[@index='2']/cell[@text='Amazon']

We can now move back to the cell's parent using the 'parent' relationship operator. The parent element is a row, therefore we have to add a new level manually using the row adapter.

/form[@controlname='MainForm']/container[@controlname='m_splitHorizontal'] //table[@controlname='m_lvEntries']/row[@index='2']/cell[@text='Amazon']/row

In the path editor we choose the relationship operator 'parent' in the 'Axis' submenu.

Contextmenu for defining the relationship operator for currently selected node

Contextmenu for defining the relationship operator for currently selected node

This path first describes the way to a cell containing the text 'Amazon' and moves up one level of hierarchy to the parent of this cell, which is a row. Highlighting the element leads to the result shown in following figure.

Highlighting the element from the newly created path

Highlighting the element from the newly created path

Adapter Types

Adapters describe the type of element that is referred to. In the path editor you are able to change the adapter type easily.

Adapters used within a path which are automatically suggested by Ranorex, can also be changed using the context menu.

Changing the adapter to a specific type of element

Changing the adapter to a specific type of element

If you do not want to use a specific adapter, you can use the asterisk adapter ('*') which is an undefined container for all types of elements. This might be useful if your application has dynamically created elements and if for some parts of the path, the adapter should not be specified.

 

Optional Path Elements

Starting with Ranorex Version 3.3 it is possible to mark some parts of a path as optional which means that the referred elements can be found even if optional parts of the path do not exist.

In some situations it can be useful to mark parts of the path as optional. If you want to refer to the 'Windows' node within the folder tree in KeePass, this node can be located at the root level but, on the other hand, it could also be located in a sub node of the tree.

Windows node located at the root level (left) or...

Windows node located at the root level (left) or...


...in a sub-node of the tree (right) in KeePass

...in a sub-node of the tree (right) in KeePass

In general, the path to the 'Windows' node on the left side of the figure would not include the 'General' folder because this folder can be seen as a sibling. The path to the 'Windows' node on the right side, which can be seen as child element of the 'General' node, would therefore include this element in the path. Thus, the 'General' folder can be seen as optional if you want to access the 'Windows' node in both cases. Here, the 'General' folder could be marked as optional which means that regardless whether the 'Windows' folder is a child of the 'General' folder (and therefore is part of the path) or is a sibling of the 'General' folder (which is not part of the path) the element will be found.
 
Marking one level of the path as optional

Marking one level of the path as optional

/form[@controlname='MainForm']//treeitem[@accessiblename='NewDatabase']/treeitem?[@accessiblename='General']/treeitem[@accessiblename='Windows']

Defining Variables

In the RanoreXPath you are able to use variables which can be used for such things as data-driven testing. Variables can be created and assigned in the path editor.

If you start the path editor from an existing repository, there is an additional button for each (selected) attribute comparison. With these buttons you are able to define variables which can be used for data driven object identification.

Buttons for creating a new variable for every selected attribute

Buttons for creating a new variable for every selected attribute

Variables can also be created using the 'As new Variable' entry in the dropdown menu

Variables can also be created using the 'As new Variable' entry in the dropdown menu

The variables you have added are placed in the repository you are working on. Each of the variables held by the repository can be used as a value for attribute comparison. For more details about variables used within the repository, please have a look at Lesson 3: Data-Driven Testing - Using Variables within the Repository .

Live View with Dynamic Capabilities and Offline View

One additional thing to mention is that if you are in live view, you get more information delivered about the adapter you are working on than in offline view.

Offline view means working with a snapshot file or working with a repository holding information from a non-running application.


Note A Ranorex Snapshot file is able to keep the entire UI structure, the UI element's attributes and its belonging values as well as screenshots from the desired element and all its child elements. Learn more in the chapter: Creating Ranorex Snapshot Files.


In 'live' view you are additionally able to use the 'verify' and 'highlighting' functionality.

Starting with Ranorex Version 3.3, you are also able to access dynamic capabilities from adapters in live view. The following screenshot shows dynamic capabilities from the mainform of KeePass (WinForms).

Path editor window in live view having dynamic capabilities

Path editor window in live view having dynamic capabilities


Note Dynamic capabilities can only be accessed for certain types of technologies (WinForms, Flash/Flex, Web and Java).