Ranorex Help Center

How can we help you?

RanoreXPath

A RanoreXPath expression is primarily used to uniquely identify UI elements within a desktop, web or mobile application. Generally, a RanoreXPath expression consists of:

  • Adapters
  • Attributes
  • and Values
Main components of a RanoreXPath expression

Main components of a RanoreXPath expression

Screencast: A detailed explanation of RanoreXPath expressions, the elements and the way they work can be found in our screencast named "RanoreXPath". You can watch it here: http://youtu.be/UqiCtDlk0hM


The adapter type specifies the type or classification of a UI element to search for (button, form, text field, listbox, etc.).

Looking at the first part of the RanoreXPath expression '/form[@title='Form 1']' the

  • '/form' string specifies a search for a UI element of adapter type form.
    A Ranorex.Form adapter represents top-level windows such as dialogs or messageboxes on the Windows desktop system.
  • The attribute value comparison '[@title='Form 1']' specifies the UI element in detail.

As an example the first part of the RanoreXPath expression shown in the pictures will look for a UI element which is of type form and has an attribute called 'title' with the value 'Form 1'. This form holds a container witch caption 'Container 1', which holds a button with text 'Button 1'.

Hierarchical structure of a RanoreXPath

Hierarchical structure of a RanoreXPath

Use the Ranorex Spy tool to get the RanoreXPath for a particular UI object. To edit a RanoreXPath use the text box in Ranorex Spy or change the path value of a repository item directly in the repository view. A more comfortable way to edit RanoreXPath is provided by the path editor.

Note Use the <CTRL> key in combination with the arrow keys to navigate to the previous or the next token in RanoreXPath. Use the <CTRL> key and the <SHIFT> key in combination with the arrow keys for selecting specific parts of the RanoreXPath. Use the <SHIFT> key in combination with the <UP> arrow key to select the current token of the  RanoreXPath (tokens can be a values, identifiers, operators ...).

In this section you will learn more about RanoreXPath:



RanoreXPath Syntax Examples

Each RanoreXPath can return multiple GUI elements which match the path query.  RanoreXPath is modeled on W3C XPath; but they are not identical. Some functions of RanoreXPath are not available in W3C XPath and vice versa.

Axes

Name Description Example
child Returns the direct children of the currently selected element.

/form/child::button

or

/form/button

descendant Returns the descendants of the currently selected element. Descendants are direct children, the children of these children, and so on. /form/descendant::button

