Ranorex Repository - Managing UI Elements

This Documentation is only for Ranorex 2.x versions.

Click here for the Ranorex 3.x test automation documentation

General

The Ranorex Element Repository is used to separate identification information (RanoreXPath) from Ranorex test automation code. Moreover each GUI element within the repository is represented by a logical user-defined name which results in more readable test automation code.

: Test automation code based on Ranorex repository 'WordPadObjects'

Each Ranorex repository represents file based mapping information and targets to centralize GUI element identification information for easier maintenance. There is no need to change test automation code which is caused by changing names or other identification attributes within the application under test.

Repositories could contain following type of items:

	Application folder #1	Represents a top level application or dialog
	Adapter item #2	Represents a Ranorex adapter (Button, ListItem, TextBox, ComboBox,...)
	Normal folder #3	Used to organize items
	Rooted folder #4	Contains GUI elements having the same parent or RanoreXPath substring

: Repository containing Application folder, Adapters, normal folder and rooted folders

Creating a new Object Repository

In the same way that the Element Browser view supports tracking, the Element Repository supports tracking of GUI elements. Use the 'Track' button or the shortcut key <CTRL> + <LWin> to add GUI elements to the current repository list. After tracking the RanorexSpy automatically suggests a logical name for each added item. Simple double click an item to change the name of the object.

: Changing name of added repository item

But, it's not necessary to add item per item separately to a repository. Alternatively, one can query for suitable UI elements to add within the Element Browser view. Simply select the context menu item 'Add Matching Children to Repository' to add multiple items at once to the repository view.

The more objects you add to a repository the more structured and organized it should be. For this reason the repository provides two types of folders for structuring and grouping GUI elements which logically belong together.

The commonly used folder type should be a so-called rooted folder. This type of folder collects GUI elements having the same parent in order to avoid the use of multiple RanoreXPath substrings.

Use the toolbar buttons to create rooted or normal logical folder types within your repository and use simple drag&drop mechanism to move existing repository items into them.

: Automatically generated repository

: Reorganized repository

: Code based on organized repository

