Documente Academic
Documente Profesional
Documente Cultură
The Ranorex Automation Framework is used to automate all kind of Windows applications and web sites.
Page 1 of 247
RanoreXPath
Ranorex UI Adapter
Android Testing
Web Testing
Ranorex Studio IDE
Visual Studio Integration
System Requirements
64-bit Platforms
Remotely Working with Ranorex
Silent Installation of Ranorex
Licensing
FAQ
Page 2 of 247
Ranorex Studio - The Layout
This initial lesson will introduce the main environment from Ranorex studio.
Before you start creating your first test case with Ranorex Studio you should know about the main views and
layout of Ranorex Studio.
#1 - Project View
A Ranorex Studio project is based on files and uses the same project file format as Microsoft Visual Studio 2008.
The project view shows all files and references currently associated with the project. A Ranorex Studio project
can have the following type of items:
C ode Files Any type of C # or VB.NET code; typically used to create code based automation modules
The project view is mainly used to add new items like Recordings, Repositories, Module Groups, or C ode Modules.
#2 - Module Browser
The 'Module Browser' view lists all available modules (C ode Modules & Recording Modules) based on the project's
code files and module groups based on the projects module group file. In addition it shows all the variables
defined by a module or module group. The view is mainly used to drag and drop and to reuse automation
modules and module groups within the test suite view.
Specify folders (e.g. for recording files) within the project's view to group modules. In order to find already
existing modules use the module browser's search field.
#3 - File View
When double-clicking a file in the 'Project View' or a module in the 'Module Browser', the associated file will be
openend in the Studio's file view. This view is mainly used for the actions shown below.
Page 3 of 247
Working with the project's test suite Working with the project's module groups
Page 4 of 247
Lesson 1: Getting Started
In this lesson you will gain a deeper understanding of the recorder. The first recording will capture a set of user
actions (mouse clicks, keystrokes) done while working with the tool KeePass which is delivered with Ranorex
Studio. KeePass is a widely available and easy to use open source password manager.
The easiest way to create a first test with Ranorex is to record a manually executed test scenario. The recorded
actions like mouse clicks or keyboard actions are the base for building a robust test case. In this lesson you will
learn about:
Do not run multiple instances of your application under test if that is not part of the test case itself.
By default mouse movements are not recorded. For this reason please also perform a mouse click in
situations like when navigating through menus. Note: Read more about how to activate mouse movement
recording in Lesson 5: Ranorex Recorder - Recorder Hotkeys.
Since version 3.3, KeePass is included with Ranorex Studio along with a sample database file.
On the start screen of Ranorex Studio you'll find a 'Sample' button which also includes a sample test suite project
that handles some test cases within the KeePass application. You can have a closer look at that in Lesson 4:
Ranorex Test Suite - General Structure of a Test Suite and its Test C ase.
Page 5 of 247
Recording a Test
In the following section you will create a new Ranorex Test Solution and record the process for adding an entry to
KeePass.
Open Ranorex Studio by choosing Start > Programs > Ranorex > Ranorex Studio. C lick the ‘New Test
Solution…’ button to create a blank test suite project.
In the categories box select C # and in the templates box select the Ranorex C # Test Suite item. Next specify a
name and a location for your new test suite project.
C lick the 'C reate' button and a new test suite project opens.
Within the test suite view, the template already contains a single test case which uses an empty recording. In
order to start recording simply open 'Recording1' by double-clicking the recording within the test suite view.
Page 6 of 247
Empty Recording
You can open the project folder by right-clicking the project in the 'Projects' view and choosing 'Open Folder in
Explorer' from the context menu
C lick the 'Record' button in order to start. The Recorder assists you in preparing the application under test.
Simply select 'Run an Application' and specify the directory and file name of the application under test. After
copying the KeePass application folder to your project folder, you can set the 'File Name' by choosing the file
'KeePass.exe' using the 'Browse' button.
Page 7 of 247
New Recording dialog - Ranorex automatically starts
the specified application
C lick on 'Start' in order to record the test. The KeePass application opens and the Ranorex Recorder starts
running.
C lick on the text field next to the 'Master Password' check box
Type in the default password ('rx')
KeePass application
Page 8 of 247
KeePass application with sub menu 'Edit' (Menu item
'Add Entry' is selected)
Page 9 of 247
KeePass form for choosing an icon
The dialog shows all available attributes for the given UI element to check. Just click the 'OK' button in order to
accept the preselected 'Text' attribute.
Page 10 of 247
Ranorex validate window
Finally press the save button in the toolbar and close the application by clicking the close button.
Stop the recording by pressing the 'Stop' button in the recorder tool bar.
You can read more about different action types within Ranorex Recorder in Lesson 5: Ranorex Recorder -
Additional Editing Options.
During the execution Ranorex simulates all user actions (mouse movements and keyboard events) in order to
test the application in the same way a tester would successfully do it.
Reporting
After executing the test, Ranorex Studio automatically opens the generated test report file (*.rxlog) which shows
whether the test run was successfully or not.
In order to force an error as shown in the right picture above, simply modify the expected value used in the
validation step of the recording (e.g. 'Typo3Demo' instead of 'WordPressDemo').
Now the test automation executable is also available within your project folder. To run the test suite without
starting Ranorex Studio, simply double-click the executable file.
Note: In order to run the test suite project on an external machine it is required to have the executable (*.EXE)
as well as the test suite file (*.RXTST) in the same directory at the target machine. If your Ranorex Studio
solution consists of more than one project, you need to ensure that the library (*.DLL) files are also part of the
same directory.
By default the report files are also generated within the same directory. Further information on changing the
report folder can be found in Lesson 4: Ranorex Test Suite - Test Suite Settings.
Page 12 of 247
Read more about alternative ways to run the test suite from the command line or with the standalone test suite
runner in Lesson 4: Ranorex Test Suite - Running Tests without Ranorex Studio.
Page 13 of 247
Lesson 2: Ranorex Modules - Test Actions
This lesson will show you the benefits of splitting your recordings into smaller pieces (to provide for reusability)
and how your projects can be easily assembled afterwards using drag and drop functionality in Ranorex Studio.
Identifying Modules
In your first recording you did the following from a keyword driven perspective:
In order to split recordings into smaller automation modules, select thematically related recorder items and use
the context menu item 'New Recording From Selection'. Within the underlying recording, three actions for doing
the log in should be selected and moved into a new recording named 'LogIn'. These three actions are a click on
the password field, a key sequence on the password field and finally a mouse click on the OK button.
Also select and move all items within the recording used to add a new entry named 'AddEntry.rxrec' in the same.
Repeat the previous steps to create modules for 'ValidateEntry', 'DeleteEntry', 'SaveDB' and for
'C loseApplication'.
Also rename the initial recording file (with only one recorded item left for starting the application) from
'Recording1.rxrec' to 'StartSUT.rxrec'. In the end you should have seven separated new recording modules.
After splitting the initial recording into smaller test actions, the Ranorex Module Browser also contains the new
modules. Now simply use the drag and drop feature to combine these modules within the test case.
Page 14 of 247
Use the drag and drop feature to specify your test
case within the test suite view
Separating a recording into smaller modules is the first step in building robust and reusable automation modules.
In addition replace constant values used within these modules with variables in order to enable parameterization.
Read more about how to use variables in Lesson 3: Data-Driven Testing.
Page 15 of 247
Lesson 3: Data-Driven Testing
In this lesson you see how tests can be done using internal (simple data tables) or external data sets (Excel files,
C SV files, SQL Databases) to do a data-driven automated test. You can use variables in recordings and even in
the repositories which are connected to internal or external data sources. Additionally, you will see how a select
action can be invoked for UI elements which are not visible by default in order to ensure your data-driven test
case does not fail.
When you test an application it might be necessary to run the same test with different input data. Next you'll learn
about:
Title (WordPressDemo)
Username (admin)
Password (demo123)
URL (http://bitly.com/wp_demo)
Expires (1 Year)
IconIndex (1)
All these input actions are done within the 'AddNewEntry' recording. You need to open the recording file and
identify the actions which have to be variable.
To make the input of the title variable, open the combo box as shown below and select 'As new Variable' to
create a new variable.
Page 16 of 247
Specify the variable name and the default value which is automatically set to the same value as it was recorded
initially. If you want to alter the name or the default values, simply open the variables dialog as described in
section Using Variables within the Repository.
Note: Please do not use variable names which are already in use by a recording or code module.
Repeat the previous step which makes the key sequence action used to set the value of the title field variable,
and also create the variables 'varPassword', 'varUsername' and 'varURL' for the specific actions.
To make a click action data driven - for example selecting a context menu item for expires-constants like 1 week
- you need to define a variable used for identification within a RanoreXPath expression.
Select that action item within the 'AddNewEntry' recording which simulates a click on a menu item and open the
context menu as shown below. C lick on 'Make Item Variable...' to open the RanoreXPath editor.
Typically the menu item for the 'Expires Date' in KeePass application is identified by the accessible name
attribute. Now you can define a new variable for the attribute text by clicking the button on the right.
When looking at the repository, you see that the item pointing to the menu item is now using the variable within
the path expression previously specified.
Also rename the repository item 'MenuItem1Year' to 'MI_Expires' to clarify that this repository element is not
pointing to a specific menu item anymore but instead uses a variable to choose one of the menu items in a data-
driven way.
Repeat the same procedure to add a new variable 'varIconIndex' into the repository item which is connected to
the icon list view.
The recording 'AddNewEntry' now uses six variables. Four of them are used for key sequences directly within the
recording while the others are used within the repository. To get an overview about all variables used within the
recording simply click the 'Variables' button as shown below.
Page 17 of 247
Open the recording's variable dialog
Assuming someone is still keeping his passwords in an excel-file, the following example could be helpful in more
safely managing the information.
This Excel file contains the fields Title, Username, Password, URL, Expires and IconIndex.
Page 18 of 247
Create a new Excel connector
For further information about different Ranorex data connector types hava a look at Data C onnectors.
Page 19 of 247
Open data binding dialog
Now you can connect each column specified within the data table with variables used by the test case. You can
also map multiple variables to one data column. You currently only have variables specified within the
'AddNewEntry' module.
In addition to typical test data specified within data tables as shown before, a test suite and its test cases allow
you to declare global and local parameters. These parameters can also be bound to module variables. This type
of data driven execution helps to specify such things as environment-related attributes as the following example
describes.
The test case starts with a recording module called 'StartSUT'. The recording only contains a single action item
used to start the KeePass application. Open the recording and create a new variable called 'varApplicationPath'.
The execution path of the system under test has to be declared as a global parameter on the test suite level in
order to combine it with multiple test cases of the test suite. Use the context menu within the test suite view and
open the parameters dialog as shown below.
Specify a new parameter name by clicking in the first cell of the column 'Name'. Now specify a value for the new
parameter. Just copy and paste the execution path from the default value shown within the variables dialog of the
recording 'StartSUT'. C lick 'OK' to apply the changes and to close the dialog. Read more about how to open a
recording's variable dialog in Lesson 5: Ranorex Recorder - Recorder Variables.
Now you are ready to combine the global parameter with the variable created within the recording before. Open
the test case's data binding dialog the same way you did previously for combining variables with the data table.
Before you execute the data driven test case, you have to make sure that the values specified within the Excel
file can be used correctly within the 'AddNewEntry' recording. The values for the title, username, password, URL
and expiration will not cause any problems during automation. C onsidering a more advanced situation such as
selecting an item from a list view which is not visible by default; there will be a problem because of the current
visibility state of the item. This situation will be handled in the next section.
Page 21 of 247
Button to open the Icon Picker
Icons with an index of 0 to 49 are visible without using the scroll bar so icons with indexes lower than 49 could
even be accessed easily when using a data-driven approach. In order to select an icon with a higher index (e.g.
66 for the US dollar icon) in an automated way, a simple click on an invisible item would fail. It is recommended
to add an 'Invoke Action' to select the icon regardless of the visibility of the item in the listview.
First of all an additional action should be added to the recording right before the action representing the click on
the icon.
Select one action before the clock action and click the 'Add New Action' button as shown below.
Page 22 of 247
Adding a new 'Invoke Action' to the recording
After adding the new item you need to specify for which repository element the invoke action should be used.
Simply open the 'Select Repository Item' dialog as shown below and select the 'IconItem'.
After assigning the repository item to the invoke action, the recorder presents the methods suitable for the role
list item. The role list item shows a 'Select' method which you can chose as seen in following figure.
Also delete the initially recorded mouse click action (action item \#7 shown in previous figure) because now the
recording uses the new invoke action to select the list item instead of the click action.
After executing the test suite the report file shows the results for each iteration. The summary chart counts each
iteration as a single test case run.
Page 23 of 247
C opyright © 2012 Ranorex
Page 24 of 247
Lesson 4: Ranorex Test Suite
As was already mentioned in Lesson 2: Ranorex Modules - Test Actions, it is recommended to separate a test
case into reusable and parameterizable test automation modules. Within the Ranorex test suite you can not only
easily create new test cases by combining already existing automation modules - you can also specify global
parameters and data connectors to set up data-driven test cases.
Looking on the project created during the lessons 1 through 3 you can now create a new test case based on the
existing modules. To open up the test suite, you can double-click the *.rxtst file or use the 'View Test Suite'
button shown in the toolbar panel.
Page 25 of 247
Ranorex Studio tool bar
Test cases
Recording modules
C ode modules
Module groups
Folders
Select the 'Test C ase' item to create a new test case at the current position.
Note: Within a test suite, test cases can be added to different layers. A test case can also be added as a child to
an existing test case or to a folder item.
The newly created test case will be used for validating the correctness of KeePass version number so the name of
the test case should be changed. Select and click on the test case and rename it to 'TC \_ValidateVersionNumber'.
Now you are ready to reuse two existing record modules from the Ranorex Module Browser View.
You can simply drag and drop items from the module browser into the test case or you can add new or existing
items using the context menu as shown.
Page 26 of 247
Add an existing recording module
Repeat the steps to add the record items 'LogIn' and 'C loseSUT' to the test case.
In order to validate the version number of the KeePass application, you can create a new recording module to be
used in the test case.
Use the context menu again, but this time to insert a new recording into the test case.
Page 27 of 247
Insert a new record module
Before starting the new recording, you should confirm that KeePass is running - you could start the application
manually if it is not running.
The new recording module 'ValidateVersionNumber' should cover the following steps:
Keep in mind that you need to select the 'Global Recording' option because the system under test will be started
by the reused recording module 'StartSUT'.
During the validation step, Ranorex automatically created a new repository item for the cell holding the version
number from KeePass - the text itself is used for identification of the cell (path). This situation would lead to a test
case failure if a version of KeePass was automated regardless the correctness of the version number. To avoid
this, the path to this cell should be modified to be more robust; additionally it should not use the version number
itself for identification.
Using the index for identification assures the accessibility of the cell even if a new version is released. To
complete this recording you could modify the validation action to use a new variable called
'varC urrentKeePassVersion' with a default value '2.19' instead of matching against the constant value. This
module variable could be bound to a new global variable 'GlobalC urrentKeePassVersion'.
Now the test case 'ValidateVersionNumber' is ready to be executed.
Use the context menu item 'Play Selected Test C ase' to run it and see whether it works or not.
Page 28 of 247
Play selected test case
In addition to the test suite file, the test suite project also contains a file defining the module groups existing in
the project. This module group file is generated automatically as <Project-Name>.rxtmg.
Double-clicking this file in the project view will open it in the module group editor.
Page 29 of 247
Module group editor
You can add module groups to your project in the following ways:
Press the 'New Module Group' button in the module group editor
Use the context menu in the test suite editor to add a module group to a test case
Use the context menu in the test suite editor to group selected modules into a module group
By grouping existing modules into a module group, the module group will be filled by the selected modules. When
adding a new module group, the module group is empty and can be filled with modules by using the context
menu in the module group and then adding a new or existing module.
Page 30 of 247
Adding an existing module to a module group using
the context menu
An existing module can also be added using drag and drop from the module browser or project view into the
module group in the module group editor.
To allow you a data driven approach as described in Lesson 3 - Data-Driven Testing, it is necessary to pass the
values from the data sources or parameters through the module group to the modules in the module group.
You can define data binding for modules in the module group by using the context menu item 'Data Binding...' is
shown appears by right-clicking a module group.
The data binding dialog allows you to specify which of the module variables should be changeable from outside
the module group and which of the module variables should have constant values inside the module group.
Note: The mechanism for using constant values within module groups allows hiding module variables. This can
reduce the complexity and increases the clarity of module groups because it is not always necessary to set each
module variable individually.
Page 31 of 247
Define which module variables should get their
values passed from outside the module group and
which module variables should have constant value
After defining a module group and its data binding, it can be added to a test case the same way a module is
added.
The data binding for module groups works exactly the same way as it works for modules.
Further details about working with modules and data binding can be found in Lesson 2: Ranorex Modules - Test
Actions and Lesson 3: Data-Driven Testing.
This sample includes different types of elements which can be used within a test suite and covers all possible
Page 32 of 247
combinations.
#6 Recording module
Automation module generated by recording
The setup region will be executed before any other module held by the test case and should hold any modules
needed to bring the system under test in exactly the state your test can start from. A typical application of this
section is to start the application under test and log in with a user.
The teardown region will be executed when the execution of the test case has been finished, which means after
all modules have been executed, or an error has aborted the test case. The teardown region should hold any
modules needed to clean up the system under test and bring it to the original state. A typical application of this
section is to delete all added data and close the application under test.
The setup region will automatically be placed at the beginning and the teardown region will automatically be
placed at the end of a test case.
Use the context menu to specify which modules or module groups from a test case should be part of the setup or
teardown process.
Page 33 of 247
Add module to a setup region
Note: If you want to define one setup and one teardown region for a set of test cases, simply nest your test
cases as shown in the following pictur
In order to quickly deactivate a certain module, instead of deleting it from the test case, use the context menu
item 'Disable'.
These test suite run configurations define if a specific test case will be executed or not.
For example one test suite run configuration can be defined where the data driven tests stored in your test suite
Page 34 of 247
will be executed and one test suite run configuration can be defined where they won’t.
Activate different test suite run configurations Add or remove test suite
run configurations
You can use the Ranorex Test Suite Runner to run the test suite, execute certain test cases or just play a specific
automation module.
Additionally one can create new run configurations the same way as is done within a Ranorex Studio Project.
<GeneratedTestSuite>.exe /<argument>
Allowed arguments:
help|?
Prints this help text.
listconfigparams|lcp
Lists all settable configuration parameters and their values.
zipreport|zr
C ompresses the report (including associated files) to a single archive (".rxzlog" extension).
Debug=10
Info=20
Warn=30
Error=40
Success=110
Failure=120
listglobalparams|lp
Lists all global parameters and their values.
the rxtst file with the same name as the <TestSuiteExe> is used
or the first rxtst file in the same folder as <TestSuiteExe>.
runconfig|rc:<configuration name>
Runs the test cases of the specified configuration defined by the rxtst file. C onfigurations can be edited using
Ranorex Studio or TestSuiteRunner. By default, the currently selected run config is used.
runlabel|rul:<custom value>
Sets a custom runlabel for the test run.
Note: C ompressed report files (*.rxzlog) can be extracted by right-clicking them in explorer and choosing
'Extract' from context menu as well as report files (*.rxlog) can be compressed by right-clicking them in explorer
and choosing 'C ompress' from context menu.
Page 36 of 247
General settings of a test suite Global parameters table
Name Specifies the name of the test suite (same as shown within the test suite editor)
Description of the test suite (same as shown within the description column of the test
Description
suite editor)
Show Progress Dialog Specifies whether a progress dialog should be shown during test suite execution or
not
Report Level Specifies the level of report shown with the report file
Report File Directory Specifies the directory for the generated report files
Specifies the filename generated by the report; move the mouse over the
Reporting Filename
'Description' label to see the variable values
Specifies a customized style sheet file used instead of the Ranorex style sheet to
C ustom XSL Filename
present the reports
Auto Save Interval
Specifies how often the report file is saved during an execution
Global Parameters
Globally specified parameters can be accessed and used by every test case within the test suite. The
KeePassTestSuite example project uses a global parameter to specify the directory path for the application under
test. You can easily connect global parameters with variables as shown in the test case 'TC _AddEntry'. In addition
you can use the global parameter to transfer values or states between test cases.
Set to 'C ontinue with iteration' if the case should not break in case of an error caused by
Error a particular data set
Behavior
Set to 'C ontinue with sibling' if the case should not break and continue with the next test
case
Set to 'Stop' in order to break the test suite run in case of an error
Page 37 of 247
Test case properties dialog
Use the context menu to change the report level or the error behavior for multiple test cases.
Page 38 of 247
Lesson 5: Ranorex Recorder
The Ranorex Recorder is used to record and replay the user's keyboard and mouse actions during a manually
executed test of the user interface. In addition the Recorder can validate current states, properties like 'Text' or
'Visibility' and compare images of UI elements. The Recorder is a capture replay editor which is available both as
stand-alone tool and as an integrated editor within Ranorex Studio.
Within Ranorex Studio you can add a new recording in different ways.
Use the project view to add a new recording by clicking the 'Add Recording Module' button on the toolbar.
Alternatively you can also add a recording directly to a test case within the test suite editor.
Page 40 of 247
Before Starting to Record
Regardless whether you use Ranorex Recorder within Ranorex Studio or as a stand-alone tool, both the Recorder
and also the system under test have to be prepared.
Prepare to Record
Before you start recording, you need to ensure that your system under test is ready to start with the manual test
execution. In addition, consider the following points in order to avoid too much effort in cleaning up the recording
and the repository afterwards.
Do not run multiple instances of your application under test if that is not part of the test case itself
By default, mouse movements are not recorded; for this reason please also perform mouse clicks in
situations such as navigating through menus (or use Recorder Hotkeys to record mouse movements)
Think about which steps should be part of the final test
Try to keep recordings small in order to make them modular
Settings for current recording file Default values used for every recording
Current Recording
This tab primarily contains configuration parameters for code generation specific to the current recording. All
settings on this tab page are stored within each recording.
Recording namespace:
Is used to specify whether recorded delays between actions should be part of the generated code.
Page 41 of 247
This setting is used to turn the generation of reports during replay on and off.
Activate this setting to turn on a default logging message for each action item.
Recorder Defaults
Under this tab you can specify global default values for every newly created recording. The settings are divided
into three sections:
Recording
If checked, relative coordinates within a recognized element are recorded. Otherwise, actions will always be
invoked on the 'center' of the recognized elements.
Specifies whether a screenshot of the current action should be made during the recording.
Use this setting to specify the maximum time for a key sequence during recording. If a key sequence exceeds
the time set, it is split into several key sequences.
Specifies the time in milliseconds used to move the mouse to the UI object related to the action.
Specifies the overall time in milliseconds used for a manually created mouse action. The value set for this setting
is only taken into account for manually created actions or when the time of an action cannot be determined
during recording.
Specifies the default overall time in milliseconds used for a manually keyboard action. The value set for this
setting is only taken into account for manual created actions or when the time of an action cannot be determined
during recording.
Code Generation
Recording namespace:
This setting is used to turn the generation of reports during replay on or off.
Activate this setting to turn on a default logging message for each action item.
Page 42 of 247
During Recording
C lick the 'Record' button to trigger a new recording.
After clicking the record button you're assisted in running an application or opening a browser to navigate to a
particular URL before recording any user performed actions. Therefore it’s not necessary to record actions like
double clicking a shortcut on the system’s desktop.
Note: If you select 'Run Application', 'Open a Browser' or 'Mobile Recording' the recording is not limited to the
application, browser or mobile device.
After clicking the 'Start' button, the Recorder or Ranorex Studio will be minimized. A running recording session is
indicated in the Ranorex Recorder tool bar.
Now perform all the actions you want to be part of the automated test. You can also pause the recording session
at any time by clicking the ‘Pause’ button.
Validation
The Ranorex Recorder provides two different types of validation during a running recording session:
Page 43 of 247
Validating States or Properties
The Ranorex Recorder tool bar can be used to validate states or properties of GUI elements during a running
recording session. C lick the 'Validate' button to pause the recording in order to start the validation.
Recording is now paused. Move your mouse pointer over a specific UI element. Wait a moment to ensure that the
highlight frame is surrounding the intended UI element indicating that it is ready to be validated. C lick on the
element to open the validation dialog.
The highlight frame specifies the element to The dialog shows the available
validate attributes for validation in a list of
checkboxes
To validate UI elements of pop-up windows like menus, use the shortcut key 'V' to turn on validation mode
without clicking the 'Validate' button. Read more about how to enable hot keys in the section Recorder Hotkeys
later on in this lesson.
Validating Images
In addition to validating attribute values of a UI element, it is also possible to validate images or screen regions
of an application. Simply switch to validation mode as described above and select a UI element. To validate the
element's image, open the 'Image' tab in the validation dialog.
Page 44 of 247
Validate whether a specific Listitem contains a
specified image or not
Recorder Hotkeys
Ranorex Recorder provides useful hot keys for triggering special features like validation or the recording of
simple mouse movements. When you start a new recording session, the hot key functionality is turned off. To
activate the Recorder's hot keys simply click on the 'Enable Hotkeys' checkbox or press the master hot key
'<SC ROLL>'.
The recorder's toolbar will then shows what type of shortcuts are available.
'V':
Press the hot key 'V' to turn on validation mode - especially useful for validating elements of a pop-up window
like menu items and drop-down lists.
'M':
Use the hot key 'M' to record simple mouse movements. Simply move the mouse pointer to a certain position and
press the hot key to record the mouse movement in relation to the underlying UI element.
'T':
It's easy to validate the content of a tooltip by pressing the hot key 'T' after the tooltip box appears. Ranorex
Recorder automatically captures a mouse move action in realtion to the underlying item and validates the current
content of the tooltip.
'I'
The hot key 'I' is used to turn on/off image-based recording - used for pop-up windows, menu items or drop-
down lists.
Page 45 of 247
'Roll Mouse Wheel'
Roll the mouse wheel during validation mode to change the level of UI element selection.
Page 46 of 247
After Recording
After pressing the ‘Stop’ button of the Recorder’s toolbar, the recorder represents all low level actions like clicking
on a button or typing text within the action’s table.
By default each recorded action has an additional screenshot shown on the right. Depending on the type of
action, each row shows additional action-related information. Whereas a mouse related action provides more
information about the type of mouse action (C lick, Double-C lick, Move, etc.) or which button was used (Left,
Right, etc.) a key sequence action only stores the keystrokes made during a recording.
Additionally each action can be connected to a UI element represented by the repository view below. For each UI
element used during a recording session the recorder generates an item in the given repository.
Note: In case an item already exists in the repository or if the UI element is used twice during a recording
session the recorder reuses this element.
By default the repository is not part of the recording file and only refers to the main repository used within a
project. In comparison to the integrated Recorder, the standalone Recorder tool embeds the repository by
default. You can also unlink and refer to another file or embed the repository into the recording file. Read more
about how to do that in Lesson 6: UI Mapping with Ranorex Repository - Repository Separation.
By default the recorder records the mouse click location performed by the user relative to a button or a text field.
It’s possible to turn that off in advance within the Recorder’s settings dialog. Alternatively, you can also change
the click location afterwards within the properties dialog.
Repository Cleanup
Each item within the repository refers to one RanoreXPath expression necessary to identify the object. The
names used for the items and folders of the repository are generated automatically. It is recommended to
rename them if it's helpful. Additionally the structure of the repository is generated automatically and depends on
the internal UI hierarchy given by the application under test. To rename items of the repository simply click in the
cell or press <F2> at the selected item.
Use logical folders to create additional structure, for example to group input fields, buttons or a log on form with
user name and password text boxes. Also, already existing rooted folders can be used for grouping as well. Learn
more about how to work with Ranorex repositories in Lesson 6: UI Mapping with Ranorex Repository.
Page 48 of 247
Replay and Debug Actions
The playback speed of each recording can be defined individually. Use the speed factor text box to increase
replay speed by a factor value.
In order to replay all actions as fast as possible, activate 'Turbo Mode' by clicking the button on the tool bar. By
activating 'Turbo Mode', the value for speed factor is ignored. Use the repeat count text box to specify the
number of iterations.
Simply click the 'Play' button in the recording to replay all actions.
During the execution, the progress box shown at the right lower corner gives information about the current
automation state. Press the 'Pause' key to stop replaying.
If the option 'Generate replay reports' is set to true, a report is shown after the replay has finished. By default
each action item logs one message to the report.
Within Ranorex Studio the report is shown as a new file view whereas the standalone Recorder opens the report
viewer to show the result. Learn more about how to use Ranorex reporting in Lesson 8: Reporting. As shown in
the picture above, each log entry allows one to quickly jump to the source action item. This is helpful in quickly
debugging single actions in case of an error. Within the Recorder's actions table, you can then fix an error
causing step and quickly re-run single or selected steps using the context menu.
Page 49 of 247
Play a selected item
Page 50 of 247
Recorder Variables
As described in Lesson 3: Data-Driven Testing a recording can have variables instead of static string values
generated during the recording session. In particular key sequence actions used to type in such things as log in
data into a form are commonly used action items which have to be data driven in many cases. At any position
within the actions table where you can change or set values in a cell, it is possible to have variables instead.
The variables shown in the table above are in green. All variables used within the recording can be connected to
a Ranorex data connector or to simple parameters provided by the the entire test suite or a single test case.
Creating Variables
There are different ways to create new variables for a recording. During Lesson 3: Data-Driven Testing you
learned how to create variables directly within the actions table.
Create a new variable for a key sequence action Create a new variable
Not only key sequences can use a variable. To make a click action data driven - for example selecting an icon for
password entry - you need to define a repository variable used for identification within a RanoreXPath
expression. Select the context menu item 'Make Item Variable...' to create a new repository variable in order to
have a data driven mouse click action.
Make new variable to be used within the path of the repository item
Page 51 of 247
Create a new variable for selecting the menu item
Another option is to open the variables dialog where you can add new or change existing variables already used
by the recording. Moreover, you can see which variables are 'In use', 'Not in use' or 'In use from Repository'.
Use the toolbar to add, remove or copy a variable from the repository. C hange the name of the variable and set
a default value by clicking in the cells of the table. Press the 'C opy Variable from Repository' button in the tool
bar to make variables defined in the given repository available for the recording. Read more about variables
specified in repositories in Lesson 3: Data-Driven Testing - Using Variables within the Repository.
Page 52 of 247
User Code Actions
A user code action is used in situations where standard out-of-the-box features provided by the recorder are not
enough. Here are some examples in which a user code action could be a great convenience.
User-specific Validation
Accessing test case related data and parameters
Extended reporting
Looking at a recording file in the project's view you will see that each recording has two code items.
Note: User code actions are not available within the standalone Recorder.
Within Ranorex Studio, each recording manages two types of source code files:
Every time you change and save a recording, the main code file 'AddVip.cs' is newly generated. Any change of
code should always be made within the recording's UserC ode.cs file.
Page 53 of 247
Convert an existing action item to a code action
After the creation of a new user code action within the actions table, a new method is added to the partial class of
the recording. If you're converting an existing action item, the code generated for the main recording file is
transferred to the new user code method.
C#
view plain c opy to c lipboard print 5
namespace MyFirstTestProject
{
public partial class AddNewEntry
{
/// <summary>
/// This method gets called right after the recording has been started.
/// It can be used to execute recording specific initialization code.
/// </summary>
private void Init()
{
// Your recording specific initialization code goes here.
}
public void ClickOnPasswordField()
{
Report.Log
(ReportLevel.Info, "Mouse", "Mouse Left Click item 'FormAdd_Entry.TabPageList.InputFields.TextPassword' a
repo.FormAdd_Entry.TabPageList.InputFields.TextPassword.Click("175;9");
}
} 6
3 4
VB.NET
view plain c opy to c lipboard print 5
Namespace MyFirstTestProject
Public Partial Class AddNewEntry
''' <summary>
Page 54 of 247
''' This method gets called right after the recording has been started.
''' It can be used to execute recording specific initialization code.
''' </summary>
Private Sub Init()
' Your recording specific initialization code goes here.
End Sub
Public Sub ClickOnPasswordField()
Report.Log
(ReportLevel.Info, "Mouse", "Mouse Left Click item 'FormAdd_Entry.TabPageList.InputFields.TextPassword' a
repo.FormAdd_Entry.TabPageList.InputFields.TextPassword.Click("175;9")
End Sub
End Class 6
3 4
To use parameters for a new user code action, simply click the cell next to the method's cell and type in a value
to be used as a parameter (e.g. 'WordPressDemo').
Of course you are also able to use more than one parameter for each action. If there are no more columns
available (maximum of three in the GUI), you can use the browse button to access the Ranorex Argument Editor.
To enhance flexibility, you can use variables instead of hardcoded values. This can be done in the normal way.
You'll find an overview of existing parameters in the Ranorex Argument Editor. Here you can also name existing
parameters and add additional parameters.
C#
view plain c opy to c lipboard print
public void AddEntryWithParams
(string aTitle, string aUsername, string aPassword, string aURL)
{
MyFirstTestProjectRepository MyRepo = MyFirstTestProjectRepository.Instance;
// Set text fields
MyRepo.AddEntry.TabSheetAddEntry.Title.TextValue = aTitle;
MyRepo.AddEntry.TabSheetAddEntry.UserName.TextValue = aUsername;
MyRepo.AddEntry.TabSheetAddEntry.Password.TextValue = aPassword;
MyRepo.AddEntry.TabSheetAddEntry.Repeat.TextValue = aPassword;
MyRepo.AddEntry.TabSheetAddEntry.URL.TextValue = aURL;
}
VB.NET
view plain c opy to c lipboard print
Public Sub AddEntryWithParams
(aTitle As String, aUsername As String, aPassword As String, aURL As String)
MyFirstTestProjectRepository MyRepo = MyFirstTestProjectRepository.Instance
' Set text fields
MyRepo.AddEntry.TabSheetAddEntry.Title.TextValue = aTitle
MyRepo.AddEntry.TabSheetAddEntry.UserName.TextValue = aUsername
MyRepo.AddEntry.TabSheetAddEntry.Password.TextValue = aPassword
MyRepo.AddEntry.TabSheetAddEntry.Repeat.TextValue = aPassword
MyRepo.AddEntry.TabSheetAddEntry.URL.TextValue = aURL
End Sub
Additionally to creating method calls in Ranorex Recorder you are able to define your methods in code and just
select the intended method in the Recorder Table. Here you are also able to choose overridden methods.
Conditions in Code
Another reason for writing user code is to read text values from UI elements like text boxes and to reuse them
for conditional automation steps.
Page 56 of 247
Note: Only create small and easy to maintain user code actions for a recording. If an implemented method is to
also be available for other test cases, create a code module (see Lesson7: C ode Modules) instead.
Within the 'DeleteEntry' recording that was created in Lesson 3: Data-Driven Testing, there are three simple
actions in deleting the selected entry (selecting the item, opening the context menu and choosing the context
menu item). As you can see it is meaningful to only delete a entry if it is selected. Therefore a condition in code
could be useful.
As a first step, open the 'DeleteEntry' recording and select the last two items as only they should be executed if
the entry is selected. C lick on the 'Merge Items to User C ode Item' menu item in the context menu.
After doing this, these two actions are merged into one user code action. Give this method a meaningful name
(e.g. 'DeleteItemIfFocused'). Switch into the code view by clicking on the context menu item 'View User C ode'.
Now change the converted code so it is only executed if the cell is focused on.
C#
view plain c opy to c lipboard print 5
public void DeleteItemIfFocused()
{
if (repo.MainForm.Entry.HasFocus) {
Report.Log
(ReportLevel.Info, "Mouse", "Mouse Right Click item 'MainForm.Entry' at 127;10.", repo.MainForm.EntryInfo
repo.MainForm.Entry.Click(System.Windows.Forms.MouseButtons.Right, "127;10");
Report.Log
(ReportLevel.Info, "Mouse", "Mouse Left Click item 'KeePass.DeleteEntry' at 168;14.", repo.KeePass.Delete
repo.KeePass.DeleteEntry.Click("168;14");
}
6
3 4
VB.NET
view plain c opy to c lipboard print 5
Public Sub DeleteItemIfFocused()
If repo.MainForm.Entry.HasFocus Then
Report.Log
(ReportLevel.Info, "Mouse", "Mouse Right Click item 'MainForm.Entry' at 127;10.", repo.MainForm.EntryInfo
repo.MainForm.Entry.Click(System.Windows.Forms.MouseButtons.Right, "127;10")
Report.Log
(ReportLevel.Info, "Mouse", "Mouse Left Click item 'KeePass.DeleteEntry' at 168;14.", repo.KeePass.Delete
repo.KeePass.DeleteEntry.Click("168;14")
End If
6
3 4
Adding New Actions
Recorder Variables
Splitting Recordings
By selecting one of the items a new action is added after the current selection within the actions table.
Depending on the type of action item, you may be able to configure each action individually. Before doing that, you should first assign a repository item to this
action - this might affect the available options for the specified action. You should click the small button framed in red in the graphic above and chose the
Repository item related to the newly created action. The items listed within the 'Select Repository Item' dialog are the same as within the recording's repository.
You can use the 'Search' text box to filter the elements. You can read more about how to use repository search and how to add new UI elements in Lesson 6: UI
Mapping with Ranorex Repository - Searching for Elements. C onfirm your selection by clicking OK.
Page 59 of 247
Select a repository item to be used by the action
Alternatively it is possible to assign the repository item to the action by dragging and dropping a repository item directly onto the newly created action in the
column 'Repository Item'.
To modify the newly created action, use the drop down menus available within the cell, for example you can change the action from 'C lick' to 'Move'.
You are asked to specify the type of action after dropping the element into the actions table. For more information about the available actions, see below.
Page 60 of 247
Mouse Adds a new mouse action item at the current position
Touch Event Adds a new touch event action item at the current position
Key Shortcut
Adds a new key shortcut action item (e.g. {F1}, {ENTER})
Key Sequence Adds a new key sequence action item (e.g. "Hello")
Invoke Action Adds a new invoke action item (e.g. call method 'Select' for a UI element of type list item)
Get Value Adds a new get value action item (e.g. get 'Text' for a UI element of type button)
Set Value Adds a new set value action to set an attribute value (e.g. 'Text' for a UI element of type text)
Run Application Runs an application at the given directory and file path
C lose Application C loses an application or web site containing the given repository item
Wait For Not Exists Waits for the disappearance of the given repository item
Note: This action can be used for any type of UI element
Separator Inserts a separation line on the currently selected position in the actions table
User C ode Adds a new user code action item which is used, for example to implement a user specific validation in code
Note: Keep in mind that most types of action can handle module variables.
Note: Next to the parameters as described in the next paragraphs there might be additional options for each action which can be accessed in the properties pane.
You can open this pane by clicking the context menu item 'Properties' on any action item.
Mouse
This mouse action can be used for 'Up', 'Down', 'C lick', 'Double-C lick' and 'Move'-actions. This action is typically used for button clicks so a repository item
assignment is required.
Mousewheel
This mousewheel action can be specified as 'Vertical' or 'Horizontal' direction. You are also able to specify a wheel-delta, which is 120 by default.
Touch Event
This touch event can be used different kinds of touch events on mobile devices. For more information please have a look at Android Testing - Record your Android
Test.
Key Shortcut
This action can be used for executing key shortcut actions. Aside from the shortcut itself, it is possible to specify the key codes 'Press', 'Up' and 'Down'. For this
action, a repository item assignment is needed.
Key Sequence
This action makes it possible to execute or to simulate a key sequence on a specified repository item. This action is typically recorded in a form filling scenario (e.g.
username field in login process). For this action a repository item assignment is required.
Validation
The validation action is typically used for validating states, text or images of specific repository items. Every validation action leads to a specific entry in the report
file and, depending on the type of validation and the validated element, there may be different validation results (success, failure). After assigning a repository
item, you are able to choose one of the following validation-types:
Exists: The validation checks for the existence of the repository item and expects an existing item.
Example: A user can validate whether a button exists with a resulting success if the button actually exists.
NotExists:The validation checks for the existence of the repository item and expects the item not to exist.
Example: A user can validate whether an error dialog does not exist with a resulting success if the dialog does not exist.
AttributeEqual: This validation checks whether an attribute (column 'Match Name') is equal to a specific value (column 'Match Value'). The matching attributes
depend on the assigned repository item and therefore an assignment of a repository item is assumed. For example a Winforms button may be validated on the
'Text', on the 'Valid' state, on the 'Pressed' state and also on 'AccessibleName', 'AccessibleValue' etc.. The matching value can either be a constant, a self-defined
value or a module variable.
Example: A user can validate whether a button has the text 'OK' with a success result if the button text is 'OK'.
AttributeRegEx: This validation is for matching a 'match value' (self-defined match value or the content of a module variable) against a specific attribute (column
'Match Name') using a regular expression. Because the attribute itself (column 'Match Value') depends on the assigned repository item, assignment of a repository
item is recommended prior to choosing a match value. If you plan to use a variable within this type of validation, you can easily implement your regular expression
in the value of that variable.
Page 61 of 247
Example: One can validate whether the title of the KeePass application ends with the text 'KeePass Password Safe' and could therefore use the 'Match Name'
containing the regular expression '.KeePass Password Safe'. The validation would lead to success if the attribute (column 'Match Name') has any character (this is
defined as a . in the regular expression) followed by the constant 'KeePass Password Safe'. For more information about Regular Expressions see RanoreXPath -
RanoreXPath with Regular Expressions.
AttributeContains: This validation checks whether a specific attribute (column 'Match Name') of a specific repository item contains a 'match value'. The match
value can either be a user-defined constant value or it can also be the content of a module variable. As above this validation assumes the assignment of a
repository item.
Example: A user can validate whether the title of the KeePass application contains the constant value 'kdbx', which is the file extension of the database used by
KeePass. The match name would thus be set to 'Title' and the match value would be set to 'kdbx'. As a result the validation would succeed if the title actually
contains the constant 'kdbx'.
AttributeNotContains: This validation can be thought of as the opposite of 'AttributeC ontains'. It checks whether an attribute (column 'Match Value') does not
contain a 'match value'.
Example: One can validate whether the content of a specific cell (URL) in KeePass does not contain the constant value 'http://'. 'Match Name' would therefore be set
to 'Text' and 'Match Value' would be set to 'http://'. This validation would lead to a positive result if the URL does not contain the constant value 'http://'.
ContainsImage: This validation checks whether the assigned repository item contains a specified screenshot. This screenshot can be easily created within the 'Edit
Image Validation' which can be accessed via a button in the 'Screenshot' column. For more information about image-based validation please have a look at the
section entitled Image-Based Automation later in this chapter.
Example: It's possible to validate whether the user-defined list of icons (for a KeePass entry) contains a specific icon. This could be done using image-based
validation. The repository item would therefore hold the list of icons and the screenshot would be a picture of the specified icon. The validation would lead to a
result if the list contains the specified icon.
CompareImage: This validation checks whether a specified repository item is equal to a specific screenshot. This screenshot can be easily created within the 'Edit
Image Validation' which can be accessed via a button in the 'Screenshot' column. For more information about image-based validation please see Image-Based
Automation later in this chapter.
Example: One can validate whether the toolbar of the KeePass application contains the intended icons and so can compare the repository item with a screenshot of
the toolbar in initial state. This validation would lead to success if the toolbar looks exactly the same as the screenshot.
Invoke Action
This action can be used for invoking actions on the specified repository item. For example a Winforms button provides functionality for 'Ensuring Visibility',
'Focusing' and 'Pressing'. More important, this action can be used to easily select items in lists and drop-downs. No mouse movement and click is simulated but
nevertheless the item itself is selected. This is a more powerful and smarter action than simulating the selection via mouse actions. Invoking a select action on a
specific item also works if the item itself is not visible by default because there are too many elements in the list and there would therefore be a need to work with
a scroll bar.
User-defined actions: In addition to providing actions delivered by default, you can also make use of user-defined (see Invoking User-Defined Actions).
Get Value
As the action name indicates, this method can be used for getting values from repository items. Depending on the assigned repository item, the available attributes
can be different. The value obtained can be assigned to a module variable. Depending on the available adapters for the assigned repository item, the attributes are
divided into several sections.
User-defined methods and attributes: In addition, it is also possible to call user-defined methods defined in your system under test. As is described in the next
section (see Invoking-User Defined Actions), a simple application could have a public function that returns a string value holding the text of a protected text field. If
the application is running during the creation of the GetValue-Action, there is a submenu for 'Dynamic' methods. Public attributes can also be accessed and
returned through the 'Dynamic' submenu.
Note: To get access to the dynamic methods and attributes, the repository item has to be available. This can be verified by highlighting the specific element by
right clicking the element in repository and choosing 'Highlight Element' from the context menu.
Reuse values from the GUI in other modules: Using a Get Value action allows one to store an attribute value of a UI element to a module variable. Doing so
makes the value available within one module.
To make the value stored in the module variable available in other modules, it's necessary to bind the variable to a parameter it can also be bound to other
variables in other modules.
Page 62 of 247
Two variable are bound to one parameter for
accessing a variable value from one module to
another
Set Value
As the action name indicates, this method can be used for setting the values of repository items. Depending on the assigned repository item, the available
attributes might be different. Depending on the available adapters for the assigned repository item, the attributes can be divided into several sections as seen
below.
User-defined attributes: In addition, it is also possible to set user-defined attributes. If the application is running during the creation of the Set Value action then
there is a submenu for 'Dynamic' methods holding dynamic attributes.
Note: To get access to the dynamic methods and attributes, the repository item has to be available. This can be verified by highlighting the specific element by
right clicking the element in repository and choosing 'Highlight Element' from the context menu.
Open Browser
This action can be used for opening a browser. For preperation you are able to use the parameter 'URL' for directly opening a website. The parameter browser can
be used for choosing a browser (e.g. 'IE', 'C hrome', 'Safari' or 'Firefox').
Note: You can use a 'module variable' inside the column 'Browser' which can be used for cross-browser testing. For an extensive description including an example
see C ross-Browser Test Automation with Ranorex.
Additionally there is a parameter 'Maximized'. When this parameter is set to 'false', the URL is opened in the default browser window size which can nevertheless be
in maximized state. With the maximized-parameter set to true, the browser will be opened in maximized window state.
Run Application
This action can be used to run an application which filename can be specified in the column 'File Name'. You can also pass some arguments (column 'Arguments')
and define, whether the application should be started in maximized window state (column 'Maximized', see explanation for open browser action to find out more
about this parameter).
Close Application
This action can be used for closing applications and web sites. If the 'C lose Method' is set to 'C loseWindow', the application is attempted to be closed. If the
parameter 'Grace Period' is set to a value greater than 0 ms, the process will be killed after the 'Grace Period' if the closing of the application failed. If 'C lose
Method' is set to 'KillProcess' the application's process is killed immediately and the grace period has no influence.
Report
The Report action is typically used for providing information related to the test report.
After assigning a repository item, you are able to choose one of the following action types:
Log: This action adds a line of text holding a given value to the test report.
Example: One could report the current value of a variable or UI element.
Screenshot: This action adds a screenshot of a specific repository item and some user-defined text to the test report.
Example: One could report a screenshot to make the report file clarify the current state of the system under test in the report file.
Snapshot: This action adds a snapshot file of a specific repository item and some user-defined text to the test report. The snapshot file can be opened directly
from the report file.
Example: One could report a snapshot file of the application under test if an automation problem occurs in order to analyze this automation problem.
In addition to the specification of the action type you are also able to deliver a 'Message' and to specify a 'Report Level'. For more information about the 'Report
Level' see Lesson 8: Reporting.
Separator
A separator can be used to visually separate recordings into smaller sections to get a clearer view of thematically related actions. You can specify a 'Header Text'
to name or describe the following group of actions.
Delay
A delay action can be used to pause test automation execution for a specific time (column 'Duration').
User Code
User code actions can be used to access some small units of code directly within the recorder. User code actions are described extensively in User C ode Actions.
C#
view plain c opy to c lipboard print
public void MyInvokedAction(string MyMessage)
{
edProtectedText.Text = MyMessage;
}
private void btSetValue_Click(object sender, EventArgs e)
{
edProtectedText.Text = "This text was set from GUI";
}
The protected text can only be set by clicking the button. The application then sets the text field to a constant value.
Ranorex provides the functionality for accessing methods that are classified as public directly within the actions table. The public method 'MyInvokedAction' can
easily be called including a user-defined parameter. When adding the new action it is recommended to keep the application ('InvokeExample') open because
accessible functionality is determined dynamically.
Page 64 of 247
Submenus for available invoke actions
You can also access an attribute editor from a browse button in the last argument column to get an overview of available parameters.
After invoking this method, the text field is set to a text that is delivered as a parameter in Ranorex.
Disabled action in gray font color - Continue-On-Fail action using italic font style
Note: In case of an error the particular action logs a warning to the report.
Splitting of Recordings
The more recorded actions you have after finishing a new recording, the less clear each single action becomes. As was already mentioned in Lesson 2: Ranorex
Modules - Test Actions, identifying reusable steps within a newly created recording is recommended. Use the context menu item 'Move to New Recording Module' to
create a new recording module.
Use the test suite editor as described in Lesson 2 and Lesson 4 to combine multiple recording modules into one test case.
Page 65 of 247
Change Repository of Recording Module
By default each newly created recording refers to the main repository file. To create a new repository or to refer to another repository simply open the drop-down
menu from the repositories toolbar as shown below.
Select 'Open From Disk' if you want to open and refer to a repository which is currently not part of your Ranorex Studio projects. If you want to use a repository
exclusively for a single recording, simply embed it into the recording file. In this case all the repository items are saved to the recording file. C reating a new
repository for your recording automatically adds a new repository file to the current project.
Page 66 of 247
Image-Based Automation
In some situations, required information for automation is not available as text but only as a graphic. Therefore
Ranorex provides image-based automation to bypass the lack of availability
Sometimes you need to automate a click action based on image information. For this reason, Ranorex Recorder
provides an optional way to capture image related mouse actions. To activate image-based recording, simply
check the 'Image based' checkbox in the Recorder's toolbar during a recording session.
Now move the mouse pointer over a certain GUI element. Ranorex highlights the last accessible UI element and
also highlights a recognized image within the GUI element. To turn off image-based recording, uncheck the
checkbox or press the shortcut key 'I'.
Note: Hot key functionality has to be activated by first using the master hot key 'SC ROLL'. Read more about hot
key useage in the current lesson in the section entitled Recorder Hotkeys.
Introductive Example
Within KeePass application, there is a way to include some user specific icons for password entries (e.g. someone
could use the WordPress logo for his WordPress password entry). For automation of a click on a custom icon, it
might be necessary to use image-based automation because the order and in addition the index of the icon can
change because icons with a lesser index can be deleted.
To prepare image-based automation for a click on a custom icon, activate image-based recording. Move the
mouse pointer to the listview for custom icons in KeePass and wait until the whole listview frame is highlighted.
Execute a mouse click on the listview (take care to not click on a custom icon). The click has to be made on the
whole list in contrast to a click on an (icon) element because this click defines on which element the prospective
image has to searched.
After stopping the recording session, the actions table contains an image-based validation action which is
indicated by the 'Image' keyword or the 'Screenshot' keyword if the cell is focused on. In addition, the related
repository item stores a snapshot at the time of recording. Generally, the repository item saves an image to
specify where to search for the image region which is specified by the image-based mouse action in the
Page 67 of 247
recorder's actions table.
In order to automate the image-based click on the custom icon, you have to tell Ranorex which image (or part of
the image in this case) you want to find and click within the graphic of the listview. Open the image editor by
clicking on the button in the location cell (see graphic above). In this dialog use the 'Select image find region'
method to define the user-defined icon which should be clicked. Additionally use the 'Select click location'
functionality to tell Ranorex at which position the mouse click should be executed. This features will be described
in more detail later on in section entitled Image Editor.
In this example, Ranorex has been automated to search for the custom WordPress logo within the entire listview
of all available custom icons. If found, this icon is clicked regardless of the position of the icon. Again, Ranorex is
not searching for any index or any list item at a specific position but for a specific graphic within a region (which
is a screenshot of the listview in this case). To check it, delete the KeePass icon with the index 0 and execute the
recording again. The WordPress icon will be found and will be clicked although the position and the index changed
in comparison to the time of recording.
To alter the settings of an image-based automation action, open the property group 'Image-Based Location'
within property grid.
Selection
Defines the image selection region and what to search for.
Rectangle
Specifies the minimum similarity that the image region to search for needs to have in
Similarity
common with the image in order to be considered a match.
To set up the default values for image-based recording, open the 'Settings' dialog and the 'Imaging' tab.
Page 68 of 247
Settings dialog for image-based recording
Image Editor
Use the context menu item 'Edit Location...' to open the image editor and to change the click location options.
The editor provides a more detailed view of the captured image information. In addition, it offers some useful
features for changing the image rectangle to be searched for.
Select Image Find Region Specifies the region to search within the image
Select C lick Location Defines the click position in relation to the searched region
Autoselect Image Find Region Helps to specify the search region within the image
Zoom Out
Zooms out
Zoom In Zooms in
C apture New Screenshot C aptures a new screenshot from the related repository item
Use the drop-down combo boxes to specify whether a mouse action should be performed relative to the image
region found or not.
Page 69 of 247
Set relative or absolute mouse action location
If the captured screenshot has to be updated, click the 'C apture New Screenshot' toolbar button. Every newly
created screenshot is also automatically added to the image list of the related repository item so it's available for
other image-based validation or automation actions.
Page 70 of 247
Lesson 6: UI Mapping with Ranorex Repository
The Ranorex Element Repository is used to separate identification information (RanoreXPath) from Ranorex test
automation modules. For test maintenance, it is recommended that you also use Ranorex repositories within code
modules to reduce the effort in adaptation necessary when the UI under test changes. In the following lesson
you'll learn about:
Page 71 of 247
Adapting an Existing Repository
During lessons one through three you created a repository by recording a manual test scenario. For each UI
element used during the recording, a new item was created within the repository. By default a new Ranorex
Studio project contains one repository file (*.rxrep) which can be used by multiple recording or code modules.
You can access and edit the repository within a recording or by double clicking the file
('MyFirstTestProjectRepository.rxrep') in the projects view as shown in the figures above.
Repository using two logical folders to group input fields and buttons
Rooted Folder #2 C ontains GUI elements having the same parent or RanoreXPath substring
Simple Folder #3
Used to group items
Use the 'Add New Item' button in the toolbar to add new items manually.
Page 73 of 247
Search result for text 'button' used in names and
paths
Repository Cleanup
The repository's 'C leanup' button is used to search for currently unused items and then to delete items which are
not used by a recording or code module. C onsidering the situation that a user clicked unintentionally on some
desktop icons during the recording, this icons would have been added to his/her repository as well. Another
situation for the need for a cleanup would be that some UI elements which are still in the repository are not part
of the software under test anymore. In order to keep your repository as tidy as possible, use the 'C leanup'
functionality from time to time to avoid disorder in repository items.
Page 75 of 247
Adding Repository Items
In this section you will find several ways to add items to your repository without using the recording functionality.
In addition, you'll learn about how you can manually add actions (clicking, typing, etc.) to the recorder and
connect these actions to repository items to specify on which UI element these actions should be executed. As an
example, a new recording module 'FindEntry' will be created which opens the KeePass search form and searches
for the 'WordPressDemo' from Lesson 3: Data-Driven Testing.
You can also add new items to your repository using the Ranorex Spy tool. The following section describes how to
add the 'Find' button which was not clicked during the recording session in order to automate a click on the button
later on.
First click the 'View Spy' button within the Ranorex Studio toolbar to open Ranorex Spy.
Next track the 'Find' button in KeePass using the 'Track' button in Ranorex Spy. The identification is indicated with
the highlighted frame around the button.
As a third step, add the button to the repository as shown in following figure.
Page 76 of 247
Add the item to the currently open repository
Note: Alternatively you could drag and drop the item from Ranorex Spy directly into the repository from Ranorex
Studio.
Note: It's also possible to track a UI elements directly from the repository using the Track button.
Now the 'Find' button is part of the repository and is ready to be used by code or recording modules. C reate a
new recording module in order to handle the 'Search' scenario. Use the 'Add New Action' drop-down button in the
toolbar of the Ranorex Recorder and add a new 'Mouse' action. There is more than one way to connect the
repository item to this action:
Drag and drop the item from the repository directly into the recording grid or
C lick on the 'browse repository button' in the recording grid (column for repository item)
Alternatively you could also drag and drop a repository item into the recording grid and create a new action this
way (you will be asked which type of action you want to create when dropping the item into the grid).
Page 77 of 247
Context menu to choose one
action when creating a new
recording action directly using
drag and drop
A new recording module was already created containing a single action for clicking on the 'Find' button in
KeePass. This recording module should be able to simulate entering text into the search form and clicking on the
'OK' button to start the search. We still need more elements in our repository and some more actions in our
recording table. Please carry out the following steps, which are quite similiar to the steps already done in this
seaction.
Note: This long list of steps shows the manually method of creating a recording. Of course these steps could be
also done as a normal recording without worrying about on the assigning of repository items.
You can easily execute a single action and multiple actions within the recorder by using the context menu item
'Play Selected Item/s' or 'Play From Here'.
Now your manually created recording consists of four actions including opening the form, clicking on the text
field, entering a key sequence and finally clicking on the 'Find' button. This simple recording can now easily be
embedded in your test case and can be made use of in any (suitable) position.
Note: Is is also possible to add a recording module two ore more times to a test case. See the following example
for more details.
To explain the test case it should be mentioned that after the setup region ('StartSUT' and 'Login') this test case
tries to 'find' a value (WordPressDemo) and to 'validate' the results. If KeePass is started with an empty
database, this validation will intentionally fail. After adding the entry ('AddNewEntry') the second instance of the
'Find' module with the subsequent 'Validate' module would succeed if the previous adding action succeeded. The
ongoing test case continues with the deletion of the item and tries to 'find' and to 'validate' again, which now
intentionally fails again. The final teardown region containing the 'Save' and the 'C loseSUT' module are executed
anyway.
Note: To prevent the recorder from stopping the run on failing the validation (intentional) please have a look at
Lesson 5: Ranorex Recorder - C ontinue On Fail and Disable and enable continuing on fail.
Use the Ranorex Spy to prepare a RanoreXPath for a multiple result and add it to the repository as described in
the previous section.
Repository items delivering a list of elements are mainly used in code modules as described in the chapter C ode
Examples.
Page 79 of 247
Waiting for UI Elements - Repository Timeouts
As was already mentioned, KeePass is not only able to work with local databases but also with databases stored
on a FTP server.
Depending on the speed of the internet connection and on the size of the database, the action of loading a
database from a FTP server can take up to 10 seconds. After the download has finished, the log in dialog
appears. To handle a scenario like that in Ranorex Recorder (or in the repository), every repository item has its
own value for a specific timeout. Use the context menu item 'Properties' to open the properties for the application
folder for the 'Log In' dialog.
In order to see what happens when the timeout value does not match the situation, set the dialog's search
timeout to 10 milliseconds in order to force an error when executing the test case again. Even without loading the
database from the external data store (e.g. FTP server) it takes some time to open the file and to bring up the
dialog. A timeout of 10 milliseconds is not enough and the 'LogIn' recording module fails.
Page 80 of 247
Test case execution failed - 'LoginWindow' was not
found within the specified timeout of 10ms
Note: In order to keep your repository suitable, reset the search timeout value for the login dialog to 30 seconds.
After confirming that KeePass is in a suitable state (opened, logged in, containing one data set) use the record
button from Ranorex Studio (choose 'Global Recording' and complete the following steps)
Because until now there was no need to access the status text, there is no repository item holding this UI
element. The validation action was accompanied with the creation of a repository item pointing to the status text
which is identified by the text value 'Ready'. After recording these simple actions, change the order in the
recording table and move the validate action (#1) to the last position (#5).
Note: You can easily rearrange the order of recording actions by dragging and dropping them in the recording
table.
Page 81 of 247
Editing RanoreXPath
The RanoreXPath is used for identifying objects and elements on the screen. Each repository item refers to a
RanoreXPath used to identify the corresponding UI element.
In order to reduce work in maintaining path expressions, repository items like buttons, text fields and list items
are automatically grouped within application folders holding the base path for each child item.
RanoreXPath separation
Press <ENTER> to change the RanoreXPath expression of an item using the edit mode or open the Path Editor
using the context menu.
By pressing the 'Edit' button, you can change the RanoreXPath using Ranorex Spy.
Use the path editor to select alternative attributes or to combine multiple attributes for unique UI element
identification. Additionally, here you can create variables to be used instead of static string values for data driven
identification (for more information see Lesson 3: Data-Driven Testing - Using Variables within the Repository).
Learn more about how to work with the path editor in Lesson 10: RanoreXPath Editor.
After changing the identification attribute from 'AccessibleName' to 'Text' you can quickly verify the new
RanoreXPath using 'Highlight element' as shown below.
Page 82 of 247
Highlight the modified element to check the
modified path
Page 83 of 247
Repository Separation
By default each Ranorex Studio project contains one repository file which is automatically used for each newly
created recording. You can manage all UI elements of a test suite project in a single repository file, but there are
several reasons for having multiple repositories within a test automation project:
The same way you think about modularization and reusability of small action recordings, the same goes for
repositories. For example when you think about a rich client application using main menus, ribbons or toolbars
you would create small reusable recordings for clicking on the main menu 'File' | 'Open' | 'Handle the Open File
Dialog' | etc. All these reusable modules work with a main menu, a main tool bar or similar common available
controls, and should be based on a repository which exclusively represents commonly used main controls on the
user interface.
Another reason to build a separate repository could be to store advanced RanoreXPath expressions which should
execlusively be used to create new actions manually instead of recording them.
As long as you're working alone on a test automation project it's not a problem to work with one single
repository. When working in teams and everyone in the team only clicks the 'Record' button to create test
automation modules, it is recommended to keep in mind who is responsible for the main repository. Who is
allowed to rename objects and to re-structure the repository? The main reason to separate repositories is to
avoid accidental damage to repository items which are used by other team members.
Add a new repository to your project by clicking the 'Add Repository' button in the Ranorex Studio toolbar.
Page 84 of 247
Create a new repository file
Note: It's crucial to understand that repositories are very essential in working with Ranorex and that the basic
principle does not depend on the technology used. Of course it is also possible to create a new repository having
the information for identifying elements on a URL or any other supported technology. This might be useful when
testing the auto-perform functionality in KeePass which assists you in opening the URL and entering the login
information which is stored in a password entry in a semi-automated way. A second, separated repository in
Ranorex Studio could therefore hold all the web elements to verify whether logging in worked or not.
Note: There are some differences in the way the elements in different technologies are identified so the
RanoreXPath is a bit different for different technologies. Once your repository is able to identify the elements in a
robust way, it doesn't matter which technology is behind your test cases. Of course, different technologies can be
tested, combined within one test automation in Ranorex Studio.
C#
view plain c opy to c lipboard print 5
[TestModule("C5B0C011-274A-4E54-83DB-0CE28DB95509", ModuleType.UserCode, 1)]
public class OptionsCodeModule : ITestModule
{
// Repository object to access UI elements of KeePass Application
MyFirstTestProjectRepository repo = MyFirstTestProjectRepository.Instance;
// Repository object to access UI elements of KeePass Options Dialog
KeePassOptionsRepository OptionsRepo = KeePassOptionsRepository.Instance;
/// <summary>
/// Constructs a new instance.
/// </summary>
public OptionsCodeModule()
{
// Do not delete - a parameterless constructor is required!
}
/// <summary>
/// Performs the playback of actions in this module.
/// </summary>
/// <remarks>You should not call this method directly, instead pass the module
/// instance to the <see cref="TestModuleRunner.Run(ITestModule)"/> method
/// that will in turn invoke this method.</remarks>
void ITestModule.Run()
{
Mouse.DefaultMoveTime = 300;
Keyboard.DefaultKeyPressTime = 100;
Delay.SpeedFactor = 1.0;
// Click the Save-Button in KeePass Mainform
repo.KeePass.ButtonSave.Click();
// Check the option to AutoClear the Clipboard
OptionsRepo.FormOptions.TabSecurity.CheckBoxClipboard_auto_clear.Checked = true
Page 85 of 247
} 6
3 4
VB.NET
view plain c opy to c lipboard print
<TestModule("BAA60B6C-5DD1-4EB5-BC39-FDFD65775742", ModuleType.UserCode, 1)> _
Public Class UserCodeModule1
Implements ITestModule
''' Repository object to access UI elements of KeePass Application
Private repo As MyFirstTestProjectRepository = MyFirstTestProjectRepository.Instance
'' Repository object to access UI elements of KeePass Options Dialog
Private OptionsRepo AS KeePassOptionsRepository = KeePassOptionsRepository.Instance
''' <summary>
''' Constructs a new instance.
''' </summary>
Public Sub New()
' Do not delete - a parameterless constructor is required!
End Sub
TestRepository repo = TestRepository.Instance;
''' <summary>
''' Performs the playback of actions in this module.
''' </summary>
''' <remarks>You should not call this method directly, instead pass the module
''' instance to the <see cref="TestModuleRunner.Run(Of ITestModule)"/> method
''' that will in turn invoke this method.</remarks>
Sub Run() Implements ITestModule.Run
Mouse.DefaultMoveTime = 300
Keyboard.DefaultKeyPressTime = 100
Delay.SpeedFactor = 1.0
''' Click the Save-Button in KeePass Mainform
repo.KeePass.ButtonSave.Click
''' Check the option to AutoClear the Clipboard
OptionsRepo.FormOptions.TabSecurity.CheckBoxClipboard_auto_clear.Checked = true
End Sub
End Class
Page 86 of 247
Repository Settings Dialog
There are two ways to open the 'Settings' dialog for the repository:
Within the 'C urrent Repository' tab you can specify the class name and the namespace of the automatically
generated source code for the current repository.
On the 'Repository Default' tab page you can specify defaults for the same for newly created repositories.
Additionally, the timeouts used for newly created repository folders and items can by simply changed in the
'Timings for new entries' group box.
The settings 'Enable folder caching' can be unchecked 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.
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 C ache' property to 'False'.
Page 87 of 247
Repository Items Properties
Each repository item (app folder, rooted folder, simple folder and item) held by a repository has a number of properties.
These properties can be altered by opening the representing properties tab which can be accesses by right-clicking the wanted repository item and choosing “Properties” in
opened context menu.
Absolute Path The “Absolute Path” represents the path to the repository item including the paths all parent folder. This property is read-only.
With the “Adapter Type” property the adapter type of the repository item can be changed. The best fitting adapter will be chosen by setting this
Adapter Type
property to default.
The “Effective Timeout” property represents the sum of the search timeouts for the specific repository item and all its parent folders. This
Effective Timeout
property is read-only.
Live Element The “Live Element” represents the control specified by the repository item found in the lice system as it is shown in Ranorex Spy.
Name The “Name” property defines the name of the repository item.
Search Timeout The “Search Timeout” property defines the amount of time an element will be searched for, before throwing exception.
Use Ensure Visible The "Use Ensure Visible" property specifies whether the repository item should be forced to become visible before automation or not.
Additionally to the properties mentioned in the table above, a rooted folder or an app folder has the following property:
Page 88 of 247
The “Use C ache” property will either enable or disable caching for the specific folder. The chapter Repository Troubleshooting - Folder C aching
Use C ache
will give more information about folder caching.
Page 89 of 247
Lesson 7: Code Modules
Though a Ranorex Recording with only smart actions, variables and user code capabilities is good enough to
create robust test automation modules, it might be useful or preferable to write pure Ranorex automation code.
In the following section you learn how to create a new code module which automates the process of adding a new
credential data set to the KeePass application.
Alternatively you are able to add a new code module by using the context menu in the Test Suite.
Page 90 of 247
Specifying the name used for the code module
After clicking the 'C reate' button a new file is added to the project and automatically opened in the file view.
Ranorex Studio creates a new test module class which contains a 'Run' method that is ready to be extended with
test automation code.
C#
view plain c opy to c lipboard print
namespace KeePass
{
/// <summary>
/// Description of AddCredentialEntry.
/// </summary>
[TestModule("03F5603B-0DDC-49AA-8C26-4D8088260C66", ModuleType.UserCode, 1)]
public class AddCredentialEntry : ITestModule
{
/// <summary>
/// Constructs a new instance.
/// </summary>
public AddCredentialEntry()
{
// Do not delete - a parameterless constructor is required!
}
/// <summary>
/// Performs the playback of actions in this module.
/// </summary>
/// <remarks>You should not call this method directly, instead pass the module
/// instance to the <see cref="TestModuleRunner.Run(ITestModule)"/> method
/// that will in turn invoke this method.</remarks>
void ITestModule.Run()
{
Mouse.DefaultMoveTime = 300;
Keyboard.DefaultKeyPressTime = 100;
Delay.SpeedFactor = 1.0;
}
}
}
VB.NET
view plain c opy to c lipboard print
Namespace KeePass
''' <summary>
''' Description of AddCredentialEntry.
''' </summary>
<TestModule("03F5603B-0DDC-49AA-8C26-4D8088260C66", ModuleType.UserCode, 1)> _
Public Class AddCredentialEntry
Implements ITestModule
''' <summary>
''' Constructs a new instance.
''' </summary>
' Do not delete - a parameterless constructor is required!
Public Sub New()
Page 91 of 247
End Sub
''' <summary>
''' Performs the playback of actions in this module.
''' </summary>
''' <remarks>You should not call this method directly, instead pass the module
''' instance to the <see cref="TestModuleRunner.Run(ITestModule)"/> method
''' that will in turn invoke this method.</remarks>
Private Sub ITestModule_Run() Implements ITestModule.Run
Mouse.DefaultMoveTime = 300
Keyboard.DefaultKeyPressTime = 100
Delay.SpeedFactor = 1.0
End Sub
End Class
End Namespace
C#
view plain c opy to c lipboard print
public class AddCredentialEntry : ITestModule
{
// Repository object to access UI Elements
MyFirstTestProjectRepository MyRepo = MyFirstTestProjectRepository.Instance;
/// Constructs a new instance.
public AddCredentialEntry()
{
// Do not delete - a parameterless constructor is required!
}
void ITestModule.Run()
{
Mouse.DefaultMoveTime = 300;
Keyboard.DefaultKeyPressTime = 100;
Delay.SpeedFactor = 1.0;
// Click 'Add Entry' Button MainMenu
MyRepo.MainForm.Edit.Click();
MyRepo.KeePass.AddEntry.Click();
// Set text fields
MyRepo.AddEntry.TabSheetAddEntry.Title.TextValue = "WordPressDemo";
MyRepo.AddEntry.TabSheetAddEntry.UserName.TextValue = "admin";
MyRepo.AddEntry.TabSheetAddEntry.Password.TextValue = "demo123";
MyRepo.AddEntry.TabSheetAddEntry.Repeat.TextValue = "demo123";
MyRepo.AddEntry.TabSheetAddEntry.URL.TextValue = "bitly.com/wp_demo";
// Choose an icon
MyRepo.AddEntry.TabSheetAddEntry.MBtnIcon.Click();
MyRepo.IconPicker.LI_Icon.Click(Location.CenterLeft);
MyRepo.IconPicker.ButtonClose.Click();
// Set Expires
MyRepo.AddEntry.TabSheetAddEntry.MBtnStandardExpires.Click();
MyRepo.KeePass.MI_Expires.Click();
// Save Credential Entry
MyRepo.AddEntry.ButtonOK.Click();
}
}
VB.NET
Page 92 of 247
view plain c opy to c lipboard print
Public Class AddCredentialEntry
Implements ITestModule
' Repository object to access UI Elements
Private MyRepo As MyFirstTestProjectRepository = MyFirstTestProjectRepository.Instance
''' Constructs a new instance.
' Do not delete - a parameterless constructor is required!
Public Sub New()
End Sub
Private Sub ITestModule_Run() Implements ITestModule.Run
Mouse.DefaultMoveTime = 300
Keyboard.DefaultKeyPressTime = 100
Delay.SpeedFactor = 1.0
' Click 'Add Entry' Button MainMenu
MyRepo.MainForm.Edit.Click()
MyRepo.KeePass.AddEntry.Click()
' Set text fields
MyRepo.AddEntry.TabSheetAddEntry.Title.TextValue = "WordPressDemo"
MyRepo.AddEntry.TabSheetAddEntry.UserName.TextValue = "admin"
MyRepo.AddEntry.TabSheetAddEntry.Password.TextValue = "demo123"
MyRepo.AddEntry.TabSheetAddEntry.Repeat.TextValue = "demo123"
MyRepo.AddEntry.TabSheetAddEntry.URL.TextValue = "bitly.com/wp_demo"
' Choose an icon
MyRepo.AddEntry.TabSheetAddEntry.MBtnIcon.Click()
MyRepo.IconPicker.LI_Icon.Click(Location.CenterLeft)
MyRepo.IconPicker.ButtonClose.Click()
' Set Expires
MyRepo.AddEntry.TabSheetAddEntry.MBtnStandardExpires.Click()
MyRepo.KeePass.MI_Expires.Click()
' Save Credential Entry
MyRepo.AddEntry.ButtonOK.Click()
End Sub
End Class
Note: By default the class name of a repository is the same as the repository file name (*.rxrep) shown in the
project's view.
Now the class uses a private member referring to repository in order to reuse some of the objects ('Title',
'Username', 'Password', 'PasswordRepeat' and 'URL') within the 'Run' method.
Depending on the structure of your repository, accessing items in code might become more and more complex.
To reduce complexity - especially when UI elements are used more than once - you should use local variables
instead of coding the whole structure of your repository everytime you need to automate a UI element.
C#
view plain c opy to c lipboard print
var ButtonOK = MyRepo.FormAdd_Entry.ButtonOK;
ButtonOK.Click();
Page 93 of 247
VB.NET
view plain c opy to c lipboard print
Dim ButtonOK = MyRepo.FormAdd_Entry.ButtonOK
ButtonOK.Click()
To create local variables as shown in the code above, simply drag and drop elements from the repository
browser directly into the code.
Note: If the repository itself is not already part of the class (e.g. newly created code modules), a local variable
for the repository is generated too
By addding a new variable Ranorex Studio inserts a new code fragment at the current cursor position. A variable
implementation consists of a public property '<VaribleName>' and a private member '_<VariableName>'.
C#
view plain c opy to c lipboard print
string _varTitle = "Wordpress Credentials";
[TestVariable("9348A7E6-80B6-4A2B-9CBF-0276A236AA3E")]
public string varTitle
{
get { return _varTitle; }
set { _varTitle = value; }
}
VB.NET
view plain c opy to c lipboard print
Private _varTitle As String = "Wordpress Credentials"
<TestVariable("9348A7E6-80B6-4A2B-9CBF-0276A236AA3E")> _
Page 94 of 247
Public Property varTitle() As String
Get
Return _varTitle
End Get
Set
_varTitle = value
End Set
End Property
Now create additional variables for the 'Username', 'Password' and 'URL'. All the module variables will appear
immediately in the module browser.
Appearance of module
variables in module browser
Variables used by the repository (e.g. 'varExpires' for the Menu Item in the context menu of KeePass's 'Add Entry
Dialog') are easily accessible via the repository, even from code. In order to bind these variables to external data
(e.g. one row in our Excel file) in a code module you have to create a new module variable to act as a bridge
between external data and repository variables. Following such an approach, it is obviously best to use the setter
methods for public variables. A public variable's setter method is called every time the value of this variable is
set; i.e. assigning the value to the private variable holding the information for the public one. This method can
easily be extended in order to set the repository variable as well.
First two new module variables, 'varExpires' and 'varIconIndex', have to be created the same way as was shown
for 'varTitle', 'varPassword'. After that, a simple code line has to be inserted into the setter method for each
variable. This code line is used for also assigning the passed value to the repository variable and facilitates
binding to external data.
C#
view plain c opy to c lipboard print
string _varRepoIconIndex = "1";
[TestVariable("EF09BC93-3447-4AC2-9DEB-FE3D78ED5538")]
public string varRepoIconIndex
{
get { return _varRepoIconIndex; }
set {
_varRepoIconIndex = value;
// Additionally set the Repository Variable in Setter-Method
MyRepo.varIconIndex = _varRepoIconIndex;
}
}
string _varRepoExpires = "1 Year";
[TestVariable("D0A54427-68FF-4B9D-B861-4882BCEC846B")]
public string varRepoExpires
{
get { return _varRepoExpires; }
set {
_varRepoExpires = value;
// Additionally set the Repository Variable in Setter-Method
MyRepo.varExpires = _varRepoExpires;
}
}
Page 95 of 247
VB.NET
view plain c opy to c lipboard print
Private _varRepoIconIndex As String = "1"
<testvariable("ef09bc93-3447-4ac2-9deb-fe3d78ed5538")> _
Public Property varRepoIconIndex() As String
Get
Return _varRepoIconIndex
End Get
Set
_varRepoIconIndex = value
' Additionally set the Repository Variable in Setter-Method
MyRepo.varIconIndex = _varRepoIconIndex
End Set
End Property
Private _varRepoExpires As String = "1 Year"
<testvariable("d0a54427-68ff-4b9d-b861-4882bcec846b")> _
Public Property varRepoExpires() As String
Get
Return _varRepoExpires
End Get
Set
_varRepoExpires = value
' Additionally set the Repository Variable in Setter-Method
MyRepo.varExpires = _varRepoExpires
End Set
End Property
</testvariable("d0a54427-68ff-4b9d-b861-4882bcec846b")></testvariable("ef09bc93-3447-4ac2-
9deb-fe3d78ed5538")>
Thus the two rows in the Excel file containing such items as the icon index can be bound to these module
variables. This binding causes the variables to be set for each iteration in the test case. During the setting of
those variables, the extended functionality also set's the repository variable assuring that the correct icon will be
used and clicked in the ongoing example.
Drag and drop the code module into a test case and
combine it with recordings
Now you can reuse the existing data connector created during Lesson 3: Data-Driven Testing with your new test
case.
Page 96 of 247
Reuse the existing data connector by choosing Bind the newly created variables to the data
the item from the drop-down field connector's columns, i.e. columns from the
Excel file
Page 97 of 247
Lesson 8: Reporting
By default each run of a test suite, a test case or a single recording generates a report file (*.rxlog) which tells
you if the run was successful or not. In the following lesson you will learn about the following:
The report shown after running a test suite provides a general overview of how many of the test cases have been
executed successfully, failed or blocked. Each executed test case and all its child modules can be analyzed more
in depth by expanding a particular test case.
In addition a test suite report also informs you about the following:
System information like execution time, machine name, operating system, screen dimensions, language,
duration
Global parameter values
If a test case uses local parameter values or external test data, the report shows the values used during
automation as shown below.
Page 98 of 247
Detailed view of a test case report
The low level log messages generated by a recording or by a code module shown in the figure above consist of a
time stamp, a report level, a category and message text. By default logging is turned on for recordings. Use the
Recorder's settings dialog to change the default value and to turn off logging for new recordings. In order to turn
logging off or on for a particular action item, open the properties and set the 'Use Default Logging' attribute to
false.
Debug a test run with quick links 'Jump to Item' and 'Open in Spy'
C lick at 'Jump to Item' to open the module and to focus on the source action item. Use the quick link 'Open in
Spy' to analyze the RanoreXPath expression used for the particular action item. This is especially useful in
situations when a test run fails with the message 'Failed to find item...' error message.
Report Folder
For each run of a test suite, a single test case or a recording a new log file (*.rxlog) is generated and saved in
the project's 'Report' folder. You can open older report files by double-clicking the file in the project view. Specify
the file names used for the report files within the test suite's settings dialog.
Note: It is not required to run Ranorex Studio to open a report file. You can also open the report file from
Windows Explorer. If you're going to copy or send the file by email, always ensure that the stylesheet file
'RanorexReport3.xsl' is located in the same target directory.
Report Levels
Within Ranorex you are able to use different levels of reporting information importance, from a debug message
to a failure information. In addition to predefined report levels, you can also easily define your own levels of
report information.
Page 99 of 247
Report Levels describe the importance of a message that is delivered to the report. Since extensive test cases
lead to extensive reports, the usage of different kinds of report levels can assist you making your reports better
arranged depending on your needs.
Within a test suite or even within a test case, you are able to define a report level that describes the minimum
level of reporting information (see Lesson 4: Ranorex Test Suite - Test Suite Settings for more information).
Report information with a lower level of importance is ignored and does not fill up your report, whereas
decreasing a test case's report level could assist you finding an error in your testing scenario.
Debug (10)
Info (20)
Warning (30)
Error (40)
Success (110)
Failure (120)
The first five items describe different levels of reporting importance and meaning. For instance an error message
in the report indicates a logical test step error whereas a warning message should only get your attention but not
indicate an error.
From report levels 'Debug' to 'Success', the result of the current module is still classified as a success whereas
the 'Failure' report level classifies the module result as a failure; this is indicated by a red mark in the report.
Additionally, at the top of a test case, warnings are indicated with a message with a yellow background.
Note: A report message, regardless of its level, never breaks the execution of a test case.
Note: A test case's failure depends on whether a Ranorex exception has been thrown or not. This could
automatically happen if a validation step fails or a new Ranorex exception is thrown.
Category
These methods can be used with one parameter indicating the 'message' itself. Alternatively they can be used
with an additional parameter indicating the category which is set to the default value 'User' in the first overload of
such methods. The default category can also be set via code by assigning the 'Ranorex.Report.DefaultC ategory'
property. The category can be seen in a distinct column in the report. The following code lines using different
reporting methods (and different reporting categories) lead to a report which is shown after the code example.
C#
view plain c opy to c lipboard print
// Reporting information (debug, info) using default Category "User"
Ranorex.Report.Debug("This is a Debug Information");
Ranorex.Report.Info("This is a Information");
// Setting Parameter Category to specific value and report a warining and an error
Ranorex.Report.Warn("Specific Category","This is a Warning Information");
Ranorex.Report.Error("Specific Category", "This is an Error Information");
// Setting the Default Category
Ranorex.Report.DefaultCategory = "My new default category";
// Reporting information (success, failure) using the new default category
Ranorex.Report.Success("This is a success information");
Ranorex.Report.Failure("This is a failure Information");
VB.NET
view plain c opy to c lipboard print
' Reporting information (debug, info) using default Category "User"
Ranorex.Report.Debug("This is a Debug Information")
Ranorex.Report.Info("This is a Information")
' Setting Parameter Category to specific value and report a warining and an error
Ranorex.Report.Warn("Specific Category", "This is a Warning Information")
Ranorex.Report.Error("Specific Category", "This is an Error Information")
' Setting the Default Category
Ranorex.Report.DefaultCategory = "My new default category"
' Reporting information(success, failure) using the new default category
Ranorex.Report.Success("This is a success information")
Ranorex.Report.Failure("This is a failure Information")
Note: Please consider that the report information at the error level with the category 'Module' (last entry)
provides a screenshot and moreover, two entries above screenshots are provided in order to visually retrace that
last steps that lead to the current error.
C#
view plain c opy to c lipboard print
Ranorex.ReportLevel MyNewReportLevel = new ReportLevel("My low Report Level", 25, null);
Ranorex.Report.Log (MyNewReportLevel, "This is unimportant information");
VB.NET
view plain c opy to c lipboard print
Dim MyNewReportLevel As Ranorex.ReportLevel = New ReportLevel
("My low Report Level", 25, Nothing)
Ranorex.Report.Log(MyNewReportLevel, "This is unimportant information")
Depending on the current Report Level (see next chapter), the report information with user-defined report level
should appear in the report as follows:
Report information on differing levels of importance only appears in the report if the parent test case has a report
level setting lower than or equal to the current report information level. The current report level can also be set
using code:
C#
view plain c opy to c lipboard print
Page 102 of 247
Ranorex.Report.CurrentReportLevel = Ranorex.ReportLevel.Parse
("Only Highest Importance;90");
VB.NET
view plain c opy to c lipboard print
"Ranorex.Report.CurrentReportLevel = Ranorex.ReportLevel.Parse
("Only Highest Importance;90")
This assignment causes the inclusion of reporting information only at a level greater the or equal to 90, which is
'Success' and 'Failure'. The resulting report, which is caused by the same code from above but with a different
current report level, can be seen below.
Note: The current report level can always be overridden by logging information with the report level 'Always'.
C#
view plain c opy to c lipboard print
Ranorex.Report.Log (Ranorex.ReportLevel.Always, "User", "Any-Case message");
VB.NET
view plain c opy to c lipboard print
Ranorex.Report.Log (Ranorex.ReportLevel.Always, "User", "Any-Case message")
Reporting Screenshots
Screenshots of the current state of the system under test or any UI element can be easily sent to the report.
C#
view plain c opy to c lipboard print
Ranorex.Report.Screenshot (MyRepo.KeePass.Toolbar.Self);
VB.NET
view plain c opy to c lipboard print
Ranorex.Report.Screenshot(MyRepo.KeePass.Toolbar.Self)
If you call the screenshot method without any arguments, a screenshot of the whole desktop will be available in
your report.
Note: Screenshots from UI elements can only be made if the element is visible at the time a screenshot is made.
C ontrolling your application using code does not necessarily bring your application to the front and make it
Page 103 of 247
visible. To ensure the visibility of UI elements, use the 'EnsureVisible' method which is provided by any element
that is derived from Ranorex Adapter class (e.g. 'Text', 'RadioButton', 'Button', etc.). C onsequently, rooted
folders from repository or even application folders do not ensure visibility. Alternatively you can ensure visibility
by using the 'Self' property from that object types (rooted folder or application folder).}
C#
view plain c opy to c lipboard print
Ranorex.Report.SystemSummary();
VB.NET
view plain c opy to c lipboard print
Ranorex.Report.SystemSummary()
Tracking UI Elements
RanoreXPath Edit Mode
C reating Ranorex Snapshot Files
General Ranorex Settings
The element browser tree shown on the left side represents the computer's desktop with all currently opened
applications. The name of the root node is set to the machine's host name. By selecting one of the elements from
the browser tree, the Spy provides more detailed information about the selected item in the tabs ‘Overview’,
‘Detail’ and ‘Screenshot’ shown on the right. Ranorex recognizes over 30 of the most commonly known types of
UI elements. In Ranorex vocabulary they are called 'adapters'. Every element shown within the element tree of
Ranorex Spy is represented by a Ranorex UI adapter. If Ranorex is not able to specify the type of adapter of a
UI element, it will be displayed as 'Unknown'.
The 'Overview' tab provides the most important view into the details of a UI element. The available attributes and
their values are divided into the following sections:
'General'
Logical adapters like 'Form', 'Button' or 'Text'
Technology related adapters like 'C ontrol', 'Accessible' or 'NativeWindow'
General
Regardless of what type of UI element is currently selected the 'General' section provides information about
whether the element is enabled, valid or visible.
All attributes shown within this tab are accessible during an automated test for validation. Depending on the type
of a UI element, they may also be used to set values. Learn more about how to use different adapters to read
and set attribute values here.
In addition all attributes can be used within the RanoreXPath. By default the attribute written in bold is
automatically used to identify the UI element.
The RanoreXPath expression shown in the figure above can be seen as a navigation path through the element
browser tree used to identify a UI element. You can use the RanoreXPath editor to change element identification
or edit the path expression directly within the text box's RanoreXPath edit mode.
Attribute equations may also be combined with 'and' and 'or' operators (e.g. button[@text='OK' and
@enabled='true']).
Specify the image region using the toolbar button 'Select Image Region' and click the 'Save' button to save the
selected region as a PNG file.
Toolbar shortcuts
Save as Snapshot Saves all UI elements from the tree view to a Ranorex snapshot file
Highlight Elements When switched on, highlights selected UI elements on the users desktop
Context menu
Set Element as Root Sets the currently selected element as root element
Note: Saved screenshots can also be used for image comparison in code, for example for finding and comparing
images or image-based automation. For more information about this, please have a look at the code examples.
Note: To abort the tracking session press <ESC > or click the 'TRAC K' button again.
In some cases it might be necessary to track UI elements which are currently behind the Ranroex Spy window.
Simply uncheck the 'Always On Top' checkbox to cause Ranorex Spy to minimize during the tracking process.
To support the editing of RanoreXPath expressions, the editor textbox provides an auto completion feature which
helps to avoid syntax errors and to speed typing. By pressing the key combination <C TRL>+<SPAC E> at any
time, the RanoreXPath editor suggests a list of suitable keywords, attributes or syntax codes.
The RanoreXPath editor mode is indicated with a yellow highlighted text box. In edit mode, RanoreXPath is used
as a query to filter UI elements as follows:
The result is presented directly within the Ranorex Spy tree. All matching items are highlighted in yellow. In
addition the result can easily be added to a repository by selecting the menu item 'Add Matching C hildren to
Repository'.
To stop the edit mode, click the red cancel button which is located in the RanoreXPath edit box.
Use the context menu item 'Save as Snapshot' within Ranorex Spy to store all elements, dialogs and applications,
including their sub-items into a single Ranorex snapshot file.
Note: In order to save screenshot information correctly, activate the desired application for which you wish to
create a snapshot before saving.
General settings
Specifies whether a UI element used as Ranorex adapter should be forced to become visible before automation
or not. By default this value is automatically used for each repository item.
Multiplies all repository timeouts with the specified value to prevent test cases from failing in case of different
timing behavior. This is especially useful when executing tests on different system configurations.
Note: The value can also be set at the time of executing a test suite using the test suite's command line
arguments or by directly using the 'Ranorex.Core.Configuration.Current.Adapter.TimeoutFactor' property
in code.
Resets 'Do not show again' checkbox used to suppress assistance dialog for technology limitations. C lick 'Reset'
to show the dialog again for not instrumented technologies or applications.
Advanced Settings
Most of the settings shown in the 'Advanced' group box are used to configure Ranorex object recognition and
RanoreXPath generation. Please be careful when changing these settings.
Use the checkbox 'Enable 32/64 Bit Bridge' to turn off the bit bridge required to handle 32/64 bit based
applications on 64 bit operating systems automatically.
This setting instructs plug-ins not to evaluate computationally intensive attributes for Ranorex Spy, Recorder, and
Ranorex Studio. If checked, attributes like Row.Index do not have a value for certain technologies when shown in
Ranorex Spy and, in that way, speeding up performance.
This setting is used to turn on or off dispatching of mouse and keyboard events during recording.
Tries to create screenshots used for recordings, repositories or Ranorex snapshot files, even for hidden
applications.
Specifies the time to wait in milliseconds before performing a key sequence simulation.
Defines the number of unique RanoreXPath levels required for a unique identification. Note: The higher the
value, the shorter the RanoreXPath strings that are generated. Keep in mind that the shorter the path, the longer
it takes to find the expected UI element.
Opens the dialog to change the current GDI capture list. More information about the Ranorex GDI plug-In can be
found here.
In order to get assistance with editing RanoreXPath weights, contact the Ranorex support team.
Note: C lick the button 'Restore Defaults' to reset all values to their default values. Use the 'Import...' and
'Export...' buttons to save and load user-specific configurations.
Plug-in specific settings can be used to alter the behavior of individual Ranorex plug-ins, for example, to achieve
backwards compatibility with older versions. For more information on each setting, read the description shown
when you click on a particular setting in the property grid.
The Advanced RanoreXPath Editor assists you in setting up the RanoreXPath of your components in an easy and
well-arranged way. So if you track some UI component with the Ranorex Spy and you want to make the
RanoreXPath of this component more readable or you’d like to simply modify the RanoreXPath you tracked,
before the Advanced RanoreXPath Editor is the tool to use.
More precisely, this will apply in Ranorex Repositories and in the Ranorex Spy. You can access the Advanced
RanoreXPath Editor by choosing any UI Element in the repository or in Spy and switch into edit mode of the
corresponding RanoreXPath by simply right-clicking on the path.
As you can see, the whole path is shown in this tree structure with each path element as one node of the tree. In
the left section of the editor you can access each of these path elements to alter the attribute equations in the
right section on which the path is based. In the bottom section you can verify and also highlight the adapters
which correspond to the path as well as apply or reject changes on the path you made. Furthermore you can
inspect how many adapters correspond to the currently selected tree item shown at the bottom left of the editor.
What we can see in the RanoreXPath structure (in Advanced RanoreXPath Editor) as well as in the RanoreXPath
itself is that the row (adapter) is indicated with the index attribute (row[@index='1']). This means that the cell
'Ranorex' is only recognized if it is located in the first row. This cell would not be found if an additional row was
inserted above and the index was changed. Also sorting for a column (e.g. column username) could easily lead to
Page 121 of 247
another row index. To avoid a problem concerning the row index, you could change the path with the use of the
RanoreXPath editor to be row independent by unchecking the index attribute checkbox in the row node.
This path leads to any cell in any row containing the text 'Ranorex'. C oncerning 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 we just open up the RanoreXPath editor again and add the column
index attribute by checking it.
If another KeePass entry is added which has the same username ('Ranorex'), this path would lead to a multiple
result. You can easily check the result of your XPath in path editor by having a look at the text in the bottom left
corner.
To find out which elements are found with the current XPath, simply click on the 'Highlight' button on the bottom
of RanoreXPath editor.
As you can see, building up a robust and unique path is a crucial task which always depends on the
characteristics of your application. Ranorex tries to support you optimally in that process by being as flexible as
possible.
Types of Equations
Ranorex provides a set of equations which can be used to build up or to modify a RanoreXPath. These equation
operators can be accessed easily via a drop-down in RanoreXPath Editor.
Textual Equations
The following types of equations are defined for textual comparisons:
"=": The value of the attribute must be equal to the given value (case sensitive)
"~": The value of the attribute must match the given regular expression
"!=": The value of the attribute must not be equal to the given value (case sensitive)
">": The value of the attribute must start with the given string (case sensitive)
Numerical Equations
The following types of equations 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 equations 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.
Note: For more details about regular expression, see RanoreXPath - RanoreXPath with Regular Expressions.
The following example shows how to use the 'unequal' operator (!=).
Relationship Operators
After exploring the equation operators, you are next going to learn more about the relationship operators.
Relationship operators define the relationship between the nodes (elements of the path). As a result it is not
necessary to always use a directed path. One element in the path can also be defined 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.
The following example describes, how to leave the directed way in the path using relationship operators, 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:
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 layer manually using the row adapter.
We simply open the Advanced RanoreXPath Editor and choose the relationship operator 'parent' in the 'Axis'
submenu.
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 layer of hierarchy to the
parent of this cell, which is a row. Highlighting the element leads to the result shown in following figure.
Adapter Types
Adapters describe the type of element that is referred to. In the RanoreXPath editor you are able to change the
attribute type easily.
Adapters used within a path, which are primarily suggested from Ranorex, can also be changed easily using the
context menu.
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.
Windows node located at the root ...in a sub-node of the tree (right)
level (left) or... 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 somehow 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.
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 easily in the RanoreXPath Editor.
If you start the RanoreXPath editor from an existing repository,, you have an additional button for each
(checked) attribute equation. With these buttons you are able to define variables which can be used for dynamical
alteration of the RanoreXPath.
The variables you have added are inherited from the repository you are working on. Each of the variables held
by the repository can be used as attribute equations. For more details about variables used within the repository,
please have a look at Lesson 3: Data-Driven Testing - Using Variables within the Repository.
Offline view means working with a snapshot file or working with a repository holding information from a non-
running application.
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).
Note: Dynamic capabilities can only be accessed for certain types of technologies (Winforms, Flash/Flex, Web
and Java).
C#
view plain c opy to c lipboard print
[TestModule("D451F1D1-C347-4B58-939F-F6187642EB56", ModuleType.UserCode, 1)]
public class UsingRepository : ITestModule
{
// Repository object to access UI elements
MyFirstTestProjectRepository repo = MyFirstTestProjectRepository.Instance;
/// <summary>
/// Constructs a new instance.
/// </summary>
public UsingRepository()
{
// Do not delete - a parameterless constructor is required!
}
void ITestModule.Run()
{
Mouse.DefaultMoveTime = 300;
Keyboard.DefaultKeyPressTime = 100;
Delay.SpeedFactor = 1.0;
// Using Ranorex.Form adapter represented by 'MyApp'
// 'MyApp' is used as a folder within the repository;
// the 'Self' property returns an object of type Ranorex.Form
// Activates application
repo.MyApp.Self.Activate();
// Log 'Active' state
Report.Info(repo.MyApp.Self.Active.ToString());
// Maximize, Minimize and Restore
repo.MyApp.Self.Maximize();
repo.MyApp.Self.Minimize();
repo.MyApp.Self.Restore();
// Closes application
repo.MyApp.Self.Close();
Page 130 of 247
// Using Ranorex.Button adapter represented by 'ButtonAdd'
// Read and log value of 'Text' attribute
Report.Info(repo.MyApp.Buttons.ButtonAdd.Text);
// Press button
repo.MyApp.Buttons.ButtonAdd.Press();
// Read and log value of 'Enabled' attribute
Report.Info(repo.MyApp.Buttons.ButtonAdd.Enabled.ToString());
// Using Ranorex.RadioButton adapter
// represented by 'GenderOption'
// Select radio button
repo.MyApp.GenderOption.Select();
// Accessing listitems of Ranorex.List adapter
// represented by 'CategoryList'
IList<Ranorex.ListItem> listItems = repo.MyApp.CategoryList.Items;
foreach ( Ranorex.ListItem item in listItems )
{
Report.Info(item.Text + " is member of CategoryList");
}
// Using Ranorex.MenuItem to open 'File' menu
repo.MyApp.MenuItemFile.Select();
// Selecting sub menu item 'Connect'
repo.FileMenu.Connect.Select();
// Read and log 'Enabled' state of menu item 'Connect'
Report.Info(repo.FileMenu.Connect.Enabled.ToString());
}
}
VB.NET
view plain c opy to c lipboard print
Public Class UsingRepository
Implements ITestModule
' Repository object to access UI elements
Private repo As MyFirstTestProjectRepository = MyFirstTestProjectRepository.Instance
''' <summary>
''' Constructs a new instance.
''' </summary>
' Do not delete - a parameterless constructor is required!
Public Sub New()
End Sub
''' <summary>
''' Performs the playback of actions in this module.
''' </summary>
''' <remarks>You should not call this method directly, instead pass the module
''' instance to the <see cref="TestModuleRunner.Run(ITestModule)"/> method
''' that will in turn invoke this method.</remarks>
Private Sub ITestModule_Run() Implements ITestModule.Run
Mouse.DefaultMoveTime = 300
Keyboard.DefaultKeyPressTime = 100
Delay.SpeedFactor = 1.0
' Using Ranorex.Form adapter represented by 'MyApp'
' 'MyApp' is used as a folder within the repository;
' the 'Self' property returns a Ranorex.Form object
' Activates application
repo.MyApp.Self.Activate()
' Log 'Active' state
Report.Info(repo.MyApp.Self.Active.ToString())
' Maximize, Minimize and Restore
repo.MyApp.Self.Maximize()
repo.MyApp.Self.Minimize()
repo.MyApp.Self.Restore()
' Closes application
repo.MyApp.Self.Close()
Page 131 of 247
' Using Ranorex.Button adapter represented by ButtonAdd'
' Read and log value of 'Text' attribute
Report.Info(repo.MyApp.Buttons.ButtonAdd.Text)
' Press button
repo.MyApp.Buttons.ButtonAdd.Press()
' Read and log value of 'Enabled' attribute
Report.Info(repo.MyApp.Buttons.ButtonAdd.Enabled.ToString())
' Using Ranorex.RadioButton adapter
' represented by 'GenderOption'
' Select radio button
repo.MyApp.GenderOption.[Select]()
' Accessing listitems of Ranorex.List adapter
' represented by 'CategoryList'
Dim listItems As IList(Of Ranorex.ListItem) = repo.MyApp.CategoryList.Items
For Each item As Ranorex.ListItem In listItems
Report.Info(item.Text & " is member of CategoryList")
Next
' Using Ranorex.MenuItem to open 'File' menu
repo.MyApp.MenuItemFile.[Select]()
' Selecting sub menu item 'Connect'
repo.FileMenu.Connect.[Select]()
' Read and log 'Enabled' state of menu item 'Connect'
Report.Info(repo.FileMenu.Connect.Enabled.ToString())
End Sub
End Class
C#
view plain c opy to c lipboard print
// Use the 'Info' object to check existence of the
// 'SaveDialog' item; Method 'Exists' uses the timeout
// specified for the 'SaveDialog' in the repository
Report.Info("Exists = " + repo.SaveDialog.SelfInfo.Exists().ToString());
// Use the 'Info' object to check existence of the
// 'TextOnline' item which uses the following RxPath:
// statusbar/text[@accessiblename='Online']
// This way you can wait with the timeout specified for
// the item within the repository for the text 'Online'
bool statusTextConnected = repo.MyApp.TextOnlineInfo.Exists();
// Using 'Info' objects for validation
// Throws a Ranorex.ValidationException if validation
// fails. Automatically reports success or failed message
// to log file
Validate.Exists(repo.SaveDialog.ButtonOKInfo);
// Validates the existance of the repository item,
// but does not throw any exception
Validate.Exists(repo.SaveDialog.ButtonOKInfo,"Check Object '{0}'",false);
VB.NET
view plain c opy to c lipboard print
' Use the 'Info' object to check existence of the
Page 132 of 247
' 'SaveDialog' item; Method 'Exists' uses the timeout
' specified for the 'SaveDialog' in the repository
Report.Info("Exists = " & repo.SaveDialog.SelfInfo.Exists().ToString())
' Use the 'Info' object to check existence of the
' 'TextOnline' item which uses the following RxPath:
' statusbar/text[@accessiblename='Online']
' This way you can wait with the timeout specified for
' the item within the repository for the text 'Online'
Dim statusTextConnected As Boolean = repo.MyApp.TextOnlineInfo.Exists()
' Using 'Info' objects for validation
' Throws a Ranorex.ValidationException if validation
' fails. Automatically reports success or failed message
' to log file
Validate.Exists(repo.SaveDialog.ButtonOKInfo)
' Validates the existance of the repository item,
' but does not throw any exception
Validate.Exists(repo.SaveDialog.ButtonOKInfo, "Check Object '{0}'", False)
C#
view plain c opy to c lipboard print
// Creating adapter of type 'NativeWindow' using the "...Info" object
Ranorex.NativeWindow nativeWnd = repo.MyApp.SelfInfo.CreateAdapter<Ranorex.NativeWindow>
(false);
// ... and read value of attribute 'ProcessName'
Report.Info("Process name of VIP Database: " + nativeWnd.ProcessName);
// Using Control Adapter to access properties and methods of
// .NET WinForms control
Ranorex.Control winFormsControl = repo.MyApp.SelfInfo.CreateAdapter<Ranorex.Control>
(false);
// Set background color of VIP application to Color.Black using the
// exposed property 'BackColor'
winFormsControl.SetPropertyValue("BackColor",Color.Black);
// Report screenshot after changing the background color
Report.Screenshot(repo.MyApp.Self);
// Closes VIP Database by invoking the 'Close' method
// exposed by the System.Windows.Forms.Form class
winFormsControl.InvokeMethod("Close");
VB.NET
view plain c opy to c lipboard print
' Creating adapter of type 'NativeWindow' using the "...Info" object
Dim nativeWnd As Ranorex.NativeWindow = repo.MyApp.SelfInfo.CreateAdapter
(Of Ranorex.NativeWindow)(False)
' ... and read value of attribute 'ProcessName'
Report.Info("Process name of VIP Database: " & nativeWnd.ProcessName)
' Using Control Adapter to access properties and methods of
' .NET WinForms control
Dim winFormsControl As Ranorex.Control = repo.MyApp.SelfInfo.CreateAdapter
(Of Ranorex.Control)(False)
' Set background color of VIP application to Color.Black using the
' exposed property 'BackColor'
Page 133 of 247
winFormsControl.SetPropertyValue("BackColor", Color.Black)
' Report screenshot after changing the background color
Report.Screenshot(repo.MyApp.Self)
' Closes VIP Database by invoking the 'Close' method
' exposed by the System.Windows.Forms.Form class
winFormsControl.InvokeMethod("Close")
Note: In order to access properties or methods exposed by a WinForms control you need to know their names. If
you're not familiar with the control's API ask the developer of your application for assistance.
C#
view plain c opy to c lipboard print
// Create a list of adapters using the "...Info" object
IList<Ranorex.Button> buttonList =
repo.MyApp.EnabledButtonsInfo.CreateAdapters<Ranorex.Button>();
// Move the mouse pointer to each button of the list
// and add a screenshot for each to the report
foreach (Ranorex.Button button in buttonList )
{
button.MoveTo();
Report.Screenshot(button);
}
VB.NET
view plain c opy to c lipboard print
' Create a list of adapters using the "...Info" object
Dim buttonList As IList(Of Ranorex.Button) =
repo.MyApp.EnabledButtonsInfo.CreateAdapters(Of Ranorex.Button)()
' Move the mouse pointer to each button of the list
' and add a screenshot for each to the report
For Each button As Ranorex.Button In buttonList
button.MoveTo()
Report.Screenshot(button)
Next
Learn more about how to create repository items delivering multiple elements here: Adding Repository Items
C#
view plain c opy to c lipboard print
// Validate for Existence
// Using 'Info' objects for validation
// Throws a Ranorex.ValidationException if validation
// fails. Automatically reports success or failed message
// to log file
Validate.Exists(repo.SaveDialog.ButtonOKInfo);
// Validates the existance of the repository item,
Page 134 of 247
// but does not throw any exception
bool exists = Validate.Exists(repo.SaveDialog.ButtonOKInfo,"Check Object '{0}'",false);
// Check whether an application form exists using a RanoreXPath
Validate.Exists("/form[@controlname='formVipApplication']");
// Check whether an application does not exists
// for the time specified as timeout for the given repository item
Validate.NotExists(repo.MyApp.SelfInfo);
// Validate 'Enabled' attribute of button 'Delete'
Validate.Attribute(repo.MyApp.Buttons.ButtonDeleteInfo,"Enabled",false);
VB.NET
view plain c opy to c lipboard print
' Validate for Existence
' Using 'Info' objects for validation
' Throws a Ranorex.ValidationException if validation
' fails. Automatically reports success or failed message
' to log file
Validate.Exists(repo.SaveDialog.ButtonOKInfo)
' Validates the existance of the repository item,
' but does not throw any exception
Dim existsn As Boolean = Validate.Exists
(repo.SaveDialog.ButtonOKInfo,"Check Object '{0}'",false)
' Check whether an application form exists using a RanoreXPath
Validate.Exists("/form[@controlname='formVipApplication']")
' Check whether an application does not exists
' for the time specified as timeout for the given repository item
Validate.NotExists(repo.MyApp.SelfInfo)
' Validate 'Enabled' attribute of button 'Delete'
Validate.Attribute(repo.MyApp.Buttons.ButtonDeleteInfo,"Enabled",false)
Note: Each method provided by the Validate class allows to suppress exceptions thrown in case of a failed
validation. The code snippet above uses only a few validation methods. For further and more detailed explanation
of the Ranorex.Validate class see the API documention.
C#
view plain c opy to c lipboard print
Ranorex.Cell cellObject = null;
// Try to find a cell object using two
// different RanoreXPath expressions
bool found=false;
found = Host.Local.TryFindSingle<Ranorex.Cell>("/form//table/row/cell
[3]", 2000, out cellObject);
found = Host.Local.TryFindSingle<Ranorex.Cell>("/form//table/row/cell
[4]", 2000, out cellObject);
// If none of the expressions returns an object
// throw new 'ElementNotFoundException' and test case fails
if (!found)
{
Ranorex.ElementNotFoundException
Page 135 of 247
throw new Ranorex.ElementNotFoundException
("Both RanoreXPath with no return", null);
}
else
{
// If the value of attribte 'Text' does not equal to the expected value
// throw new 'ValidationException' to break the test case
if ( cellObject.Text == "MyExpectedTextValue" )
{
Report.Success
("User Specific Validation","Text validation of cell object succeeded");
}
else
{
throw new Ranorex.ValidationException
("Text validation of cell object succeeded failed");
}
}
VB.NET
view plain c opy to c lipboard print
Dim cellObject As Ranorex.Cell = Nothing
' Try to find a cell object using two
' different RanoreXPath expressions
Dim found As Boolean = Host.Local.TryFindSingle(Of Ranorex.Cell)("/form//table/row/cell
[3]", 2000, cellObject)
found = Host.Local.TryFindSingle(Of Ranorex.Cell)("/form//table/row/cell
[4]", 2000, cellObject)
' If none of the expressions returns an object
' throw new 'ElementNotFoundException' and test case fails
If Not found Then
Throw New Ranorex.ElementNotFoundException("Both RanoreXPath with no return", Nothing)
Else
' If the value of attribte 'Text' does not equal to the expected value
' throw new 'ValidationException' to break the test case
If cellObject.Text = "MyExpectedTextValue" Then
Report.Success
("User Specific Validation", "Text validation of cell object succeeded")
Else
Throw New Ranorex.ValidationException
("Text validation of cell object succeeded failed")
End If
End If
C#
view plain c opy to c lipboard print
void ITestModule.Run()
{
Mouse.DefaultMoveTime = 300;
Keyboard.DefaultKeyPressTime = 100;
Delay.SpeedFactor = 1.0;
}
VB.NET
view plain c opy to c lipboard print
C#
view plain c opy to c lipboard print
// ----------------- Code Block used by Code Module A -----------------
// Click 'Save' button to open 'SaveDialog'
repo.MyApp.Buttons.ButtonSave.Click();
// Read text message shown with 'SaveDialog'
// and assign it to test case parameter 'DialogText'
TestCase.Current.DataContext.Parameters
["DialogText"] = repo.SaveDialog.TextMessage.TextValue;
// -------- Code Block used by User Code Action of recording B --------
// Read value of 'DialogText' paramaeter in other code module
// or recording module using a user code action
Report.Info(TestCase.Current.DataContext.Parameters["DialogText"]);
// Get the current data context and log
// the current row index of a data driven run
Report.Info(TestCase.Current.DataContext.CurrentRow.ToString());
VB.NET
view plain c opy to c lipboard print
' ----------------- Code Block used by Code Module A -----------------
' Click 'Save' button to open 'SaveDialog'
repo.MyApp.Buttons.ButtonSave.Click()
' Read text message shown with 'SaveDialog'
' and assign it to test case parameter 'DialogText'
TestCase.Current.DataContext.Parameters
("DialogText") = repo.SaveDialog.TextMessage.TextValue
' Read value of 'DialogText' paramaeter in other code module
' or recording module using a user code action
Report.Info(TestCase.Current.DataContext.Parameters("DialogText"))
' Get the current data context and log
' the current row index of a data driven run
Report.Info(TestCase.Current.DataContext.CurrentRow.ToString())
' -------- Code Block used by User Code Action of recording B --------
' Read value of 'DialogText' paramaeter in other code module
' or recording module using a user code action
Report.Info(TestCase.Current.Parameters("DialogText"))
Page 137 of 247
' Get the current data context and log
' the current row index of a data driven run
Report.Info(TestCase.Current.DataContext.CurrentRow.ToString())
C#
view plain c opy to c lipboard print
// Create Ranorex.Button adapter using 'FindSingle' method
// from Host.Local (starting at root node) with absolute RanoreXPath
// Note: ElementNotFound exception is thrown if item is not found within
// the specified timeout of 2000 ms.
Ranorex.Button addButtonVar1 = Host.Local.FindSingle<Ranorex.Button>("/form
[@controlname='formVipApplication']/button[@controlname='btAdd']",2000);
addButtonVar1.MoveTo();
// Alternatively you can use the 'TryFindSingle' method to prevent
// a test case from failing because of an exception thrown if
// the element is not found within the specified timeout of 2000 ms
Ranorex.Button addButtonVar2 = null;
bool found = Host.Local.TryFindSingle<Ranorex.Button>("/form
[@controlname='formVipApplication']/button
[@controlname='btAdd']", 2000, out addButtonVar2);
// Move mouse pointer to button
addButtonVar2.MoveTo();
// Request a list of buttons shown from the VIP Database application
// and create a screenshot for each button in the report file
IList<Ranorex.Button> buttonList = Host.Local.Find<Ranorex.Button>("/form
[@controlname='formVipApplication']/button",500);
foreach (Ranorex.Button bt in buttonList)
{
Report.Screenshot(bt);
}
// Using find methods in combination with existing Ranorex repository items
Ranorex.Button btAdd = repo.MyApp.Self.FindSingle<Ranorex.Button>("button
[@controlname='btAdd']",2000);
VB.NET
view plain c opy to c lipboard print
' Create Ranorex.Button adapter using 'FindSingle' method
' from Host.Local (starting at root node) with absolute RanoreXPath
' Note: ElementNotFound exception is thrown if item is not found within
' the specified timeout of 2000 ms.
Dim addButtonVar1 As Ranorex.Button = Host.Local.FindSingle(Of Ranorex.Button)("/form
[@controlname='formVipApplication']/button[@controlname='btAdd']", 2000)
addButtonVar1.MoveTo()
' Alternatively you can use 'TryFindSingle' method to prevent
' a test case from failing because of an exception thrown if
' the element is not found within the specified timeout of 2000 ms
Dim addButtonVar2 As Ranorex.Button = Nothing
Dim found As Boolean = Host.Local.TryFindSingle(Of Ranorex.Button)("/form
[@controlname='formVipApplication']/button[@controlname='btAdd']", 2000, addButtonVar2)
' Move mouse pointer to button
addButtonVar2.MoveTo()
' Request a list of buttons from the VIP Database application
' and create a screenshot for each button in the report file
Dim buttonList As IList(Of Ranorex.Button) = Host.Local.Find(Of Ranorex.Button)("/form
[@controlname='formVipApplication']/button", 500)
Page 138 of 247
For Each bt As Ranorex.Button In buttonList
Report.Screenshot(bt)
Next
' Using find methods in combination with existing Ranorex repository items
Dim btAdd As Ranorex.Button = repo.MyApp.Self.FindSingle(Of Ranorex.Button)("button
[@controlname='btAdd']", 2000)
C#
view plain c opy to c lipboard print
// Create bitmap to search for
// within application form and
// click it
Bitmap bmp = Ranorex.Imaging.Load(
@"..\..\Green Sea Turtle Small.bmp");
// Performs a right click on the image found
// within the application window based on
// the image location
myRepo.WinFormsApp.Self.Click(MouseButtons.Right,bmp);
// You can also search for images that are slightly different to the
// loaded image by specifying the minimum Similarity for a match (95% = 0.95).
myRepo.WinFormsApp.Self.Click(new Location(bmp, new Imaging.FindOptions(0.95)));
// OR Set the default Similarity value for all following image operations
Imaging.FindOptions.Default.Similarity = 0.95;
myRepo.WinFormsApp.Self.Click(bmp);
Report.Success("Image found and clicked successfully");
VB.NET
view plain c opy to c lipboard print
' Create bitmap to search for
' within application form and
' click it
Dim bmp As Bitmap = Ranorex.Imaging.Load("..\..\Green Sea Turtle Small.bmp")
' Performs a right click on the image found
' within the application window based
' on the image location
myRepo.WinFormsApp.Self.Click(MouseButtons.Right, bmp)
' You can also search for images that are slightly different to the
' loaded image by specifying the minimum Similarity for a match (95% = 0.95).
myRepo.WinFormsApp.Self.Click(new Location(bmp, new Imaging.FindOptions(0.95)))
' OR Set the default Similarity value for all following image operations
Imaging.FindOptions.Default.Similarity = 0.95
myRepo.WinFormsApp.Self.Click(bmp)
Report.Success("Image displayed successfully")
C#
// Create bitmap
Bitmap bmp = Ranorex.Imaging.Load(
@"..\..\Green Sea Turtle Small.bmp");
// Search for it within the application window
if (Ranorex.Imaging.Contains(myRepo.WinFormsApp.Self,bmp) == true)
{
Report.Success("Image found within WinForms application");
}
VB.NET
view plain c opy to c lipboard print
' Create bitmap
Dim bmp As Bitmap = Ranorex.Imaging.Load("..\..\Green Sea Turtle Small.bmp")
' Search for it within the application window
If Imaging.Contains(myRepo.WinFormsApp.Self,bmp Then
Report.Success("Image found within WinForms application")
End If
Note: Both examples load an uncompressed file (BMP or PNG format) in order to carry out a one-to-one
comparison. Use the FindOptions class to configure similarity, preprocessing and other search settings.
C#
view plain c opy to c lipboard print
Form optionsDialog = "/form[@title='Folder Options']";
Tree settingsTree = optionsDialog.FindSingle<Ranorex.Tree>
("container[@caption='View']/tree[@controlid='30120']");
foreach (TreeItem item in settingsTree.Items)
{
IterateTree(item);
}
static void IterateTree(Ranorex.TreeItem treeItem)
{
foreach (Ranorex.TreeItem item in treeItem.Items)
{
item.Click();
CheckForWarningDialog();
Thread.Sleep(100);
if (item.Items.Count > 0)
{
IterateTree(item);
}
item.Click();
CheckForWarningDialog();
}
}
// Some mouse clicks causes a warning dialog to popup
// which has to be handled and closed
static void CheckForWarningDialog()
{
Ranorex.Button button=null;
if (Host.Local.TryFindSingle("/form[@title='Warning']/button
[@text='&No']", 1000, out button))
button.Click();
}
VB.NET
view plain c opy to c lipboard print
Dim optionsDialog As Form = "/form[@title='Folder Options']"
Dim settingsTree As Tree = optionsDialog.FindSingle(Of Ranorex.Tree)("container
[@caption='View']/tree[@controlid='30120']")
For Each item As TreeItem In settingsTree.Items
IterateTree(item)
Next
Private Shared Sub IterateTree(treeItem As Ranorex.TreeItem)
For Each item As Ranorex.TreeItem In treeItem.Items
item.Click()
CheckForWarningDialog()
Thread.Sleep(100)
If item.Items.Count > 0 Then
IterateTree(item)
End If
Page 141 of 247
item.Click()
CheckForWarningDialog()
Next
End Sub
' Some mouse clicks causes a warning dialog to popup
' which has to be handled and closed
Private Shared Sub CheckForWarningDialog()
Dim button As Ranorex.Button = Nothing
If Host.Local.TryFindSingle("/form[@title='Warning']/button
[@text='&No']", 1000, button) Then
button.Click()
End If
End Sub
In this dialog you can add new data connectors of the types described in the next chapters and rename or delete
existing data connectors.
To add an existing data connector or create a new data connector to one of your test cases, select the desired
test case from test suite view and open the data source dialog by pressing the “Data Source…” button.
In this new opened dialog you can create a new data connector by selecting one of the data connector types
described in the next chapters from the combo box marked in green. You can also choose an existing data
connector by selecting one of the data sources from the combo box marked in red. By pressing the blue marked
button, labeled “Manage Data Sources” the data source management dialog, explained before, will be opened. By
pressing the yellow marked button labeled “Refresh”, the data of the actual selected data source will be updated
from its source file or database. You can limit the data of your data source by selecting a data range in the area
marked orange. To open a dialog showing you the effective data set limited by a range (area marked in orange),
press the purple marked button, labeled “Preview effective data set…”.
In this dialog you can update the effective data set from the data file or database by pressing the green marked
button labeled “Refresh”. You can also export the effective data set to a C SV file by pressing the red marked
button, labeled “Export C SV”.
You can edit the name of the data connector in the text box marked in red and choose the C SV file by selecting a
file in the green marked area. By checking or un-checking the check box marked blue you can decide either to
include or to exclude the selected C SV file to your test suite. By checking this check box, a copy of the file will be
placed in your solutions folder. By checking the yellow marked check box, the first line of your C SV file will be
added as the header of all rows.
C SV data connectors are, like simple data connectors, not read-only. You can add rows and columns in the same
way as described in chapter Simple Data Table. The changes to your table will be applied to the C SV file. If you
have chosen the option 'Include File in Test Suite' in the data source management dialog, the changes will be
applied to the local copy of your C SV file.
You can edit the name of the data connector in the text box marked yellow. To generate a connection string to
connect to your database, press the red marked 'C reate' button. After establishing a connection to the database
by generating a connection string, you can add an SQL query by pressing the green marked 'C reate' button.
Create Query
By pressing the green marked 'C reate' button in the data source management dialog the query design dialog will
be opened.
You can add a column by double clicking an attribute of a table in your database. These attributes can be found in
the area marked green. These attributes will be added to the area marked red, keeping the column headings
shown in your data connector, as well as in the area marked blue, with the SQL query. Pressing the button
marked yellow will add a 'GROUP BY' statement to the SQL query. Pressing the button marked orange will allow
you to add advanced settings to your SQL query. Pressing the purple button will check SQL syntax. Pressing the
light blue button will show you a preview of the data set retrieved by the SQL query. Pressing the button marked
brown will reset the SQL query.
You can edit the name of the data connector in the text box marked red and choose the Excel file by selecting a
file in the green marked area. By checking or un-checking the check box marked blue you can decide either to
include or to exclude the selected Excel file to your test suite. By checking this check box, a copy of the file will
be placed in your solutions folder. Additionally you can define the worksheet and the range of the worksheet
which will provide the data for the Excel file connector in the yellow marked area.
The Ranorex Instrumentation Wizard can be started either from “Tools” menu in Ranorex Studio, from the pop-up
dialog triggered by a technology limitation, from the start menu, or directly from the binary folder of your
Ranorex installation (<Ranorex Installation Folder>\bin\Ranorex.InstrumentationWizard.exe). When starting the
Wizard from the “bin” folder of your Ranorex installation, you have to make sure to start the executable with
administrator rights.
Java AWT/Swing
Adobe Flash/Flex
Mozilla Firefox
Google C hrome
Apple Safari
Android
By starting the wizard from the “Tools” menu, from the start menu or from the “bin” folder, you can choose which
kind of technology you want to instrument, whereas the technology limitation pop-up leads you directly to the
instrumentation of the technology with limited identification capabilities.
Instrumentation Wizard
The Instrumentation Wizard tries to add the Plug-In specific files to the Java Runtime Environment (JRE) of your
choice and to activate the Java Plug-In for Ranorex.
Select a JRE from a list of running Java applications: Here you can choose the Java runtime based
on the application you want to instrument. This is the preferred method, as you can determine exactly
which Java runtime is being used by your application under test.
Select a JRE from a list of installed Java runtimes: Here you can choose the Java Runtime
Environment you want to be instrumented from a list of all installed Java runtimes on your machine.
Specify a custom Java runtime directory: Here you can specify the folder holding the Java runtime
you want to be instrumented.
After activating the Java AWT/Swing instrumentation, Ranorex will not be limited in recognizing UI elements of
your Java application. Restart your application under test and your Ranorex tools to ensure that the newly added
instrumentation works correctly.
If you are using Windows XP SP2, please also make sure that the Windows Update KB884020 is installed, which
resolves problems with the local network communication.
If the activation of the Java Plug-In was not successful, please make sure that you have installed Ranorex
correctly, that you have chosen the right directory of your JRE, and if you have started the Instrumentation
Wizard from the “bin” folder that it has been started with admin rights.
Note: If you need to automate an Adobe AIR application, please read how to do the instrumentation manually for
Adobe AIR testing chapter.
The instrumentation Wizard tries to install either the Flash Debug Player for Internet Explorer or
the Flash Debug Player for Mozilla Firefox, Google Chrome and Safari or both Flash Debug Players if
you like.
Moreover, you can enable the Ranorex Preloader Instrumentation. This allows you – in combination with the Flash
Debug Player – to instrument your application under test without the need to alter your application.
Additionally, you can enable logging for the Flash Debug Player. This might be helpful if you have any problems
with this kind of instrumentation. In such case you can then simply provide this logging information to our support
team.
After installing the Debug Players and activating the Ranorex Preloader, Ranorex should be able to recognize
your Flash and Flex applications without any limitations. Restart your application under test and your Ranorex
tools to ensure that the newly added instrumentation works correctly.
If you still have problems within recognition of Flash/Flex applications, please make sure that your applications
are not double instrumented, i.e. make sure that you do not use any Ranorex Library or Ranorex Module within
your Flash/Flex application.
Google Chrome
To use the preloader method with Google C hrome, you have to disable the internal Flash Player.
This can be done by performing following steps:
Disable the internal Flash Player (framed red) and keep the Flash Debug Player (framed green) enabled:
The Instrumentation Wizard tries to install the Mozilla Firefox Add-On when checking the checkbox “Activate
Mozilla Firefox Add-On” and tries to uninstall the Add-On when unchecking the mentioned checkbox.
After installing the Add-On, Ranorex should not have any limitation recognizing UI elements within your web
document. Restart your application under test and your Ranorex tools to ensure that the newly added
instrumentation works correctly.
If the activation of the Add-On was not successful, please make sure that you have installed Ranorex correctly
and if you have started the Instrumentation Wizard from “bin” folder that it has been started with admin rights.
If you still get a limitation when tracking web elements, please assure that the Mozilla Firefox Add-On is enabled
in the Firefox Add-On settings.
Note: To successfully activate the Ranorex Add On for Firefox 8 and greater, it is necessary to confirm its
installation.
The Instrumentation Wizard tries to activate the Google C hrome Extension when checking the checkbox “Activate
Google C hrome Addon” and tries to deactivate the Extension when unchecking the mentioned checkbox.
After activating the Extension, Ranorex should not have any limitation recognizing UI elements within your web
document. Restart your application under test and your Ranorex tools to ensure that the newly added
instrumentation works correctly.
If the activation of the Add-On was not successful, please make sure that you have installed Ranorex correctly
and if you have started the Instrumentation Wizard from “bin” folder that it has been started with admin rights.
If you still get a limitation when tracking web elements, please assure that the Ranorex Automation Extension is
enabled in the C hrome Extensions settings (chrome://settings/extensionSettings).
If you have removed the Ranorex Automation Extension manually, you have to manually re-add the Extension.
Therefore you have to open the file RanorexAutomation.crx, which can be found in the binary folder of your
Ranorex installation ('..\Ranorex 3.2\bin\ RanorexAutomation.crx '), in C hrome and install by following the
instructions.
Note: If you want to test cross domain iframe scripting with Google C hrome, you have to start C hrome with the
command line argument “--disable-web-security”.
Note: If you want to test file URLs, you have to enable “Allow access to file URLs” for the Ranorex Automation
Extension.
Note: if the NotScript C hrome Extension is installed it has to be disabled to allow from point tracking with
Ranorex.
The Instrumentation Wizard tries to activate the Safari Extension when checking the checkbox “Activate Apple
Safari Addon” and tries to deactivate the Extension when unchecking the mentioned checkbox.
After activating the Extension, you have to confirm the installation in Safari.
After activating the Extension and confirming the installation, Ranorex should not have any limitation recognizing
UI elements within your web document. Restart your application under test and your Ranorex tools to ensure that
the newly added instrumentation works correctly.
If the activation of the Extension was not successful, please make sure that you have installed Ranorex correctly
and if you have started the Instrumentation Wizard from “bin” folder that it has been started with admin rights.
If you still get a limitation when tracking web elements, please assure that the Apple Safari Extension is enabled
in the Safari Extensions settings (Preferences->Extensions).
Note: Testing file URLs with Apple Safari is currently not supported.
Note: Testing cross domain iframe scripting with Apple Safari is currently not supported.
Note: Have a look at Android Testing - Getting Started to learn how to automate Android applications.
C hoose the APK file of the app and the device, the instrumented APK file will be deployed to. More information
about setting up a mobile device can be found in section Manage Devices.
If the APK is already instrumented and only needs to be deployed on a mobile device, the checkbox “Instrument
the APK under test before deployment” can be unchecked.
After processing the instrumentation and deploying the instrumented APK file to the selected device, the
installation has to be confirmed on the device.
The instrumented APK file can be found at location referenced by the link “Open instrumentation File location”.
After instrumenting the APK file, the app is available in the “Mobile Recording” section of Record Setting dialog.
The Ranorex Service App installed on the mobile device shows an overview of instrumented apps installed on the
device.
Overview of instrumented
APKs
2. Make a backup of your existing 2.X project and add it to the Test Suite Project
You can easily adapt your existing data-driven test recording modules by doing following:
1. Open your recording file and click on the "Variables..." button in the Ranorex Recorder view
3. Open the UserCode file of your recording and remove your existing properties
1. Select your project in the projects view and click on "Add Code Module"
C#
view plain c opy to c lipboard print
namespace MyFirstTestProject
{
/// <summary>
/// Description of AddAndDeleteVip.
/// </summary>
[TestModule("A730AB98-9CFE-49D5-BDA7-0CAE6C614866")]
public class AddAndDeleteVip : ITestModule
{
public AddAndDeleteVip()
{
}
void ITestModule.Run()
{
Mouse.DefaultMoveTime = 300;
Keyboard.DefaultKeyPressTime = 100;
Delay.SpeedFactor = 1.0;
// Call your existing test method
Program.ExistingTest();
}
}
}
Now you can add your code module to a test case. Please see following pages for more information about code
modules:
Breaking Changes
A few changes had to be introduced that can break existing Ranorex 2.X projects when updating to Ranorex 3.X.
If your automation project does not work any more after updating to 3.X, please see the following list that
explains what has changed and how you need to update your project to make it work with 3.X again:
The Delay class has been moved from the "Ranorex.C ore" to the "Ranorex" namespace. If the Delay class
cannot be found, you need to include the "Ranorex" namespace at the top of the file:
C#
Page 168 of 247
view plain c opy to c lipboard print
using Ranorex;
VB.NET
view plain c opy to c lipboard print
imports Ranorex
The IReportLogger interface has been extended. In particular, the signature of the LogText and LogData
methods changed and the PreFilterMessages property was added. If you get compile errors after updating
stating that your classes do not correctly implement the IReportLogger interface, please update the
implementing classes accordingly. See following blog on how to implement the new IReportLogger
interface:
C ustomizing Ranorex Reports
The tree structure for MSAA elements has changed under certain circumstances and potentially includes
more levels and elements now. If you do not want to use the new elements, set the MSAA "Filter
compatibility level" setting in the "Plugins" tab of the Ranorex settings to "V2X". Otherwise, please, update
broken RanoreXPaths accordingly.
Text nodes which consist only of white-spaces are no longer appended to Mozilla WebElement.InnerText.
Please, update RanoreXPaths and validations that depend on this property and fail accordingly.
Some Win32 controls in the tree no longer have the role Form, but a more appropriate role instead. If you
want Ranorex to not use the new role, set the Win32 "Use legacy Form role" setting in the "Plugins" tab of
the Ranorex settings to "True". Otherwise, please, update broken RanoreXPaths accordingly.
C ontrol.Get/SetPropertyValue now use Reflection instead of the C omponentModel. If a property cannot be
found, please check that the used name correctly reflects the API name of the property.
The C ontrolNet11 capability is no longer used as the preferred capability for .NET 1.1 controls. As a
consequence, the generated path to items with that capability can change (existing paths will still work).
With version 3.0.1 Ranorex added basic support for Delphi controls resulting into different RanoreXPaths
being generated for many Delphi controls. If you do not want to use the new functionality, set the Win32
"Enable basic Delphi support" setting in the "Plugins" tab of the Ranorex settings to "False".
Learn more about technology dependent instrumentation and how to troubleshoot object recognition issues using
the information below:
Flash/Flex Testing
Testing of Java Applications
Qt Testing
Testing of Legacy Applications
General Troubleshooting
Prerequisites Samples
The automation of Flash/Flex applications A flash/flex test sample project is included
requires inclusion of the Ranorex Flex with the Ranorex installation package
Automation Lib. (shown on the startpage of Ranorex
Studio).
Using the Ranorex PreLoader
How to read/set attributes and
styles
OR including the Ranorex Lib
into Adobe Flex: How to load the
Ranorex Lib into a Flex application
PreLoader (recommended)
The Ranorex PreLoader enables automation of your flash/flex application without modifying the application itself.
Automation Lib
The AutomationLib swc file has to be included into your flash/flex application (by adding a compiler argument).
AutomationLib will be loaded in background (will not affect the functionality of your flash/flex application)
No modifications to your website needed
Module
The Module swf file has to be loaded by adding a code snippet to your AC TIONS (for flash) or to your
"applicationC ompleteHandler" function (for flex).
Module will be loaded in background (will not affect the functionality of your flash/flex application)
No modifications to your website needed
Module swf has to be copied to the web server
The following table shows you the different instrumentation options available for the supported versions of flash/flex ( =
supported, = recommended):
Automation Lib
Module
* Support for Adobe AIR 2 Release in combination with Flex 3.5 and Flex 4 Release
Use Ranorex Recorder to automate Flash/Flex applications in all supported browser (Internet Explorer, Firefox, C hrome
and Safari). You can add user code actions to your recordings to access custom Flex properties.
// Set the checked state with the property "Checked"
repo.FlexTestPageDom.CheckBox_Control_Example.CheckBoxEggs.Checked = true;
To access custom attributes and styles, you first have to load your Flex item as a FlexElement in order to read your
attributes. Here's an example:
1. Install the Adobe Debug Flash Player on the machine on which you would like to record and execute Ranorex
test scripts and for all browsers you would like to test with. The installers are available on Adobe’s download page;
the following are the links to the Debug Player for Internet Explorer and Firefox/C hrome/Safari.
2. Open your user profile directory %UserProfile%, e.g. by opening Windows Explorer and copying the string %
UserProfile% into the address bar.
3. Create a new file called „mm.cfg” in your user profile directory and insert the following line of code, where
“C :\FlashFlex\RanorexAutomation.swf” needs to be replaced by the preloader location of your Ranorex installation:
PreloadSwf= C:\Program Files\Ranorex 3.X\Bin\RanorexAutomation.swf
Additional to this configuration entry you can enable the logging mechanisms of the Adobe Debug Flash Player,
which might be helpful if you have any problems with this kind of instrumentation. In such a case you can then
simply provide this logging information to our support team. To enable logging you have to add the following line of
code to your “mm.cfg” file:
TraceOutputFileEnable=1
This additional configuration entry forces the Debug Player to create a log file at following location:
C :\Users\username\AppData\Roaming\Macromedia\Flash Player\Logs
4. If you run your application from the local drive, add your output directory to the trusted locations of Flash Player as
follows:
1. Open following link
http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04a.html#119065
2. Add your project output directory
Adobe Flex: Load the Ranorex Lib into your Flex application
-include-libraries "C:\Program Files\Ranorex 3.X\Bin\RanorexAutomation.swc"
import Ranorex.RxAutomation;
RxAutomation.Init();
Adobe Flash: Load the Ranorex Lib into your Flash application
import Ranorex.RxAutomation;
RxAutomation.InitFromApp(stage);
import mx.controls.*;
import flash.events.*;
import flash.display.*;
import flash.ui.Keyboard;
import flash.geom.Rectangle;
import fl.events.SliderEvent;
// Add Ranorex library
import Ranorex.RxAutomation;
public class Simple extends MovieClip
{
public function Simple()
{
// Add to your constructor
RxAutomation.InitFromApp(stage);
}
}
6. Run your application in a supported browser (Internet Explorer, Firefox, C hrome, Safari)
7. If you run your Flash application from the local drive, add your output directory to the trusted locations of Flash
Player as follows:
1. Open following link
http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04a.html#119065
2. Add your project output directory
import flash.net.URLRequest;
var rxloader : Loader = new Loader();
stage.addChild(rxloader);
rxloader.name = "__rxloader";
rxloader.width = 0; rxloader.height = 0;
rxloader.load(new URLRequest("RanorexAutomation.swf"));
3. C opy the RanorexAutomation.swf file, located in the Bin directory of your Ranorex installation, to your web
server (where your .swf file is located)
4. Run your application in a supported browser (Internet Explorer, Firefox, C hrome, Safari)
5. If you run your Flash application from the local drive, add your output directory to the trusted locations of Flash
Player as follows:
1. Open following link
www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04a.html
2. Add your project output directory
1. Start Adobe Flex Builder or Flash Builder and open your workspace
2. Append following code to your "applicationC ompleteHandler" function or initialization code:
For Flex 3:
For Flex 4:
var rxloader : Loader = new Loader();
FlexGlobals.topLevelApplication.parent.addChild(rxloader);
rxloader.name = "__rxloader";
rxloader.width = 0; rxloader.height = 0;
rxloader.load(new URLRequest("RanorexAutomation.swf"));
3. C opy the RanorexAutomation.swf file, located in the Bin directory of your Ranorex installation, to your web
server (where your .swf file is located) or where your AIR application is located.
4. Run your application in a supported browser (Internet Explorer, Firefox, C hrome, Safari)
5. If you run your Flash application from the local drive, add your output directory to the trusted locations of Flash
Player as follows:
1. Open following link
www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04a.html
2. Add your project output directory
If you are using Windows XP SP2, please also make sure that the Windows Update KB884020 is installed, which
resolves problems with the local network communication.
After restarting you Java application you should be able to use the Ranorex for your Java application under test.
1. C opy the "accessible" directory (and all its contents) from the Qt SDK (used to build the application
under test) installation folder to the folder of the automated application (e.g. “Program Files/Your-
Application/plugins”). If you do not have access to the Qt SDK which the Qt application is developed
with, please contact the developer of the application and request the "accessible" directory from him.
2. C reate a file called "qt.conf" (or append if the file already exists) in the root directory of the automated
application (e.g. "Program Files/Your-Application") with following content (copy and paste the
following two lines):
[Paths]
Plugins = plugins
The pictures below show the different object recognition for a MFC -based menu bar control before and after GDI
activation.
You can also add a process name to the GDI capture list by right-clicking on the parent form element of a control
in the Ranorex Spy tree.
Simply delete class or process names which have been added via the context menu from the text boxes shown
above.
.NET WinForms
.NET Silverlight
Flash/Flex Applications
Win32 Based Applications
Browser (Mozilla Firefox, Google C hrome, Apple Safari)
Image Related Automation or Validation
Geometry Related Issues
.NET WinForms
Ranorex failed to load the assemblies containing the definition of this control. UI element identification capabilities
for this control are limited. There might be several reasons for limited support of .NET WinForms based
applications or controls:
Reason #1:
The automating process (Ranorex executable) and the automated application (AUT) are not started with the same
security rights, i.e. not as the same Windows user.
Solution:
Reason #2:
Either the automating executable or the AUT are started from a network drive or encrypted folder and
consequently do not have the required security rights.
Solution:
Reason #3:
The controls that cannot be identified are implemented in a mixed-mode EXE file (not DLL). This can be the case
with some obfuscating applications or assembly merging utilities that create mixed-mode EXE files. The .NET
Framework does not support loading such mixed-mode executables in other processes and that's why Ranorex
cannot recognize controls implemented within them.
Solution:
As a workaround, you can try to automate the non-obfuscated version of your application.
Reason #4:
The controls that cannot be identified are implemented in an assembly that targets a particular
platform/processor and the automating executable targets a different platform/processor. This can cause
problems on 64 bit operating systems, since such assemblies cannot be loaded by the automating process.
Solution:
Try changing the "Target C PU" (Ranorex Studio) or "Platform Target" (Visual Studio) option in the automation
project settings to match the target of the automated application as described in this section. If you don't know
the target C PU/platform of the automated application, first try to change the option to "Any processor" or "Any
C PU", respectively, then try the remaining options.
Reason #5:
The .NET Framework 4.0 Extended package is needed but not installed. An indication for this problem typically is
that controls can correctly be identified by the standalone Ranorex Spy application, but not by the integrated
Page 180 of 247
Ranorex Spy or Recorder in Ranorex Studio.The application under test uses the .NET Framework 4.0 and you
may get Technology Limitation pop-ups saying that specific assemblies cannot be loaded.
Solution:
Either install the .NET Framework 4.0 Extended or if that is not possible always use the standalone Ranorex Spy
and Recorder tools instead of the integrated ones in Ranorex Studio.
Reason #6:
If the application under test is built with the .NET Framework 4.0, a <executableName>.exe.config file (where
<executableName> has to be replaced by the name of the Ranorex executable) needs to reside in the same
folder as the automating Ranorex executable and it needs to contain the configuration below.
Solution:
C reate and add an app.config file with the below content to your project. Make sure that after compiling and when
executing the executable there is a <executableName>.exe.config file in the same folder as the Ranorex
executable with following content:
<configuration>
<startup useLegacyV2RuntimeActivationPolicy="true">
<supportedRuntime version="v4.0"/>
<supportedRuntime version="v2.0.50727"/>
</startup>
</configuration>
.NET Silverlight
Ranorex is not able to access UI objects inside your Silverlight application.
Solution:
Please make sure that the Windowless property of your Silverlight application is set to 'False'.
Flash/Flex Applications
After activating the Flash/Flex Plug-In for your applciation using the instrumentation wizard Ranorex is still not
able to recognize Flash/Flex elements within your application.
Reason #1
The AllowScriptAccess parameter in the HTML code that loads a SWF file controls the ability to perform outbound
URL access from within the SWF file.
Solution:
Set this parameter inside the PARAM or EMBED tag to "always".
Reason #2
Your Flash/Flex application was instrumented twice using different versions of Ranorex Flash components.
Solution:
Ensure that only one of the recommended instrumentation approaches for Flash/Flex is used.
Reason #1:
The automating process is not being run with the required security permissions to access the process under test.
UI element identification capabilities for controls in that process are limited.
Solution:
The automating process (Ranorex executable) and the automated application (AUT) are not started with the same
security rights, i.e. not as the same Windows user. Ensure that both processes are started with the same rights.
Solution:
Reason #3:
The automating and the automated process do not have the same bit width and the 32/64 Bit Bridge is disabled.
UI element identification capabilities for controls in that process are limited.
Solution:
Solution:
Please make sure that you have installed and enabled the Ranorex Addon in your Mozilla browser. Please refer to
the Mozilla Firefox instrumentation wizard documentation for more information.
Google Chrome:
Solution:
Please make sure that you have installed and activated the Ranorex Extension in your Goggle browser. Please
refer to the Google C hrome instrumentation wizard documentation for more information.
Apple Safari:
Solution:
Please make sure that you have installed and activated the Ranorex Extension in your Apple browser. Please
refer to the Apple Safari instrumentation wizard documentation for more information.
Solution:
If you experience problems when making image based recordings, please enable asynchronous dispatching of
mouse and keyboard events using the Recorder's settings dialog.
Solution:
Set the "Use Ensure Visible" property of the corresponding repository items (and their parent folders) to "False"
as described in the chapter Repository Items Properties.
Adapters
Attributes
and Values
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
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 'C ontainer 1', which holds a button with text 'Button 1'.
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 chang the path value of a repository
item directly int the repository view. A more comfortable way to edit RanoreXPath is provided by the Ranorex Path Editor.
Attributes
/form identifies a top level application
/form[@title='Calculator'] identifies a top level application with the title 'C alculator'
/form[ identifies a top level application with the title 'C alculator' and an attribute of instance
@title='Calculator' and @instance='2'] with value two
/form[
identifies a top level application with the title 'C alculator' or by its process name
@title='Calculator' or @class='SciCalc']
/form/button identifies a button in the application
/form/button[2] identifies the second button in the application
/form/button[-2] identifies the second-to-last 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'
Functions
/form/table/row/cell[first()=‘True‘] identifies the first cell of a row
/form/table/row/cell[last()=‘True‘] identifies the last cell of a row
/form/table/row/cell[index()=2] identifies the second cell of a row
/form[x()>100 and y()>100] identifies a top level application with screen coordinates greater than 100
identifies a button with client coordinates (coordinates of an element relative to its
/form/button[cx()>10 and cy()>10]
parent) greater than 10
/form[width()>100 and height()>100] identifies a top level application with width and height greater than 100.
Each row in the table represents a user. The users attributes are mapped into separate cells.
<pre>/table/*/tr/td/a[@InnerText='Username']
</pre>
2. Select the corresponding checkbox with a relative path from the name (red highlighted)
<pre>/../../td/input[@type='checkbox']
</pre>
3. Get the full path to the checkbox by combining the two paths.
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\.'.
C haracter 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.
Page 184 of 247
() The parenthesis affects the order of pattern evaluation.
Ranorex adapters provide more convenience when creating automated tests. Here is an example: A Ranorex
Text adapter provides text box related properties like 'Text' or 'SelectionText'. In comparison to a simple Text
adapter, a Ranorex TreeItem adapter provides tree item specific properties and methods like expand or collapse.
Ranorex Spy shows all adapter related properties in the 'Overview' tab.
The section 'General' in Ranorex Spy shows the general properties which are available for any type of UI
element. All the other information within the 'Overview' tab is related to the type of adapter supported by the
element.
C#
view plain c opy to c lipboard print
// Create Text adapter from RanoreXPath
Text textBox = "/form[@title='Calculator']/text[@controlid='403']";
// Set text value of text box
textBox.TextValue = "12";
// Check on of the 'General' properties
if (textBox.Enabled)
Report.Info("Text is enabled");
VB.NET
view plain c opy to c lipboard print
' Create Text adapter from RanoreXPath
Dim textBox As Text = "/form[@title='Calculator']/text[@controlid='403']"
' Set text value of text box
textBox.TextValue = "12"
' Check on of the 'General' properties
If textBox.Enabled Then
Report.Info("Text is enabled")
End If
Page 187 of 247
The following example accesses properties of a Ranorex TreeItem adapter:
C#
view plain c opy to c lipboard print
// Create TreeItem adapter from RanoreXPath
TreeItem treeItem= "/form[@title='Documents and Settings']/*/*/*/*
/*/*/treeitem[@text='Documents and Settings']";
// Collapse and expand tree item
if (treeItem.Expanded)
treeItem.Collapse();
else
treeItem.Expand();
VB.NET
view plain c opy to c lipboard print
' Create TreeItem adapter from RanoreXPath
Dim treeItem As TreeItem = "/form[@title='Documents and
Settings']//treeitem[@text='Documents and Settings']"
' Collapse and expand tree item
If treeItem.Expanded Then
treeItem.Collapse()
Else
treeItem.Expand()
End If
As an example the Ranorex WinForms Plug-In is able to provide more information about a simple button in a .NET
application. This additional information is provided via an additional adapter called 'C ontrol'. The following
screenshots compare the information shown by Ranorex Spy for a Win32 and a WinForms button:
The C ontrol adapter, which is available for .NET WinForms applications, allows Ranorex to access more properties
in the application under test, like the background color or font size of the displayed text. Simply convert a
standard Button adapter to a WinForms C ontrol adapter as follows:
C#
view plain c opy to c lipboard print
// Create Button adapter with RanoreXPath
Ranorex.Button button= "/form[@controlname='TestedApp']
/button[@controlname='button1']";
// Convert Button adapter to Control adapter
Ranorex.Control winFormsButton = new Ranorex.Control(button);
// Call 'GetPropertyValue' method provided by the Control adapter
Color color = winFormsButton.GetPropertyValue<Color>("BackColor");
VB.NET
view plain c opy to c lipboard print
' Create Button adapter with RanoreXPath
Dim button As Ranorex.Button = "/form[@controlname='TestedApp']
/button[@controlname='button1']"
' Convert Button adapter to Control adapter
Dim winFormsButton As New Ranorex.Control(button)
' Call 'GetPropertyValue' method provided by the Control adapter
Dim color As Color = winFormsButton.GetPropertyValue(Of Color)("BackColor")
It is not required to work with Ranorex adapters. It's also possible to write automation code using Ranorex
Element instances (which are used internally by Ranorex adapters) - it's just more difficult.
Note: UI objects managed within Ranorex repositories always use Ranorex adapters.
Infrastructure
Getting Started
Record your Android test
Run your test on any Android device
Infrastructure
Before getting started with Android test automation, it’s necessary to make sure that the system under test (the
mobile devices) and the machine running the tests (where Ranorex is installed) are in the same network.
As the recording and executing of tests is processed via the network, there is no need for an USB connection
between the system under test and the machine running the test.
But it is recommended to have your system under test plugged into a power supply during test recording and
execution.
Getting Started
This quick start guide will show you how easy it is to record your Android test and execute the test on different
devices and Android languages.
Start your first recording by pressing the record button in Ranorex Recorder.
Next to starting a “Global Recording”, “Run an Application” or “Open a Browser” it is also possible to start a
“Mobile Recording”.
Add Device
Open the “Manage Device” dialog by pressing the Devices button from the Record Settings dialog.
If no devices have been added yet, the Install Services description will be shown.
Note: the QR code and description can be shown at any time by pressing the “Install Service” button.
By using the QR code with a bar code reader app or by entering the URL mentioned in the description, the
Ranorex Service app can be downloaded and installed on the mobile device.
After downloading and installing, the Ranorex Service app will be started on the device which can now be added
to the list of devices in the Manage Devices dialog by pressing the “Add” button.
If you would like to add an emulator or have problems with a device, have a look at the Manage Devices and the
Troubleshooting section.
As mentioned before, the Android app KeePassDroid is taken as an example how to automate mobile applications
using Ranorex. The APK file can be downloaded at http://keepassdroid.googlecode.com/files/KeePassDroid-
1.9.9.apk.
After choosing a device to deploy and an APK file to instrument, the process will be started by pressing the “Next”
button.
After the instrumentation of the APK file, it will be automatically deployed to the selected device.
To finish the instrumentation and deployment process, the installation has to be confirmed on the mobile device.
Confirm installation of
instrumented APK
By pressing the “Start” button, the instrumented app will be automatically started on the mobile device and a
notification on the desktop will inform the user, that actions will be recorded directly on the mobile device.
Record notification
During the recording process, the action table of the Ranorex Recorder will give a good overview over the
performed steps, as the table is updated live.
Note: The recommended way to add a value to a text box is to tap on the text box before typing.
Note: It’s recommended to wait a short period of time before operating on list elements after scrolling the list.
Note: It’s recommended to touch the text of a list element and not the empty space next to the text when
operating a list element.
During recording it’s possible to add validations using the “Validation” button. By pressing the button, a dialog will
open where the element which should be validated can be chosen.
After choosing an element, the “Validate Element” dialog will pop up. In this dialog, the attributes which should be
validated can be selected.
Additionally to recording actions, it’s also possible to add actions to the action table after the recording process.
This can be done by dragging a repository item to the action table and choosing the action which should be
performed from the menu.
After recording and adding actions manually, the action table might look something like the following.
Action #1 is a “Run Mobile App” action which starts the instrumented APK file on the selected device.
Action # 2 is a Touch Event on a button. There are 5 different kinds of touch events recognized by Ranorex:
Action # 4 is a “Set Value” action, which is typically used for keyboard input.
Action # 6 is a “Wait For Not Exists” action, which is useful when having for example an item indicating a loading
process and the automation should go ahead when the item has disappeared.
Action # 8 is a “Get Value” action, which can be used to write back an attribute value of a control to a variable for
further processing.
Action # 9 is a “Report” action, which is used to add information to the test report.
Action # 10 is a “Invoke Action” which performs a scroll action on a list control to its index “0”. “Invoke Actions”
directly call the corresponding method of the selected control.
Action # 11 is a “Mobile Key Press” action. “Mobile Key Press” actions simulate the physical buttons “Back” and
“Menu” of the mobile device.
Action # 12 is a “C lose Application” action. “C lose Application” actions stop the selected application on the mobile
device.
Note: Make sure to add a “C lose Application” action, when running your test on different devices, because if the
app will not be closed on the devices, the app on the first identified device will be automated.
Stop Recording
After performing the test on the mobile device, the recording process can to be stopped by pressing the “Stop”
button.
Stop recording
Run Test
After recording and altering the action table, the test can be executed on the mobile device by pressing the “Run”
button.
After doing so, make the “Device Display Name” of the “Run Mobile App” action in your recording variable.
After making the device variable, open the “Data Source” dialog of the test case holding your recording and add
a new simple data table holding the names of the devices you want to run the test on.
Have a look at Lesson 3: Data-Driven Testing if you want to learn more about the data-driven approach of
testing.
Now, the test suite is prepared for running the recording on different devices. After successfully running the test,
the test report should look something like the following.
Add a device
Add a device manually
Show device information
Add a device
The “Manage Device” dialog can be opened from the Devices pane or from the Record Settings dialog.
If no devices have been added yet, the Install Services description will be shown.
Note: the QR code and description can be shown at any time by pressing the “Install Service” button.
By using the QR code with a bar code reader app or by entering the URL mentioned in the description, the
Ranorex Service app can be downloaded and installed on the mobile device.
After downloading and installing, the Ranorex Service app will be started on the device, which can now be added
to the list of devices in the Manage Devices dialog by pressing the add button.
Add device
Note: To add an emulator, please type in "127.0.0.1" in the IP address field. (Please make sure that only one
emulator is running at the same time)
The IP address can be found within the service app on the device by pressing the “Details” button.
Details view
Devices can be disabled by pressing the “Disable” button. By disabling devices, they will not be available in
devices pane and “Record Settings” dialog until they are enabled again.
The name, IP address and port of a device can be changed by pressing the Edit button.
By pressing the “Remove” button, the selected device will be removed for the list of devices.
Pressing the Reconnect/Retry button will try to connect to the device over the network.
By moving your mouse over the device, a tooltip will appear, giving detailed information about the problem.
Make sure that the system under test (the mobile devices) and the machine running the tests (where
Ranorex is installed) are in the same network.
After changing Wi-Fi settings on the device, make sure to restart the device.
Try to increase the Discovery Timeout at the “Mobile” section in the “Plugins” tab of general settings.
Try to find out more about the connection problem by moving your mouse over the device in “Manage
Devices” dialog.
If you have more than one device from the same model, make sure to set unique device names for these
devices in the service app on the devices.
All open websites are shown as a single Dom node in the spy tree. In addition to standard browser hosted
applications, Ranorex is able to see embedded browser objects too (e.g. compiled help files). Additional each
tab item within a browser window is presented as a separate Dom node within the spy tree.
The web document and its HTML structure can be identified using RanoreXPath. Similar to XPath in HTML,
the RanoreXPath provides a simple search mechanism for finding single or multiple web elements within a web
page.
WebDocument Adapter
The WebDocument Adapter creates a representation of the complete web-site including all tags (e.g. the header
tag, body tag, etc.). Furthermore it offers useful ways to make your test scripts more effective.
C#
view plain c opy to c lipboard print
// Identify a web document by its title
WebDocument webDocument = "/dom[@caption='Ranorex Test Page']";
// Open a website
webDocument.Navigate("http://www.ranorex.com");
// Wait until the document is loaded
webDocument.WaitForDocumentLoaded();
// Execute a javascript code
webDocument.ExecuteScript("history.back();");
' Identify a web document by its title
Dim webDocument As WebDocument = "/dom[@caption='Ranorex Test Page']"
' Open a website
webDocument.Navigate("http://www.ranorex.com")
' Wait until the document is loaded
webDocument.WaitForDocumentLoaded()
' Execute a javascript code
webDocument.ExecuteScript("history.back();")
C#
view plain c opy to c lipboard print
// Start IE with a specific website
System.Diagnostics.Process.Start("iexplore.exe", "www.ranorex.com/web-testing-examples");
// Identify the webdocument by its title
WebDocument webDocument = "/dom[@caption='Ranorex Test Page']";
// Find a link by its link text (innertext)
ATag link = webDocument.FindSingle(".//a[@innertext='simple link']");
link.Click();
VB.NET
view plain c opy to c lipboard print
' Start IE with a specific website
System.Diagnostics.Process.Start("iexplore.exe", "www.ranorex.com/web-testing-examples")
' Identify the webdocument by its title
Dim webDocument As WebDocument = "/dom[@caption='Ranorex Test Page']"
' Find a link by its link text (innertext)
Dim link As ATag = webDocument.FindSingle(".//a[@innertext='simple link']")
link.Click()
Cross-Browser Testing
During the installation of Ranorex the setup package automatically installs add-ins for all supported browsers,
which enable the communication between the Ranorex Browser Plug-In and the specific browser. If you have
problems with instrumenting a specific browser use the Ranorex Instrumentation wizard as explained here.
C reating tests for Firefox does not differ to creating tests for Internet Explorer or any other supported browser.
All web UI elements are specified through RanoreXPath, which uses HTML attributes and values for identification.
For this reason a single web repository can be used for testing all supported types of web browsers. Learn more
about how to test multiple browsers with a test case based on one single repository introduced by our web testing
example project, which is part of the Ranorex setup package.
The Ranorex Automation library provides you with a property called "BrowserName" which tells you the current
browser of the web site under test:
C#
Page 206 of 247
view plain c opy to c lipboard print
// Click the OK button in popping up dialog of one of the supported browser
// If the current browser is Internet Explorer
if(webDocument.BrowserName == "IE")
{
Button okIE = "/form[@processname~'(iexplore|IEXPLORE)']//button[@text='OK']";
okIE.Click();
}
// If the current browser is Mozilla Firefox
else if(webDocument.BrowserName == "Mozilla")
{
Button okFF = "/form[@processname='firefox']//button[@text='OK']";
okFF.Click();
}
// If the current browser is Google Chrome
else if(webDocument.BrowserName == "Chrome")
{
Button okChrome = "/form[@processname='chrome']//button[@text='OK']";
okChrome.Click();
}
// If the current browser is Apple Safari
else if(webDocument.BrowserName == "Safari")
{
Button okSafari = "/form[@processname='Safari']//button[@text='OK']";
okSafari.Click();
}
VB.NET
view plain c opy to c lipboard print
' Click the OK button in popping up dialog of one of the supported browser
' If the current browser is Internet Explorer
If webDocument.BrowserName = "IE" Then
Dim okIE As Button = "/form[@processname~'(iexplore|IEXPLORE)']//button[@text='OK']"
okIE.Click()
' If the current browser is Mozilla Firefox
ElseIf webDocument.BrowserName = "Mozilla" Then
Dim okFF As Button = "/form[@processname='firefox']//button[@text='OK']"
okFF.Click()
End If
' If the current browser is Google Chrome
ElseIf webDocument.BrowserName = "Chrome" Then
Dim okChrome As Button = "/form[@processname='chrome']//button[@text='OK']"
okChrome.Click()
End If
' If the current browser is Apple Safari
ElseIf webDocument.BrowserName = "Safari" Then
Dim okSafari As Button = "/form[@processname='Safari']//button[@text='OK']"
okSafari.Click()
End If
C#
view plain c opy to c lipboard print
// Load repository
ProjectRepository repo = ProjectRepository.Instance;
// Open a website
repo.WebPage.Self.Navigate("http://www.ranorex.com");
// Wait until the document is loaded
repo.WebPage.Self.WaitForDocumentLoaded();
VB.NET
view plain c opy to c lipboard print
' Load repository
Dim repo As ProjectRepository = ProjectRepository.Instance
' Open a website
repo.WebPage.Self.Navigate("http://www.ranorex.com")
' Wait until the document is loaded
repo.WebPage.Self.WaitForDocumentLoaded()
Handling of AJAX
List elements of a table and set css style
Set inputs, tag attributes and perform a click without mouse
Execute javascript code
Handling of layer menus
The Ranorex web site provides a small page especially for web testing purposes:
www.ranorex.com/web-testing-examples/
All examples are available in the Web Test Sample Ranorex Studio and Visual Studio project located within
your installation folder (..\Samples\WebTestSample)
Handling of AJAX
C#
view plain c opy to c lipboard print
GlobalRepository repo = GlobalRepository.Instance;
WebDocument webDocument = repo.WebPage.Self;
// Fill out the AJAX form
InputTag input1 = webDocument.FindSingle(".//form[@id='ajax-form']/fieldset//input
[@name='value1']");
input1.EnsureVisible();
input1.Value = "Size";
InputTag input2 = webDocument.FindSingle(".//form[@id='ajax-form']/fieldset//input
[@name='value2']");
input2.Value = "Weight";
InputTag checkbox = webDocument.FindSingle(".//form[@id='ajax-form']/fieldset//input
[@name='checkbox2']");
checkbox.Checked = "true";
SelectTag selectColor = webDocument.FindSingle(".//form[@id='ajax-form']/fieldset//select
[@name='color2']");
selectColor.TagValue = "blue";
// Submit data
InputTag submit = webDocument.FindSingle(".//form[@id='ajax-form']//input[@id='submit-
ajax']");
submit.Click();
Page 209 of 247
// Wait for the ajax request for max 10 seconds (10000 milliseconds)
PreTag result = webDocument.FindSingle(".//div[@id='ajax_response']/div/pre", 10000);
VB.NET
view plain c opy to c lipboard print
Dim repo As GlobalRepository = GlobalRepository.Instance
Dim webDocument As WebDocument = repo.WebPage.Self
' Fill out the AJAX form
Dim input1 As InputTag = webDocument.FindSingle(".//form[@id='ajax-form']/fieldset//input
[@name='value1']")
input1.EnsureVisible()
input1.Value = "Size"
Dim input2 As InputTag = webDocument.FindSingle(".//form[@id='ajax-form']/fieldset//input
[@name='value2']")
input2.Value = "Weight"
Dim checkbox As InputTag = webDocument.FindSingle(".//form[@id='ajax-form']/fieldset//input
[@name='checkbox2']")
checkbox.Checked = "true"
Dim selectColor As SelectTag = webDocument.FindSingle(".//form[@id='ajax-
form']/fieldset//select[@name='color2']")
selectColor.TagValue = "blue"
' Submit data
Dim submit As InputTag = webDocument.FindSingle(".//form[@id='ajax-form']//input
[@id='submit-ajax']")
submit.Click()
' Wait for the ajax request for max 10 seconds (10000 milliseconds)
Dim result As PreTag = webDocument.FindSingle(".//div
[@id='ajax_response']/div/pre", 10000)
C#
view plain c opy to c lipboard print
GlobalRepository repo = GlobalRepository.Instance;
WebDocument webDocument = repo.WebPage.Self;
// List all elements of a table
foreach (TrTag row in repo.WebPage.DivTagContent.TableTagSimpletable.Find("./tbody/tr"))
{
string rowInfo = "";
TdTag rowNameCell = row.FindSingle("./td[2]");
rowInfo += "Row index: " + rowNameCell.PreviousSibling.InnerText + ", ";
rowInfo += "Row name: " + rowNameCell.InnerText + ", ";
rowInfo += "Row value: " + rowNameCell.NextSibling.InnerText + ", ";
// Get all cells from the row
rowInfo += "All Cells: ";
foreach (TdTag cell in row.Find("./td"))
{
rowInfo += cell.InnerText + ", ";
// Move the mouse to each cell element
cell.MoveTo();
// Set css style
cell.SetStyle("background-color","#33ff00");
}
Report.Info(rowInfo);
}
VB.NET
Page 210 of 247
view plain c opy to c lipboard print
Dim repo As GlobalRepository = GlobalRepository.Instance
Dim webDocument As WebDocument = repo.WebPage.Self
' List all elements of a table
For Each row As TrTag In repo.WebPage.DivTagContent.TableTagSimpletable.Find("./tbody/tr")
Dim rowInfo As String = ""
Dim rowNameCell As TdTag = row.FindSingle("./td[2]")
rowInfo += "Row index: " & rowNameCell.PreviousSibling.InnerText & ", "
rowInfo += "Row name: " & rowNameCell.InnerText & ", "
rowInfo += "Row value: " & rowNameCell.NextSibling.InnerText & ", "
' Get all cells from the row
rowInfo += "All Cells: "
For Each cell As TdTag In row.Find("./td")
rowInfo += cell.InnerText & ", "
' Move the mouse to each cell element
cell.MoveTo()
' Set css style
cell.SetStyle("background-color", "#33ff00")
Next
Report.Info(rowInfo)
Next
C#
view plain c opy to c lipboard print
// Use mouse and keyboard to set Name
repo.WebPage.TestForm.InputTagTestname.Click();
Keyboard.Press("Test Name");
// Set email address directly via 'Value'
repo.WebPage.TestForm.InputTagTestemail.Value = "test@ranorex.com";
// Open calendar form
repo.WebPage.TestForm.ButtonTagCalendar.Click();
// Select the 22th of the current month
repo.WebPage.TdTag_22nd.Click();
// Select each item of list box
foreach (OptionTag option in repo.WebPage.TestForm.SelectTagTestmultiple.Find(".//option"))
{
option["selected"] = "selected";
}
// Perform a click without moving the mouse to the button
repo.WebPage.TestForm.InputTagSubmit.PerformClick();
VB.NET
view plain c opy to c lipboard print
' Use mouse and keyboard to set Name
repo.WebPage.TestForm.InputTagTestname.Click()
Keyboard.Press("Test Name")
' Set email address directly via 'Value'
repo.WebPage.TestForm.InputTagTestemail.Value = "test@ranorex.com"
' Open calendar form
repo.WebPage.TestForm.ButtonTagCalendar.Click()
' Select the 22th of the current month
repo.WebPage.TdTag_22nd.Click()
' Select each item of list box
For Each [option] As OptionTag In repo.WebPage.TestForm.SelectTagTestmultiple.Find
Page 211 of 247
(".//option")
[option]("selected") = "selected"
Next
' Perform a click without moving the mouse to the button
repo.WebPage.TestForm.InputTagSubmit.PerformClick()
C#
view plain c opy to c lipboard print
webDocument.ExecuteScript("history.back();");
VB.NET
view plain c opy to c lipboard print
webDocument.ExecuteScript("history.back();")
C#
view plain c opy to c lipboard print
WebDocument webDocument = "/dom[@caption='Ranorex Test Page']";
DivTag topMenuDiv = webDocument.FindSingle(".//div[@id='top-menu']");
// Bring the main menu to the front
topMenuDiv.EnsureVisible();
// Automating a dropdown menu
foreach (LiTag item in topMenuDiv.Find(".//li[@visible='true']"))
{
Mouse.MoveTo(item);
// Move the mouse to each submenu item
foreach (LiTag subitem in item.Find(".//li[@visible='true']"))
Mouse.MoveTo(subitem);
}
VB.NET
view plain c opy to c lipboard print
Dim webDocument As WebDocument = "/dom[@caption='Ranorex Test Page']"
Dim topMenuDiv As DivTag = webDocument.FindSingle(".//div[@id='top-menu']")
' Bring the main menu to the front
topMenuDiv.EnsureVisible()
' Automating a dropdown menu
For Each item As LiTag In topMenuDiv.Find(".//li[@visible='true']")
Mouse.MoveTo(item)
' Move the mouse to each submenu item
For Each subitem As LiTag In item.Find(".//li[@visible='true']")
Mouse.MoveTo(subitem)
Next
Next
C reate
Build
Run
Adding New Items
Solution Explorer
Debugging
C ode C ompletion
C ode C onversion
C ode Navigation
C ode Generation
Refactoring
A project holding a Ranorex Test Suite which may contain recordings and code modules. This might be your first choice when starting with
Ranorex Test Suite
Ranorex Studio
Ranorex Test Suite Module
A project holding recordings and code modules which can be shared and reused
Library
Ranorex C lass Library A project for creating classes which are used in other applications
Ranorex C onsole Application A project that creates a command line application
Ranorex Windows Application A project that creates an application with a windows interface
After choosing a project type and a name for the project, a project will be created in the solution and Ranorex Studio is ready for you to start developing.
Ranorex Studio
“Build” Menu
Within this menu, either the whole solution, or a specific project in the solution can be built, rebuilt or cleaned.
“Output” window
“Errors” window
Project specific settings can be defined in the ”Project Options” dialog, which can be accessed from the “Project”
menu.
To name some of these settings, you can set the name or the type of the generated assembly in the “Application”
tab, for example.
You can also set the target C PU and framework or the output path in the “C ompiling” tab.
“Debug” menu
C ode Module,
Recording Module and
Repository
C lass,
Interface,
Struct and
Form
After adding a Form it’s possible to use a forms designer which allows to visually design the UI as described
explicitly in the article “Visually Designing Forms” posted at SharpDevelop C ommunity Blog.
For example adding folders to organize projects by separating recording modules from user code modules.
Additionally you are able to delete unused files. This feature is useful especially to delete outdated log files.
Alternatively, unused files can be excluded from the project without deleting them from the solution.
by clicking on the left margin at the line you want to set it, or
by putting the cursor to the line you want to add a breakpoint, open the “Debug” menu an choose “Toggle Breakpoint”.
By setting a breakpoint, a red circle will be added at the margin and the line of code will be highlighted red. The breakpoint can be removed in the same way as it has been
added.
After setting a breakpoint the debugger can be started by executing your application as described in the chapter Run.
Note: To run an application with debugger, it’s necessary to not choose “Run without Debugger” from menu.
The application will start and Ranorex Studio will switch to the “Debug Layout” which causes the following menu items to be available from “Debugger” menu and toolbar:
Step Over Executes the statement on the current line but it will not step into
Step Into Executes the statement on the current line and stops at the first line of code inside the method
Step Out Finishes executing the current method and returns to its parent method
To skip several lines of code and continue debugging on a specific line, the context menu item “Set C urrent Statement” can be chosen by right-clicking on the line and
choosing “Set C urrent Statement” from the context menu.
In paused mode, the actual state of the individual objects can be diagnosed.
The following windows can be activated in the sub-menu “Debug” which is part of the “View” menu.
Note: If Visual Studio 2010 is installed on the machine running Ranorex Studio, debugging might be slow. To overcome this issue it is recommended to search the key
“LowLevelHooksTimeout” in the registry and delete all occurrences.
Further details about how this works can be found in the article C ode C ompletion posted at SharpDevelop
C ommunity Blog.
This can be performed by right-clicking on the specific element in the Project Explorer and choosing “C onvert”
from the context menu.
Note: The sample works with both Microsoft Visual Studio 2005 and 2008.
C#
view plain c opy to c lipboard print
VB.NET
view plain c opy to c lipboard print
Imports System.Drawing
Imports Ranorex
Mark the main thread with the attribute [STAThread] and change the return value of the Main function to int.
C#
view plain c opy to c lipboard print
[STAThread]
static int Main(string[] args)
VB.NET
view plain c opy to c lipboard print
<STAThread> _
Public Shared Function Main(args As String()) As Integer
Add the following code lines to the 'Main' routine of the class 'Program':
C#
view plain c opy to c lipboard print
int error = 0;
try
{
System.Diagnostics.Process.Start("calc.exe");
Form form = Host.Local.FindChild<Ranorex.Form>("Calculator");
form.Activate();
Button button = form.FindSingle<Ranorex.Button>(".//button[@controlid='132']");
button.Click();
button = form.FindSingle<Ranorex.Button>(".//button[@controlid='92']");
button.Click();
button = form.FindSingle<Ranorex.Button>(".//button[@controlid='133']");
button.Click();
button = form.FindSingle<Ranorex.Button>(".//button[@controlid='121']");
button.Click();
}
}
catch (RanorexException e)
{
Console.WriteLine(e.ToString());
error = -1;
}
return error;
VB.NET
view plain c opy to c lipboard print
Dim returnError As Integer = 0
Page 231 of 247
Try
System.Diagnostics.Process.Start("calc.exe")
Dim form As Form = Host.Local.FindChild(Of Ranorex.Form)("Calculator")
form.Activate()
Dim button As Button = form.FindSingle(Of Ranorex.Button)(".//button[@controlid='132']")
button.Click()
button = form.FindSingle(Of Ranorex.Button)(".//button[@controlid='92']")
button.Click()
button = form.FindSingle(Of Ranorex.Button)(".//button[@controlid='133']")
button.Click()
button = form.FindSingle(Of Ranorex.Button)(".//button[@controlid='121']")
button.Click()
Catch e As RanorexException
Console.WriteLine(e.ToString())
returnError = -1
End Try
Return returnError
All versions (32 and 64 bit, except those for Itanium-based systems) of the following operating systems are
supported by Ranorex:
Software Prerequisites
The following software prerequisites are required to run all Ranorex components (Runtime, Spy, Recorder,
License Server). All needed prerequisites are usually automatically installed when running the Ranorex setup:
Additionally, for running Ranorex Studio the following prerequisites are required:
Hardware Requirements
The hardware requirements depend on the version of the .NET Framework that needs to be installed for the
respective Ranorex package. Ranorex (Runtime, Spy, Recorder, License Server) requires at least the .NET
Framework 2.0 to be installed, Ranorex Studio requires the .NET Framework 3.5. C onsequently:
The minimum system requirements for running Ranorex (Runtime, Spy, Recorder, License Server) are the same
as those for the .NET Framework 2.0:
http://msdn.microsoft.com/en-us/library/ms229070.aspx
The minimum system requirements for running Ranorex Studio are the same as those for .NET Framework 3.5:
http://msdn.microsoft.com/en-us/library/bb882520.aspx
If you disable the bit bridge feature (not recommended!) or your Ranorex version does not support
the bit bridge (versions prior to V2.3), follow these guidelines to make 32/64 bit automation
interoperable:
On 64 bit versions of Windows processes may run using 64 bit or 32 bit (also called “x86”) architecture.
Applications that are started as 32 bit processes are marked with “*32” in the Windows Task Manager, all others
use the 64 bit architecture.
Ranorex can as well run as a 32 bit or 64 bit process, both versions are included in the setup. In general, one
should use the Ranorex version that matches the bit architecture of the automated application. I.e. if you
automate a 32 bit application, use "Ranorex Spy (32bit)" (formerly "Ranorex Spy (x86)") and "Ranorex Recorder
(32bit)" (formerly "Ranorex Recorder (x86)"), otherwise use "Ranorex Spy" and "Ranorex Recorder" (64 bit
versions).
When you compile your own Ranorex executables, be sure to specify the right target architecture in your project
settings. In Ranorex Studio this setting is on the “C ompiling” tab in the project properties. .NET applications are
by default started as 64 bit processes on 64 bit operating systems unless the target C PU is explicitly set to the 32
bit (x86) architecture. C onsequently, set the “Target C PU” property to “Any processor” for automating 64 bit
applications and to “32-bit Intel-compatible processor” for 32 bit applications.
The only way to automate using the Remote Desktop window to work coordinate based or with image
comparison. This is not recommended by Ranorex because minimal variances in your system will make your
tests fail.
To guarantee successfully testing on remote machines, you have to install and start all Ranorex Tools you need
on the remotely connected machine.
Also make sure that the screensaver is not activated on your remotely connected machine as the screensaver
will also lock the Remote Desktop’s screen.
As a workaround, you can set up one machine having all of your Remote Desktop windows opened. This machine
does not do any automation. And while your tests are running on the different Remote Desktops – with the client
windows opened on the mentioned machine – you can lock the desktop on this machine. While your client
desktop is locked, the Remote Desktop sessions will remain opened and your test will continue.
An alternative to RDP is using VNC or the VMWare Remote C onsole as these tools will not lock the screen when
closing or minimizing the remote client window.
If you want to disable the input for the whole test cycle, you should set
C#
view plain c opy to c lipboard print
Keyboard.Enabled = false;
and
Mouse.Enabled = false;
But again be careful when using these properties because when you set both to false you cannot abort the test
without an AbortKey set.
So also set
C#
view plain c opy to c lipboard print
Keyboard.AbortKey = System.Windows.Forms.Keys.Pause;
in Program.cs to abort the test if something unexpected (e.g. an endless loop) happens.
You can also use this technique for one recording only. In this case you have to enable/disable the mouse and
keyboard controls in user code directly before executing specific actions. As always, don't forget to enable
controls again at the end of your recording and to set an AbortKey.
Please also make sure that you have activated the same windows scheme since your application under test might
be displayed differently when having different schemes activated.
Installation Packages
Installation C ommand Line Arguments
Install Ranorex License
Installation Packages
Ranorex uses the Microsoft/Windows Installer (MSI) for its setup. C onsequently, all standard MSI command line
arguments can be used. The command line arguments work both with the self-extracting zip file ("Ranorex-
x.x.x.exe") and the "setup.exe" and "Ranorex-x.x.x.x.msi" files contained in the "Ranorex-x.x.x.zip" file.
System administrators may use the Ranorex MSI package for installation. You can download the "Ranorex-
x.x.x.zip" containing the MSI package from our homepage; the download link is the same as for the self-
extracting zip file ("Ranorex-x.x.x.exe"). Just replace the file ending "exe" with "zip".
When installing Ranorex using the MSI package you have to make sure that all Ranorex prerequisites are
installed before executing the MSI package (please see the "README.txt" included in the ZIP archive or the
Ranorex system requirements). If you are unsure, please use the "setup.exe" or self-extracting zip file "Ranorex-
x.x.x.exe" to start the installation, which will also install all required prerequisites.
If you do not want to install all Ranorex features you can (de)select these features using the command line
options "ADDLOC AL" and "REMOVE".
For example, the following command line will install all Ranorex components except for Ranorex Studio:
Possible feature names used as parameter to ADDLOC AL or REMOVE (separated by commas) are:
For more installation options see the help for the MsiExec program by typing ("/v" is needed for the "*.exe" files):
msiexec /help
or: setup /v /help
or: Ranorex-x.x.x.exe /v /help
If you’d like to install a floating license you have to copy the file Ranorex3_Server.lic (for Ranreox3.x
installations) or Ranorex2_Server.lic (for Ranorex 2.x installations) into the folder “%ALLUSERSPROFILE%” by
using the "XC OPY" command in a batch file. The file will be created when you first install a License Server license
Page 239 of 247
on a Ranorex C lient. Just search for that file on a client machine running a floating license.
If you’d like to install a node locked license you have to generate a license file. The web address used to
authenticate the license key is part of the licensing email delivered after purchasing licenses. Simply open a
browser, navigate to the authentication page and enter your license key and the machine's host name into the
respective fields. After clicking the 'Authenticate' button you will be able to download the license file. Rename the
downloaded file to Ranorex3.lic (for Ranreox3.x installations) or Ranorex2.lic (for Ranorex 2.x installations) and
copy it to the folder “%ALLUSERSPROFILE%” by using the "XC OPY" command in a batch file.
The node locked license type is bound to the machine's host name. After registration each license can be used
perpetually on the registered machine. A floating user license can be shared between different machines, but can
only be used by one machine (and user) at a time.
Both license types are available for Ranorex Runtime, Professional, and Premium Edition.
License Registration
In order to register a Ranorex license, start the Ranorex Licensing tool, which is available in the Ranorex start
menu folder.
Note: The "Transfer License" button is used to prepare your license for transferring from one machine to
another.
The web site adress used to authenticate the license key is part of the licensing email delivered after purchasing
licenses. Simply open a browser and navigate to the authentication page. Fill in your license key and the
machine's host name. After clicking the 'Authenticate' button you'll be able to download the license file. Load the
downloaded file within the Ranorex licensing tool in order to finish the license installation process on the target
machine.
Note: To prevent firewalls from blocking communication between license server and client, it is required to open
port 7266 for TC P and UDP access on the server.
Note: By installing a Ranorex license server it's required to use a Ranorex license server installation package
which is at least as actual as your Ranorex client installation.
Open the Ranorex license server configuration tool. Add the floating license keys to the text box and press
'Install'. These licenses are now ready to use.
Note: It is recommended to have an internet connection available in order to install a new license.
If there is no internet connection available authenticate the floating license using the license authentication web
site. The web site adress used to authenticate the license key is part of the licensing email delivered
after purchasing licenses. Simply open a browser and navigate to the authentication page. Fill in your license key
and the machine's host name. After clicking the 'Authenticate' button you'll be able to download the license file.
Load the downloaded file within the Ranorex licensing tool in order to finish the license installation process on the
target machine.
In order to use an installed floating license, open the Ranorex license tool on the client and select the option "Use
License Server".
Press the button 'Detect' to request a list of the currently available license servers within the local network.
The license type specifies which license (Runtime, Professional, Premium) should be used on the client. By
selecting 'Auto', the client automatically requests the appropriate license. In case of running Ranorex tests
without starting any Ranorex tool, only a Runtime floating license will be used. When starting Ranorex Spy tool a
Professional floating license will be leased on the server. After pressing the 'Install' button the client is assigned to
the selected license type. To switch the currently installed license type, simply select another one from the list
and click 'Install' again.
Every time a Ranorex test, a Ranorex tool, or Ranorex Studio is started the client sends a license request to the
server. If the type of the required license is available, it will be assigned to the requesting client. By closing
Ranorex Studio or finishing a test run the license will be automatically released and can then be used by other
clients.
Is it possible to run the same Ranorex test code on Vista and XP?
Yes. All identification information is stored within a RanoreXPath expression and is therefore separated from the
test automation code. The following RanoreXPath expression finds a button both on Windows XP and on Windows
Vista:
The RanoreXPath searches for a button, whether it contains the text '&No' or ''Do&n't Save'.
A general description of how to create data driven test cases can be found here:
1. Search timeout: Each element and each folder stored within the objects repository defines is it's own
timeout used for search. In many cases it is required to wait for a dialog before continuing automation.
Use the 'SearchTimeout' property to define the maximum time to search for the specified element.
2. Wrong RanoreXPath: Start the application under test and make sure that the relevant GUI object is
visible. C heck the object's RanoreXPath within the repository browser using the 'Highlight Element' context
menu item to see if Ranorex can find the element. Open Ranorex Spy to track the specified GUI object
again. C ompare the absolute path, shown within the object repositorie's property grid, with the given
RanoreXPath provided by Ranorex Spy. If the given path by Ranorex Spy differs from the path
represented by the repository use the path from Spy to the repository.
What shall I do with unexpected dialogs and popup windows during test
automation?
Ranorex recognizes and specifies whether an application still has the top level characteristic or not. In case of
totally unexpected dialogs, the Ranorex.Report class provides a simple way to log screen shots of the current
desktop status. Read more about how to handle popup dialogs within Ranorex test auotmation code:
http://www.ranorex.com/support/user-guide-20/test-automation-code-examples.html#c3328
What are the system requirements for developing and running Ranorex
Page 246 of 247
tests?
The following link to our online documentation shows what is needed to develop or to simply run Ranorex tests.
C lick here ...