descendant-or-self (also: //)

Returns the descendants of the currently selected element and itself.

/form/descendant-or-self::button

or

/form//button

parent (also: ..) Returns the direct parent of the currently selected element.

/form/button[@caption='OK']/parent::*

or

/form/button[@caption='OK']/..

ancestor Returns the ancestors of the currently selected element. Ancestors are direct parents, the parents of these parents, and so on. //button[@caption='OK']/ancestor::*
ancestor-or-self Returns the ancestors of the currently selected element and itself. //button[@caption='OK']/ancestor-or-self::*
preceding-sibling Returns all siblings of the currently selected element that occur before itself. /form/button[@caption='OK']/preceding-sibling::button
following-sibling Returns all siblings of the currently selected element that occur after itself. /form/button[@caption='OK']/following-sibling::button
self (also: .) Returns the currently selected element itself.

/form//ancestor::container/self::[@enabled='True']

or

/form//ancestor::container/.[@enabled='True']


Attributes

 Example

Description

Identifies a top level application

/form

Identifies a top level application with the title 'Calculator'

/form[@title='Calculator']

Identifies a top level application with the title 'Calculator' and an attribute of instance with value two

/form[
@title='Calculator' and @instance='2']

Identifies a top level application with the title 'Calculator' or by its class

/form[@title='Calculator'
or @class='SciCalc']

Identifies a button in the application

/form/button

Identifies the second button in the application

/form/button[2]

Identifies the second-to-last button in the application

/form/button[-2]

Identifies a button with a text attribute value of '7'

/form/button[@text='7']

Identifies a button with a text attribute value that is not '7'

/form/button[@text!='7']

Identifies a button with a text attribute starting with 'sample'

/form/button[@text>'sample']

Identifies a button with a text attribute ending with 'sample'

/form/button[@text<'sample']

Identifies a button using a regular expression

/form/button[@text~'^7']

Identifies a button not matching a regular expression

/form/button[@text!~'^7']

Identifies a WinForms control using cascaded attribute names. The identified control has an "Items" property that has a "Count" property which returns the value 100

/form/control[@items.count=100]

Identifies any element with a text attribute value of '7'

/form/*[@text='7']

Optional location step fitting a container adapter between form and button; Identifies both, '/form/container[@caption='Container 1']/button' and '/form/button'

/form/container?

[@caption='Container 1']/button

Identifies button with any attribute containing the substring 'add' (case-insensitive)

/form/button[?'add']

Identifies a button where the attribute text is not null

/form/button[@text!=null()]

Identifies a progress bar with value greater than or equal 13.5 (following comparison operators are also available: >, <=, <)

/form/progressbar[@Value>=13.5]

Identifies a top level application with title attribute value set to value stored in variable $var

/form[@title=$var]

Identifies the button with index equals the value stored in the variable $var

/form/button[$var]

Identifies an input element on a web document with unique id 'search' (supported for web testing)

/dom//input[#'search']

Combines the path to a unique id with an additional attribute (enabled is true)

/dom//input[#'search'][@enabled='True']

Functions

Example

Description

Identifies the first cell of a row

/form/table/row/cell[first()='True']

Identifies the last cell of a row

/form/table/row/cell[last()='True']

Identifies the second element in the current result list (containing cells only) (Note:  the result of the index()-function is one-based)

/form/table/row/cell[index()=2]

From the current result list of all element types (everything beneath the row), the element on the second position will be identified if it is from type cell (Note: the pos()-function is zero-based)

/form/table/row/cell[pos()=1]

Identifies a top level application with screen coordinates greater than 100

/form[x()>100 and y()>100]

Identifies a button with client coordinates (coordinates of an element relative to its parent) greater than 10

/form/button[cx()>10 and cy()>10]

Identifies a top level application with width and height greater than 100

/form[width()>100 and height()>100]

If the innertext-attribute is available (web testing), test() brings back the value of the innertext attribute

/dom/body/form/button[text()='Clear']

Identifies a form with the id-attribute not being set (=null)

/dom/body/form[@id=null()]

Result Set Selector

Every step in a RanoreXPath expression produces a list containing zero or more elements. These elements can be in various relationships to each other, for example siblings, parent-child or any other relationship imaginable.

Example:

form//button[@enabled='True']

The expression above selects all enabled buttons on all available levels below a Form element.

For picking one element from the entire result set, a Result Set Selector can be specified by using an additional set of brackets.

Example:

form//button[@enabled='True'][2]

From the complete list of enabled buttons (on various levels), the Result Set Selector selects the second element. Note that the Result Set Selector is only applied after the step where it was specified has been completely evaluated. The result will be fundamentally different from the result list of the following statement:

form//button[@enabled='True' and index()=2]

(This would select all enabled buttons with index equal to 2)

Advanced RanoreXPath Example

The following example describes how to use RanoreXPath to identify a GUI element not having unique attributes. The example shows how to access a HTML checkbox using a relative RanoreXPath expression.

Each row in the table represents a user. The users attributes are mapped into separate cells.

  1. Identify a user from a list by name (highlighted green)

    /table/*/tr/td/a[@InnerText='Username']
  2. Select the corresponding checkbox with a relative path from the name ( highlighted red)

    /../../td/input[@type='checkbox']

  3. Get the full path to the checkbox by combining the two paths.
Advanced RanoreXPath example

Advanced RanoreXPath example

RanoreXPath with Regular Expressions

Description Example

Matches the following button elements: 'sample0', 'sample1', ... 'sample9', 'My sample26'

button[@text~'sample[0-9]']

Matches all elements starting with text value sample

listitem[@text~'^sample']

Matches all elements ending with text value sample

listitem[@text~'sample$']

Matches text value gray or grey

listitem[@text~'gr(a|e)y']

Matches 'sample 123' (use backslash to escape special characters like space)

listitem[@text~'^sample\ 123$']

Matches the regular expression case-insensitive, e.g. 'mytext', 'MYTEXT', 'mYTeXT', ...

listitem[@text~'^(?i:MyTeXt)$']

The following are special characters that need to be escaped when used in a regular expression by prefixing them with a backslash '\'. E.g. when you want to match the text 'Sample.' (with a dot at the end), the dot needs to be escaped: 'Sample\.'. 

Character Description
.
The dot will match any single character. For example 'Sample.' matches 'Sample1', 'Samplex', etc.
$
The dollar sign will match the end of the string. The expression 'abc$' will match the sub-string 'abc' only if it is at the end of the string.
|
The alternation character allows either expression on its side to match the target string. The expression 'gr(a|e)y' can match 'gray' or 'grey'.
*
The asterisk indicates that the character to the left of the asterisk in the expression should match zero or more times. For example 'go*gle' matches ggle, gogle, google, gooogle, etc.
+
The plus is similar to asterisk but there must be at least one match of the character to the left of the + sign in the expression. For example 'go+gle' matches gogle, google, gooogle, etc.
?
The question mark (?) matches the character to its left 0 or 1 times. For example, 'colou?r' matches both color and colour.
^
Beginning of the string. The expression '^A' will match an A only at the beginning of the string.
()
The parenthesis affects the order of pattern evaluation.
[]
Brackets enclosing a set of characters indicate that any of the enclosed characters may match the target character.
[^0-9]
The caret immediately following the left-bracket  has a different meaning. It is used to exclude the remaining characters within brackets from matching the target string. The expression '[^0-9]' indicates that the target character must not be a digit.

For additional information on regular expressions please consult the corresponding MSDN web site: http://msdn.microsoft.com/en-us/library/az24scfc.aspx