The example code above uses an application folder called 'MainForm' which represents in that case the main window of the application under test. Both application folders ('MainForm' and 'ContextMenu) are part of a logical folder called 'VIPApplication'. Such a folder is used to group all kind of application folders like forms, dialogs or message boxes belonging to one logical application.

Within code all rooted and application folder types provide a property called 'Self' to work directly with the Ranorex form adapter for example as follows.

C#

// Close the application form directly
vipUIObjects.VIPApplication.MainForm.Self.Close();
// ... or activate it if it is required
vipUIObjects.VIPApplication.MainForm.Self.Activate();

VB.NET

' Close the application form directly
vipUIObjects.VIPApplication.MainForm.Self.Close()
'... or activate it if it is required
vipUIObjects.VIPApplication.MainForm.Self.Activate()

For that reason there is no need to create an additional Ranorex repository item for application windows or dialogs.

Create a new folder or a new rooted folder by clicking one of the provided toolbar buttons. Add an existing repository item to your folder using the drag and drop functionality supported through Ranorex Spy.

Validating Repository Items

The repository browser provides two ways to check the RanoreXPath expressions of repository items:

Use of context menu item 'Highlight element'
Activation of toolbar button 'Highlight Repository Item'

Both can help to check the RanoreXPath expression of an object item and highlight the UI element if the path is valid.

Turn on 'Highllight Repository Item' using the toolbar button to browse quickly through your object tree to get a better understanding of the repository structure.

Use the context menu item 'Highlight element' to search for a specific object item. After clicking the menu item, a pop-up dialog appears showing the search progress. That's a useful way to validate a RanoreXPath expression especially for context menu items or other pop-up windows requiring a manual trigger to bring in front. Simply open the related context menu or pop-up window manually. The UI element will be highlighted if the searched item is part of the window.

: Validating a repsitory item in progress

Read more about how to validate items within code here.

Item related Properties

A Ranorex repository is more than a simple GUI mapping table. Each item and each folder of a repository should be used to handle typical wait scenarios using the SearchTimeout property. Additionally all adapter items can be configured to ensure visibility before use (for instance clicking on a non-visible button or list item). Simply open the property grid using the context menu item 'Properties'.

: Properties of Application folder 'FormCalculator'

The following Ranorex exception reports that the specified element for the given RanoreXPath was not found within the specified timeout. Check the validation of the RanoreXPath expression using the 'Highlight element' context menu item within Ranorex Repository. If the path seems to be correct, you should confirm that the required dialog or application is valid at the time of automation, and additionally increase the 'SearchTimeout' property for the related Application folder.

: Report message 'Ranorex.ElementNotFoundException'

General Repository Configuration

To change the default search timeouts used for the repository simply open the configuration dialog by clicking toolbar button.

: Opens the configuration dialog of the repository

The repository's configuration dialog contains four tab sections, but only two of them rely directly on the repository. The tab items 'General' and 'Imaging' contain general Ranorex settings which affect the behaiviour of Recorder and Repository during recording and replay.

Simple adapt the values of the 'Repository Defaults' tab to specify the defaults for repository folders and items. Also uncheck the 'Enable folder caching' to turn off folder caching for all items by default. Uncheck the checkbox 'Enable folder autogeneration' to prevent the repository from creating rooted folders automatically.

To rename the class name or the general namespace of the automatically generated source code, change the values within the 'Current Repository' tab.

: Current settings of a repository

: Default repository configuration

Repository Troubleshooting - Folder Caching

In some situations, repository items cannot be found because the caching information of the item's parent folder is incorrect. In such cases, replaying the steps involving these items may only work part of the time or only with long delays.

This is caused by a fallback mechanism which is used to search for an item without using the cache if the first attempt fails. If this occurs, it is recommended to disable the folder cache for the item's parent folder by setting the 'Use Cache' property to 'False'.

How to use repositories for test automation

A Ranorex Repository can be created in different ways. The Repository editor is available within Ranorex Spy, Ranorex Studio and Ranorex Recorder. Irrespective of the context, how one works with the Repository remains the same.

: Element Repository within Ranorex Spy

: Integrated repository within Ranorex Recorder

: Integrated repository within Ranorex Studio

To reuse a Ranorex Repository within a Ranorex Studio project or within a Ranorex recording save your repository as a file (*.rxrep) by clicking the ‘Save’ button. Simply add the saved repository to an existing Ranorex Studio project. Click here to learn more about Ranorex repositories within Ranorex Studio.

Most of the action items within a Ranorex recording refer to GUI elements. Within the Recorder, the repository represents a pool of GUI elements used for Recorder based test automation. To use an existing repository for a new recording, open an existing repository before starting a new recording session. During recording the Recorder reuses the items from the existing repository.

For .NET based Visual Studio projects another way to provide repository items is to generate source code directly by clicking the ‘Generate Code’ button.

: Generate code from current repository

Toolbar short cuts
	New Folder	Creates a new folder to group items belonging logícally together
	New Application Folder	Creates a new Application Folder
	New Rooted Folder	Creates a new rooted folder to group items having the same parentage
	New Item	Adds a new unspecified item
	Copy Item	Copies the selected item(s) into the clipboard
	Paste Item	Inserts the item(s) from the clipboard
	Undo	Undo the last action within the repository
	Redo	Redo the last action within the repository
	Delete Item	Deletes the currently selected item
	Load Repository	Opens an existing repository
	Save current Repository	Saves the current repository
	Save current Repository As...	Saves the current repository to a new file location or file name
	Show Item Properties	Opens an item related property view
	Configuration	Opens the configuration dialog
	Generate Code	Generates C#, VB.NET or IronPython source from the current repository
	Highlight Repository Item	When switched on highlights visible items on the system desktop