Ranorex Basics: RanoreXPaths and Repositories

In the previous post, we discussed plugins, elements and adapters, the most basic Ranorex components that make everything else tick. Whereas elements and adapters are the raw materials, RanoreXPaths and the repository are the sauce that makes it possible to query and work with the UI effectively. And while there isn’t much you can do to improve your tests by understanding elements and adapters alone, RanoreXPaths and the repository provide many optimization opportunities.


Ranorex uses special paths, called RanoreXPaths and derived from the XPath query language, to locate elements in the UI. XPath is a special query language designed to search XML documents, which are essentially hierarchical representations of data. Similarly, Ranorex depicts the UI as a hierarchical representation of elements and provides the RanoreXPath query language to search the UI hierarchy.

Syntactically, RanoreXPath expressions are similar to XPath expressions; they share most of the syntax and logically behave the same. They both use axis specifiers (such as descendant or following-sibling), functions (e.g., position()), boolean operators, and so forth. But there are also a few differences, so they are not fully compatible or interchangeable. Quite simply, XPath elements map to Ranorex adapters, and attributes to adapter properties.

Take the following RanoreXPath expression as an example:


The expression represents a query that finds all button elements whose Text attribute matches the regular expression ^Submit, and which are somewhere inside a dom element whose Domain property is exactly equal to www.example.com.

The important thing to note here is that dom and button are the names of (or synonyms for) the WebDocument and Button adapters, respectively, and domain and text are the names of their attributes. What this means is that RanoreXPaths are directly related to adapters. If an element can be represented with an adapter, that adapter can be placed in the path.

And you can mix and match. You can specify an adapter with a filter associated with a different adapter. For example, a browser window element can be used with either a WebDocument or Container adapter. Since the Container adapter has a Caption attribute, the RanoreXPath expression can look as follows even though the WebDocument does not have a Caption attribute:



A repository provides a map of an application’s UI. It is not a one-to-one element mapping and almost never directly mirrors the element tree shown by the Ranorex Spy. A tester generally adds to the repository only the folders and items explicitly needed by the test suite. In general, every repository item and folder can be used in a module, not just repository items.

Each item and folder is associated with a partial RanoreXPath. Whenever an item or folder is used, Ranorex constructs a full RanoreXPath from the partial RanoreXPaths of all the folders in the selected item or folder’s hierarchy.

Whereas coders may be more comfortable using elements directly, repositories provide a more user-friendly mechanism for working with RanoreXPaths and querying elements. Behind the scenes, Ranorex Studio generates code to represent repository folders and items. This code relies internally on the Element class, but provides additional services, including the following:

  • The user can choose which adapter to expose after querying the UI independently of the adapter specified in the RanoreXPath, by modifying the repository item’s Adapter Type property in Ranorex Studio.
  • Repository items and folders use RanoreXPaths that support variables and data binding. A single repository item can be used to find different UI elements, based on the variable value.
  • App folders and rooted folders, two types of repository folders, support caching to improve test run performance.

Most importantly, the repository represents a manageable subsection of the UI that your tests actually use.


This post explains some of the basic functionality of the RanoreXPaths and Ranorex repositories. These two tools are ubiquitous and central to writing a successful test suite, and understanding the basics is important to troubleshooting any issues you might encounter.

If you’re looking for ways to optimize your test run performance, read more on test run speed optimization.

Leave a Reply