RanoreXPath

General

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

Adapters
Attributes
and Values

: Main components of a RanoreXPath expression

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[@controlname='formVipApplication']' 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'[@controlname='formVipApplication']' specifies the UI element in detail.

As an example the first part of the RanoreXPath expression shown in the picture above will look for a UI element which is of type form and has an attribute called 'controlname' with a value of 'formVipApplication'.

Learn more about RanoreXPath

Get the RanoreXPath for a UI element

To get the RanoreXPath you can use:

Ranorex Spy provides all the functionality needed to explore and analyze applications or websites
Element Browser in Ranorex Studio

This example shows you how to do tracking and get the RanoreXPath from an element:

Start the Windows calculator.
Start the Ranorex Spy.
Click the 'Track' button to start tracking.
Move your mouse pointer over button ‘7’ on the calculator so that it is highlighted.
Click ‘7’ button.

The following RanoreXPath represents the unique identifier for the '7' button in the calculator application:

How to modify the RanoreXPath manually

Depending on the type of the element, Ranorex Spy provides role specific attributes like ‘Text’ for a button. To change or combine it with some other attributes you can modify the RanoreXPath.

This example shows you how to find button ‘6’:

Delete the text ‘text =’7’’.
Edit the text to “controlid=’130’”.
Press “Enter”.

By editing the path use <CTRL> + <SPACE> to open the path completion window which provides you to find the correct element.

You can also combine attributes in RanoreXPath like this:

Ranorex tests are always based on RanoreXPath expressions. Depending on the type of technology used by the AUT, there are different attributes used for identification within the RanoreXPath. In cases of .NET controls for example, a button control is always identified by its control name which is language independent.

Other types of applications like the main window of the windows calculator application are mostly identified using the title of the application. In such cases you're able to extend the generated RanoreXPath by Ranorex Spy with a simple OR disjunction.

How to use RanoreXPath within code

Within Ranorex Studio simply drag&drop elements from the Element Browser into code. The Ranorex API also supports the Find() and FindSingle() methods to search for elements. Combine these methods with relative RanoreXPath expressions to filter for elements or to search for single items.

C#

// Setting default search timeout for absolute path assignment to 10 seconds
Adapter.DefaultSearchTimeout = 10000;
// Automate a button with absolute RanoreXPath 
Ranorex.Button myButton5 = "/form[@title='Calculator']/button[@text='5']";
myButton5.Click();

// Automate a button with relative RanoreXPath
Ranorex.Form form = Host.Local.FindSingle("/form[@title='Calculator']");
// Calling FindSingle without a search timeout,
// searches for the specified path one time
Ranorex.Button myButton7 = form.FindSingle("button[@text='7']");
myButton7.Click();

// Automate all buttons within a form  
foreach (Ranorex.Button button in form.Find("button"))  
{  
	Mouse.MoveTo(button);  
}

VB.NET

' Setting default search timeout for absolute path assignment to 10 seconds
Adapter.DefaultSearchTimeout = 10000
' Automate a button with absolute RanoreXPath 
Dim myButton5 As Button = "/form[@title='Calculator']/button[@text='5']"
myButton5.Click()

' Automate a button with relative RanoreXPath
Dim form As Ranorex.Form = Host.Local.FindSingle("/form[@title='Calculator']")
' Calling FindSingle without a search timeout,
' searches for the specified path one time
Dim myButton7 As Ranorex.Button = form.FindSingle("button[@text='7']")
myButton7.Click()

' Automate all buttons within a form  
For Each button As Button In form.Find("button")
	Mouse.MoveTo(button)
Next

Python

# Setting default search timeout for absolute path assignment to 10 seconds
Adapter.DefaultSearchTimeout = 10000
# Automate a button with absolute RanoreXPath   
myButton5 = Button("/form[@title='Calculator']/button[@text='5']")  
myButton5.Click()  
 
# Automate a button with relative RanoreXPath  
form = Form(Host.Local.FindSingle("/form[@title='Calculator']"))
# Calling FindSingle without a search timeout,
# searches for the specified path one time
myButton7 = Button(form.FindSingle("button[@text='7']"))  
myButton7.Click()  
 
# Automate all buttons within a form    
for button in form.Find("button"):
	Mouse.MoveTo(button)

Learn more about Ranorex GUI Adaptors used in the above sample (Form, Button).

RanoreXPath syntax examples

Each RanoreXPath can return multiple GUI elements which match the path query. RanoreXPath is modeled on W3C XPath.

Axes
/form/button	absolute path identifying all buttons that are children of a form
./button	relative path identifying all buttons that are children of the current element
//button	identifies all buttons that are descendants of the root element, i.e. all buttons in all levels of the element tree
.//button	identifies all buttons that are descendants of the current element, i.e. all buttons in the subtree of the current element
../button	identifies all buttons that are descendants of the parent of the current element
Attributes
/form	identifies a top level application
/form[@title='Calculator']	identifies a top level application with the title 'Calculator'
/form[ @title='Calculator' and @instance='2']	identifies a top level application with the title 'Calculator' and an attribute of instance with value two
/form[ @title='Calculator' or @class='SciCalc']	identifies a top level application with the title 'Calculator' or by its process name
/form/button	identifies a button in the application
/form/button[2]	identifies the second button in the application
/form/button[@text='7']	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 using a regular expression
/form/*[@text='7']	identifies any element with a text attribute value of '7'

Advanced RanoreXPath example

The following example describes how to use RanoreXPath to identify a GUI element having no 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.

Identify a user from a list by its name (green highlighted)
```
/table/*/tr/td/a[@InnerText='Username']
```
Select the corresponding checkbox with a relative path from the name (red highlighted)
```
/../../td/input[@type='checkbox']
```
Get the full path to the checkbox by combining the two paths.

RanoreXPath with regular expression

button[@text~'sample[0-9]']	matches the following button elements: 'sample0', 'sample1', ... 'sample9', 'My sample26'
listitem[@text~'^sample.*']	matches all elements starting with text value sample
listitem[@text~'.*sample$']	matches all elements ending with text value sample
listitem[@text~'gr(a\|e)y']	matches text value gray or grey
listitem[@text~'^sample\ 123$']	matches 'sample 123' (use backslash to escape special characters like space)
listitem[@text~'(?i:MyTeXt)']	matches the regular expression case-insensitive, e.g. 'mytext', 'MYTEXT', 'mYTeXT', ...

The following are special characters that need to be escaped when used in a regular expression by preceding 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 'g*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