Beruflich Dokumente
Kultur Dokumente
Ranorex
Test Automation Guide
Based on version 6.1
Copyright 2016
Ranorex GmbH
Created on: August 31, 2016
Ranorex Version: 6.1
Authors:
Roland Enzinger, Martin Fahrenberger,
Christoph Preschern, Christina Reisinger and Tobias Walter
Special Thanks to:
Michael Gissing, Alexander Hoisl
Contents
Ranorex Studio - The Layout 1
Studio Start Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Working Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
#1 - Projects View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
#2 - Module Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
#3 - File View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
I
Using Repository within Code Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Accessing Screen Shots within Code Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Using Variables with Code Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Using Code Modules within Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Remote 252
Ranorex Remote at a glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
What to find where? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Ranorex Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Install and set up Ranorex Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Configure Ranorex Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Remote Pad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Adding Ranorex Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Agent List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Execute tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Run History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Remote System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Remote Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Remote FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
II
Advanced Validation - Clipboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Advanced Validation - Whole Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Advanced Validation - Whole Table in Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Advanced Validation - File (text-based) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Advanced Validation - File (non text-based, binary) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Advanced Validation - Database (Single Field) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Advanced Validation - Database (Whole Table) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Advanced Validation - XML code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
RanoreXPath 390
RanoreXPath Syntax Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Result Set Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Advanced RanoreXPath Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
RanoreXPath with Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
III
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Record and Run an Android Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Manage Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Non-UI Testing on Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Automation of System Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Run Your Test on Any Android Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Testing of Mobile Websites on Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
Instrumentation with Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
Add Device with Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Testing of Android Wear Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Integration 558
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
Continuous Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
Test Management and Application Lifecycle tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
Source Control / Revision Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
IV
Create a new Visual Studio project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
Add Ranorex core assemblies as references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
Write some Ranorex automation code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
Licensing 599
License Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
Installing a Node Locked License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
Installing a Floating License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601
Uninstall License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
Transfer Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
FAQ 608
How does Ranorex identify UI elements? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
Is it possible to run the same Ranorex test code on Vista and XP? . . . . . . . . . . . . . . . . . . . . . . 608
Is it required to use RanoreXPath for test automation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
Does Ranorex support data driven testing? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
How can I speed up my Excel-based data connector? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
What to do when items cant be found during Ranorex test execution? . . . . . . . . . . . . . . . . . . . . 609
Is it possible to extend recordings with user specified code actions? . . . . . . . . . . . . . . . . . . . . . . 609
What is the difference between Adapter and Element? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Is it possible to trigger Ranorex tests from an existing test or build environment? . . . . . . . . . . . . . . 610
Can I run my tests on machines where I am not allowed to install Ranorex? . . . . . . . . . . . . . . . . . 610
Can I use Ranorex libraries within Visual Studio? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
What shall I do with unexpected dialogs and popup windows during test automation? . . . . . . . . . . . . 610
Is it possible to test Silverlight applications with Ranorex? . . . . . . . . . . . . . . . . . . . . . . . . . . 610
Is it possible to automate a webpage without moving the mouse pointer? . . . . . . . . . . . . . . . . . . 610
V
What are the system requirements for developing and running Ranorex tests? . . . . . . . . . . . . . . . . 610
Are there known incompatibilities with other software? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611
VI
Ranorex Studio - The Layout
1
Ranorex Studio - The Layout
In Ranorex Studio, several product samples are available on the startpage. Studying them more closely you can learn
how to create automated tests for desktop, web, and mobile applications. Additionally a cross-platform sample is
available performing tests on all mentioned platforms in one test scenario.
To access these samples move the mouse pointer over the button Samples. This move lets a container pop up
providing descriptions and links to the samples (see screenshot below).
2
Ranorex Studio - The Layout
Move your mouse to any of the presented samples on desktop, web, mobile or cross-platform to get more details on
the product samples.
3
Ranorex Studio - The Layout
Figure 4
Sample on Desktop
4
Ranorex Studio - The Layout
Figure 5
Sample in Web
This sample performs automated tests in the online blog tool WordPress.
Learn something about: #module library #popup watcher #project organization #report screenshot #validation
#web testing #handling flyout menu #setup/teardown regions #data binding
Figure 6
This samples for Android and iOS perform automated tests in the mobile app KeePass.
Learn something about: #mobile testing #android #ios #deploy mobile app #module groups #usercode actions
#setup/teardown regions #data connectors #arguments
Cross-Platform sample
This sample performs automated tests in desktop, web, and mobile applications.
Learn something about: #cross-platform test #end2end test #ios #android #deploy mobile app #module library
#project organization #popup watcher #web testing #mobile web testing #setup/teardown regions #data binding
Working Environment
Before you start creating your first test case with Ranorex Studio you should know about the main views and layout
of Ranorex Studio.
5
Ranorex Studio - The Layout
Screencast: You can find an introductory screencast (Quick Start with Ranorex Test Automation) here:
http://youtu.be/0S YC7uwI-s. At the very beginning of the video youll learn the different views offered by
Ranorex Studio.
#1 - Projects View
A Ranorex Studio project is based on files and uses the same project file format as Microsoft Visual Studio 2008/2010.
The project view shows all files and references currently associated with the project. A Ranorex Studio project can
have the following type of items:
The project view is mainly used to add new items like Lesson 5: Ranorex Recorder, Lesson 6: UI Mapping with
Ranorex Repository, Module Groups, or Lesson 7: Code Modules.
6
Ranorex Studio - The Layout
#2 - Module Browser
The Module Browser view lists all available modules (Lesson 7: Code Modules & Lesson 5: Ranorex Recorder) based
on the projects 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 projects view to group modules. In order to find already existing
modules use the module browsers 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
opened in the Studios file view. This view is mainly used for the actions shown below.
7
Ranorex Studio - The Layout
8
Ranorex Studio - The Layout
9
Ranorex Studio - The Layout
10
Ranorex Studio - The Layout
11
Ranorex Studio - The Layout
12
Lesson 1: Getting Started
Recording a Test
Screencast: The screencast Quick Start with Ranorex Test Automation gives a short introduction
to the Ranorex Recorder. You can jump directly to the noted position in the video by clicking http:
//youtu.be/0S YC7uwI-s#t=1m8s.
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.
13
Lesson 1: Getting Started
Since version 3.3, KeePass is included with Ranorex Studio along with a sample database file.
On the start screen of Ranorex Studio youll 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 Cases.
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. Click the New Test Solution. . .
button to create a blank test suite project.
14
Lesson 1: Getting Started
Figure 15: Ranorex Studio Start Page - creating a new test solution
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.
Note: Because of possible performance and security impacts, projects should not reside on a network drive
(neither should Ranorex itself be installed on a network drive). Its recommended to use a version control
system (VCS) instead.
Click the Create button and a new test suite project opens.
15
Lesson 1: Getting Started
Figure 17: New Ranorex Test Suite containing one test case using an empty recording
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.
16
Lesson 1: Getting Started
Note: Its recommended to copy the KeePass application folder from the sample directory
within the Ranorex installation folder (<Ranorex Installation Folder>\Samples\Desktop\KeePass Sam-
ple\KeePassTestSuite\KeePass) to your projects folder as by default you do not have write access to the
program folder which is necessary to save the database handled by KeePass.
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
17
Lesson 1: Getting Started
Figure 19: Open project folder in explorer to copy the sample application to the project folder
18
Lesson 1: Getting Started
Click the Record button in order to start. The Recorder assists you in preparing the application under test. Choose
Desktop as technology and click on Add app to add KeePass to the list of applications under test.
Click on Record in order to record the test. The KeePass application opens and the Ranorex Recorder starts running.
19
Lesson 1: Getting Started
Note: You will notice that a red border will be shown when moving the mouse over a UI element indicating
which element is taken for automation. The red border will assist you during the recording process. You can
en-/disable this feature in the Recorder Settings Dialog.
Click on the text field next to the Master Password check box
20
Lesson 1: Getting Started
Figure 25: KeePass application with sub menu Edit (Menu item Add Entry is selected)
21
Lesson 1: Getting Started
Type in demo123
Click on OK button
22
Lesson 1: Getting Started
23
Lesson 1: Getting Started
24
Lesson 1: Getting Started
After adding a new password entry, a new row is added to the KeePass grid holding the recently entered item. Click
the Validate button within the Recording toolbar to check whether the entry appears in the grid. Move the mouse
pointer to the grid (i.e. the first cell) and wait a moment until the underlying UI element is highlighted.
At the first step of the validation you can choose the UI element you want to validate. Verify that the correct element
is selected and click on the Next button. At the second step, all available attributes for the given UI element to
check are shown. Just click the OK button in order to accept the preselected Text attribute.
25
Lesson 1: Getting Started
26
Lesson 1: Getting Started
27
Lesson 1: Getting Started
In order to finish the recording scenario select the added item within the data grid and delete it from the list by
pressing the DEL button on your keyboard.
Finally press the save button in the toolbar and close the application by clicking the close button.
Figure 32: Screenshot indicating the save button in the tool bar
Stop the recording by pressing the Stop button in the recorder tool bar.
28
Lesson 1: Getting Started
You can read more about different action types within Ranorex Recorder in Lesson 5: Ranorex Recorder - Additional
Editing Options.
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.
29
Lesson 1: Getting Started
In order to force an error as shown in the picture above, simply modify the expected value used in the validation step
of the recording (e.g. Typo3Demo instead of WordPressDemo).
Figure 37: Force an error by changing the expected value of the validation step
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.
30
Lesson 1: Getting Started
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. In short, it is best to copy the complete output folder (e.g. bin/debug) to the
target machine.
Figure 38: MyFirstTestProject.exe located within the build folder of the project
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.
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.
31
Lesson 2: Ranorex Modules - Test Actions
The ease of recording user actions encourages one to record all test cases without thinking about reusability. But in
the long run, this could increase the effort in test automation maintenance. For this reason you should separate a
recording into smaller reusable recording modules as suggested by the keyword driven methodology. In the following
section you will learn how to separate existing recordings into smaller pieces to be reused by other test cases.
Screencast: The screencast Ranorex Modules Test Automation Actions provides a short introduction to
preparing recorded actions for reusability by extracting reusable Ranorex Modules. This screencast can be
found at http://youtu.be/GrrKnf8cQ2g
Identifying Modules
In your first recording, you did the following from a keyword driven perspective:
Logged in
In order to split recordings into smaller automation modules, select related actions and use the context menu item
Move to new Recording Module. Within the underlying recording, the three actions performing 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.
32
Lesson 2: Ranorex Modules - Test Actions
Then, select and move all items used to add a new entry to the database to a new recording named AddEntry.rxrec.
Repeat the previous steps to create modules for ValidateEntry, DeleteEntry, SaveDB and for CloseSUT.
Also rename the initial recording file (with only one recorded item left for starting the application) from Record-
ing1.rxrec to StartSUT.rxrec. In the end you should have seven separate 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.
Figure 41: Use the drag and drop feature to specify your test case within the test suite view
When having a huge amount of different modules you can use the search functionality of the Ranorex Module Browser
which searches through the module name as well as the modules XmlDoc Summary. The XmlDoc Summary can be
set in the properties of the module. You can open the properties by right-clicking a module in the Ranorex Module
Browser and choosing Properties in the context menu.
33
Lesson 2: Ranorex Modules - Test Actions
Note: When you are going to use the XmlDoc Summary, be sure to enable XML documentation creation
in your project settings. In Ranorex Studio this setting can be found in the Compiling tab in the project
properties.
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.
34
Lesson 3: Data-Driven Testing
Screencast: There is a screencast called Data Driven Test Automation with Ranorex which might be
useful as you get a quick overview of how to get started with using external data sources to drive Ranorex
test cases: http://youtu.be/TRQy2Jl79-U
When you test an application it might be necessary to run the same test with different input data. Next youll learn
about:
Title (WordPressDemo)
Username (admin)
Password (demo123)
Expires (1 Year)
IconIndex (1)
All these input actions are done within the AddEntry 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.
35
Lesson 3: Data-Driven Testing
Figure 43: Create a new variable for a key sequence action item
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 value (1 week, 1 year. . . )
- you need to define a variable used for identification within a RanoreXPath expression.
Select that action item within the AddEntry recording which simulates a click on a menu item and open the context
menu as shown below. Click on Make Item Variable. . . to open The Path Editor.
36
Lesson 3: Data-Driven Testing
Figure 45: Make Item Variable menu item from context menu in Recorder
Typically the menu item for the Expires Date in the 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.
Figure 46: Create a new variable for the expires menu item
When looking at the repository, you can see that the item pointing to the menu item is now using the variable within
the path expression specified previously.
37
Lesson 3: Data-Driven Testing
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 AddEntry 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 of all variables used within the recording simply
click the Variables button as shown below.
38
Lesson 3: Data-Driven Testing
Select the test case which uses the AddEntry recording and open the Data Source dialog by clicking the Manage
Data Sources button in the tool bar.
Assuming someone is keeping his/her 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.
Note: The top row is handled as a header. Therefore the cells of the first row will be interpreted as captions
for the current column.
39
Lesson 3: Data-Driven Testing
40
Lesson 3: Data-Driven Testing
For further information about different Ranorex data connector types have a look at Data Connectors.
Note: To protect proprietary data like passwords you can mask specific columns of your data source.
Note: It is recommended to store your Excel data files in the native binary format xlsb instead of the
suggested default format xlsx. The binary format is up to ten times faster than xlsx, and supported since
Microsoft Office 2007.
41
Lesson 3: Data-Driven Testing
Note: Please assure that the ExcelConnector is chosen in the Data Source tab sheet (drop down in the
middle of the 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 AddEntry module.
Note: Variable binding (e.g. to a data column) only takes place if the test automation is run from the test
suite view. When running modules separately (e.g. Play in recorder), variables default values are used.
42
Lesson 3: Data-Driven Testing
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 can help with environment-related attribute values and similar issues 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.
Figure 56: Create a new variable for the execution path of system under test
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.
43
Lesson 3: Data-Driven Testing
Figure 58: Define a new global parameter for the test suite
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. Click OK to apply the changes and to close the dialog. Read more about how to open a
recordings 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 cases data binding dialog the same way you did previously for combining variables with the data table.
44
Lesson 3: Data-Driven Testing
Figure 59: Bind global parameter to the variable used within recording StartSystemUnderTest
Note: By pressing the button Auto-Create a parameter for each unbound module variable will be generated
based on the name of the module variable. By pressing the button Auto-Bind unbound module variables will
be bound to parameters having identical names.
Note: When moving the mouse over a module in the test suite a tool tip will appear displaying which variables
are bound and which are not
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 AddEntry recording. The values for the title, username, password, URL and expiration
will not cause any problems during automation. Considering 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.
Note: Variable binding (e.g. to a global parameter) only takes place if the test automation is run from the
test suite view. When running modules separately (e.g. Play in recorder), variables default values are used.
45
Lesson 3: Data-Driven Testing
46
Lesson 3: Data-Driven Testing
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 click action (#5) and click the Add New Action button as shown below.
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 IconItem.
Figure 63: Open the Select Repository Item dialog by clicking on the highlighted button and choosing ListItem Icon
from the repository
After assigning the repository item to the invoke action, the recorder presents the methods suitable for the role list
item. The role ListItem shows a Select method which you can chose as seen in following figure.
47
Lesson 3: Data-Driven Testing
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.
Finally, please modify the text-attribute-value in the RanoreXPath expression of the assigned repository item as
learned in the previous sections.
48
Lesson 3: Data-Driven Testing
Now switch back to the test suite view and start your data driven test by clicking the Run button.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.
Figure 67: Report file showing two iterations of the test case
49
Lesson 4: Ranorex Test Suite
50
Lesson 4: Ranorex Test Suite
Using 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.
You can add a new test case by clicking the NEW button. Depending on the current item selection of the test suite
you are allowed to add different types of test suite elements. A test suite can be made up of the following items:
Test cases
Recording modules
Code modules
Module groups
51
Lesson 4: Ranorex Test Suite
Folders
Select the Test Case item to create a new test case at the current position.
Note: Within a test suite, test cases can be added at different levels. 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.
52
Lesson 4: Ranorex Test Suite
53
Lesson 4: Ranorex Test Suite
For now the test case only covers starting the application under test, logging in and closing the application under test
using three existing modules.
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.
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 Instant Recording option because the system under test will be started by
the reused recording module StartSUT.
54
Lesson 4: Ranorex Test Suite
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). Since the content of the cell
(KeePass version number) is used for identification, a higher version number would cause the test case to fail because
the cell cant be found anymore - independent from the match of version number in the validation step itself. To
avoid this, the path to this cell should be modified to be more robust. The path can be edited using The Path Editor.
Additionally it should not use the version number itself for identification.
Figure 76: Click the Edit in Spy button open the path editor
Figure 77: Change attributes for identification: deselect text attribute and select column- and row-index attributes
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 varCurrentKeePassVersion with a
default value 2.20.1 instead of matching against the constant value. This module variable could be bound to a new
global variable GlobalCurrentKeePassVersion.
55
Lesson 4: Ranorex Test Suite
56
Lesson 4: Ranorex Test Suite
57
Lesson 4: Ranorex Test Suite
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
Figure 81: Adding a module group to a test case using the context menu in the test suite editor
58
Lesson 4: Ranorex Test Suite
Figure 82: Grouping existing modules into a new module group using the context menu in the test suite editor
By grouping existing modules into a module group, the module group will be filled with the selected modules. In
addition, a possible data binding of selected modules will automatically be applied to the created module group which
therefore is the recommended approach. 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.
Figure 83: Adding an existing module to a module group using the context menu
Next to adding existing modules it is possible to add folders to module groups to add additional hierarchical levels.
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.
59
Lesson 4: Ranorex Test Suite
To allow for a data driven approach as described in Lesson 3: Data-Driven Testing, it is necessary to pass values from
data sources or parameters through the module group to the modules contained in that module group.
You can define data binding for modules in the module group by using the context menu item Data Binding. . .
which appears by right-clicking a module group.
Figure 85: Open the data binding dialog for 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.
60
Lesson 4: Ranorex Test Suite
Figure 86: Define which module variables should get their values passed from outside the module group and which
module variables should have constant value
Note: By pressing the button Auto-Create a group variable for each unbound module variable will be
generated based on the name of the module variable. By pressing the button Auto-Bind unbound module
variables will be bound to group variables having identical names.
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.
61
Lesson 4: Ranorex Test Suite
This sample includes different types of elements which can be used within a test suite and covers all possible
combinations.
62
Lesson 4: Ranorex Test Suite
#1 Test case Represents a test case which can contain modules, a setup or teardown region or other
test cases
#2 Setup region Groups modules used to prepare a test case (e.g. start system under test, initialize a
database, etc.)
#3 Module group Used to group several modules into a reusable set
#4 Teardown region Groups modules used to clean up a test case (e.g. deleting files generated during test
execution, closing application, etc.)
#5 Code module Automation module written in code
#6 Recording module Automation module generated by recording
63
Lesson 4: Ranorex Test Suite
The setup and teardown regions are used to prepare and clean up a single test case run.
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.
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 picture
64
Lesson 4: Ranorex Test Suite
Figure 91: Nested test case for a general setup and teardown region
Note: In order to define global setup and teardown regions click on Add Setup/Teardown in context menu
of the test suite node and drag and drop the wanted modules or module groups to displayed the setup and
teardown regions.
Figure 92: Show setup and teardown region for test suite node
65
Lesson 4: Ranorex Test Suite
In order to quickly deactivate a certain module, instead of deleting it from the test case, use the context menu item
Disable.
Use the Search text box to find elements in the Test Suite.
66
Lesson 4: Ranorex Test Suite
For example one test suite run configuration can be defined where the mobile tests stored in your test suite will be
executed and one test suite run configuration can be defined where they wont.
67
Lesson 4: Ranorex Test Suite
Simply double-click the *.RXTST file from the projects output folder to open the Ranorex Test Suite Runner.
You can use the Ranorex Test Suite Runner to run the test suite, execute certain test cases or just run a specific
automation module.
Additionally one can create new run configurations the same way as is done within a Ranorex Studio Project.
Note: When executing a test suite from command line the return value 0 signals the successful execution of
the test script and the return value -1 signals a failure.
Using the following, you can execute the test suite from the command line:
<GeneratedTestSuite>.exe /<argument>
Allowed arguments:
68
Lesson 4: Ranorex Test Suite
reportfile|rf:<report file path> Sets the name (and path) of the report file. If no path is provided, the current
directory is used. By default, the filename specified in the rxtst file is used. (for example: %S %Y%M%D %T.rxlog).
zipreport|zr Compresses the report (including associated files) to a single archive (.rxzlog extension).
zipreportfile|zrf:<zip report file path> When used with /zipreport|zr, sets the name (and path) of the compressed
report file. If no path is provided, the path of the report file is used. If the file extension is not .rxzlog, the extension
will be replaced with .rxzlog. By default, the report filename specified in the rxtst file or the value of reportfile|rf is
used with an .rxzlog extension (for example: %S %Y%M%D %T.rxzlog).
reportlevel|rl: Debug|Info|Warn|Error|Success|Failure|<any integer> Sets the minimum report level that log
messages need to have in order to be included in the log file. Specify None to completely disable reporting. These
levels correspond to the following integer values: Debug=10,Info=20,Warn=30,Error=40,Success=110,Failure=120
listtestcaseparams|ltcpa:<name or guid of test case> Lists all testcase parameters and their values.
testsuite|ts:<path to test suite file> Runs the test cases defined by the test suite (rxtst) file. By default
the rxtst file with the same name as the <TestSuiteExe> is used
runconfig|rc:<configuration name> Runs the test cases of the specified configuration defined by the rxtst file.
Configurations can be edited using Ranorex Studio or TestSuiteRunner. By default, the currently selected run config
is used.
module|mo:<module name or guid> Runs the module with the specified name or guid. Assemblies loaded by
<TestSuiteExe> and assemblies referenced in the rxtst file are searched.
param|pa:<global parameter name>=<value> Creates or overrides values for global parameters specified in
the test suite.
testcasedatarange|tcdr:<name or guid of test case>=<data range> Sets the data range for a testcase.
69
Lesson 4: Ranorex Test Suite
Note: Compressed report files (*.rxzlog) can be extracted by right-clicking them in explorer and choosing
Extract from context menu. Report files (*.rxlog) can be compressed by right-clicking them in explorer and
choosing Compress from context menu.
Using the KeePass sample test suite - included in Ranorex installation - as reference, the following samples will fulfill
the following use cases:
KeePassTestSuite.exe /pa:GlobalExecutionPath=.\KeePass\KeePass.exe
KeePassTestSuite.exe /tc:AddNewEntry
Start the test suite with generating a zipped report called report.rxzlog:
KeePassTestSuite.exe /rc:SmokeTest
KeePassTestSuite.exe /tcdr:AddEntryByRecording=1-2
70
Lesson 4: Ranorex Test Suite
71
Lesson 4: Ranorex Test Suite
72
Lesson 4: Ranorex Test Suite
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
Description test suite editor). Use the HTML text editor to format the description and to add
links to the description. The formatted description will be represented as HTML
content in the generated report
Show Progress Dialog Specifies whether a progress dialog should be shown during test suite execution
Report Level Specifies the minimum report level of messages shown with the report file
Warn for unbound variables Specifies whether a warning should be shown for unbound variables
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.
73
Lesson 4: Ranorex Test Suite
Compressed Copy Specifies whether a copy of the report should be generated as compressed
folder
Collect screenshots in a subdirectory Specifies whether the created screenshots will be stored in a specific folder
for each report or directly in the report folder
Specifies the directory holding customized style files used instead of the
Ranorex default style to present the reports; a new template can be created
Report Template by pressing the button Create Custom Template as explained in Create a
Custom Report Template; an existing template can be chosen by pressing
the button Choose Custom Template
Specifies whether the screenshots will be captured in foreground (before
Tracing Screenshot Mode action is executed) or background (while action is being executed) or
capturing tracing screenshots is disabled
Quality Specifies the image quality of the captured screenshots
Error Behavior Specifies the behavior of the test case and the test suite in case of on error. For further information
please have a look at the next paragraph.
Set to Continue with iteration if, in case of an error, the case should not break continue with the next iteration
Set to Continue with sibling if, in case of an error, the currently running test case should break and the
execution should continue with the sibling test case
Set to Continue with parent if, in case of an error, the currently running test case should break and the
execution should continue with the sibling of the parent test case
Set to Stop in order to break the test suite run in case of an error
74
Lesson 4: Ranorex Test Suite
75
Lesson 4: Ranorex Test Suite
Use the context menu to change the report level or the error behavior for multiple test cases.
76
Lesson 4: Ranorex Test Suite
These variables can be connected to internal or external data sources and parameters.
Module Variables:
Variables are the interface between a module and the nesting test case, or - if module groups are used - the module
group, respectively.
Variables can be used in
code modules (as described in section Using Variables with Code Modules) and
After building up the test suite with its test cases as described in the previous sections, the included module variables
can be bound to group variables, constant values, data columns, or parameters.
77
Lesson 4: Ranorex Test Suite
Constant Values:
Constant values can be used in module groups to hide module variables outside a module group. This can help to
reduce the complexity and increases the clarity of module groups.
For further details have a look at the section about the Module Group Editor.
Group Variables:
In module groups, group variables are the interface between the nested modules and the nesting test case.
For further details have a look at the section about the Module Group Editor.
Data Columns:
The columns of a data connector are called Data Columns and specify the columns from external data sources.
Have a look at the data connectors section (Data Connectors) to get an overview about the different kinds of data
connectors. Data columns can be connected to variables in the data binding dialog of a test case as described in
section Combining Variables with Test Data.
Parameters:
Module variables can also be bound to parameters. A distinction is made between local parameters, which are part
of a specific test case and are available in the test case and all child test cases, and global parameters which are
available in the whole test suite.
Unlike local parameters, global parameters can be set from the command line as explained in section Running Tests
via Command Line.
Have a look at the section Combining Variables with Parameters to see how parameters can be connected to variables.
Global parameters are available in the whole test suite. This means you can bind global parameters in any test case
of a test suite.
Local parameters and data columns will be inherited by all children of a test case. This means you can bind all local
parameters and data columns of a test case in its child test cases.
The following figure will illustrate the scope of different data containers.
The green rectangle illustrates the scope of global parameters, the blue rectangle the scope of local parameters and
78
Lesson 4: Ranorex Test Suite
data columns of the test case named Parent Test Case 1 and the red rectangle the scope of local parameters and
data columns of the test case named Test Case 1.
This means, in Test Case 1 you can bind all global parameters as well as all local parameters and data columns of
itself and its parent test case Parent Test Case 1, as illustrated in the following figure.
The green rectangle illustrates a global parameter, the blue rectangle a local parameter and a data columns of the test
case named Parent Test Case 1 and the red rectangle a local parameter and data column of the test case named
Test Case 1.
Parameter values as well as data column values can be changed by a module. In order to transfer values from one
module to another, parameter or data column values are updated from their bound module variables once the module
has finished execution.
This means you can freely transfer values within the scope of a parameter or data column.
One example of this application would be to dynamically get a value from the UI which should be reused in another
module as described in the section Types of Action Items addressing the Get Value action or at Accessing Test Case
& Test Suite Context.
79
Lesson 5: Ranorex Recorder
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.
80
Lesson 5: Ranorex Recorder
Figure 111: Add a recording module by clicking the button on the toolbar
Alternatively you can also add a recording directly to a test case within the test suite editor.
81
Lesson 5: Ranorex Recorder
During Recording
After Recording
Recorder Variables
Image-Based Automation
82
Lesson 5: Ranorex Recorder
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)
Before running a new recording session, you can configure Ranorex Recorder using the settings dialog. Click the
Settings button to open the settings dialog.
83
Lesson 5: Ranorex Recorder
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.
Description:
Recording namespace:
The speed factor is used to increase or decrease the replay overall speed by a specific factor value.
84
Lesson 5: Ranorex Recorder
Recorder UI mode:
By specifying the recorder UI mode the set of actions available in the actions table will be adapted (Global: all
actions, Desktop & Web: no mobile actions, Mobile: no mouse and keyboard actions).
Is used to specify whether recorded delays between actions should be part of the generated code.
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
In this tab you can specify global default values for every newly created recording. The settings are divided into three
sections:
Recording
Capture a screenshot for each step: Specifies whether a screenshot of the current action should be made during
the recording.
Highlight elements: Specifies whether element highlighting during recording should be enabled.
Coordinate recording mode: Specifies the way coordinates will be recorded. Following options are available:
None: Actions will always be invoked on the center of the recognized elements
Pixel: Relative coordinates within a recognized element are recorded in pixels
Proportional: Relative coordinates within a recognized element are recorded in percent
Note: Please note that the following settings only affect newly created actions, not existing actions.
Use timings also for recorded actions: When enabled, the specified timings below will be taken instead of the
recorded durations.
Key sequence split time (ms): Use this setting to specify the maximum time between key presses in a key sequence
during recording. If this time is exceeded, the sequence is split into multiple key sequences.
Mouse move time per action (ms): Specifies the time in milliseconds used to move the mouse to the UI object
related to the action.
85
Lesson 5: Ranorex Recorder
Mouse/Pointer-related action time (ms): 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, when the time of
an action cannot be determined during recording or when Use timings also for recorded actions is activated.
Keyboard-related action time (ms): Specifies the default overall time in milliseconds used for a manually created
keyboard action. The value set for this setting is only taken into account for manually created actions, when the time
of an action cannot be determined during recording or when Use timings also for recorded actions is activated.
Code Generation
Recording namespace: Specifies the namespace used for the generated code.
Recording class name: Specifies the class name used for the generated code.
Generate replay reports: This setting is used to turn the generation of reports during replay on or off.
Use item logging by default: Activate this setting to turn on a default logging message for each action item.
86
Lesson 5: Ranorex Recorder
During Recording
Click the Record button to trigger a new recording.
After clicking the record button youre assisted in running an application, opening a browser to navigate to a particular
URL or starting an app on a mobile device before recording any actions. Therefore its not necessary to record actions
like double clicking a shortcut on the desktop. By choosing the option instant recording its on you to start the
application under test.
87
Lesson 5: Ranorex Recorder
After clicking the Record button, the Recorder or Ranorex Studio will be minimized. A running recording session is
indicated in the Ranorex Recorder tool bar.
88
Lesson 5: Ranorex Recorder
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.
Note: The Recording can be stopped either by using the keyboard shortcut <SHIFT>+<ESC> or by
pressing the Stop button.
The Ranorex Recorder provides two different types of validation during a running recording session:
Image-based validation
Screencast: The screencast Quick Start with Ranorex Test Automation provides a short overview, and
among other useful information also shows how to create a validation step during a recording. You can jump
directly to the noted position in the video by clicking http://youtu.be/0S YC7uwI-s#t=2m17s.
The Ranorex Recorder tool bar can be used to validate states or attributes of GUI elements during a running recording
session. Click the Validate button to pause the recording in order to start the validation.
89
Lesson 5: Ranorex Recorder
The 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. Click on the
element to open the validation dialog.
In the Validation dialog you can check if you have chosen the right UI element to validate. By clicking Next button
you can define the attributes and their values you want to validate.
90
Lesson 5: Ranorex Recorder
91
Lesson 5: Ranorex Recorder
92
Lesson 5: Ranorex Recorder
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 hotkeys 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 elements
image, open the Image tab in the validation dialog.
Figure 127: Validate whether a specific listitem contains a specified image or not
93
Lesson 5: Ranorex Recorder
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
Recorders hot keys simply click on the Enable Hotkeys checkbox or press the master hot key <SCROLL>.
The recorders toolbar will then show which shortcuts are available.
V:
Press the hot key V to turn on Validation (aka Checkpoint) - 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:
Its 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 relation to the underlying item and validates the current
content of the tooltip.
The hot key I is used to turn on/off Image-Based Automation - used for pop-up windows, menu items or drop-down
lists.
Roll the mouse wheel during validation mode to change the level of UI element selection.
94
Lesson 5: Ranorex Recorder
After Recording
After pressing the Stop button on the Recorder toolbar, the recorder represents all low level actions like clicking on a
button or typing text within the actions 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 (Click, Double-Click, Move, etc.) or which button was used (Left, Right, etc.) a key
sequence action only stores the keystrokes made during a recording.
95
Lesson 5: Ranorex Recorder
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.
Figure 132: Key sequence action (at password textfield) refers to the repository item Password
Action Cleanup
After finishing the recording, it is advisable to look at each recorded action item in detail. The recorder offers some
editing features to clean up the sequence, for example merging key sequence actions.
96
Lesson 5: Ranorex Recorder
By default the recorder records the mouse click location performed by the user relative to a button or a text field. Its
possible to turn that off in advance within the Recorders settings dialog. Alternatively, you can also change the click
location afterwards within the properties dialog.
Figure 134: Changing click location for all mouse related action items to Center
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 its 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.
97
Lesson 5: Ranorex Recorder
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.
98
Lesson 5: Ranorex Recorder
Note: To set the Turbo Mode for more than one module select the desired modules in the Module
Browser and set the option Enable Turbo Mode in the properties pane.
Figure 138
Note: You can specify the report level for the present replay directly in the context menu of the play button.
See Lesson 8: Reporting - Report Levels for more details.
99
Lesson 5: Ranorex Recorder
During execution, the progress box shown at the right lower corner gives information about the current automation
state. Press the <Pause> key to stop execution. Press <SHIFT> + <PAUSE> to skip delays and timeouts during
replaying.
Note: If a test is stopped with the abort key, the teardown region will not be executed.
If the option Generate replay reports is set to true, a report is shown after replay has finished. By default, each
action item logs one message to the report.
100
Lesson 5: Ranorex Recorder
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 Recorders actions table, you can then fix a step causing an
error and quickly re-run single or selected steps using the context menu. Additionally, you can play to and play
from the selected item
101
Lesson 5: Ranorex Recorder
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 use variables instead.
The variables in the table above are shown in green. All variables used within the recording can be connected to a
Ranorex data connector or to local/global 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.
102
Lesson 5: Ranorex Recorder
Most action types can make use of variables. 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.
Figure 146: Creating a new variable for use within the path of the repository item
103
Lesson 5: Ranorex Recorder
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.
104
Lesson 5: Ranorex Recorder
Use the toolbar to add, remove or copy a variable from the repository. Change the name of the variable and set a
default value by clicking in the cells of the table. Press the Copy 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.
105
Lesson 5: Ranorex Recorder
User-specific Validation
Extended reporting
Looking at a recording file in the projects view you will see that each recording has two associated code files.
Note: User code actions are not available within the standalone Recorder.
Within Ranorex Studio, each recording manages two types of source code files:
You can jump to the generated code of a recorded action by right-clicking the action and choosing View Code from
the context menu. Alternatively you might use the shortcut <CTRL> + <ENTER> to achieve the same as with the
context menu.
106
Lesson 5: Ranorex Recorder
Every time you change and save a recording, the main code file AddEntry.cs is newly generated. Any change of code
should always be made within the recordings UserCode.cs file.
You can create user specific code actions by converting existing items or by adding a new Usercode action item via
the toolbar button Add New Action.
107
Lesson 5: Ranorex Recorder
Figure 153: Specify method name used for user code item
108
Lesson 5: Ranorex Recorder
Figure 154: Use the context menu item View Code to jump into the code
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 youre converting an existing action item, the code generated for the main recording file is transferred to
the new user code method.
C#
namespace M y F i r s t T e s t P r o j e c t
{
public partial class AddEntry
{
// / < summary >
// / This method gets called right after the recording has been started .
// / It can be used to execute recording specific initiali zation code .
// / </ summary >
private void Init ()
{
// Your recording specific in itializ ation code goes here .
}
public void C l i c k O n P a s s w o r d F i e l d ()
{
Report . Log ( ReportLevel . Info , " Mouse " , " Mouse Left Click item FormAdd_Entry .
TabPageList . InputFields . TextPassword at 175;9. " , repo . FormAdd_Entry .
TabPageList . InputFields . T e x t P a s s wo r d I n f o ) ;
repo . FormAdd_Entry . TabPageList . InputFields . TextPassword . Click ( " 175;9 " ) ;
}
}
}
VB.NET
Namespace M y F i r s t T e s t P r o j e c t
Public Partial Class AddEntry
< summary >
This method gets called right after the recording has been started .
It can be used to execute recording specific initiali zation code .
</ summary >
Private Sub Init ()
Your recording specific init ializat ion code goes here .
End Sub
Public Sub C l i c k O n P a s s w o r d F i e l d ()
Report . Log ( ReportLevel . Info , " Mouse " , " Mouse Left Click item
FormAdd_Entry . TabPageList . InputFields . TextPassword at 175;9. " ,
repo . FormAdd_Entry . TabPageList . InputFields . T e x t P a s s w o r d I n f o )
repo . FormAdd_Entry . TabPageList . InputFields . TextPassword . Click ( " 175;9 " )
End Sub
End Class
End Namespace
109
Lesson 5: Ranorex Recorder
With Ranorex it is possible to use parameters for user code actions. You can pass arguments with different types to
your user code methods to gain more flexibility in your testing environment.
Next to passing different types of values it is also possible to pass repository items to user code actions. This enables
e.g. combining several actions on one UI object or building up a generic library of smart actions independent of the
underlying technology to only name some of the potential applications.
To use parameters for a new user code action, click the Args button next to the methods cell to open the Argument
Editor.
By pressing the Add button, you can choose the type of the argument you are going to pass to the user code action.
After adding a new argument, you can edit its properties. To enhance flexibility, you can use variables instead of
hardcoded values.
110
Lesson 5: Ranorex Recorder
After declaring the parameters with values or variables, you can switch to the user code method and use the passed
parameters..
C#
public void A d d E n t r y W i t h P a r a m s ( string aTitle , string aUsername , string aPassword , string aURL )
{
// Set text fields
repo . PwEntryForm . Text . TextValue = aTitle ;
repo . PwEntryForm . UserName . TextValue = aUsername ;
repo . PwEntryForm . Password . TextValue = aPassword ;
repo . PwEntryForm . Repeat . TextValue = aPassword ;
repo . PwEntryForm . URL . TextValue = aURL ;
}
VB.NET
Public Sub A d d E n t r y W i t h P a r a m s ( aTitle As String , aUsername As String , aPassword As String , aURL
As String )
Set text fields
repo . PwEntryForm . Title . TextValue = aTitle
repo . PwEntryForm . UserName . TextValue = aUsername
repo . PwEntryForm . Password . TextValue = aPassword
repo . PwEntryForm . Repeat . TextValue = aPassword
repo . PwEntryForm . URL . TextValue = aURL
End Sub
You can bind the return value of a user code method by setting the option Return Value Variable in the properties
pane.
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 overloaded methods.
111
Lesson 5: Ranorex Recorder
Figure 159: Ranorex Argument Editor with arguments and variable binding from overloaded method
As mentioned above it also is possible to pass repository items to user code actions. This can be accomplished by
either choosing the argument type Adapter or RepoItemInfo, when adding arguments using the Argument Editor.
After defining the repository item arguments, the can simply be bound to repository items the same way as any other
action in the actions table by selecting them in the action table or dragging and dropping them from the repository.
After declaring the parameters with repository items, values or variables, you can switch to the user code method and
use the passed parameters.
The following example simulates a keyboard input to the given repository item using the given string value. Followed
by a validation whether the text value attribute of the given repository equals the given string value. After that a
screenshot of the current state of the UI element represented by the repository item will be reported.
C#
public void S e t A n d V a l i d a t e T e x t V a l u e ( Ranorex . Adapter repoitem , string val )
{
Keyboard . Press ( repoitem , val ) ;
Validate . AreEqual ( repoitem . As < Ranorex . Text >() . TextValue , val ) ;
Report . Screenshot ( repoitem , true ) ;
}
VB.NET
Public Sub S e t A n d V a l i d a t e T e x t V a l u e ( repoitem As Ranorex . Adapter , val As String )
Keyboard . Press ( repoitem , val )
Validate . AreEqual ( repoitem .[ As ]( Of Ranorex . Text ) () . TextValue , val )
Report . Screenshot ( repoitem , True )
End Sub
112
Lesson 5: Ranorex Recorder
Using repository items as arguments for user code actions enables a variety of possibilities such as providing a
framework of smart test actions, defining generic technology independent get/set value actions, combining several
related actions to one user code action, implementing complex validations and many more.
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.
Note: Only create small and easy to maintain user code actions for a recording. If an implemented method
should also be available for other test cases, create a code module (see Lesson 7: Code Modules) instead.
Within the DeleteEntry recording that was created in Lesson 3: Data-Driven Testing, there are three simple actions
for 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 an entry if it is selected. To accomplish this, code with a condition can
be used.
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. Click on the Merge Items to User Code Item menu item in the context menu.
Figure 161: Context menu item to Merge Items to User Code Item
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 Code. Now
change the converted code so it is only executed if the cell is focused on.
C#
public void D e l e t e I t e m I f F o c u s e d ()
{
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 . D el et eE n tr yI nf o ) ;
repo . KeePass . DeleteEntry . Click ( " 168;14 " ) ;
}
}
VB.NET
113
Lesson 5: Ranorex Recorder
Public Sub D e l e t e I t e m I f F o c u s e d ()
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 . D el et eE n tr yI nf o )
repo . KeePass . DeleteEntry . Click ( " 168;14 " )
End If
End Sub
114
Lesson 5: Ranorex Recorder
Recorder Variables
Splitting Recordings
There are two ways to manually add actions to the actions table. One way is specifying the action itself (Add New
Action) and assigning a repository item (in most of the cases) afterwards. The second method is dragging and
dropping the repository item directly into the actions table including the specification of the action itself.
Using the Add New Action-button To add a new action item, open the Add New Action drop-down menu as
shown below:
By selecting one of the items a new action is added after the current selection within the actions table.
115
Lesson 5: Ranorex Recorder
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 recordings
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.
Confirm your selection by clicking OK.
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.
116
Lesson 5: Ranorex Recorder
Figure 165: Assign a repository item to the action via drag and drop
To modify the newly created action, use the drop down menus available within the cell, for example you can change
the action from Click to Move.
Drag and drop repository item to initiate adding a new action Alternatively to the method presented above,
you can also drag and drop repository items into a new line in the actions table of a recording as shown in following
graphic.
117
Lesson 5: Ranorex Recorder
Figure 167: Use drag and drop to create a new action for a specific repository item
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.
Actions used in the actions table can be divided into two groups: Basic and Smart Actions. Basic Actions are
performed by the end user with the keyboard, mouse, on-screen keyboard or touchscreen utilizing the mouse, mouse
wheel, touch, key shortcut, key sequence or mobile key-press. These actions are automatically recorded with the
Ranorex Recorder. All other actions are so-called Smart Actions.
118
Lesson 5: Ranorex Recorder
Instruments the given Android application and deploys it on the given mobile
Deploy Android/iOS App device or deploys the already instrumented iOS application on the given
mobile device
Set Device Orientation Sets the orientation of the device either to Portrait or Landscape
Close Application Closes an application or web site containing the given repository item
Waits for a given repository item to appear or disappear
Wait For
Note: This action can be used for any type of UI element
Adds a new report action item logging a user defined message
Log Message Note: In addition to the standard report levels, you can define custom report
levels by changing the level from Info to Custom
Capture Screenshot Adds a new report action logging a screenshot of a specific repository item
Adds a new report action item adding a snapshot file of a specific repository
Create Snapshot
item
Separator Inserts a separation line on the currently selected position in the actions table
Delay Adds a new delay action item
Adds a new user code action item which is used, for example to implement a
User Code
user specific validation in code
Note: Keep in mind that most types of actions can handle module variables.
Note: Based on the Recorder UI Mode there will be different sets of actions available. You can change the
Recorder UI Mode in the Current Recording tab in the settings dialog.
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, Click, Double-Click 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 A touch event can be used to perform different kinds of touch events on mobile devices as well as on
Windows 8 desktops. The duration of the different kinds of touch events can be defined in the properties pane. You
can open this pane by clicking the context menu item Properties on the Touch Event action item.
119
Lesson 5: Ranorex Recorder
Swipe Gesture This action can be used to simulate a swipe gesture on a given repository item. You can specify
the direction and the distance as well as the swipe duration. The distance can either be specified in pixels or as a
percentage relative to the repository item connected to the action. The swipe gesture can only be added manually, it
will not be recorded. Additionally you can set the start location as well as the amount of swipe steps in the properties
pane. The properties pane can be accessed by right-clicking the swipe action and choosing Properties in the context
menu.
Key Shortcut This action can be used for executing key shortcut actions. Aside from the shortcut itself, it is
possible to specify the events Press, Up and Down. For this action, a repository item assignment is not required.
Key Sequence This action makes it possible to execute or to simulate a key sequence. 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 not required. To protect proprietary data like passwords you can mask the key sequence by setting the option
Mask Sequence in the properties pane.
Mobile Key Press This action can be used for pressing mobile keys like {BACK} and {MENU}. For more detailed
information please have a look at Android Testing - Record and Run an Android Test.
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.
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.
120
Lesson 5: Ranorex Recorder
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.
CONTAINSIMAGE: This validation checks whether the assigned repository item contains a specified screenshot.
This screenshot can be easily created within the Edit Image Validation dialog which can be accessed via a button
in the Screenshot column. You can enable reporting the similarity in the properties pane. This can be useful
for tweaking the similarity of the corresponding image validation action. For more information about image-based
validation please have a look at the section entitled Image-Based Automation later in this chapter.
Example: Its 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 a better understanding of what is different between the two compared images you can
enable Report Difference Images in the properties pane. This will report a difference mask showing the differing
pixels as well as the differential image. Additional you can enable reporting the similarity in the properties pane. This
can be useful for tweaking the similarity of the corresponding image validation action. For more information about
image-based validation please see Image-Based Automation later in this chapter.
Example: To validate whether the toolbar of the KeePass application contains the intended icons you can compare
the repository item with a screenshot of the toolbar in its initial state.
Invoke Action 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. You can bind the return value of an invoke action by setting the option Return Value Variable
in the properties pane.
Invoking user-defined (dynamic) actions: In addition to access actions delivered by default, you can also invoke
user-defined actions (see Invoking User-Defined Actions) in your System Under Test.
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 (see figure below).
121
Lesson 5: Ranorex Recorder
Parse strings with regular expressions: In the Capture Regex column of the GetValue action you can specify a
regular expression.
For additional information on regular expressions please consult the corresponding MSDN web site: http://msdn.
microsoft.com/en-us/library/az24scfc.aspx
With this regular expression it is possible to easily parse a string out of the specified field. The matched string will be
saved to the chosen module variable for further use. So far there is no need to write a single line of code. If the
regular expression delivers more than one match, the first match will be stored in the module variable.
Example: If you have a string Count: 42 and you want to return the digits only (42) you can use the following
regular expression: Count: ([0-9]*)$
The first non-trivial group matched by the regular expression is returned. If there are no groups captured the full
match will be returned. In case that there are more grouping constructs in the regular expression, you can mark the
requested group using the following construct ?<1>.
122
Lesson 5: Ranorex Recorder
Example: If you have a string Rows: 23, Columns: 42 and you want to return the number of columns you can use
following regular expression: Rows: ([0-9]*), Columns: (?<1>[0-9]*)$
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 this module.
To make the value stored in the module variable available to other modules, its necessary to bind the variable to a
parameter. By doing so, it can then be bound to variables in other modules.
Figure 170: Two variables are bound to one parameter for passing a variable value from one module to another
Set Value As the action name indicates, this method can be used for setting the attribute 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 shown below.
123
Lesson 5: Ranorex Recorder
To protect proprietary data like passwords you can mask the value by setting the option Mask Value in the properties
pane.
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 preparation 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, Chrome,
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 Cross-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 with the filename specified in the column File
Name. You can also pass arguments (column Arguments) and define the working directory.
Run Mobile App When using this action you can specify a Device, an App, and whether the specified app should
be restarted or not. For more information see Android Testing - Record and Run an Android Test for Android testing
or iOS Testing - Record and Run an iOS Test for iOS testing.
Deploy Android/iOS App When using this action, you can specify a Device and an APK/IPA file. The given
application will be deployed to the given device.
124
Lesson 5: Ranorex Recorder
Set Device Orientation When using this action, you can specify the orientation of the device. You can choose
one of the following orientations: Portrait, PortraitUpsideDown, LandscapeLeft, LandscapeRight.
Close Application This action can be used for closing applications and web sites. If the Close Method is set to
CloseWindow, 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 closing the application failed. If Close Method is set
to KillProcess the applications process is killed immediately and the grace period is ignored.
Wait For You can use the Wait for action to wait until the assigned repository item appears (choosing the option
Exists) or does not exist anymore (choosing the option NotExists). You can also specify a Timeout.
Report The Report action is typically used for providing information related to the test report.
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.
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. Please mind that the assignment of a repository item is
obligatory for this type.
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).
Note: This time delay is not scaled with the speed factor and is also present in Turbo Mode
User Code User code actions can be used to execute custom class methods defined in the recording user code file.
User code actions are described extensively in User Code Actions
Sometimes it might be useful to access internal, user-defined functionality from your system under test. You could
use the recorder action Invoke Action which also allows parameters. For example a simple WinForms application
Invoke-Example written in Visual Studio (C#) provides a button which automatically sets a constant text to a
protected text field. The sample project including the source code can be downloaded here: sample-project.
125
Lesson 5: Ranorex Recorder
Figure 172: Example (in initial state) with public functionality which will be invoked
C#
public void MyIn v ok ed Ac t io n ( string MyMessage )
{
e dP ro te c te dT ex t . Text = MyMessage ;
}
private void bt S e t V a l u e _ C l i c k ( object sender , EventArgs e )
{
e dP ro te c te dT ex t . 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.
Figure 173: Example after clicking the button without using custom invoke functionality
Ranorex provides the functionality for accessing methods that are declared as public directly within the actions table.
The public method MyInvokedAction can easily be called using a custom argument value. When adding the new
action it is recommended to keep the application (InvokeExample) open because accessible functionality is determined
dynamically.
126
Lesson 5: Ranorex Recorder
You can also access an attribute editor using the Browse (. . . ) button in the last argument column to get an
overview of available parameters.
127
Lesson 5: Ranorex Recorder
Invoking this method causes the text fields content to be set to the desired value.
Each action item listed in the table can be disabled or set to Continue On Fail. Set an action item to Continue On
Fail if, in cases of an error, module execution should not stop at that position. You can set both options via the
context menu or the property grid. Items set to continue on fail are in italics in the actions table whereas disabled
action items appear in gray.
Figure 178: Disabled actions are grayed out while Continue-On-Fail is indicated by an italic font style
Note: In case of an error the particular action logs a warning to the report.
128
Lesson 5: Ranorex Recorder
Note: To make a validation action optional you additionally have to set the Report Level on Failure of the
action to Warning. You can set this option via the property grid.
Splitting 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: Ranorex Modules - Test Actions and Lesson 4: Ranorex Test Suite
to combine multiple recording modules into one test case.
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.
129
Lesson 5: Ranorex Recorder
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. Creating a new repository for your recording
automatically adds a new repository file to the current project.
130
Lesson 5: Ranorex Recorder
Image-Based Automation
In some situations, required information for automation is not available as text but only as pixel image. Ranorex
provides image-based automation to bypass this lack of accessibility.
Screencast: Information about image based automation can also be found in our screencast How and When
to Use Imaging Capabilities. Please follow the link to view this video: http://youtu.be/wwr5ddOe4h0.
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 Recorders toolbar during a recording session.
Now move the mouse pointer over a certain UI element. Ranorex highlights the UI element below the mouse and also
highlights a recognized image region within the UI element. To turn off image-based recording, uncheck the checkbox
or press the shortcut key I.
Note: Hotkey functionality has to be activated by first using the master hot key SCROLL. Read more about
hotkey usage in the current lesson in the section entitled Recorder Hotkeys.
Introductive Example
In KeePass, 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 lower index can be deleted.
131
Lesson 5: Ranorex Recorder
Figure 182: KeePass Icon Picker dialog containing two custom icons
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 done on the listview control
in contrast to a click on an (icon) element itself because this click defines the region in which the prospective image
has to searched. Thus the image is searched in the entire list control.
After stopping the recording, the actions table contains an image-based mouse click action. At the time of recording
the mouse click, a screenshot of the control was created and is now listed as a child element of the corresponding
repository item.
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 figure of the listview. Open the image editor by clicking on
132
Lesson 5: Ranorex Recorder
the button in the location cell (see graphic above). In this dialog use the Select image find region toolbar button 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 the Image Editor section.
Figure 184: Select image find region and Select click location in Ranorex Image Editor
In this example, Ranorex has been used to automate a mouse click on 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 figure 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 in the
property grid.
Use the property group to set advanced image search options like Clipping or Best Match If
Advanced Options Best Match is set to true, the result position with the highest similarity is used for validation.
If is set to false, the first available result position will be used for the validation. The first is
more accurate and the second is faster.
Preprocessing Defines preprocessing steps that can be performed on an image before search (see table
Image Preprocessing Filters below).
Screenshot Name Specifies the name of the screenshot used in the search.
Selection Rectangle Defines the image selection region (= what to search for).
Similarity Specifies the minimum similarity (0.0-1.0), that the image region to search for needs to
have in common with the image in order to be considered a match.
133
Lesson 5: Ranorex Recorder
None: No preprocessing
Image-Based Settings
To set up the default values for image-based recording, open up the Settings dialog and continue with activating the
Imaging tab.
134
Lesson 5: Ranorex Recorder
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.
Figure 186: Click location dialog to change the settings of image-based mouse actions
135
Lesson 5: Ranorex Recorder
Use the drop-down combo boxes to specify whether a mouse action should be performed relative or absolute to the
currently defined Image Find Region.
Absolute location means the distance from the upper left corner of the Image Find Region to the click location (in
pixels).
Relative location offers a couple of pre-defined location settings (e.g. Center, CenterLeft . . . ) relative to the Image
Find Region. Its also possible to define relative position statements for the click location. Therefore the click-location
inside the Image Find Region is defined by a value between 0 and 1 for both directions (X and Y-Axis). A relative
click location of 0.9;0.9 defines a click near the bottom right corner of the specified region. Values greater than 1
(or negative values) mean locations outside the defined region relative to the size of the region.
If the captured screenshot has to be updated, click the Capture New Screenshot toolbar button. Every newly created
screenshot is also automatically added to the image list of the related repository item so its available for other
image-based validation (checkpoint) or automation actions.
136
Lesson 5: Ranorex Recorder
Figure 188: Add a new image or select an existing image to specify the location/graphic to search
137
Lesson 6: UI Mapping with Ranorex Repository
Editing RanoreXPath
Repository Separation
138
Lesson 6: UI Mapping with Ranorex Repository
You can access and edit the repository (directly) in the recorder view by double clicking the file (MyFirstTestProjec-
tRepository.rxrep) in the projects view as shown in the figures above.
139
Lesson 6: UI Mapping with Ranorex Repository
Each UI element within the repository can have a logical user-defined name. The more logical names you use the
easier it is to understand test automation code and report files. In order to rename an item in the repository, first
select it and then click the item to enter edit mode. Optionally you can use the keyboard shortcut <F2> to edit the
names.
The more objects you have in a repository the more structured and organized it should be. For this reason you can
structure and group UI elements which logically belong together. Add a new Simple Folder using the drop-down
button in the repository toolbar.
140
Lesson 6: UI Mapping with Ranorex Repository
Figure 193: Repository using two logical folders to group input fields and buttons
Use the Add New Item button in the toolbar to add new items manually.
Use the Search text box to find elements in the repository. Specify where to search for the given text value using
the drop-down menu.
141
Lesson 6: UI Mapping with Ranorex Repository
Figure 195: Specify whether to search in Names, Paths or to Search All elements
Figure 196: Search result for text button used in names and paths
Repository Cleanup
The repositorys Cleanup button is used to search for currently unused items and to delete these items afterwards.
Unused items mean they are neither used by recording modules nor by code modules.
Considering the situation that a user clicked unintentionally on some desktop icons during the recording, these icons
would have been added to the repository as well. Cleaning up would be beneficial in that case.
Another situation where cleaning up is helpful is when UI elements which are still linked from the repository are no
longer part of the software under test.
In order to keep your repositories as tidy as possible, use the Cleanup functionality from time to time to avoid
disorder.
In the Cleanup dialog unused repository items are listed and checked automatically. Uncheck items if you do not
want to delete them.
142
Lesson 6: UI Mapping with Ranorex Repository
Figure 198: After clicking the Cleanup button a dialog is shown with the repository elements currently not in use by
any of recording or code modules within the project
143
Lesson 6: UI Mapping with Ranorex Repository
Note: The cleanup functionality only searches for used items in the solution the repository is located in.
There is no check if items are used in other solutions referencing the repository.
In Using Repository within Code Module you will learn about how to use repository items in code modules. Before
you modify an existing repository item (e.g. the items name or the items RanoreXPath), it might be necessary to
check which code files use that item. Use the context menu item Find All Code References to list all code files using
a certain repository item. You can choose whether to search in all the code files or only in the user code files.
Figure 200: Search result - simply double-click a result item to open the code file
Next to finding repository items in code you can also search all test modules.
144
Lesson 6: UI Mapping with Ranorex Repository
Figure 201: Search for references of a repository item in all test modules
Figure 202: Search result - simply click a result to open the test module
145
Lesson 6: UI Mapping with Ranorex Repository
Screencast: In addition to going through the explanations on the following pages, you can get a good
overview of Adding Repository Items by watching our screencasts on this topic. How to add items manually
is explained here: http://youtu.be/C1AVdFbUlIo. Several ways to use the Ranorex Spy tool are pointed out
in this video: http://youtu.be/p25kFcjcuBs.
In this section you will find several ways to add items to your repository without using the recording functionality. In
addition, youll learn about how you can manually add actions (clicking, typing, etc.) to the recorder and connect these
actions to repository items to specify the UI element the action should be executed on. 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.
Figure 203: Open Ranorex Spy to track and add items to the repository
Next track the Find button in KeePass using the Track button in Ranorex Spy. Successful identification is indicated
by a highlight frame around the button.
Figure 204: Track and identify the Find button with Ranorex Spy
146
Lesson 6: UI Mapping with Ranorex Repository
As a third step, add the button to the repository as shown in following figure.
Note: Alternatively you can drag and drop the item from Ranorex Spy directly into the repository from
Ranorex Studio.
Note: It is also possible to track UI elements directly from the repository using the Track button.
147
Lesson 6: UI Mapping with Ranorex Repository
Now the Find button is part of the repository and is ready to be used by code or recording modules. Create 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
Click on the browse repository button in the recording grid (column for repository item)
Figure 208: Connect repository item to action using the browse repository button
Alternatively you can 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).
148
Lesson 6: UI Mapping with Ranorex Repository
Figure 209: Context menu for choosing action type 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 similar to the steps already done in this section.
149
Lesson 6: UI Mapping with Ranorex Repository
Note: This long list of steps shows the manual method of creating a recording. Of course these steps could
be also done as a normal recording without worrying about assigning 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, Play To Here or Play From Here.
Figure 210: Execute a single action to simulate a key sequence on the edit field FindText
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: It is also possible to add a recording module two or more times to a test case. See the following
example for more details.
Within this test case it may be a good idea to combine the FindEntry module with the Validate module. The test
case structure in the following figure would extend the current example with a more complex combination of modules:
Figure 211: Example of an advanced test case using different code modules multiple times
To explain the test case it should be mentioned that after the setup region (StartAndLogin) 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 (AddEntry) the second instance of the Find module with
the subsequent ValidateEntry 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 SaveAndClose module group is executed anyway.
150
Lesson 6: UI Mapping with Ranorex Repository
Note: To prevent the recorder from stopping the run on failing the validation (intentional) please have a
look at Lesson 5: Ranorex Recorder - Continue On Fail and Disable and enable continuing on fail.
You can create a repository item using a RanoreXPath which delivers multiple UI elements. This might be very
helpful, for example, if you want to validate the visibility of any element among a great number of checkboxes on a
configuration form. This is mainly used by code modules if you do not want to have a list of hundreds of repository
items representing a single checkbox each.
Figure 212: RanoreXPath delivering multiple results (All buttons from the toolbar in KeePass)
Screencast: This scenario is presented in the screencast Code Modules - Benefits and Use Cases. Please
follow the link to watch it now: http://youtu.be/4k-lcNxQd2U#t=3m28s it will open at the position in
which this topic is covered.
Use the Ranorex Spy to prepare a RanoreXPath with multiple result elements and add it to the repository as described
in the previous section.Repository items delivering a list of elements can be used in code modules as described in
Create a List of Adapters From a Repository Element.
151
Lesson 6: UI Mapping with Ranorex Repository
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 specific timeout
value. Use the context menu item Properties to open the properties for the application folder for the Log In dialog.
152
Lesson 6: UI Mapping with Ranorex Repository
In order to see what happens when the timeout value does not match the situation, set the dialogs 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.
Figure 215: Test case execution failed - LoginWindow was not found within the specified timeout of 10ms
Note: In order to restore your repository into a working condition, reset the search timeout value for the
login dialog to 30 seconds.
You can also use the timeout approach to wait for text states such as dynamically changing text values. KeePass
provides the functionality to copy a username or a password to the clipboard in a time limited manner (12 seconds by
default). During that time, the status text in the application changes indicating that confidential information is kept
in the clipboard. After 12 seconds the clipboard is cleared of the information; this is indicated by the status text
Ready. The timeout value from the repository items can also be used to wait for a specific state or property of any
item (e.g. text changes to Ready).
To demonstrate the functionality of waiting for a particular UI element state, create a new test case (e.g. ClipBoard-
TestCase) containing the recording modules StartSUT, Login as well as Save and CloseSUT. Between those
two blocks insert a new recording module ValidateClipBoard.
153
Lesson 6: UI Mapping with Ranorex Repository
Figure 216: Insert a new recording module after the LogIn recording
After confirming that KeePass is in a suitable state (opened, logged in, containing one data set) use the record button
from Ranorex Studio (choose Instant Recording and complete the following steps)
Validate the status text Ready after the highlight frame appears
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.
154
Lesson 6: UI Mapping with Ranorex Repository
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 required for 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.
Press <ENTER> to change the RanoreXPath expression of an item using the edit mode or open the Path Editor by
clicking the Edit button.
155
Lesson 6: UI Mapping with Ranorex Repository
Use the path editor to select alternative attributes or to combine multiple attributes for unique UI element identification.
Additionally, 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 9: Ranorex Spy - The Path Editor.
After changing the identification attribute from AccessibleName to Text you can quickly verify the new RanoreXPath
using Highlight element as shown below.
Figure 220: Highlight the modified element to check the modified path
156
Lesson 6: UI Mapping with Ranorex Repository
157
Lesson 6: UI Mapping with Ranorex Repository
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:
Another reason to build a separate repository could be to store advanced RanoreXPath expressions which should
exclusively be used to create new actions manually instead of recording them.
Multiple Testers on the Same Project
As long as youre working alone on a test automation project its 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.
Ranorex Studio is able to handle multiple repositories. When performing automated tests on the KeePass application,
this could be useful for testing the complex configuration dialog with a separated repository file to keep your repositories
simple and structured and to provide for possibility of multiple users working on different repository files.
Add a new repository to your project by clicking the Add Repository button in the Ranorex Studio toolbar.
158
Lesson 6: UI Mapping with Ranorex Repository
Figure 223: New repository representing the complex options dialog in KeePass
Screencast: There is a screencasts that specifically explains why and how to use multiple repositories in a
single Ranorex Project. You can find that video here: http://youtu.be/WYlGt-IG5Uo.
Note: Its crucial to understand that repositories are essential in working with Ranorex and that the basic
principle does not depend on the technology used.
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 doesnt matter which technology is behind your test cases. Of course, different technologies
can be tested and combined within one test automation project in Ranorex Studio.
Now your test project contains two repository files. While a recording module can only have one repository assigned,
a code module can use multiple repositories.
159
Lesson 6: UI Mapping with Ranorex Repository
C#
[ TestModule ( " C5B0C011 -274 A -4 E54 -83 DB -0 CE28DB95509 " , ModuleType . UserCode , 1) ]
public class O p t i o n s C o d e M o d u l e : ITestModule
{
// Repository object to access UI elements of KeePass Application
M y F i r s t T e s t P r o j e c t R e p o s i t o r y repo = M y F i r s t T e s t P r o j e c t R e p o s i t o r y . Instance ;
// Repository object to access UI elements of KeePass Options Dialog
K e e P a s s O p t i o n s R e p o s i t o r y OptionsRepo = K e e P a s s O p t i o n s R e p o s i t o r y . Instance ;
// / < summary >
// / Constructs a new instance .
// / </ summary >
public O p t i o ns C o d e M o d u l e ()
{
// 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 =" T e s t M o d u l e R u n n e r . Run ( ITestModule ) " > method
// / that will in turn invoke this method . </ see > </ remarks >
void ITestModule . Run ()
{
Mouse . D ef a ul tM ov e Ti me = 300;
Keyboard . D e f a u l t K e y P r e s s T i m e = 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 . C h e c k B o x C l i p b o a r d _ a u t o _ c l e a r . Checked = true ;
}
}
VB.NET
< testmodule ( " baa60b6c -5 dd1 -4 eb5 - bc39 - fdfd65775742 " , moduletype . usercode ,= " " 1) = " " > _
Public Class Us e rC od eM o du le 1
Implements ITestModule
Repository object to access UI elements of KeePass Application
Private repo As M y F i r s t T e s t P r o j e c t R e p o s i t o r y = M y F i r s t T e s t P r o j e c t R e p o s i t o r y .
Instance
Repository object to access UI elements of KeePass Options Dialog
Private OptionsRepo AS K e e P a s s O p t i o n s R e p o s i t o r y = K e e P a s s O p t i o n s R e p o s i t o r y . Instance
< summary >
Constructs a new instance .
</ summary >
Public Sub New ()
Do not delete - a parameterless constructor is required !
End Sub
Test Reposito ry repo = TestRep ository . 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 =" T e s t M o d u l e R u n n e r . Run ( Of ITestModule ) " > method
that will in turn invoke this method . </ see > </ remarks >
Sub Run () Implements ITestModule . Run
Mouse . D ef a ul tM ov e Ti me = 300
Keyboard . D e f a u l t K e y P r e s s T i m e = 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 . C h e c k B o x C l i p b o a r d _ a u t o _ c l e a r . Checked = true
End Sub
End Class
</ testmodule ( " baa60b6c -5 dd1 -4 eb5 - bc39 - fdfd65775742 " ,>
160
Lesson 6: UI Mapping with Ranorex Repository
Within the Current 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 class name and namespace of newly created
repositories. Additionally, the timeouts used for newly created repository folders and items can be changed in the
Timings for new entries group box.
The setting 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.
161
Lesson 6: UI Mapping with Ranorex Repository
In some situations, repository items cannot be found because the caching information of the items parent folder is
incorrect. In such cases, replaying the steps involving these items may only work part of the time or only with long
delays. This is caused by a fallback mechanism which is used to search for an item without using the cache if the
first attempt fails. If this occurs, it is recommended to disable the folder cache for the items ancestor folders by
setting the Use Cache property to False.
162
Lesson 6: UI Mapping with Ranorex Repository
These properties can be altered by opening the properties tab which can be accessed by right-clicking the desired
repository item and choosing Properties in the context menu.
163
Lesson 6: UI Mapping with Ranorex Repository
Absolute Path The Absolute Path represents the path to the repository item including the paths of all
parent folders. This property is read-only.
Adapter Type 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 property to default.
Effective Timeout The Effective Timeout property represents the sum of the search timeouts for the specific
repository item and all its parent folders. This property is read-only.
Comment Using the comment property, the repository item can be described textual.
Live Element The Live Element represents the element specified by the repository item found in the live
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 an exception is thrown.
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:
164
Lesson 6: UI Mapping with Ranorex Repository
Use Cache The Use Cache property will either enable or disable caching for the specific folder. The chapter
Repository Troubleshooting - Folder Caching will give more information about folder caching.
165
Lesson 7: Code Modules
Screencast: In addition to going through the explanations below, you can have a look at the screencast
Code Modules - Benefits and Use Cases which provides a good overview of reasons for switching to the
code level and how do this well. The screencast can be found here: http://youtu.be/4k-lcNxQd2U
Figure 230: Adding a new code module with the toolbar button
Alternatively you are able to add a new code module by using the context menu in the Test Suite.
166
Lesson 7: Code Modules
Figure 231: Adding a new code module using the context menu
Figure 232: Specifying the name used for the code module
After clicking the Create 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#
namespace KeePass
{
// / < summary >
// / Description of A d d C r e d e n t i a l E n t r y .
// / </ summary >
[ TestModule ( " 03 F5603B -0 DDC -49 AA -8 C26 -4 D8088260C66 " , ModuleType . UserCode , 1) ]
public class A d d C r e d e n t i a l E n t r y : ITestModule
{
// / < summary >
// / Constructs a new instance .
// / </ summary >
public A d d C r e d e n t i a l E n t r y ()
{
// Do not delete - a parameterless constructor is required !
}
// / < summary >
167
Lesson 7: Code Modules
VB.NET
Namespace KeePass
< summary >
Description of A d d C r e d e n t i a l E n t r y .
</ summary >
< TestModule ( " 03 F5603B -0 DDC -49 AA -8 C26 -4 D8088260C66 " , ModuleType . UserCode , 1) > _
Public Class A d d C r e d e n t i a l E n t r y
Implements ITestModule
< 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 =" T e s t M o d u l e R u n n e r . Run ( ITestModule ) "/ > method
that will in turn invoke this method . </ remarks >
Private Sub IT e st Mo du l e_ Ru n () Implements ITestModule . Run
Mouse . D e fa ul tM o ve Ti me = 300
Keyboard . D e f a u l t K e y P r e s s T i m e = 100
Delay . SpeedFactor = 1.0
End Sub
End Class
End Namespace
C#
public class A d d C r e d e n t i a l E n t r y : ITestModule
{
// Repository object to access UI Elements
M y F i r s t T e s t P r o j e c t R e p o s i t o r y MyRepo = M y F i r s t T e s t P r o j e c t R e p o s i t o r y . Instance ;
// / Constructs a new instance .
public A d d C r e d e n t i a l E n t r y ()
{
// Do not delete - a parameterless constructor is required !
}
void ITestModule . Run ()
{
Mouse . D e fa ul tM o ve Ti me = 300;
168
Lesson 7: Code Modules
Keyboard . D e f a u l t K e y P r e s s T i m e = 100;
Delay . SpeedFactor = 1.0;
// Click Add Entry Button MainMenu
MyRepo . MainForm . Edit . Click () ;
MyRepo . KeePass . AddEntry . Click () ;
// Set text fields
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . Title . TextValue = " WordPressDemo " ;
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . UserName . TextValue = " admin " ;
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . Password . TextValue = " demo123 " ;
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . Repeat . TextValue = " demo123 " ;
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . URL . TextValue = " bitly . com / wp_demo " ;
// Choose an icon
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . MBtnIcon . Click () ;
MyRepo . IconPicker . LI_Icon . Click ( Location . CenterLeft ) ;
MyRepo . IconPicker . ButtonClose . Click () ;
// Set Expires
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . M B t n S t a n d a r d E x p i r e s . Click () ;
MyRepo . KeePass . MI_Expires . Click () ;
// Save Credential Entry
MyRepo . AddEntry . ButtonOK . Click () ;
}
}
VB.NET
Public Class A d d C r e d e n t i a l E n t r y
Implements ITestModule
Repository object to access UI Elements
Private MyRepo As M y F i r s t T e s t P r o j e c t R e p o s i t o r y = M y F i r s t T e s t P r o j e c t R e p o s i t o r y . Instance
Constructs a new instance .
Do not delete - a parameterless constructor is required !
Public Sub New ()
End Sub
Private Sub IT e st Mo du l e_ Ru n () Implements ITestModule . Run
Mouse . D ef a ul tM ov e Ti me = 300
Keyboard . D e f a u l t K e y P r e s s T i m e = 100
Delay . SpeedFactor = 1.0
Click Add Entry Button MainMenu
MyRepo . MainForm . Edit . Click ()
MyRepo . KeePass . AddEntry . Click ()
Set text fields
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . Title . TextValue = " WordPressDemo "
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . UserName . TextValue = " admin "
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . Password . TextValue = " demo123 "
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . Repeat . TextValue = " demo123 "
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . URL . TextValue = " bitly . com / wp_demo "
Choose an icon
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . MBtnIcon . Click ()
MyRepo . IconPicker . LI_Icon . Click ( Location . CenterLeft )
MyRepo . IconPicker . ButtonClose . Click ()
Set Expires
MyRepo . AddEntry . T a b S h e e t A d d E n t r y . M B t n S t a n d a r d E x p i r e s . 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 projects view.
Now the class uses a private member to refer to the repository in order to reuse some of the objects (Title, Username,
Password, PasswordRepeat and URL) within the Run method.
169
Lesson 7: Code Modules
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#
var ButtonOK = MyRepo . FormAdd_Entry . ButtonOK ;
ButtonOK . Click () ;
VB.NET
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.
Note: Screenshots will be captured automatically if you chose to record image based. Get more information
here: Image-Based Automation.
170
Lesson 7: Code Modules
C#
// get the screenshot from the repository
Bitmap MyScreenshot = MyRepo . IconPicker . LI_IconInfo . G e t S c r e e n s h o t _ I c o n () ;
// create FindOptions with similarity set to 95%
Imaging . FindOptions MyFindOptions = new Imaging . FindOptions (0.95) ;
// compare the captured screenshot with the actual list item
Validate . CompareImage ( MyRepo . IconPicker . LI_Icon , MyScreenshot , MyFindOptions ) ;
VB.NET
get the screenshot from the repository
Dim MyScreenshot As Bitmap = MyRepo . IconPicker . LI_IconInfo . G e t S c r e e n s h o t _ I c o n ()
create FindOptions with similarity set to 95%
Dim MyFindOptions As New Imaging . FindOptions (0.95)
compare the captured screenshot with the actual list item
Validate . CompareImage ( MyRepo . IconPicker . LI_Icon , MyScreenshot , MyFindOptions )
Note: Using the FindOptions, you can set custom values like similarity. This option allows you to define
the minimum similarity that the image region to search for needs to have in common with the screenshot in
order to be considered a match. For further details have a look at Lesson 5: Ranorex Recorder - Image-Based
Automation.
171
Lesson 7: Code Modules
Figure 236: Specify the variable name and the default value
By adding a new variable Ranorex Studio inserts a new code fragment at the current cursor position. A variable
implementation consists of a public property <VariableName> and a private member <VariableName>.
C#
string _varTitle = " Wordpress Credentials " ;
[ TestVariable ( " 9348 A7E6 -80 B6 -4 A2B -9 CBF -0276 A236AA3E " ) ]
public string varTitle
{
get { return _varTitle ; }
set { _varTitle = value ; }
}
VB.NET
Private _varTitle As String = " Wordpress Credentials "
< TestVariable ( " 9348 A7E6 -80 B6 -4 A2B -9 CBF -0276 A236AA3E " ) > _
Public Property varTitle () As String
Get
Return _varTitle
End Get
Set
_varTitle = value
End Set
End Property
172
Lesson 7: Code Modules
Now create additional variables for the Username, Password and URL. All the module variables will appear
immediately in the module browser.
To bind repository variables to external data when accessing the repository element via the code module, you have to
create a new module variable to act as a bridge. You can use the setter method for the public variable to also set the
repository variable.
Variables used by the repository (e.g. varExpires for the Menu Item in the context menu of KeePasss 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 variables 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 property. 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 assigning the passed value to the repository variable and facilitates binding to external data.
C#
string _ v a r R e po I c o n I n d e x = " 1 " ;
[ TestVariable ( " EF09BC93 -3447 -4 AC2 -9 DEB - FE3D78ED5538 " ) ]
public string va r R e p o I c o n I n d e x
{
get { return _ v a r R e p o I c o n I n d e x ; }
set {
_ v a r R e p o I c o n I n d e x = value ;
// Additionally set the Repository Variable in Setter - Method
MyRepo . varIconIndex = _ v a r R e p o I c o n I n d e x ;
}
}
string _ va r Re po Ex p ir es = " 1 Year " ;
173
Lesson 7: Code Modules
VB.NET
Private _ v a r R e p o I c o n I n d e x As String = " 1 "
< testvariable ( " ef09bc93 -3447 -4 ac2 -9 deb - fe3d78ed5538 " ) > _
Public Property v a r R e p o I c o n I nd e x () As String
Get
Return _ v a r R e p o I c o n I n d e x
End Get
Set
_ v a r R e p o I c o n I n d e x = value
Additionally set the Repository Variable in Setter - Method
MyRepo . varIconIndex = _ v a r R e p o I c o n I n d e x
End Set
End Property
Private _v ar R ep oE xp i re s As String = " 1 Year "
< testvariable ( " d0a54427 -68 ff -4 b9d - b861 -4882 bcec846b " ) > _
Public Property varR epoExpi res () As String
Get
Return _ va r Re po Ex p ir es
End Get
Set
_ va rR ep o Ex pi re s = value
Additionally set the Repository Variable in Setter - Method
MyRepo . varExpires = _ v ar Re po E xp ir es
End Set
End Property
</ testvariable ( " d0a54427 -68 ff -4 b9d - b861 -4882 bcec846b " ) > </ testvariable ( " ef09bc93 -3447 -4 ac2 -9 deb
- fe3d78ed5538 " ) >
Thus the two columns in the Excel file can be bound to these module variables. This binding causes the variables
to be set for each iteration in the test case. When setting those variables, the extended functionality also sets the
repository variable assuring that the correct icon will be used and clicked in our example.
174
Lesson 7: Code Modules
Figure 238: 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.
Figure 239: Reuse the existing data connector by choosing the item from the drop-down
175
Lesson 7: Code Modules
Figure 240: Bind the newly created variables to the data connectors columns, i.e. columns from the Excel file
176
Lesson 8: Reporting
Lesson 8: Reporting
By default, each run of a test suite, test case or single module 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:
Report Levels
The auto save interval for a report is configured in the properties of the test suite. Open up the properties of the
current test suite and switch to tab page Report. In field Auto Save Interval you can set the interval in seconds.
177
Lesson 8: Reporting
Figure 242
In case you execute a test module, which is in a project without a test suite, the auto save interval is 30 seconds by
default.
178
Lesson 8: Reporting
The report shown after running a test suite provides a general overview of how many of the test cases have been
executed successfully, have failed or have been blocked. Each executed test case and all its child modules can be
analyzed in depth by expanding a particular test case.
In addition to that, a test suite report also informs you about the following:
System information like execution time, machine name, operating system, screen dimensions, language, duration,
total errors, total warnings
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.
179
Lesson 8: Reporting
The detailed 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
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.
Expand the report as shown above and move the mouse pointer over the first log message.
Figure 245: Debug a test run with quick links Jump to Item and Open in Spy
Click at Jump to Item to open the module and to select the corresponding action. 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. Move the mouse cursor over a test case and
click on Jump to Test Case to select the corresponding test case in the test suite.
Use the checkboxes shown at the top of each module to filter log messages.
180
Lesson 8: Reporting
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
projects 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 Settings.
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 youre going to copy or send the file by email, it is recommended to use the zipped
report as described in Test Suite Settings.
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.
Report Levels describe the importance of a message that is delivered to the report. Using different kinds of report
levels can help you keep your reports short and better readable.
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
cases report level could assist you in finding errors in your testing scenario.
181
Lesson 8: Reporting
Ranorex provides the following predefined report levels - the level itself is indicated by integer values (which are
written in parenthesis):
Debug (10)
Info (20)
Warning (30)
Error (40)
Success (110)
Failure (120)
The first five items describe different levels of importance for report messages. 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 using a message with a yellow background.
Figure 249: A message indicating the existence of warning messages inside a test case
Note: A test cases failure depends on the success of its child elements which can either be modules or nested
test cases. A module fails when an exception is thrown or a failure message is being logged. Exceptions are
typically thrown by failed validation actions, by searching for nonexistent elements or by an explicit call at
code level.
In addition to predefined report levels, you are able to define your own report level with a custom importance value.
You can do that either from code or within the Recorder (see Logging Individual Information for detailed information).
182
Lesson 8: Reporting
You can use one of the following methods from the Ranorex Report class in order to report information at a specific
level:
Ranorex.Report.Success(Success Message);
Ranorex.Report.Failure(Failure Message);
Category
These methods can be used with a single parameter, the message text. 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.DefaultCategory property.
The category can be seen in a distinct column in the report. The following code lines demonstrate different reporting
methods (and different reporting categories), resulting in the report shown after the code example.
C#
// 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 warning 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 . De f au lt Ca t eg or y = " 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
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 warning 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 . De f au lt Ca t eg or y = " 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 " )
183
Lesson 8: Reporting
Figure 250: Report with different reporting methods and categories indicating the different levels of importance
Note: Please consider that the report information at the failure level provides a screenshot automatically
(if tracing screenshots is enabled). In order to visually retrace the last steps that lead to the current error,
screenshots will be provided for the last three actions.
You are able to define your own report levels with a custom name and a value for the level:
C#
Ranorex . ReportLevel M yN ewR ep or tL ev el = new ReportLevel ( " My low Report Level " , 25 , null ) ;
Ranorex . Report . Log ( MyNewReportLevel , " This is unimportant information " ) ;
VB.NET
Dim M y N e w R e p o r tL ev el 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 the user-defined report level
should appear in the report as follows:
184
Lesson 8: Reporting
Report information will only appear in the report if its report level is higher than or equal to the current report
information level from the parents test case. The current report level can also be set using code:
C#
Ranorex . Report . C ur r e n tR e p o rt L e v el = Ranorex . ReportLevel . Parse ( " Only Highest Importance ;90 " ) ;
VB.NET
" Ranorex . Report . C ur r e n tR e p o rt L e v e l = 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#
Ranorex . Report . Log ( Ranorex . ReportLevel . Always , " User " , " Any - Case message " ) ;
185
Lesson 8: Reporting
VB.NET
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#
Ranorex . Report . Screenshot ( MyRepo . KeePass . Toolbar . Self ) ;
VB.NET
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. Controlling your application using code does not necessarily bring your application to the front and
make it 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.).
Consequently, 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).
The Ranorex reporting class provides a way to simply report a system summary:
C#
Ranorex . Report . SystemSummary () ;
VB.NET
Ranorex . Report . SystemSummary ()
186
Lesson 8: Reporting
The Ranorex Recorder provides a way to send information directly to the report. Just use the Add New Action
button from the toolbar and add a LogMessage Action.
187
Lesson 8: Reporting
188
Lesson 8: Reporting
Just like a call from code, you can specify one of the predefined report levels directly within the recorders actions
table.
Report messages with a custom report level can also be submitted. Simply choose the Custom report level in the
drop-down.
Since Ranorex Version 3.3, you can send screenshots and even snapshots to your report directly from the recorders
actions table. These two actions require a connection to a repository item in order to specify from which object the
screenshot or snapshot should be made.
Figure 258: Usage of the report action using the screenshot and the snapshot action type
189
Lesson 8: Reporting
Clicking on the warning will open a resolve dialog. In this dialog you can choose to either copy the custom report to a
template folder and use this folder as report template, or to use the default report template.
190
Lesson 8: Reporting
A new report template folder has automatically been created at <Project Folder>\NewCustomTemplate.
The newly created files can be shown in project view by pressing the Show All Files button.
Note: Press the Refresh button to ensure that the new created folder will be shown.
Open the file RanorexReport5.css to edit the style of the report according to your wishes.
191
Lesson 8: Reporting
Open the file RanorexReport5.xsl to edit the structure of the report according to your wishes.
Open the file View.rxlog to get a preview of your customizations using some sample data.
192
Lesson 9: Ranorex Spy
Tracking UI Elements
RanoreXPath Edit Mode
The Path Editor
Creating Ranorex Snapshot Files
The element browser tree shown on the left side represents the computers desktop with all currently opened
applications. The name of the root node is set to the machines 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 an adapter as described in 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 Control, Accessible or NativeWindow
193
Lesson 9: Ranorex Spy
Figure 265: Ranorex Spy Overview tab divided into three attribute sections
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.
Regardless of what technology is used from the application under test, Ranorex tries to abstract it with logical
adapters as explained in Ranorex UI Adapter. These adapters are also used within repositories and provide class
specific attribute values like the text value or the state of a checkbox.
This type of adapter is used to group technology related information like the ControlName of a .NET WinForms
button or the process name of an application.
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
194
Lesson 9: Ranorex Spy
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 The Path Editor to change element identification or edit the path
expression directly within the text boxs RanoreXPath Edit Mode.
Note: You are able to access common text functionality like Select All (<CTRL>+A), Copy (<CTRL>+C),
Cut (<CTRL>+X), Paste (<CTRL>+V), Undo (<CTRL>+Z) or Delete (<DEL>) in RanoreXPath.
Another way to navigate through the element tree is to use the image navigator which can be found at the bottom of
the Overview/Detail tab.
195
Lesson 9: Ranorex Spy
At the top of the image navigator you can see the adapter type and the name of the currently selected UI element.
By moving the mouse over a specific child element of the currently selected element, you will see the adapter type
and its name. Clicking a UI element selects it, double-clicking outside the selected element selects the parent.
196
Lesson 9: Ranorex Spy
Attribute comparisons may also be combined with and and or operators (e.g. button[@text=OK and @en-
abled=true]).
197
Lesson 9: Ranorex Spy
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.
198
Lesson 9: Ranorex Spy
Toolbar shortcuts
Browse Local Host Shows currently running host applications
Connect to a Mobile Device Opens the Manage Devices dialog
Refresh Updates the current state of applications
Load from Snapshot Loads an existing Ranorex snapshot file
Save as Snapshot Saves the currently selected node and all its descendants to a Ranorex snapshot
file
Highlight Elements When switched on, highlights selected UI elements on the users desktop
Update Path Sets the path from the currently selected element
Context menu
Update Path Sets the path from the currently selected element
Set Element as Root Sets the currently selected element as root element
Highlight Element Highlights the current element
Add to Repository Adds the current element to a Ranorex Repository
Add to Repository (incl. Children) Adds the current element and the elements children to a
Ranorex Repository
Add Matching Children to Repository Adds all UI elements matching the given RanoreXPath
to the Repository
Update Element Data Updates all attributes of the specified UI element
Save as Snapshot. . . Saves the current UI element including the child structure
to a Ranorex snapshot file
199
Lesson 9: Ranorex Spy
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 How
to do image based automation and How to find and compare images.
200
Lesson 9: Ranorex Spy
Tracking UI Elements
You can navigate manually through the Ranorex Spys element tree or use element tracking to identify UI elements in
your application under test. The Ranorex Spy supports two ways of tracking UI elements:
Instant Tracking
Click the TRACK button to start tracking a UI element. Move your mouse pointer over a specific control (e.g.
button, text box) so that the currently identified object is highlighted. By clicking the control, the tracking mode will
be stopped and all information on the selected UI element will be shown within Ranorex Spy.
Note: To abort the tracking session press <ESC> or click the TRACK button again.
Note: Holding the <F12> key temporarily disables the tracking mechanism.
In some cases it might be necessary to track UI elements which are currently behind the Ranorex Spy window. Simply
uncheck the Always On Top checkbox to cause Ranorex Spy to minimize during the tracking process.
201
Lesson 9: Ranorex Spy
Instant Tracking
When tracking menu or pop-up items, you use the Instant Tracking method by using a shortcut to select a UI
element. Simply move your mouse pointer over a menu item and press the <CTRL> + <Win> key combination to
instantly track the UI element. Instant Tracking is not only available for popup items, it can be used for any UI
element.
202
Lesson 9: Ranorex Spy
The RanoreXPath editor mode is indicated by a yellow background color. In edit mode, RanoreXPath is used as a
query to filter UI elements as follows:
203
Lesson 9: Ranorex Spy
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 Children to Repository.
204
Lesson 9: Ranorex Spy
To stop the edit mode, click the red cancel button which is located in the RanoreXPath edit box or press the
<ESC> key.
205
Lesson 9: Ranorex Spy
206
Lesson 9: Ranorex Spy
Types of Comparisons
Relationship Operators
Adapter Types
Defining Variables
As you might know, the RanoreXPath expression is a powerful identifier of UI elements for desktop and Web
applications. To learn more about the RanoreXPath have a look at the section RanoreXPath.
Its this easy: Everywhere a RanoreXPath is visible in a Ranorex Tool you can edit this RanoreXPath with the path
editor.
You can access the path editor by choosing any UI Element in the repository and then clicking the Edit button on
the left of the RanoreXPath, or alternatively by pressing the key shortcut <CTRL><E>.
Figure 278: Click the Edit button to open the path editor
In Ranorex Spy, the path editor can be accessed by simply switching to the PATH EDITOR tab.
207
Lesson 9: Ranorex Spy
The editor can be broken down into two main areas: the RanoreXPath shown in a tree view on the left (marked in
green) and the attribute comparison list of the selected tree item on the right (marked in red).
208
Lesson 9: Ranorex Spy
Additionally you can see the number of identified UI elements using the given RanoreXPath in the status bar. Buttons
to refresh and to highlight the identified elements can be found right above the tree view and the original RanoreXPath
can be found at the top of Ranorex Spy, right below the modified one.
As you can see, the whole path is shown in this tree structure with each path element being a node of the tree. In the
left section of the editor, you can access each of these path elements to alter the attribute comparisons in the right
section on which the path is based.
After altering the RanoreXPath, you can review the effects by pressing the refresh and highlight buttons and apply
the changes using the Apply button next to the RanoreXPath at the top of Ranorex Spy.
Of course you can change the RanoreXPath by using the Track button, too. To simplify tracking, the tracking area
is limited to the parent folder of the selected repository item (grayed out in RanoreXPath at the top of Ranorex Spy),
which will be indicated with a yellow border.
209
Lesson 9: Ranorex Spy
As described above you can see the whole RanoreXPath you want to edit mapped as a tree structure. For example if
you start KeePass and add two entries, one called WordPressDemo and the other called GMail and you track the
cell holding the username of GMail, you will get the following tree structure in the path editor:
210
Lesson 9: Ranorex Spy
Figure 282: KeePass with one cell being tracked by Ranorex Spy
Figure 283: RanoreXPath structure in path editor for a cell in second row
211
Lesson 9: Ranorex Spy
In the attribute comparison section of the path editor you can define the attribute value comparison which the
RanoreXPath is based on. If you want to define the adapter being accessed with different attributes than the ones
being suggested by Ranorex, you are free to change the method of object identification here by simply checking and
unchecking attributes.
Concerning KeePass and the data-driven approach (see Lesson 3: Data-Driven Testing) we validated the success
of Adding an entry with the validation of the existence of the entry in the grid. Thus we add two sample entries
(WordPressDemo and GMail) to KeePass. When Ranorex Spy is used to track the username of the GMail entry
(second cell in the second row), the following structure of RanoreXPath results in the path editor window:
/ form [ @controlname = MainForm ]/ container [ @controlname = m \ _ s p l i t H o r i z o n t a l ] // table [
@controlname = m \ _lvEntries ]/ row [ @index = 1 ]/ cell [ @text = Ranorex ]
What we can see in the RanoreXPath structure (in path editor) as well as in the RanoreXPath itself is that the row
(adapter) is identified by its index attribute (row[@index=1]). This means that the cell Ranorex is only recognized
if it is located in the second row. This cell would not be found if an additional row was inserted above and the
index was changed. Sorting by a column (e.g. column username) could easily lead to another row index. To avoid a
problem concerning the row index, you could change the path with the use of the path editor to be row independent
by unchecking the index attribute checkbox in the row node.
212
Lesson 9: Ranorex Spy
This path leads to any cell in any row containing the text Ranorex. Concerning 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 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 multiple results.
You can easily check the result of your RanoreXPath in path editor by having a look at the text in the bottom left
corner.
213
Lesson 9: Ranorex Spy
To find out which elements are found with the current RanoreXPath, simply click on the Highlight button on the
bottom of path editor.
214
Lesson 9: Ranorex Spy
As you can see, building up a robust and unique path is a crucial task which always depends on the characteristics of
your application.
Types of Comparisons
Ranorex provides a set of comparisons which can be used to build up or to modify a RanoreXPath. These comparison
operators can be accessed via a drop-down in path editor.
Textual Comparisons The following types of comparisons are defined for textual comparisons (case sensitive):
Numerical Comparisons The following types of comparisons 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 comparisons 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.
215
Lesson 9: Ranorex Spy
Example for Regular Expression The following example shows how to use a regular expression operator ().
Figure 288: Matches all entries ending with the text fragment rex using a regular expression
Note: For more details about regular expressions, see RanoreXPath - RanoreXPath with Regular Expressions.
Example for Not Equal The following example shows how to use the not equal operator (!=).
Figure 290: Matches all entries that are not equal to Ranorex
216
Lesson 9: Ranorex Spy
Example for Starts With The following example shows how to use the starts with operator (>).
Example for Numerical Comparisons The following examples demonstrates how numerical operators (>, >=,
<and <=) can be used in the path Editor.
217
Lesson 9: Ranorex Spy
Figure 294: Matches all rows matching index > 2 and index <= 3
Relationship Operators
After exploring the comparison operators, you are going to learn more about the relationship operators. Relationship
operators define the relationship between the nodes (elements of the path). It is therefore not necessary to always use
a directed path. One element in the path can also be defined by 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.
218
Lesson 9: Ranorex Spy
descendant-or-self: Refers to all descendants (children, grandchildren, etc.) of the current node and the node
itself
ancestor: Refers to all ancestors (parents, grandparents, etc.) of the current node
descendant: Refers to all descendants (children, grandchildren, etc.) of the current node
ancestor-or-self: Refers to all ancestors (parents, grandparents, etc.) of the current node and the current
node itself
preceding-sibling: Refers to all siblings before the current node
The following example describes,how to change the common parent-child relationship in the path using relationship
operators (Axis), 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 wouldnt be possible. We start with the path referring to the cell:
/ form [ @controlname = MainForm ]/ container [ @controlname = m \ _ s p l i t H o r i z o n t a l ] // table [
@controlname = m \ _lvEntries ]/ row [ @index = 2 ]/ cell [ @text = Amazon ]
219
Lesson 9: Ranorex Spy
We can now move back to the cells parent using the parent relationship operator. The parent element is a row,
therefore we have to add a new level manually using the row adapter.
/ form [ @controlname = MainForm ]/ container [ @controlname = m \ _ s p l i t H o r i z o n t a l ] // table [
@controlname = m \ _lvEntries ]/ row [ @index = 2 ]/ cell [ @text = Amazon ]/ row
In the path editor we choose the relationship operator parent in the Axis submenu.
Figure 297: 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 level of hierarchy to the
parent of this cell, which is a row. Highlighting the element leads to the result shown in following figure.
Figure 298: Highlighting the element from the newly created path
220
Lesson 9: Ranorex Spy
Adapter Types
Adapters describe the type of element that is referred to. In the path editor you are able to change the adapter type
easily.
Adapters used within a path which are automatically suggested by Ranorex, can also be changed 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.
Starting with Ranorex Version 3.3 it is possible to mark some parts of a path as optional which means that the
referred elements can be found even if optional parts of the path do not exist.
In some situations it can be useful to mark parts of the path as optional. If you want to refer to the Windows node
within the folder tree in KeePass, this node can be located at the root level but, on the other hand, it could also be
located in a sub node of the tree.
221
Lesson 9: Ranorex Spy
Figure 300: Windows node located at the root level (left) or. . .
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 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.
222
Lesson 9: Ranorex Spy
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 and assigned in the path editor.
If you start the path editor from an existing repository, there is an additional button for each (selected) attribute
comparison. With these buttons you are able to define variables which can be used for data driven object identification.
223
Lesson 9: Ranorex Spy
Figure 303: Buttons for creating a new variable for every selected attribute
224
Lesson 9: Ranorex Spy
Figure 304: Variables can also be created using the As new Variable entry in the dropdown menu
225
Lesson 9: Ranorex Spy
The variables you have added are placed in the repository you are working on. Each of the variables held by the
repository can be used as a value for attribute comparison. For more details about variables used within the repository,
please have a look at Lesson 3: Data-Driven Testing - Using Variables within the Repository.
One additional thing to mention is that if you are in live view, you get more information delivered about the adapter
you are working on than in offline view.
Offline view means working with a snapshot file or working with a repository holding information from a non-running
application.
Note: A Ranorex Snapshot file is able to keep the entire UI structure, the UI elements attributes and its
belonging values as well as screenshots from the desired element and all its child elements. Learn more in the
chapter: Creating Ranorex Snapshot Files.
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).
226
Lesson 9: Ranorex Spy
Figure 305: Path editor window in live view having dynamic capabilities
227
Lesson 9: Ranorex Spy
Note: Dynamic capabilities can only be accessed for certain types of technologies (WinForms, Flash/Flex,
Web and Java).
228
Lesson 9: Ranorex Spy
229
Lesson 9: Ranorex Spy
230
Lesson 9: Ranorex Spy
Figure 307: Ranorex Spy tool with opened snapshot file from KeePass
231
Lesson 9: Ranorex Spy
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.
For creating a snapshot from the File menu pop-up of KeePass, you can use the <SCROLL> key (keyboard) in
combination with the instant tracking feature of Ranorex Spy:
4. Press the <SCROLL> key to cache the current elements including their underlying items for Ranorex Spy.
5. Lastly save the current view as snapshot.
Another possibility of creating a snapshot from the File menu pop-up of KeePass is to use the TRACK button in
combination with the <F12> key which temporarily disables the tracking mechanism:
4. In the KeePass application open the File menu while holding the <F12> key.
5. After releasing the <F12> key track the parent menu container window of the menu items using the mouse
wheel to change the recognition level.
6. Reopen the menu and press the <SCROLL> key to cache the current elements including their underlying items
for Ranorex Spy.
7. Lastly save the current view as snapshot.
232
Lesson 9: Ranorex Spy
Figure 308: Track menu container window using instant tracking (<CTRL>+<Win>)
233
Ranorex Settings
Ranorex Settings
Settings in Ranorex
Use the Ranorex Settings to adjust the test automation software to the needs of your working environment, test
execution, project and technology.
You can find a full list of settings here: Settings Overview
Solution settings include all settings which relate to the test solution, such as plugins, RanoreXPath generation,
Ranorex Recorder defaults and many more, which can be shared between different systems, within teams and also be
put under Version control. Find out more here: Solution settings
To maintain settings (user settings and solution settings) stored locally on a machine, without having Ranorex Studio,
Ranorex Spy or Ranorex Recorder, do the following:
Start the Ranorex Settings executable from folder Bin in the Ranorex installation directory.
234
Ranorex Settings
235
Ranorex Settings
User settings
User settings are always stored on the local machine. In the Settings dialog, user settings are shown in regular font.
At the bottom of the Settings dialog, a short info text indicates how to differentiate user and solution settings and
the location they are stored in.
Figure 313
236
Ranorex Settings
Solution settings
Solution settings can be stored either in a solution or on the local machine. In the Settings dialog, solution settings
are shown in italic font.
At the bottom of the Settings dialog, a short info text indicates where the solution settings are currently stored.
Figure 314
Solution settings are automatically saved to the local machine and used during test execution, if:
237
Ranorex Settings
you work in Ranorex Studio and a solution is loaded, but the solution does not include solution settings.
you work in Ranorex Recorder, Ranorex Spy or Ranorex Settings (started as standalone tool).
The solution settings stored on the local machine are used as default for newly created solutions in Ranorex Studio.
The info text at the bottom of the Settings dialog indicates that the solution settings are stored on the local machine
(highlighted in red in the screenshot below).
Figure 315
238
Ranorex Settings
In newly created solutions, solution settings are automatically saved in the corresponding solution settings file and
used during test execution (starting with Ranorex 6.1).
In the following situations, the solution settings are automatically saved in its corresponding solution settings file and
used during test execution:
Ranorex Spy (as part of Ranorex Studio, opened with View Spy and EDIT at a repository item)
The info text at the bottom of the Settings dialog indicates that the settings are saved in the solution. The title of
the dialog shows which solution the settings are saved in (highlighted in red in the screenshot below).
239
Ranorex Settings
Figure 316
240
Ranorex Settings
The solution settings are saved in the settings file Ranorex.rxsettings, which is located in the Solution Items folder
of the corresponding solution.
Figure 317
Please note:
If you remove the settings file (Ranorex.rxsettings), the solution settings stored on the local machine are
automatically used during test execution.
If you open the settings file, it is shown in its raw format. It is not recommended to edit the file in this view.
If a solution does not contain a settings file, you can add it following these instructions: How to add a solution
settings file to a solution
The solution settings file Ranorex.rxsettings is automatically copied into the output directory of the test project. It
is saved in the same folder as the test executable. This is why the solution settings will be used for test execution.
Please note:
When deploying the test executable, make sure to include the solution settings.
If the solution settings are not stored in the same folder as the test executable, the solution settings from the local
machine will be used.
When selecting a solution for remote test execution, the solution settings saved in this solution will automatically be
sent to the Ranorex Agent and used during test execution.
If the solution does not include a solution settings file, the solution settings stored locally on the Ranorex Agents
machine will automatically be used during test execution.
241
Ranorex Settings
Settings Overview
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.
Specifies whether web elements should be identified using their unique id or not.
Specifies whether an exception should be thrown if the mouse/pointer tries to move outside the visible desktop bounds
or not.
242
Ranorex Settings
The factor that all timeouts of find operations are multiplied with
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 Running Tests without
Ranorex Studio or by directly using the Ranorex.Core.Configuration.Current.Adapter.TimeoutFactor
property in code.
Resets the Do not show again checkboxes used to suppress the assistance dialog for technology limitations. Click
Restore Limitation Warnings to show the dialog again for not instrumented technologies or applications.
Opens the dialog to change the current GDI capture list. More information about the Ranorex GDI plug-In can be
found at Testing of Legacy Applications.
Mobile Devices. . .
Opens the Manage Devices dialog as described in the sections iOS Testing and Android Testing.
Note: Click 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.
Advanced Settings
243
Ranorex Settings
Most of the settings shown in the Advanced tab 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.
Tries to capture screenshots used by recordings, repositories or Ranorex snapshot files, even from application windows
which are not in the foreground. If disabled, Ranorex tries to make the application window visible before capturing a
screenshot.
When checked, the subtree containing the whole application will be stored when saving a snapshot file. If not checked,
only the direct subtree to the selected item will be stored.
This setting is used to turn on or off asynchronous dispatching of mouse and keyboard events during recording. With
enabled asynchronous dispatching mouse and keyboard events will not be forwarded to an application before Ranorex
has finished processing the event.
244
Ranorex Settings
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. This improves performance is some cases.
Specifies whether a UI element will be automatically selected in Ranorex Spy when the representing repository item
will be selected or not.
Specifies the time to wait in milliseconds before performing a key sequence simulation.
Defines how RanoreXPaths will be built during recording actions or tracking elements using the Ranorex tools (by
default, the mode StepCostReduce is selected).
StepCostReduce Reduces the number of path predicates such that the path remains non-ambiguous. In addition to
that, removes intermediate steps considered as unimportant. Can be heavily tuned using the RxPath.PathBuildMode
settings. This usually shortens the path and makes it more robust by eliminating unnecessary attributes.
Reduce Reduces the number of path predicates such that the path remains non-ambiguous. This usually shortens
the path and makes it more robust by eliminating unnecessary attributes.
Simple No optimization is performed. Path predicates contain valid, appropriate and existing attribute values or
indexes if no attributes can be used.
In order to get assistance with editing RanoreXPath weights, have a look at the blog post Automated Testing and
Dynamic IDs. Please also have a look at our RanoreXPath Weight Rule Library for the latest RanoreXPath Weight
Rules.
Recorder Settings
The description of the settings regarding the Ranorex Recorder can be found in the Recorder Settings Dialog in Lesson
5: Ranorex Recorder.
245
Ranorex Settings
Repository Settings
The description of the settings regarding the Ranorex Repository can be found in the Repository Settings Dialog in
Lesson 6: UI Mapping with Ranorex Repository.
Imaging Settings
The Imaging settings are explained in the section Image-Based Automation in Lesson 5: Ranorex Recorder.
246
Ranorex Settings
Plugin specific settings can be used to alter the behavior of individual Ranorex plugins, for example, to achieve
backwards compatibility with older versions.
Java
Enable filtering on the Fx scenegraph Filters dummy and intermediate containers out of the Fx scenegraph.
Show SWT custom data properties Includes SWT custom Widget Data values as dynamic properties.
Use Java SWT legacy automation mode Enable Java SWT legacy automation mode using MSAA and Win32
Whitelisted class names Adds additional whitelisted class names (comma separated) for java object recognition.
Mobile
Auto reconnect attempts When the connection to a device is lost Ranorex tries to reconnect automatically. With
this parameter you can specify how many reconnect attempts should be made until the device will be set to the Error
state. If you dont want to reconnect automatically, set this parameter to 0.
Connect timeout After this time span the connection attempt will be aborted if the device is not reachable.
247
Ranorex Settings
Deploy timeout Sets the timeout for deploying an mobile app. The required time depends on your application
size and the deploy method. Deploying an app takes longer when deploying via network.
Devices This is used internally by the Ranorex system and is not user editable.
General timeout The timeout for short running background processes. This timeout is used for very short running
processes (less than 10 seconds in general). If you get a lot of timeout exceptions, that do not occur during special
operations like instrumentation or deploying, try to increase this value.
Instrument timeout Sets the timeout for instrumentation operations. A good initial value is 2 minutes. For very
large applications the time required for instrumentation can take up to 10 minutes depending on the machine power.
iOS: Maximum number of invisible children -1 will fetch all cells of UITable and UICollection views. Use this
setting only, when all views have a relatively small number of cells and static/finite data sources. 0 will disable
fetching of invisible cells. Generally you should use this setting, when data in your tables is loaded dynamically e.g.
from successive web requests. # (e.g. 50) will fetch all visible cells and the first 50 cells surrounding the visible cells
area.
Java Runtime installation path. The path of the currently used Java Runtime Environment (JRE) installation
required for Android automation.
Network discovery timeout Specifies for how long Ranorex sends UDP broadcasts to find devices that can be
used for automation. Normally, a device should respond within a few seconds.
Prompt on IP - address change If set to true, Ranorex will try to check if the IP-address of a device has changed
since the last usage and will show a message if so. By setting this parameter to false you can disable this check.
Remote call timeout The time Ranorex waits for a remote procedure call response until it assumes a connection
loss if no response was received.
Screenshots on AndroidOS Captures screenshots on AndroidOS screens. Disable to improve test execution
performance.
USB discovery timeout The timeout for discovering USB connected devices.
MSAA
Evaluate computationally expensive attributes Setting this value to true will instruct the plugin to evaluate
attributes that are expensive to compute and may result in longer delays when getting such attributes. Note that
spying an element with such expensive attributes may then take considerable time.
Filter elements Setting this value to false will make all MSAA elements available without filtering, including
elements being unavailable, invisible, or equivalent to elements of other flavors.
248
Ranorex Settings
Filter Windows Forms elements Setting this value to false will make MSAA elements available that are direct
children of Windows Forms elements and have the same role and screen rectangle as the parent element.
Filtering compatibility level If you need legacy RanoreXPaths (created with an older Ranorex version) to work
with the current Ranorex version, set this property to the appropriate value matching the Ranorex version used to
create the legacy RanoreXPaths.
Refine FromPoint results Setting this value to true results in an additional search operation for a better fitting
element for every MSAA FromPoint operation (e.g. used by Element.FindFromPoint). This may produce better
results if the MSAA FromPoint implementation of a control is broken.
Qt
Enable filtering on the QtQuick scenegraph Enables filtering the QtQuick scenegraph by skipping or removing
unnecessary layout, loader and style items.
Use QT legacy automation mode Enable Qt legacy automation mode using MSAA and Qt Accessibility.
UIA
Enable debugging mode for Windows apps If set to true, the debugging mode for Windows apps will be enabled,
causing them to not be suspended until the logon session is closed (user logout). When set to false, the plugin will
instead try to resume suspended apps when it needs to access them (possible race condition may cause freeze until
app is manually resumed).
Enable filtering of Windows app frames If set to true, the frames of Windows apps introduced with Windows
10 are filtered and all relevant elements of those frames are displayed as child of the app element. This allows for
transparent automation of Windows apps in windowed and full-screen mode.
Enumerate lists using the ItemContainerPattern Setting this value to true instructs the plugin to use the
ItemContainerPattern to iterate items of virtual lists that implement this UI Automation pattern. Depending on the
implementation of the control, iterating children using this pattern should also return items that are currently scrolled
out of view, but might also be slower than the usual way to get child elements. Note that switching this setting can
render existing RanoreXPaths invalid for controls implementing the ItemContainerPattern.
Evaluate computationally expensive attributes Setting this value to true will instruct the plugin to evaluate
attributes that are expensive to compute and may result in longer delays when getting such attributes. Note that
spying an element with such expensive attributes may then take considerable time.
Force virtual items to be realized Forces virtual items to be realized when trying to get their child elements.
Setting this value to true will allow to search lists with virtual items, but realizing may have undesired effects on the
list depending on the list implementation, e.g. that the list is scrolled to make the realized item visible.
Provide elements for non-WPF windows natively implementing UIA Setting this value to true instructs the
plugin to provide elements also for non-WPF windows which natively implement the UIA interface.
Web
Enable automation of embedded IE web documents Enable automation of Internet Explorer web documents
embedded in other applications.
249
Ranorex Settings
Win32
Enable accessibility (MSAA) actions and attributes Specifies whether Win32 elements provide accessibility
(MSAA) actions and attributes (as Dynamic capability).
Enable basic Delphi support Enables support for basic Delphi controls such as textboxes, buttons, etc. Set to
False for backwards compatibility.
Use legacy Form role Enables 2.X legacy mode where many elements improperly had the Form role. Set to True
for backwards compatibility with 2.X paths.
WPF
Allow selected instance properties Extend the dynamic attribute list with entries for plain .NET properties. Each
line specifies a full-type name and the attribute name, separated by a pipe, like: Ranorex.ExampleType|IsAvailable
Disable WPF plug-in for processes Do not use the native WPF plug-in for any process specified in the list; keep
using UIAutomation for WPF as in Ranorex version up to 5.2.
Enable WpfDebug capability Enable the WpfDebug capability for all WPF elements. This capability provides
attributes and dynamic actions that are useful for analyzing issue in the element tree.
Ignore Attributes starting with Reduce clutter in the list of dynamic attributes.
Realize Items in Virtualizing Containers Many WPF containers only show children which are also visible on the
screen; to show all child-items, set this option to true. By default this is false, as the performance impact for large
grids can be very high.
Show All Elements Show the complete element tree, incorporating all visual and logical WPF elements. This
option disables any other filtering, and is useful for analyzing the structure of WPF applications when elements cannot
be accessed.
WPF Legacy/UIA Interaction Set to UiaOnly to completely deactivate this plug-in, making all other settings
obsolete. WpfOnly: Show only the native WPF plug-in tree, suppress UIA. WpfPreferred: Show both WPF and
UIA tree, and return WPF elements for tracking. UiaPreferred: Show both WPF and UIA tree, and return UIA
elements for tracking. UiaOnly: Do not use the native WPF plug-in at all, and keep using UIAutomation for WPF as
in Ranorex versions up to 5.2.
WPF Tree
Always Show Visual Children Always show the visual children for specific types, even if those type do also have
one or more logical children. Enables accessing elements that are not part of the logical WPF element tree, like
data-binding generated elements for well-known types. Example: CurrentType|ParentType|ApparentParentType
Each entry is a pipe (the |character) separated tuple of type-names for (current, parent, apparent-parent) elements.
An empty field denotes match-all, e.g. FrameworkElement|| matches for all parent and apparent-parent elements.
Never Show Visual Children Do not show the visual children for matching elements, even if those types do not have
any logical children. Reduces unnecessary element tree branched. Example: CurrentType|ParentType|ApparentParentType
Each entry is a pipe (the |character) separated tuple of type-names for (current, parent, apparent-parent) elements.
An empty field denotes match-all, e.g. FrameworkElement|| matches for all parent and apparent-parent elements.
250
Ranorex Settings
Skip Elements Neither show nor traverse elements for specific types. Reduces the size of the element tree by
hiding types not used in UI testing. Example: CurrentType|ParentType|ApparentParentType Each entry is a pipe
(the |character) separated tuple of type-names for (current, parent, apparent-parent) elements. An empty field denotes
match-all, e.g. FrameworkElement|| matches for all parent and apparent-parent elements.
Skip Elements but Descend to Children Reduce the hierarchy levels by always hiding redundant elements, and
instead continuing the tree with its children. By default this skips over some common nested containers constructs.
Example: CurrentType|ParentType|ApparentParentType Each entry is a pipe (the |character) separated tuple of type-
names for (current, parent, apparent-parent) elements. An empty field denotes match-all, e.g. FrameworkElement||
matches for all parent and apparent-parent elements.
Skip Elements but Descend to Single Child Reduce the hierarchy levels by hiding redundant containers, if they
have none or only one child element. By default this hides some layout-containers. Containers will be shown if they
contain at least two children. Example: CurrentType|ParentType|ApparentParentType Each entry is a pipe (the
|character) separated tuple of type-names for (current, parent, apparent-parent) elements. An empty field denotes
match-all, e.g. FrameworkElement|| matches for all parent and apparent-parent elements.
251
Remote
Remote
Ranorex Agent
Remote FAQ
Remote Pad
Agent List
Execute tests
Run History
Remote Troubleshooting - what to do, when a Ranorex Agent can not be found?
Remote FAQ
252
Remote
Ranorex Agent
A Ranorex Agent is a standalone tool that enables remote test execution.
Quick facts:
A Ranorex Agent queues multiple requests and Execute tests one test at a time.
Agents can be Install and set up Ranorex Agent on physical and virtual machines.
One Ranorex Agent can be Install and set up Ranorex Agent per machine.
Remotely Execute tests tests are fully functional, including mouse and keyboard actions.
A Ranorex Runtime License is required for remote test Execute tests. When starting the agent, it is automatically
requested from the License Manager installed in the network. The license is released once the agent is shut
down.
When a Ranorex Agent is started, an icon will be shown in the Windows system tray. To open the Ranorex Agent
window, just click on this icon:
Figure 322
Using the context menu of this icon, you can open and close the agents window. Select Exit to shut down the
agent. Shutting down the agent will release the license, close the whole application. Running tests remotely will not
be possible after this action.
Figure 323
The window of the Ranorex Agent displays the agents job queue as well as the agents log, including technical details,
and the agents display name. The host name of the machine is shown in the title bar.
253
Remote
Figure 324
You can also configure the settings of an agent. For more information on this topic visit this section: Configure
Ranorex Agent
The Job Queue provides an overview of the currently executed and planned tests. The jobs are listed with their
individual Test Suite name and the issuer is presented with the machines name the issuing Ranorex Studio is running
on.
254
Remote
Figure 325
255
Remote
1. Download the installation package. Alternatively, you can click the Adding Ranorex Agents link in the Remote
Pad in Ranorex Studio.
2. Accept the terms in the License Agreement and press Install
Figure 326
3. Wait for the Setup Wizard to finish installing the Ranorex Agent.
256
Remote
Figure 327
Note: Depending on your windows system configuration, you might need to give your consent in the Windows
User Account Control.
4. The installation has finished.
257
Remote
Figure 328
Check Start Ranorex Agent to automatically open the agent. The First Run Wizard will guide you through
the set up.
Complete the following steps to use a Ranorex Agent. When starting the Ranorex Agent for the first time, the First
Run Wizard will appear.
258
Remote
Figure 329
1. The display name will help you manage your Ranorex Agents in the Remote Pad of Ranorex Studio.
259
Remote
Figure 330
2. You need to install Ranorex Runtime to execute tests. You can decide to install Ranorex Runtime manually or
at a future point in time.
260
Remote
Figure 331
If you choose to install Ranorex Runtime at this point, it will immediately download and install automatically.
261
Remote
Figure 332
262
Remote
Figure 333
3. Configuration finished. Make sure the steps for preparing the agents host machine are completed.
263
Remote
Figure 334
The Ranorex Agent has been configured and the setup is finished. Press Next to open the main window of
the agent.
264
Remote
Figure 335
In the top right corner of the agents window, open the main menu to:
Change Display Name The agents display name is shown in the top left corner of the agents window and in
the Remote Pad in Ranorex Studio. If youve changed the agents display name, all those, who have this agent
in their Agent List, will have to remove the agent with the former display name from their list, and re-add it
manually with the new display name.
Change License Manager Select to switch to another License Manager.
Show Files Opens the folder in the file system, which contains all data related to the agent.
Autostart at Logon Select to automatically start the Ranorex Agent after login into the machine.
Keep Session Active This setting makes sure that the user session keeps unlocked even if you close the remote
session. For more information also consult the How do I make sure that my user session keeps unlocked if I
close my remote session?.
Note: As this mechanism will keep your remote machine unlocked even if youve disconnected your RDP
session, an essential security mechanism is now disabled. Please beware that your remote machine can now
easily be accessed as the system security is disabled. We advise you to not store sensitive data on your remote
machine.
Always on Top Check this option to show the agents window on top of all other windows.
Exit Select to shut down the agent and release the license. In the Remote Pad in Ranorex Studio, this agent
will be displayed as not reachable.
265
Remote
Remote Pad
The Remote Pad is the central point of management to deploy tests to Ranorex Agents within Ranorex Studio.
This Remote Pad welcome screen will be shown after first installing Ranorex Studio or when your Agent List is empty.
To add an agent to your Agent List, press Add Ranorex Agent and follow the instructions.
266
Remote
Figure 336
267
Remote
Remote Pad is opened by default. In case it is closed just open the Remote Pad in Ranorex Studio by pressing the
View Remote button in the toolbar section.
Figure 337
Once the Remote Pad is open, the View Remote button is disabled.
Figure 338
268
Remote
Adding the first agent to your Agent List - Your Agent List is empty
In case your Agent List is empty, the Remote Pad will show the Remote Welcome Screen.
269
Remote
Figure 339
270
Remote
Figure 340
In order to add a Ranorex Agent to your Agent List, an agent has to be installed on a machine in your network.
Start with step 1 to find a link to download the installation package. Find details on installing the Ranorex Agent
here: Install and set up Ranorex Agent
Once youve successfully installed a Ranorex Agent, or if you already have several agents running in your network,
please continue with step 2 to manage your Agent List. Follow this link to find out how to add an agent to your
Agent List: Managing your Agent List
271
Remote
In case you already have agents in your Agent List, please click on the icon in the top right corner of the Remote Pad
to manage your Agent List.
Figure 341
Follow this link to find out how to add an agent to your Agent List: Managing your Agent List
272
Remote
Agent List
The Agent List provides an overview of your agents, and enables you to manage agents and access the Run History.
The agents are listed with their display name, a status information and three controls.
Figure 342
Please find detailed information on how to execute remote tests in the section Execute tests. If you want to view your
remote test results, please refer to the section Run History.
To add or remove agents from the Agent List, press the icon in the top right corner of the Remote Pad.
273
Remote
Figure 343
274
Remote
275
Remote
276
Remote
277
Figure 345
Remote
The section My Agents shows all agents currently contained in your Agent List. Use the Remove button to delete
agents from this list. Note that this action neither deletes the agent itself nor data on the agent, but merely removes
the agent from the list. You can always re-add a previously removed agent to your Agent List.
The section Available agents in your network lists all auto-discoverable agents in your network. To add an agent
to your Agent List, press Add Agent.
In the last section of this list, you can manually search for agents within your network that are not auto-discoverable.
Enter the name or IP-address of the machine the agent is installed on, to find the desired agent.
Figure 346
If it cannot be found, please refer to the section Ranorex Agent in the user guide and make sure it has been correctly
Install and set up Ranorex Agent.
If an agent cannot be found even though it has been installed and configured, please make sure the System Requirements
for Ranorex Versions up to 6.0 are correct. If it still cannot be found, please consult the Remote Troubleshooting
section.
278
Remote
Execute tests
Press the run button next to an agents name to start executing the currently selected Running a Test Suite - Run
Configurations on this Ranorex Agent.
Figure 347
To run a specific Running a Test Suite - Run Configurations, open the Run button menu and select one of the items.
279
Remote
Figure 348
280
Remote
The test will be executed on the remote machine. You dont have to wait for the test run to finish. Once youve
deployed your test to a remote machine, you can immediately continue using your local machine.
During remote test execution, youll receive information on the progress. By pressing the red stop button, you can
abort the remote test run.
Figure 349
Once the remote test has been executed successfully, youll receive a notification shown at the right most button
Open Run History. Youll see a number of unread items in the Run History. If the circle is grey, it indicates that no
error has occurred since youve last accessed the Run History.
281
Remote
Figure 350
282
Remote
If there is at least one unread item in the Run History with an error state, the circle is shown in red.
Figure 351
An agent can queue several jobs. The number of items in the queue is shown in the grey circle on the Run button.
283
Remote
Figure 352
284
Remote
Run History
The Run History lists all finished runs of an agent. You can open the Run History with the right most button next to
each agent in your Agent List.
Figure 353
The Run History shows all tests that have been executed remotely in a descending order. By default, youll see all
test runs youve sent to the agent in the past 24 hours.
When selecting a test run, the actions that have been performed are shown in the details view below the list.
The list displays the result of the test run and the name of the test suite, including a timestamp of when the test
execution has finished. A check mark in a green circle indicates that the test has been executed successfully, whereas
a failed execution is highlighted with a white cross in a red circle.
285
Remote
Figure 354
286
Remote
Reports of remotely executed tests are stored on the machine of the agent they have been executed on. You have
three options to open a report: you can either double-click the desired test run, right-click the test run to open
its context menu and select Open Report, or press the download button in the bottom right corner in the details
view. To save the report to your local machine or any other location, right-click on the opened report to get to the
context menu and select Save as. If a test-run has failed, no report will be available.
The Run History provides three filter options: result, ownership and timespan. The ownership of a test run refers to
the name of the machine Ranorex Studio is running on.
Test runs can be deleted by all those who have access to the agent. Simply select the desired test run(s) and press the
delete key, or select Delete in the context menu for selected test run(s). When deleting a test run, all information
connected to this test run will be removed from the agent.
287
Remote
288
Remote
Remote Troubleshooting
If the auto discovery or manual search for an agent have failed:
Make sure the Ranorex Agent is running in an active user session. Do not log off the user from the machine
the Ranorex Agent is running on.
Make sure the machine Ranorex Studio is running on, is in the same network (subnet) as the machine the
Ranorex Agent is running on.
Double-check the System Requirements for Ranorex Versions up to 6.0on the machine the Ranorex Agent is
running on.
Check the Windows Event Log on the machine the Ranorex Agent is running on for entries related to Ranorex
Agent.
289
Remote
Remote FAQ
These frequently asked questions regarding Ranorex Remote want to help you to find quick answers to important
topics. Just click on one of these questions to get to the answer.
Can I install more than one Ranorex Agent on the same machine?
How many licenses do I need for remote test execution on a Ranorex Agent?
How do I make sure that my user session keeps unlocked if I close my remote session?
Can I install more than one Ranorex Agent on the same machine?
One Ranorex Agent can be installed in one operating system. If you want to run more than one Ranorex Agent on a
physical machine, you have to set up more operating systems on that machine.
A Ranorex Agent uses one Ranorex Runtime license provided through a Ranorex License Manager.
How many licenses do I need for remote test execution on a Ranorex Agent?
The Ranorex Agent takes a Ranorex Runtime License at startup, and keeps it until the agent is shut down. The same
license is used for test execution. While the Ranorex Agent is running, one license is blocked - no matter if the agent
is idle (no tests executed) or tests are executed. Also the number of tests executed by the agent has no effect on the
number of licenses used.
Settings which were configured on your local machine, e.g. technology plugin settings, can be deployed to the remote
machine with the Ranorex Solution. Follow these steps to do so:
290
Remote
Figure 355
291
Remote
Figure 356
292
Remote
Figure 357
293
Remote
7. Open Properties pane for the file. Use the context menu or press F4 to do so.
8. Change property Copy to output directory to PreserveNewest.
Figure 358
With this Setting, the configuration file will always be deployed to the Ranorex Agent.
If you change any setting after this procedure, you have to manually update the file in this project. Repeat steps 1 to
4 to do so.
How do I make sure that my user session keeps unlocked if I close my remote session?
Ranorex Remote requires an active user session to run tests on a remote machine. You can connect to a remote
machine using a remote desktop connection (RDP). As long as this remote connection is active, the remote machine
is unlocked and tests can be executed. If you disconnect the RDP session, your remote machine will be locked. As no
GUI is available in locked mode, your remote tests will fail.
Ranorex Agent shipped with Ranorex 6.0.1 and later includes the setting Keep Session Active, which is enabled
by default. So no further steps are required. Find more information in section Configure Ranorex Agent.
To keep the remote session unlocked even if youve disconnected the RDP session in Ranorex 6.0, please follow
these instructions:
1. Create a batch file on your remote machine and insert the code below: for /f skip=1 tokens=3 usebackq
%%s in ( query user %username% ) do ( %windir%\System32\tscon.exe %%s /dest:console )
2. Save this batch file on the desktop of your remote machine and name it: KeepSessionOpen.bat.
3. If you need to disconnect the RDP session, you can now simply run this batch file using administrator privileges
and your remote machine will remain unlocked.
Note: As this mechanism will keep your remote machine unlocked even if youve disconnected your RDP
session, an essential security mechanism is now disabled. Please beware that your remote machine can now
easily be accessed as the system security is disabled. We advise you to not store sensitive data on your remote
machine.
294
Remote
If the machine with the installed Ranorex Studio and the machine with the Ranorex Agent are connected to different
networks, this agent may not automatically appear in your Agent List and you may not be able to manually add it
using the IP address. By default, machines do not have the routing information to connect to a machine outside its
own network.
To overcome this issue, a network route has to be configured either on the gateways between the networks, or on
each machine.
Below, weve showcased an example in which Ranorex Studio and the Ranorex Agent are installed on machines which
are connected to different networks and have provided a solution on how to create a network route between them.
Figure 359
As you can see in the image above, our exemplary networks are starting with 192.168.x.x. One has the gateway
192.168.2.1, the other 192.168.3.1. Both gateways share the subnet 192.168.1.x. This subnet has the gateway
192.168.1.1., which is connected to the internet.
The network of gateway 192.168.3.1 contains two computers, one of which with three virtual machines (VMs) running
on it. All of them have 192.168.3.x IP addresses.
On the 192.168.2.1 network there is a router, and just two computers. All of these computers have 192.168.2.x IP
addresses.
If you ping 192.168.2.2 (PC 2) from computer 192.168.3.6 (VM C), then the request will time out, unless you
enable a proper route across the gateways. Assuming the 192.168.3.6 (VM C) is running Windows 7, type one of the
following commands on 192.168.3.6 (VM C):
route add 192.168.2.0 mask 255.255.255.0 192.168.1.2 metric 2 (add whole network to the route table) or
route add 192.168.2.2 mask 255.255.255.0 192.168.1.2 metric 2 (add single computer to the route table)
Once the command has been entered, the ping/communication would successfully go from 192.168.3.6 (VM C) to
295
Remote
192.168.2.2 (PC 2), but 192.168.2.2 (PC 2) would still not be able to ping 192.168.3.6 (VM C). There are two
workarounds to enable communication between these two networks:
Set up the route on the machines that need to communicate across networks
Please consider the gateway firewalls when setting up the routes, as they may block cross-traffic from the machines.
If this is the case, you will need a network admin to either set up the route on the gateway instead or to set up port
forwarding to allow traffic through the firewall.
As most gateways behind corporate internet firewalls function as bridges, not much internal traffic is firewalled on the
local network. To check if your connection is firewalled, try tracert 192.168.2.2. If stars * appear in the trace
route instead of IP addresses, then either the connection went through the firewall, or it has been misdirected into
the internet.
Please beware that a standard subnet has been chosen in this scenario: 255.255.255.0 Youll need to confirm the
subnet on either side of the gateways, and adjust your route setup commands as needed.
The route metric (last number in command) is assigned to a route and is used to identify its priority with 1 being
of the highest priority. Usually network admins base the router metric on the amount of hops in a route, as the route
with the least hops is usually the best. As the route in our example contains two hops, our router metric is 2.
Please note: A route command is only persistent (it will stay after reboot) if you add the -p argument to it. Thus,
you can easily try route commands at no risk beforehand, and simply reboot if youd like to make them undone. Once
youve found the right route, you can make the commands persistent after reboot.
296
Code Examples
Code Examples
The following code examples explain how to use Ranorex API in order to write code modules or to extend recording
modules with user specific code.
C#
[ TestModule ( " D451F1D1 - C347 -4 B58 -939 F - F6187642EB56 " , ModuleType . UserCode , 1) ]
public class Us i ng Re po s it or y : ITestModule
{
// Repository object to access UI elements
M y F i r s t T e s t P r o j e c t R e p o s i t o r y repo = M y F i r s t T e s t P r o j e c t R e p o s i t o r y . Instance ;
// / < summary >
// / Constructs a new instance .
// / </ summary >
public U si n gRep os i to ry ()
{
// Do not delete - a parameterless constructor is required !
}
void ITestModule . Run ()
297
Code Examples
{
Mouse . D ef a ul tM ov e Ti me = 300;
Keyboard . D e f a u l t K e y P r e s s T i m e = 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 () ;
// 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
Public Class Us i ng Re po s it or y
Implements ITestModule
Repository object to access UI elements
Private repo As M y F i r s t T e s t P r o j e c t R e p o s i t o r y = M y F i r s t T e s t P r o j e c t R e p o s i t o r y . 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 =" T e s t M o d u l e R u n n e r . Run ( ITestModule ) " > method
that will in turn invoke this method . </ see > </ remarks >
Private Sub IT e st Mo du l e_ Ru n () Implements ITestModule . Run
Mouse . D ef a ul tM ov e Ti me = 300
Keyboard . D e f a u l t K e y P r e s s T i m e = 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
298
Code Examples
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 ()
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#
// 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 [ @ ac ce ss i bl en am e = Online ]
// This way you can wait with the timeout specified for
// the item within the repository for the text Online
bool s t a t u s T e x t C o n n e c t e d = repo . MyApp . Te xtOnline Info . Exists () ;
// Using Info objects for validation
// Throws a Ranorex . V a l i d a t i o n E x c e p t i o n if validation
// fails . Automatically reports success or failed message
// to log file
Validate . Exists ( repo . SaveDialog . ButtonOKInfo ) ;
// Validates the existence of the repository item ,
// but does not throw any exception
Validate . Exists ( repo . SaveDialog . ButtonOKInfo , " Check Object {0} " , false ) ;
299
Code Examples
VB.NET
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 [ @a c ce ss ib l en am e = Online ]
This way you can wait with the timeout specified for
the item within the repository for the text Online
Dim s t a t u s T e x t C o n n e c t e d As Boolean = repo . MyApp . Te xtOnline Info . Exists ()
Using Info objects for validation
Throws a Ranorex . V a l i d a t i o n E x c e p t i o n if validation
fails . Automatically reports success or failed message
to log file
Validate . Exists ( repo . SaveDialog . ButtonOKInfo )
Validates the existence of the repository item ,
but does not throw any exception
Validate . Exists ( repo . SaveDialog . ButtonOKInfo , " Check Object {0} " , False )
C#
// Creating adapter of type NativeWindow using the "\ dots Info " object
Ranorex . NativeWindow nativeWnd = repo . MyApp . SelfInfo . CreateAdapter < Ranorex . NativeWindow >( false
);
// \ dots 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 w i nF or ms C on tr ol = repo . MyApp . SelfInfo . CreateAdapter < Ranorex . Control >( false ) ;
// Set background color of VIP application to Color . Black using the
// exposed property BackColor
w in Fo rm s Co nt ro l . S e t P r o p e rt y V a l u e ( " 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
w in Fo rm s Co nt ro l . InvokeMethod ( " Close " ) ;
VB.NET
Creating adapter of type NativeWindow using the "\ dots Info " object
Dim nativeWnd As Ranorex . NativeWindow = repo . MyApp . SelfInfo . CreateAdapter ( Of Ranorex .
NativeWindow ) ( False )
\ dots 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 w in Fo r ms Co nt r ol 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
300
Code Examples
Note: In order to access properties or methods exposed by a WinForms control you need to know their
names. If youre not familiar with the controls API ask the developer of your application for assistance.
C#
// Create a list of adapters using the " Info " object
IList < Ranorex . Button > buttonList =
repo . MyApp . E n a b l e d B u t t o n s I n f o . 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
Create a list of adapters using the " Info " object
Dim buttonList As IList ( Of Ranorex . Button ) =
repo . MyApp . E n a b l e d B u t t o n s I n f o . CreateAd apters ( 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: Repository Items Representing
Multiple Elements
C#
301
Code Examples
VB.NET
Validate for Existence
Using Info objects for validation
Throws a Ranorex . V a l i d a t i o n E x c e p t i o n if validation
fails . Automatically reports success or failed message
to log file
Validate . Exists ( repo . SaveDialog . ButtonOKInfo )
Validates the existence of the repository item ,
but does not throw any exception
Dim exists 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 documentation.
C#
Ranorex . Cell cellObject = null ;
// Try to find a cell object
bool found = false ;
found = Host . Local . TryFindSingle < Ranorex . Cell >( " / form // table / row / cell [3] " , 2000 , out
cellObject ) ;
// If the expressions does not return an object
// call Validate . Fail and the test case fails
if (! found ) Validate . Fail ( " RanoreXPath with no return " ) ;
302
Code Examples
VB.NET
Dim cellObject As Ranorex . Cell = Nothing
Try to find a cell object
Dim found As Boolean = False
found = Host . Local . TryFindSingle ( Of Ranorex . Cell ) ( " / form // table / row / cell [3] " , 2000 , cellObject
)
If the expressions does not return an object
call Validate . Fail and the test case fails
If Not found Then
Validate . Fail ( " RanoreXPath with no return " )
End If
C#
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 = found \ textpipe \ textpipe 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 )
{
throw new Ranorex . E l e m e n t N o t F o u n d E x c e p t i o n ( " Both RanoreXPath with no return " , null ) ;
}
else
{
// If the value of attribute Text does not equal to the expected value
// throw new ValidationException to break the test case
if ( cellObject . Text == " M y E x p e c t e d T e x t V a l u e " )
{
Report . Success ( " User Specific Validation " ," Text validation of cell object
succeeded " ) ;
}
else
{
throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( " Text validation of cell object
succeeded failed " ) ;
}
}
VB.NET
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 = found OrElse Host . Local . TryFindSingle ( Of Ranorex . Cell ) ( " / form // table / row / cell [4] " ,
2000 , cellObject )
303
Code Examples
C#
void ITestModule . Run ()
{
Mouse . D efa ul tM o ve Ti me = 300;
Keyboard . D e f a u l t K e y P r e s s T i m e = 100;
Delay . SpeedFactor = 1.0;
}
VB.NET
Private Sub IT e st Mo du l e_ Ru n () Implements ITestModule . Run
Mouse . D efa ul tM o ve Ti me = 300
Keyboard . D e f a u l t K e y P r e s s T i m e = 100
Delay . SpeedFactor = 1.0
End Sub
C#
// - - - - - - - - - - - - - - - - - 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 the variable varDialogTextA bound to a test case parameter
varD ialogTex tA = repo . SaveDialog . TextMessage . TextValue ;
// - - - - - - - - Code Block used by User Code Action of recording B - - - - - - - -
304
Code Examples
VB.NET
- - - - - - - - - - - - - - - - - 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 the variable varDialogTextA bound to a test case parameter
varD ialogTex tA = repo . SaveDialog . TextMessage . TextValue
- - - - - - - - Code Block used by User Code Action of recording B - - - - - - - -
Read value of module variable varDialogTextB in other code module
or recording module using a user code action
Report . Info ( varDial ogTextB )
Get the current data context and log
the current row index of a data driven run
Report . Info ( TestCase . Current . DataContext . C ur r en tR ow I nd ex . ToString () )
C#
305
Code Examples
VB.NET
C#
// 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
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
306
Code Examples
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
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.
307
Code Examples
C#
void ITestModule . Run ()
{
// Create PopupWatcher
PopupWatcher myP opupWatc her = new PopupWatcher () ;
// Add a Watch using a RanoreXPath and triggering the Method C l o s e U p d a t e C h e c k D i a l o g
myPo pupWatch er . Watch ( " / form [ @controlname = UpdateCheckForm ]/ button [ @controlname = m_btnClose ]
", CloseUpdateCheckDialog );
// Add a Watch using the info object of a button and triggering the Method
CloseUpdateCheckDialog
// myP opupWat cher . Watch ( repo . U p d a t e C h e c k D i a l o g . btCloseInfo , C l o s e U p d a t e C h e c k D i a l o g ) ;
// Add a Watch using the info object of the dialog and the info object of the button to click
// myP opupWat cher . WatchAndClick ( repo . U p d a t e C h e c k D i a l o g . SelfInfo , repo . U p d a t e C h e c k D i a l o g .
btCloseInfo ) ;
// Add a Watch using a repository folder object and the info object of the button to click
// myP opupWat cher . WatchAndClick ( repo . UpdateCheckDialog , repo . U p d a t e C h e c k D i a l o g . btCloseInfo ) ;
// Start PopupWatcher
myPo pupWatch er . Start () ;
}
public static void C l o s e U p d a t e C h e c k D i a l o g ( Ranorex . Core . Repository . RepoItemInfo myInfo , Ranorex
. Core . Element myElement )
{
myElement . As < Ranorex . Button >() . Click () ;
}
public static void C l o s e U p d a t e C h e c k D i a l o g ( Ranorex . Core . RxPath myPath , Ranorex . Core . Element
myElement )
{
myElement . As < Ranorex . Button >() . Click () ;
}
VB.NET
308
Code Examples
C#
public void V a l i d a t e _ C l i p b o a r d C o n t e n t E q u a l ( string compareText , string c u s t o m L o g M e s s a g e )
{
// check if content of clipboard is text
if ( System . Windows . Forms . Clipboard . ContainsText () )
{
// Get text from clipboard
string clipboardtext = System . Windows . Forms . Clipboard . GetText () ;
// prepare log message if the log - parameter is empty
if ( string . IsNullOrEmpty ( clipboardtext ) )
{
c u s t o m L o g M e s s a g e = " Comparing content of clipboard with given text :
({0} vs . {1}) " ; ;
}
// Validate if given text ( compareText ) is equal to current text in clipboard
Ranorex . Validate . AreEqual ( clipboardtext , compareText , c u s t o m L o g M e s s a g e ) ;
}
else
{
throw new Ranorex . R a n o r e x E x c ep t i o n ( " There is not text on the clipboard that
can be compared " ) ;
}
}
VB.NET
Public Sub V a l i d a t e _ C l i p b o a r d C o n t e n t E q u a l ( compareText As String , c u s t o m L o g M e s s a g e As String )
check if content of clipboard is text
309
Code Examples
C#
public void V a l i d a t e _ T a b l e C o n t e n t E q u a l ( Ranorex . Adapter repoItem , string
f i le n a me _ R ef e r e nc e T ab l e S na p s ho t , string customLogMessageOverall , string
customLogMessageDetail )
{
// check if snapshot file exists
const string fileNotExists = " The given file does not exist : {0} " ;
if (! System . IO . File . Exists ( f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) )
{
throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( string . Format ( fileNotExists ,
filename_ReferenceTableSnapshot ));
}
E le me nt S na ps h ot snap = null ;
try
{
snap = Ranorex . Core . El em en t Sn ap sh o t . CreateFr omFile (
f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) ; // E le me n tS na ps h ot . Cre ateFromF ile is
available starting with Ranorex 5.4.2
}
catch
{
throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( " Snapshot could not be loaded from file "
);
}
// restore table from snapshot
Ranorex . Table refTable ;
try
{
refTable = snap . Element ;
}
catch
{
throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( " Table could not be created from
snapshot " ) ;
}
var tableAdapter = repoItem . As < Ranorex . Table >() ;
if ( tableAdapter == null )
{
310
Code Examples
throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( " Repo - item could not be accessed " ) ;
}
// check if rowcount is identical
if ( tableAdapter . Rows . Count != refTable . Rows . Count )
{
throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( String . Format ( " Tables do not have same
number of rows ({0} vs . {1}) " , tableAdapter . Rows . Count , refTable . Rows .
Count ) ) ;
}
// run through table - rows
for ( int iRow = 0; iRow <= tableAdapter . Rows . Count - 1; iRow ++)
{
int cellCountCur = tableAdapter . Rows [ iRow ]. Cells . Count ;
int cellCountRef = refTable . Rows [ iRow ]. Cells . Count ;
// check if number of cells is identical in current row
if ( cellCountCur != cellCountRef )
{
throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( String . Format ( " Table - Rows do not
have same number of cells ({0} vs . {1}) " , cellCountCur ,
cellCountRef ) ) ;
}
// run through cells in current row
for ( int iCol = 0; iCol <= cellCountCur - 1; iCol ++)
{
string aCurText = tableAdapter . Rows [ iRow ]. Cells [ iCol ]. As < Ranorex . Cell
>() . Text ;
string aRefText = refTable . Rows [ iRow ]. Cells [ iCol ]. As < Ranorex . Cell >() .
Text ;
string v a l i d a t i o n M e s s a g e = string . Empty ;
if ( string . IsNullOrEmpty ( c u s t o m L o g M e s s a g e D e t a i l ) )
{
v a l i d a t i o n M e s s a g e = String . Format ( " Comparing content of cell
({2}/{3}) ( found : {0} , expected : {1} ) " , aCurText ,
aRefText , iRow , iCol ) ;
}
else
{
validationMessage = customLogMessageDetail ;
}
// validate whether current text and expected text are identical
Ranorex . Validate . AreEqual ( aCurText , aRefText , v a l i d a t i o n M e s s a g e ) ;
}
}
// Log overall success
if ( string . IsNullOrEmpty ( c u s t o m L o g M e s s a g e O v e r a l l ) )
c u s t o m L o g M e s s a g e O v e r a l l = " Successfully completed content - validation of table
with provided snapshot of table ( reference ) " ;
Ranorex . Report . Log ( ReportLevel . Success , c u s t o m L o g M e s s a g e O v e r a l l ) ;
}
VB.NET
public Sub V a l i d a t e _ T a b l e C o n t e n t E q u a l ( repoItem As Ranorex . Adapter ,
f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t As String , c u s t o m L o g M e s s a g e O v e r a l l As String ,
c u s t o m L o g M e s s a g e D e t a i l As String )
check if snapshot file exists
Const fileNotExists As String = " The given file does not exist : {0} "
If Not System . IO . File . Exists ( f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) Then
Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( String . Format ( fileNotExists ,
filename_ReferenceTableSnapshot ))
End If
Dim snap As E le m en tS n ap sh ot = Nothing
Try
snap = Ranorex . Core . El em en t Sn ap sh o t . CreateFr omFile (
f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) E le m en tS na p sh ot . Cre ateFrom File is
available starting with Ranorex 5.4.2
Catch
Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( " Snapshot could not be loaded from file "
)
311
Code Examples
End Try
restore table from snapshot
Dim refTable As Ranorex . Table
Try
refTable = snap . Element
Catch
Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( " Table could not be created from
snapshot " )
End Try
Dim tableAdapter = repoItem .[ As ]( Of Ranorex . Table ) ()
If tableAdapter Is Nothing Then
Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( " Repo - item could not be accessed " )
End If
check if rowcount is identical
If tableAdapter . Rows . Count <> refTable . Rows . Count Then
Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ([ String ]. Format ( " Tables do not have same
number of rows ({0} vs . {1}) " , tableAdapter . Rows . Count , refTable . Rows .
Count ) )
End If
run through table - rows
For iRow As Integer = 0 To tableAdapter . Rows . Count - 1
Dim cellCountCur As Integer = tableAdapter . Rows ( iRow ) . Cells . Count
Dim cellCountRef As Integer = refTable . Rows ( iRow ) . Cells . Count
check if number of cells is identical in current row
If cellCountCur <> cellCountRef Then
Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ([ String ]. Format ( " Table - Rows do
not have same number of cells ({0} vs . {1}) " , cellCountCur ,
cellCountRef ) )
End If
run through cells in current row
For iCol As Integer = 0 To cellCountCur - 1
Dim aCurText As String = tableAdapter . Rows ( iRow ) . Cells ( iCol ) .[ As ]( Of
Ranorex . Cell ) () . Text
Dim aRefText As String = refTable . Rows ( iRow ) . Cells ( iCol ) .[ As ]( Of
Ranorex . Cell ) () . Text
Dim v a l i d a t i o n M e s s a g e As String = String . Empty
If String . IsNullOrEmpty ( c u s t o m L o g M e s s a g e D e t a i l ) Then
v a l i d a t i o n M e s s a g e = [ String ]. Format ( " Comparing content of cell
({2}/{3}) ( found : {0} , expected : {1} ) " , aCurText ,
aRefText , iRow , iCol )
Else
validationMessage = customLogMessageDetail
End If
validate whether current text and expected text are identical
Ranorex . Validate . AreEqual ( aCurText , aRefText , v a l i d a t i o n M e s s a g e )
Next
Next
Log overall success
If String . IsNullOrEmpty ( c u s t o m L o g M e s s a g e O v e r a l l ) Then
c u s t o m L o g M e s s a g e O v e r a l l = " Successfully completed content - validation of table
with provided snapshot of table ( reference ) "
End If
Ranorex . Report . Log ( ReportLevel . Success , c u s t o m L o g M e s s a g e O v e r a l l )
End Sub
312
Code Examples
C#
public void V a l i d a t e _ W e b T a b l e C o n t e n t E q u a l ( Ranorex . Adapter repoItem , string
f i le n a me _ R ef e r e nc e T ab l e S na p s ho t , string customLogMessageOverall , string
customLogMessageDetail )
{
// check if snapshot file exists
Ranorex . Validate . IsTrue ( System . IO . File . Exists ( f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) ,
string . Format ( " Checking existence of snapshot file : {0} " ,
filename_ReferenceTableSnapshot ));
E le me nt S na ps h ot snap ;
try
{
snap = Ranorex . Core . El em en t Sn ap sh o t . CreateFr omFile (
f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) ; // E le me n tS na ps h ot . Cre ateFromF ile is
available starting with Ranorex 5.4.2
}
catch
{
throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( " Snapshot could not be loaded from file
");
}
// restore table from snapshot
Ranorex . TableTag refTable ;
try
{
refTable = snap . Element ;
}
catch ( Exception e )
{
throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( " Table could not be created from snapshot . " , e )
;
}
Ranorex . TableTag tableAdapter = repoItem . As < Ranorex . TableTag >() ;
if ( tableAdapter == null )
{
throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( " Repo - item could not be accessed . " ) ;
}
IList < TrTag > actTableRows = tableAdapter . FindDescendants < TrTag >() ;
int rowCntAct = actTableRows . Count ;
IList < TrTag > refTableRows = refTable . FindDescendants < TrTag >() ;
int rowCntRef = refTableRows . Count ;
// check if rowcount is identical
Ranorex . Validate . AreEqual ( rowCntAct , rowCntRef , " Comparing number of rows ({0} vs .
{1}) " ) ;
// run through table - rows
for ( int iRow = 0; iRow <= actTableRows . Count - 1; iRow ++)
{
IList < Ranorex . WebElement > cellsInActRow = actTableRows [ iRow ]. FindChildren <
Ranorex . WebElement >() ;
IList < Ranorex . WebElement > cellsInRefRow = refTableRows [ iRow ]. FindChildren <
Ranorex . WebElement >() ;
// check if number of cells is identical in current row
Ranorex . Validate . AreEqual ( cellsInActRow . Count , cellsInRefRow . Count , "
Comparing number of cells in current row ({0} vs . {1}) " ) ;
// run through cells in current row
for ( int iCol = 0; iCol <= cellsInActRow . Count - 1; iCol ++)
{
string aCurText = new WebElement ( cellsInActRow [ iCol ]) . InnerText ;
string aRefText = new WebElement ( cellsInRefRow [ iCol ]) . InnerText ;
string v a l i d a t i o n M e s s a g e = string . Empty ;
if ( string . IsNullOrEmpty ( c u s t o m L o g M e s s a g e D e t a i l ) )
{
v a l i d a t i o n M e s s a g e = String . Format ( " Comparing content of cell
({2}/{3}) ( found : {0} , expected : {1} ) " , aCurText ,
aRefText , iRow , iCol ) ;
}
else
{
validationMessage = customLogMessageDetail ;
}
// validate whether current text and expected text are identical
313
Code Examples
VB.NET
public Sub V a l i d a t e _ W e b T a b l e C o n t e n t E q u a l ( repoItem As Ranorex . Adapter ,
f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t As String , c u s t o m L o g M e s s a g e O v e r a l l As String ,
c u s t o m L o g M e s s a g e D e t a i l As String )
check if snapshot file exists
Ranorex . Validate . IsTrue ( System . IO . File . Exists ( f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) , String
. Format ( " Checking existence of snapshot file : {0} " ,
filename_ReferenceTableSnapshot ))
Dim snap As E le m en tS n ap sh ot
Try
snap =
C#
public void V a l i d a t e _ F i l e T e x t E q u a l ( string filePath_Expected , string filePath_Current , string
customLogMessage )
{
// prepare log messages
const string f i l e N o t F o u n d M e s s a g e = " File not found for comparison in
V a l i d a t e _ F i l e C o n t e n t E q u a l : {0} " ;
const string logMessage = " Comparing content of files ({0} vs . {1}) " ;
if ( string . IsNullOrEmpty ( c u s t o m L o g Me s s a g e ) )
{
c u s t o m L o g M e s s a ge = string . Format ( logMessage , filePath_Expected ,
filePath_Current );
}
// check if file exists
if (! System . IO . File . Exists ( f i l e P a t h _ C u r r e n t ) )
{
throw new Ranorex . R a n o r e x E x c ep t i o n ( string . Format ( fileNotFoundMessage ,
filePath_Current ));
}
// check if referencing file exists
if (! System . IO . File . Exists ( f i l e P a t h _ E x p e c t e d ) )
{
throw new Ranorex . R a n o r e x E x c ep t i o n ( string . Format ( fileNotFoundMessage ,
filePath_Expected ));
}
// check if filenames are identical
if ( f i l e P a t h _ E x p e c t e d . Equals ( f i l e P at h _ C u r r e n t ) )
{
Ranorex . Validate . IsTrue ( true , c u s t o m L og M e s s a g e ) ;
}
else
{
314
Code Examples
VB.NET
Public Sub V a l i d a t e _ F i l e T e x t E q u a l ( f i l e P a t h _ E x p e c t e d As String , f i l e P a t h _ C u rr e n t As String ,
c u s t o m L o g M e s s a g e As String )
prepare log messages
Const f i l e N o t F o u n d M e s s a g e As String = " File not found for comparison in
V a l i d a t e _ F i l e C o n t e n t E q u a l : {0} "
Const logMessage As String = " Comparing content of files ({0} vs . {1}) "
If String . IsNullOrEmpty ( c u s to m L o g M e s s a g e ) Then
c u s t o m L o g M e s s a ge = String . Format ( logMessage , filePath_Expected ,
filePath_Current )
End If
check if file exists
If Not System . IO . File . Exists ( f i l e P a t h _ C u r r en t ) Then
Throw New Ranorex . R a n o r e x E x c ep t i o n ( String . Format ( fileNotFoundMessage ,
filePath_Current ))
End If
check if referencing file exists
If Not System . IO . File . Exists ( f i l e P a t h _ E x p e c t e d ) Then
Throw New Ranorex . R a n o r e x E x c e pt i o n ( String . Format ( fileNotFoundMessage ,
filePath_Expected ))
End If
check if filenames are identical
If f i l e P a t h _ E x p e c t e d . Equals ( f i l e P a t h _ C u r r e n t ) Then
Ranorex . Validate . IsTrue ( True , c u s t o m L og M e s s a g e )
Else
Dim current As String = System . IO . File . ReadAllText ( f i l e P a t h_ C u r r e n t )
Dim expected As String = System . IO . File . ReadAllText ( f i l e P a t h _ E x p e c t e d )
validate whether expected value equals to current value
Ranorex . Validate . AreEqual ( current , expected , c u s t o m L o g M e s s a g e )
End If
End Sub
C#
public void V a l i d a t e _ F i l e B i n a r y C o n t e n t E q u a l ( string filePath_Expected , string filePath_Current ,
string c us t o m L og M e s s a g e )
{
// prepare log messages
const string f i l e N o t F o u n d M e s s a g e = " File not found for comparison in
V a l i d a t e _ F i l e C o n t e n t E q u a l : {0} " ;
const string logMessage = " Comparing content of files ({0} vs . {1}) " ;
if ( string . IsNullOrEmpty ( c u s t o m L o g Me s s a g e ) )
{
c u s t o m L o g M e s s a ge = string . Format ( logMessage , filePath_Expected ,
filePath_Current );
}
// check if file exists
if (! System . IO . File . Exists ( f i l e P a t h _ C u r r e n t ) )
315
Code Examples
{
throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( string . Format ( fileNotFoundMessage ,
filePath_Current ));
}
// check if referencing file exists
if (! System . IO . File . Exists ( f i l e P a t h _ E x p e c t e d ) )
{
throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( string . Format ( fileNotFoundMessage ,
filePath_Expected ));
}
// check if filenames are identical
if ( f i l e P a t h _ E x p e c t e d . Equals ( f i l e P at h _ C u r r e n t ) )
{
Ranorex . Validate . IsTrue ( true , c u s t o m L og M e s s a g e ) ;
}
else
{
using ( var file1 = new System . IO . FileStream ( filePath_Current , System . IO .
FileMode . Open ) )
using ( var file2 = new System . IO . FileStream ( filePath_Expected , System . IO .
FileMode . Open ) )
// Check whether files are equal
Ranorex . Validate . IsTrue ( StreamEquals ( file1 , file2 ) , c u s t o m L o g M es s a g e ) ;
}
}
// compare file - streams
private static bool StreamEquals ( System . IO . Stream stream1 , System . IO . Stream stream2 )
{
const int bufferSize = 2048;
byte [] buffer1 = new byte [ bufferSize ];
byte [] buffer2 = new byte [ bufferSize ];
while ( true )
{
int count1 = stream1 . Read ( buffer1 , 0 , bufferSize ) ;
int count2 = stream2 . Read ( buffer2 , 0 , bufferSize ) ;
if ( count1 != count2 )
return false ;
if ( count1 == 0)
return true ;
for ( int i = 0; i < count1 ; i ++)
{
if ( buffer1 [ i ] != buffer2 [ i ])
{
return false ;
}
}
}
}
VB.NET
Public Sub V a l i d a t e _ F i l e B i n a r y C o n t e n t E q u a l ( f i l e P a t h _ E x p e c t e d As String , f i l e P a t h _ C ur r e n t As
String , c us t o m L o g M e s s a g e As String )
prepare log messages
Const f i l e N o t F o u n d M e s s a g e As String = " File not found for comparison in
V a l i d a t e _ F i l e C o n t e n t E q u a l : {0} "
Const logMessage As String = " Comparing content of files ({0} vs . {1}) "
If String . IsNullOrEmpty ( c u s to m L o g M e s s a g e ) Then
c u s t o m L o g M e s s a ge = String . Format ( logMessage , filePath_Expected ,
filePath_Current )
End If
check if file exists
If Not System . IO . File . Exists ( f i l e P a t h _ C u r r e nt ) Then
Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( String . Format ( fileNotFoundMessage ,
filePath_Current ))
End If
check if referencing file exists
If Not System . IO . File . Exists ( f i l e P a t h _ E x p e c t e d ) Then
316
Code Examples
C#
public void V a l i d a t e _ D a t a b a s e F i e l d W i t h Q u e r y ( string OLEConnectionString , string SQLQuery ,
string expectedValue , string c u s t o m L o g M e s s a g e )
{
// check is connection string is empty
if ( string . IsNullOrEmpty ( O L E C o n n e c t i o n S t r i n g ) )
{
throw new Ranorex . R a n o r e x E x c ep t i o n ( " C o n n e c t io n S t r i n g is empty " ) ;
}
// check if SQL statement is empty
if ( SQLQuery . Trim () . Equals ( string . Empty ) )
{
throw new Ranorex . R a n o r e x E x c e pt i o n ( " SQLQuery is empty " ) ;
}
317
Code Examples
VB.NET
Public Sub V a l i d a t e _ D a t a b a s e F i e l d W i t h Q u e r y ( O L E C o n n e c t i o n S t r i n g As String , SQLQuery As String ,
expectedValue As String , c us t o m L o g M e s s a g e As String )
check is connection string is empty
If String . IsNullOrEmpty ( O L E C o n n e c t i o n S t r i n g ) Then
Throw New Ranorex . R a n o r e x E x c ep t i o n ( " C o n n e c t io n S t r i n g is empty " )
End If
check if SQL statement is empty
If SQLQuery . Trim () . Equals ( String . Empty ) Then
Throw New Ranorex . R a n o r e x E x c e pt i o n ( " SQLQuery is empty " )
End If
establish connection to database
Using connection As New System . Data . OleDb . O le D bC on ne c ti on ( O L E C o n n e c t i o n S t r i n g )
connection . Open ()
Dim command As System . Data . OleDb . OleDbCommand = Nothing
Dim SQLReader As System . Data . OleDb . O le D bD at aR e ad er = Nothing
Try
set SQL statement and execute search
command = New System . Data . OleDb . OleDbCommand ( SQLQuery , connection )
SQLReader = command . ExecuteReader ()
SQLReader . Read ()
check if there is a result
If SQLReader . FieldCount > 0 Then
retrieve single result from SQL database
Dim actualValue = SQLReader . GetString (0)
318
Code Examples
C#
public void V a l i d a t e _ D a t a b a s e T a b l e W i t h Q u e r y ( string OLEConnectionString , string SQLQuery ,
string referenceCSVTable , string csvSeparator , string customLogMessageOverall , string
customLogMessageDetail )
{
// check if reference file exists
if (! System . IO . File . Exists ( r e f e r e n c e C S V T a b l e ) )
{
throw new Ranorex . R a n o r e x E x c ep t i o n ( string . Format ( " File does not exist : {0} " ,
referenceCSVTable ));
}
// check if connection string is empty
if ( O L E C o n n e c t i o n S t r i n g . Trim () . Equals ( string . Empty ) )
{
throw new Ranorex . R a n o r e x E x c e pt i o n ( " C o n n e c t io n S t r i n g is empty " ) ;
}
// check if SQL statement is empty
if ( SQLQuery . Trim () . Equals ( string . Empty ) )
{
throw new Ranorex . R a n o r e x E x c e pt i o n ( " SQLQuery is empty " ) ;
}
// prepare separator for csv file ( if not passed in )
char separator ;
if ( string . IsNullOrEmpty ( csvSeparator ) )
{
separator = ; ;
}
else
{
separator = csvSeparator [0];
319
Code Examples
}
// establish database connection
using ( System . Data . OleDb . Ol eD b Co nn ec t io n connection = new System . Data . OleDb .
O le Db Co n ne ct io n ( @ O L E C o n n e c t i o n S t r i n g ) )
{
connection . Open () ;
System . Data . OleDb . OleDbCommand command = null ;
System . Data . OleDb . O l eD bD at a Re ad er SQLReader = null ;
System . IO . StreamReader CSVReader = null ;
try
{
// set SQL statement and execute search
command = new System . Data . OleDb . OleDbCommand ( SQLQuery , connection ) ;
SQLReader = command . ExecuteReader () ;
// open csv file ( reference file )
CSVReader = new System . IO . StreamReader ( System . IO . File . OpenRead (
@referenceCSVTable ));
// run through every line in file
int iRow = 0;
while (( SQLReader . Read () ) && (! CSVReader . EndOfStream ) )
{
// read line from csv file
var line = CSVReader . ReadLine () ;
// split line into array of values
var values = line . Split ( separator ) ;
// check if number of values equals ( in current row of csv
file and in SQL result )
if ( values . Length != SQLReader . FieldCount )
{
throw new Ranorex . R a n o r e x E x c e p ti o n ( string . Format ( "
Number of fields in SQL query and reference - file
does not match ({0} vs . {1}) " , values . Length + 1 ,
SQLReader . FieldCount ) ) ;
}
// run through every field in SQL result
for ( int iFields = 0; iFields <= SQLReader . FieldCount - 1;
iFields ++)
{
var expectedValue = values [ iFields ];
var actualValue = SQLReader [ iFields ]. ToString () ;
// prepare log message
string v a l i d a t i o n M e s s a g e = string . Empty ;
if ( string . IsNullOrEmpty ( c u s t o m L o g M e s s a g e D e t a i l ) )
{
v a l i d a t i o n M e s s a g e = String . Format ( " Comparing
content of cell ({2}/{3}) ( found : {0} ,
expected : {1} ) " , actualValue ,
expectedValue , iRow , iFields ) ;
}
else
{
validationMessage = customLogMessageDetail ;
}
// validate if actual value and expected value are
equal
Ranorex . Validate . AreEqual ( actualValue , expectedValue ,
customLogMessageDetail );
}
iRow ++;
}
if ( string . IsNullOrEmpty ( c u s t o m L o g M e s s a g e O v e r a l l ) )
{
c u s t o m L o g M e s s a g e O v e r a l l = " Successfully validated SQL Table
with given SQL - Statement against content of given CSV file
";
}
// Log success
Ranorex . Report . Log ( Ranorex . ReportLevel . Success ,
customLogMessageOverall );
}
finally
{
320
Code Examples
command . Dispose () ;
SQLReader . Dispose () ;
CSVReader . Dispose () ;
}
}
}
VB.NET
Public Sub V a l i d a t e _ D a t a b a s e T a b l e W i t h Q u e r y ( O L E C o n n e c t i o n S t r i n g As String , SQLQuery As String ,
r e f e r e n c e C S V T a b l e As String , csvSeparator As String , c u s t o m L o g M e s s a g e O v e r a l l As String ,
c u s t o m L o g M e s s a g e D e t a i l As String )
check if reference file exists
If Not System . IO . File . Exists ( r e f e r e n c e C S V T a b l e ) Then
Throw New Ranorex . R a n o r e x E x c ep t i o n ( String . Format ( " File does not exist : {0} " ,
referenceCSVTable ))
End If
check if connection string is empty
If O L E C o n n e c t i o n S t r i n g . Trim () . Equals ( String . Empty ) Then
Throw New Ranorex . R a n o r e x E x c e pt i o n ( " C o n n e c t io n S t r i n g is empty " )
End If
check if SQL statement is empty
If SQLQuery . Trim () . Equals ( String . Empty ) Then
Throw New Ranorex . R a n o r e x E x c e pt i o n ( " SQLQuery is empty " )
End If
prepare separator for csv file ( if not passed in )
Dim separator As Char
If String . IsNullOrEmpty ( csvSeparator ) Then
separator = " ; " C
Else
separator = csvSeparator (0)
End If
establish database connection
Using connection As New System . Data . OleDb . O le D bC on ne c ti on ( O L E C o n n e c t i o n S t r i n g )
connection . Open ()
Dim command As System . Data . OleDb . OleDbCommand = Nothing
Dim SQLReader As System . Data . OleDb . O le D bD at aR e ad er = Nothing
Dim CSVReader As System . IO . StreamReader = Nothing
Try
set SQL statement and execute search
command = New System . Data . OleDb . OleDbCommand ( SQLQuery , connection )
SQLReader = command . ExecuteReader ()
open csv file ( reference file )
CSVReader = New System . IO . StreamReader ( System . IO . File . OpenRead (
referenceCSVTable ))
run through every line in file
Dim iRow As Integer = 0
While ( SQLReader . Read () ) AndAlso ( Not CSVReader . EndOfStream )
read line from csv file
Dim line = CSVReader . ReadLine ()
split line into array of values
Dim values = line . Split ( separator )
check if number of values equals ( in current row of csv file
and in SQL result )
If values . Length <> SQLReader . FieldCount Then
Throw New Ranorex . R a n o r e x E x c e p ti o n ( String . Format ( "
Number of fields in SQL query and reference - file
does not match ({0} vs . {1}) " , values . Length + 1 ,
SQLReader . FieldCount ) )
End If
run through every field in SQL result
For iFields As Integer = 0 To SQLReader . FieldCount - 1
Dim expectedValue = values ( iFields )
Dim actualValue = SQLReader ( iFields ) . ToString ()
prepare log message
Dim v a l i d a t i o n M e s s a g e As String = String . Empty
If String . IsNullOrEmpty ( c u s t o m L o g M e s s a g e D e t a i l ) Then
v a l i d a t i o n M e s s a g e = [ String ]. Format ( " Comparing
content of cell ({2}/{3}) ( found : {0} ,
321
Code Examples
Use case and example: This method might be useful to validate the result of a web service in XML format. Assuming
an online library provides a web service allowing to gather detailed information of books when submitting a unique
ISBN. The result from the web service is in XML format and contains information like author, title, year of publication
and more of the found book. The XML result (see sample XML code below) can now be validated using the code
method with the following call:
C#
// call method to validate xml code
V a l i d a t e _ X M L R e s p o n s e ( xml , " books / book / @title " , " Ranorex Test Automation Guide " , " Validating
result of web service request ({0} vs . {1}) " ) ;
VB.NET
call method to validate xml code
V a l i d a t e _ X M L R e s p o n s e ( xml , " books / book / @title " , " Ranorex Test Automation Guide " , " Validating
result of web service request ({0} vs . {1}) " )
Note: This method can also be called from the recorders action table. Therefore the usercode file needs to provide
this method (directly or derived from a base class).
C#
322
Code Examples
VB.NET
Public Sub V a l i d a t e _ X M L R e s p o n s e ( xmlContent As String , node As String , expectedValue As String ,
c u s t o m L o g M e s s a g e As String )
Dim actualValue As String = String . Empty
check if xml content is empty
If String . IsNullOrEmpty ( xmlContent ) Then
Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( " Parameter xmlContent is empty " )
End If
check if node ( XPath ) is empty
If String . IsNullOrEmpty ( node ) Then
Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( " Parameter node is empty " )
End If
check if expected value is empty
If String . IsNullOrEmpty ( expectedValue ) Then
Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( " Parameter expectedValue is empty " )
End If
Dim document As New System . Xml . XmlDocument ()
Try
323
Code Examples
Below there is the a sample XML code allowing you to implement the sample from above.
XML
< books >
< book title = " Ranorex Test Automation Guide " author = " Ranorex " year = " 2014 " >
</ book >
</ books >
324
Data Connectors
Data Connectors
In this section you learn about how to define different types of external data sources to be used for test automation.
CSV File
SQL Connector
Excel File
Figure 361: Open Manage Data Sources dialog from test suite view
325
Data Connectors
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.
326
Data Connectors
Figure 364: Test case properties dialog shows the currently used data source
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, e.g. 1-5, 8, 11-13), press the purple
marked button, labeled Preview effective data set. . . .
327
Data Connectors
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 CSV file by pressing the red marked button,
labeled Export CSV.
CSV File
SQL Connector
Excel File
328
Data Connectors
329
Data Connectors
Figure 367: Add new test data directly to a table of type Simple Data Connector
To protect proprietary data like passwords you can mask specific columns of your data source. To do so, open the
Manage Data Sources dialog, choose the connector and select the column you want to mask.
330
Data Connectors
331
Data Connectors
CSV File
You can also use a CSV file to provide data for your test suite by choosing this type of data connector. After adding
a CSV file data connector, the data source management dialog will be opened.
You can edit the name of the data connector in the text box marked in red and choose the CSV 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 CSV 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 CSV file will be added as the
header of all rows.
To protect proprietary data like passwords you can mask specific columns of your data source.
CSV 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 CSV 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 CSV file.
332
Data Connectors
SQL Connector
The third type of data connector is the SQL connector. This connector allows you to access a SQL database and
get the desired data using a SQL query. After adding a SQL connector, the data source management dialog will be
opened.
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 Create button. After establishing a connection to the database by
generating a connection string, you can add an SQL query by pressing the green marked Create button.
After setting up the connector you can mask specific columns of your data source to protect proprietary data like
passwords.
By pressing the red marked Create button in the data source management dialog the connection properties dialog
will be opened.
333
Data Connectors
The appearance of this dialog depends on the data source which can be chosen by pressing the Change button
marked red. In this screenshot, a Microsoft Access Database File is chosen as data source. You can choose the
database file by pressing the Browse button marked green and set the user name and the password in the area
marked yellow. But as explained before, the kind and number of properties will depend on the chosen data source. By
pressing the orange marked button labeled Advanced. . . the advanced property dialog will be opened. In this dialog
you can edit the advanced options of your database connection. After configuring all relevant options, you can check
if the database connection is working by pressing the purple marked button labeled Test Connection.
Create Query
By pressing the green marked Create button in the data source management dialog the query design dialog will be
opened.
334
Data Connectors
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.
335
Data Connectors
Excel File
The last type of data connector is the Excel file connector. This connector allows you to use an Excel file to provide
data for your test suite. After adding an Excel file connector, the data source management dialog will be opened.
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.
To protect proprietary data like passwords you can mask specific columns of your data source.
Note: Instead of using the default Excel file format xlsx for your test data you can also use the native
binary file format xlsb. This file format is supported since Microsoft Office 2007 and is much faster than the
non-binary version.
336
Instrumentation Wizard
Instrumentation Wizard
Note: Ranorex supports the testing of many different UI technologies, however some technologies need to be
instrumented correctly to guarantee the best possible automation results.
The Ranorex Instrumentation Wizard is a tool which helps you instrumenting these technologies to ensure optimal
object recognition and consequently robust test automation projects.
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). The last method is useful if
you are going to automatically instrument a technology. Have a look at the section Running Instrumentation Wizard
from the Command Line for further details.
The wizard is used to instrument the following technologies:
Java AWT/Swing
Adobe Flash/Flex
Mozilla Firefox
Google Chrome
Apple Safari
Android
iOS
337
Instrumentation Wizard
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.
338
Instrumentation Wizard
Ranorex.Instrumentation.exe /<arguments>
p|pagename:
Default is Select. Set this option to directly navigate to a specific page. Is also required for automated command
line based instrumentation.
Pages are: android, chrome, firefox, flex, ios, java and safari.
?|help:
android
d|device: The name of the device to that the APK file shall be deployed. This parameter is not required if deploymode
is set to NoDeploy.
a|apkfile: Required. The path where the APK file resides.
s|skip: Default is False. Set this switch to skip APK file instrumentation prior to deploying.
339
Instrumentation Wizard
dm|deploymode: Possible Values: WiFi, Usb, NoDeploy, Auto. Default is Auto. Specifies how the apk file shall be
deployed. Set to nodeploy if the file shall not be deployed to the device. Auto means the connection mechanism used
to configure the device will be used.
o|outfile: Sets a custom output location for the instrumented file. This can be a directory or a file path. Read/Write
permission is required for this path. If a directory was specified, (to specify a directory add a trailing \) the process
will place the APP file in it with the -instrumented suffix added to the source file name. If the file already exists it will
be overwritten. This option only has an effect if an APP is instrumented (no skip).
KeyStorePass: Password of the keystore used for jarsigner. Warning: Please note that password is stored in plain
text. Do not use production certificates.
Note: For custom signing, Keystore, Keystore alias, Keystore password, Key password and JDK bin path
have to be set.
RIdClass: Provide a custom class name for locating resource ids (e.g. com.ranorex.demo.R). By default Ranorex will
search id in <manifestpackage>.R.
EnableWebTesting: When set to true Ranorex shows DOM content of Web Views in UI-Hierarchy. Note that this
feature has a huge performance impact on your app. Default is true.
FullImageComparison: When enabled, more robust image comparison is used to determine resource ids for images.
This option decreases startup performance.
TreeSimplification: When set to false, no post processing of the UI-Tree takes place. This results in a larger UI-Tree
which could be useful for automating 3rd party Android controls.
android
d|device: The name of the device to that the APK file shall be deployed. This parameter is not required if deploymode
is set to NoDeploy.
a|apkfile: Required. The path where the APK file resides.
s|skip: Default is False. Set this switch to skip APK file instrumentation prior to deploying.
dm|deploymode: Possible Values: WiFi, Usb, NoDeploy, Auto. Default is Auto. Specifies how the apk file shall be
deployed. Set to nodeploy if the file shall not be deployed to the device. Auto means the connection mechanism used
to configure the device will be used.
o|outfile: Sets a custom output location for the instrumented file. This can be a directory or a file path. Read/Write
permission is required for this path. If a directory was specified, (to specify a directory add a trailing \) the process
will place the APP file in it with the -instrumented suffix added to the source file name. If the file already exists it will
be overwritten. This option only has an effect if an APP is instrumented (no skip).
340
Instrumentation Wizard
chrome
e|enable: Required. Enable this switch to activate Chrome browser addon. If the switch is disabled the addon will be
deactivated.
firefox
e|enable: Required. Enable this switch to activate FireFox browser addon. If the switch is disabled the addon will be
deactivated.
flex
pl|preloader: Required. Enable this switch to enable the Ranorex preloader. If the switch is disabled the preloader
will get deactivated.
ie: Enable this switch to enable Internet Explorer Flex debug player. If the switch is disabled Internet Explorer Flex
debug player will get deactivated.
ff|firefox: Enable this switch to enable the Firefox/Safari NPAPI Flex debug player. If the switch is disabled
Firefox/Safari Flex debug player will get deactivated.
cr|chrome: Enable this switch to enable the Chrome PPAPI Flex debug player. If the switch is disabled the Chrome
PPAPI Flex debug player will get deactivated.
o|other: Enable this switch to enable the Chrome *and* Firefox Flex debug player. If the switch is disabled the
Chrome and Firefox Flex debug player will get deactivated. [Obsolete option use /cr and/or /ff instead.]
ft|flextrace: Default is False. Enable this switch to enable Flash tracelog. If the switch is disabled flash trace log will
get deactivated.
java
safari
e|enable: Required. Enable this switch to activate Safari browser addon. If the switch is disabled the addon will be
deactivated.
ios
u|udid: The unique device identifier for the device on that the application shall be installed (Note: instead of UDID
the new option devicename can be used). To get the UDID start Ranorex Studio open the manage devices dialog
and select your device (that was added as a USB device) and click edit. In the meta data field you will find the UDID
of the device.
dn|devicename: The name of the device. You can specify the name instead of the UDID. The name needs to exactly
match the name, you set for your device in the settings app of that device.
ip|inputpath: The path to the application archive (*.ipa).
o|outfile: Sets a custom output location for the instrumented file. This can be a directory or a file path. Read/Write
permission is required for this path. If a directory was specified, (to specify a directory add a trailing \) the process
will place the APP file in it with the -instrumented suffix added to the source file name. If the file already exists it will
be overwritten. This option only has an effect if an APP is instrumented (no skip).
si|skipinstrumentation: Default is False. Set this switch to skip IPA file instrumentation.
341
Instrumentation Wizard
sd|skipdeployment: Default is False. Set this switch to skip IPA file deployment.
k|keypath: The path to the p12 key file (*.p12).
pw|password: The password for the p12 key file.
ds|deployservice: Default is False. Set this switch to deploy Ranorex service app.
ub|uninstallbrowser: Default is False. Set this switch to uninstall Ranorex browser before deploy
us|uninstallservice: Default is False. Set this switch to uninstall Ranorex service before deploy
uf|uninstallfail: Default is False. Set this switch to throw exception when uninstalling an app fails.
342
Instrumentation Wizard
Java AWT/Swing
The Ranorex Java Plug-In allows testing of Java Swing and Java AWT applications. With Ranorex 5.0.0 and higher,
the instrumentation will be enabled automatically. If you have instrumented your Java Runtime Environment using
the Ranorex Instrumentation Wizard of a previous Ranorex version, its recommended to deactivate the obsolete
instrumentation. To do so, start the Ranorex Instrumentation Wizard from command line with argument /p:java:
Select a JRE from a list of running Java applications: Here you can choose the Java runtime based on
the application under test. 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
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.
After deactivating the obsolete Java AWT/Swing instrumentation, restart your application under test and your
Ranorex tools to ensure that the automatically added instrumentation works correctly.
343
Instrumentation Wizard
344
Instrumentation Wizard
Adobe Flash/Flex
The Flash/Flex technology limitation will pop up if your Flash/Flex application is not instrumented correctly.
Note: If you need to automate an Adobe AIR application, please read Methods for loading the Automation
Lib chapter.
The instrumentation Wizard tries to install the Flash Debug Player for Internet Explorer and the Flash
Debug Player for Mozilla Firefox and Safari and the Flash Debug Player for Google Chrome 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.
345
Instrumentation Wizard
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.
346
Instrumentation Wizard
Google Chrome
To use the preloader method with Google Chrome, 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:
347
Instrumentation Wizard
348
Instrumentation Wizard
Mozilla Firefox
The Mozilla technology limitation will pop up if the Ranorex Add-On for you Mozilla Browser is not installed or
enabled. This technology limitation should only occur if you install Firefox after successfully installing Ranorex. If
Mozilla Firefox has been installed before installing Ranorex, the Mozilla Browser Add-On will be installed and activated
automatically.
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.
349
Instrumentation Wizard
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.
350
Instrumentation Wizard
351
Instrumentation Wizard
Google Chrome
The Chrome technology limitation will pop up if the Ranorex Extension for the Chrome Browser is not installed or
enabled.
The Instrumentation Wizard opens the Chrome web store page when pressing the Next button. You can install the
Extension by clicking the + sign in the store page.
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.
352
Instrumentation Wizard
When not using the default Chrome user profile, you have to add the Ranorex Chrome Add-On manually. To do so,
open the Chrome Extensions settings (chrome://extensions), enable Developer mode and press the Load unpacked
extension button. After choosing the Ranorex Chrome Extension folder (<Ranorex Installation Folder>\Ranorex
Chrome Extension) and confirming the new Extension, the Ranorex Add-On will be listed on the Extensions page.
353
Instrumentation Wizard
354
Instrumentation Wizard
Note: If you want to test cross domain iframe scripting with Google Chrome, you have to start Chrome with
the command line argument --disable-web-security --user-data-dir=<user data dir> .
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 Chrome Extension is installed, it has to be disabled to allow from point tracking with
Ranorex.
355
Instrumentation Wizard
Apple Safari
The Safari technology limitation will pop up if the Ranorex Extension for the Safari Browser is not installed or enabled.
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.
356
Instrumentation Wizard
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.
357
Instrumentation Wizard
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.
358
Instrumentation Wizard
Android
To make an Android app automatable by Ranorex, it is necessary to instrument this application using the Instrumen-
tation wizard.
Note: Have a look at Getting Started to learn how to automate Android applications.
Note: Note: Its recommended to fresh instrument your app for every new Ranorex release. For further
information have a look at the section Versioning.
Next to instrumenting and deploying your Android app, the Instrumentation Wizard allows you to update the Ranorex
Service on your device as well as deploy the RXBrowser app, which enables Testing of Mobile Websites on Android.
Choose 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
App under test 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.
359
Instrumentation Wizard
The instrumented APK file can be found at location referenced by the link Open instrumentation File location.
After instrumenting and deploying the APK file, the app is available in the Record a Mobile Test section of Record
Setting dialog.
360
Instrumentation Wizard
The Ranorex Service App installed on the mobile device shows an overview of instrumented apps installed on the
device.
Note: If you have problems with instrumenting your APK using the instrumentation wizard or if you want to
integrate the instrumentation into your build process, please have a look at the Instrumentation with Source
Code section.
361
Instrumentation Wizard
iOS
To make an iOS app automatable by Ranorex, it is necessary to instrument this application and deploy it to a device.
The Instrumentation wizard can be used to deploy the instrumented app to the device.
Note: Deployment only works for USB connected iOS devices.Have a look at Instrumentation and Preparation
to learn how to instrument iOS applications.
Note: Note: Its recommended to fresh instrument your app for every new Ranorex release. For further
information have a look at the section Versioning.
Figure 409
362
Instrumentation Wizard
Figure 410
Next to instrumenting and deploying your iOS app, the Instrumentation Wizard allows you to update the Ranorex
Service on your device as well as deploy the RXBrowser app, which enables web testing for iOS.
Choose the IPA file of the app and the device, the app will be deployed to.
To instrument the IPA file of the app, a p12 key file, the corresponding password and the mobileprovision file are
necessary.
Note: The iOS signing needs to be configured only once. The settings will be saved for future IPA files
instrumentation.
More information about setting up a mobile device and deploying from windows machines can be found in the section
iOS Testing.
To delete the existing version of the app on your device before deploying a new one, check the corresponding check
box.
363
Instrumentation Wizard
The instrumented IPA file can be found at location referenced by the link Open Instrumentation File location.
After instrumenting and deploying the IPA file, the app is available in the Record a Mobile Test section of Record
Setting dialog.
Note: iOS application packages (IPA files) that have been downloaded from the App Store will not be
instrumented correctly, because they have the DRM (Digital Rights Management) restriction.
364
Instrumentation Wizard
Note: Because the Ranorex automation lib uses non-public APIs, make sure that you do not submit a
Ranorex instrumented app to the app store as your app might be rejected and you might be banned from
submitting apps to the app store for a period of time.
365
Technology Instrumentation
Technology Instrumentation
Ranorex supports testing of many different UI technologies. Although some of them need to be instrumented correctly
to ensure optimal object recognition and furthermore to built robust test automation projects. If an application under
test requires additional manual instrumentation, a pop-up dialog is shown when using a Ranorex tool.
Figure 413: Technology limitation box shown for not instrumented application
Learn more about technology dependent instrumentation and how to troubleshoot object recognition issues using the
information below:
Flash/Flex Testing
Qt Testing
General Troubleshooting
366
Technology Instrumentation
Flash/Flex Testing
The Flash/Flex Test Automation Plugin provides a smooth integration with the Ranorex Automation Framework
and its tools. You can easily filter, access and validate Flex controls easily using RanoreXPath. You have full access
to all the properties and attributes of Flash and Flex elements.
Prerequisites
The automation of Flash/Flex applications requires inclusion of the Ranorex Flex Automation Lib.
OR including the Ranorex Lib into Adobe Flex: Adobe Flex: Load the Ranorex Lib into your Flex applica-
tioninto Adobe Flash: Adobe Flash: Load the Ranorex Lib into your Flash application
Samples
A flash/flex test sample project is included with the Ranorex installation package (shown on the startpage of Ranorex
Studio).
Depending on your flash/flex application, you can choose to use one of the following flexible instrumentation methods:
The Ranorex PreLoader enables automation of your flash/flex application without modifying the application itself.
Adobe Flash/Flex
No modifications to your application needed
Adobe Flash Debug Player has to be installed on the runtime machine
Adobe Flex: Load the Ranorex Lib into your Flex application
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
The Module swf file has to be loaded by adding a code snippet to your How to load the Ranorex Module into your
Flash application or to your How to load the Ranorex Module into your Flex/AIR application.
Module will be loaded in background (will not affect the functionality of your flash/flex application)
No modifications to your website needed
367
Technology Instrumentation
The following table shows you the different instrumentation options available for the supported versions of flash/flex:
* Support for Adobe AIR 2 Release in combination with Flex 3.5 and Flex 4 Release
Figure 414
= supported
Figure 415
= recommended
The architecture of a Flash/Flex object is easy to see within Ranorex Spy. All embedded Flash or Flex elements are
shown as a Flex element in the tree view.
Use Ranorex Recorder to automate Flash/Flex applications in all supported browser (Internet Explorer, Firefox,
Chrome and Safari). You can add user code actions to your recordings to access custom Flex properties.
368
Technology Instrumentation
You can read/set common attributes (e.g. the checkstate of a checkbox) directly by using the adapter as follows:
// Set the checked state with the property " Checked "
repo . Fl ex T es tPag eDo m . C h e c k B o x _ C o n t r o l _ E x a m p l e . 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. Heres an example:
// Load the slider as a Flex element to access flex attributes
FlexElement sliderFlex = repo . Flex Tes tPag eD o m . C o n t a i n e r H S l i d e r _ C o n t r o l . SliderHSlider . As <
flexelement >() ;
sliderFlex [ " value " ] = " 100 " ;
FlexElement containerFlex = repo . Fle xTe st Pa g eD om . Self . FindSingle ( " .// container [ @caption = Tree
Control ] " ) ;
containerFlex . SetStyle ( " borderColor " ," # ee0000 " ) ;
</ flexelement >
The Adobe Flash/Flexautomatically activates Flash/Flex automation for your machine as Adobe Flash/Flex.
If the automatic instrumentation did not work, you can follow these steps to achieve what the Instrumentation Wizard
would have done:
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 Adobes download
page; the following are the links to the Debug Player for
Internet Explorer (Windows 8: x86 / x64 and Windows 8.1: x86 / x64)
Firefox / Safari
Chrome
2. Open your user profile directory %UserProfile%, e.g. by opening Windows Explorer and copying the string
%UserProfile% into the address bar.
369
Technology Instrumentation
3. Create a new file called mm.cfg in your user profile directory and insert the following line of code:
PreloadSwf = C :\ Program Files \ Ranorex X . X \ Bin \ R a n o r e x A u t o m a t i o n . swf
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
Adobe Flex: Load the Ranorex Lib into your Flex application
3. Under Flex Compiler add the RanorexAutomation.swc file (located in the Bin directory of your Ranorex
installation) to the the compiler argument as follows:
- include - libraries " C :/ Program Files / Ranorex X . X / Bin / R a n o r e x A u t o m a t i o n . swc "
6. Run your application in a supported browser (Internet Explorer, Firefox, Chrome, Safari)
7. If you run your Flex application from the local drive, add your output directory to the trusted locations of Flash
Player as follows:
(a) Open following link http://www.macromedia.com/support/documentation/en/flashplayer/help/settings
manager04.html
(b) Add your project output directory
370
Technology Instrumentation
Adobe Flash: Load the Ranorex Lib into your Flash application
6. Run your application in a supported browser (Internet Explorer, Firefox, Chrome, 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:
(a) Open following link http://www.macromedia.com/support/documentation/en/flashplayer/help/settings
manager04.html
(b) Add your project output directory
4. Run your application in a supported browser (Internet Explorer, Firefox, Chrome, 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:
(a) Open following link http://www.macromedia.com/support/documentation/en/flashplayer/help/settings
manager04a.html#119065
(b) Add your project output directory
371
Technology Instrumentation
1. Start Adobe Flex Builder or Flash Builder and open your workspace
2. Append following code to your applicationCompleteHandler function or initialization code: For Flex 3:
3. Copy 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, Chrome, 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:
(a) Open following link http://www.macromedia.com/support/documentation/en/flashplayer/help/settings
manager04.html
(b) Add your project output directory
372
Technology Instrumentation
373
Technology Instrumentation
Qt Testing
The Ranorex Automation Framework fully supports out-of-the-box test automation of Qt based applications.
Qt versions:
When Qt legacy automation mode has been enabled, MSAA support for your Qt application must be enabled to
ensure that Ranorex can access UI elements and properties in the Qt application. This provides additional information
on Qt UI elements to automation software like Ranorex and can be accomplished by shipping and loading the
Accessible Plug-in included in the Qt SDK (Software Development Kit) with the Qt application under test (see
below).
2. Create 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
374
Technology Instrumentation
375
Technology Instrumentation
By default the Ranorex GDI Plug-In is not activated. Use the Ranorex Spy tool to activate the Plug-In for a specific
control.
The pictures below show the different object recognition for a MFC-based menu bar control before and after GDI
activation.
376
Technology Instrumentation
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.
Open the main Settings dialog within Ranorex Spy and click the GDI Capture Settings button to edit the list of
captured class names and processes.
377
Technology Instrumentation
Figure 423: GDI Capture Settings dialog shows currently observed processes and class names
Simply delete class or process names which have been added via the context menu from the text boxes shown above.
378
Technology Instrumentation
To do so, open the SAP GUI options dialog and enable scripting in the Accessibility and Scripting section. Additionally
deactivate the notification options as shown in the following figure.
Note: The administrator has to enable the support by setting the profile parameter sapgui/user scripting to
TRUE on the application server.
379
Technology Instrumentation
General Troubleshooting
This section provides an overview of possible reasons for a limited object recognition with Ranorex tools and
recommends ways to correct a malfunction.
.NET WinForms
.NET WPF
.NET Silverlight
Flash/Flex Applications
Win32 Based Applications
Browser (Mozilla Firefox, Google Chrome, Apple Safari, Microsoft Internet Explorer)
Image Related Automation or Validation
Geometry Related Issues
Windows Apps (aka Windows 8 UI Apps)
Other Software
Different Display DPI Scaling Values
.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:
Try starting both applications as the same user.
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:
Try copying both applications to a folder on your hard disk.
Reason #3:
The .NET Framework 4 (or higher) got installed after Ranorex was already installed and the AUT uses .NET 4.0.
Consequently, as the .NET Framework 4 was not present when Ranorex was installed, the Ranorex setup could not
install the DLLs required to recognize and automate .NET 4.0 applications.
Solution:
Uninstall Ranorex completely and then re-install Ranorex.
380
Technology Instrumentation
Reason #4:
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 thats 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 #5:
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 CPU (Ranorex Studio) or Platform Target (Visual Studio) option in the automation
project settings to match the target of the automated application as described in 64-bit Platforms. If you dont know
the target CPU/platform of the automated application, first try to change the option to Any processor or Any
CPU, respectively, then try the remaining options.
Reason #6:
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
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 #7:
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:
Create 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 u s e L e g a c y V 2 R u n t i m e A c t i v a t i o n P o l i c y = " true " >
< s u p p o r t e dR u n t i m e version = " v4 .0 " / >
< s u p p o r t e dR u n t i m e version = " v2 .0.50727 " / >
</ startup >
</ configuration >
.NET WPF
For compatibility with existing tests, Ranorex 5.3+ shows WPF windows twice in its tree; once using the WPF-specific
plug-in, another time using UIAutomation. When selecting a specific element, the UIAutomation tree was chosen,
381
Technology Instrumentation
Reason #1:
While selecting an element of a WPF application in the element-tree of Spy, you selected the UIAutomation tree of
that application.
Solution:
The preceding sibling of the selected window will identify the same window, but provide the WpfElement capability
instead of UiAutomation. When browsing elements in Spy, select elements below the WpfElement window.
Reason #2:
Instrumentation of the WPF application has failed, because the application runs on a .NET 3.0 runtime, and .NET
3.5 is not installed.
Solution:
Upgrade the .NET installation to version 3.5. No changes are required for the application under test.
.NET Silverlight
Reason #1:
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 application 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 Flash/Flex Testing approaches for Flash/Flex is used.
There might be several reasons for limited support of Win32 based applications:
382
Technology Instrumentation
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.
Reason #2:
The automating and the automated process do not have the same bit width and Ranorex was unable to start the
32/64 Bit Bridge. UI element identification capabilities for controls in that process are limited.
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:
Browser (Mozilla Firefox, Google Chrome, Apple Safari, Microsoft Internet Explorer)
Mozilla Firefox:
Google Chrome:
Apple Safari:
383
Technology Instrumentation
Note: The Internet Explorer Enhanced Security Configuration has to be disabled for the add-on to work
on Windows Server machines.
Reason #1:
Ranorexs image based recording ability is limited because the asynchronous dispatching of input events is disabled.
Solution:
If you experience problems when making image based recordings, please enable asynchronous dispatching of mouse
and keyboard events using the Recorder Settings Dialog.
Reason #1:
Controls being displaced, staying empty, or being scrolled out of view during automation.
Solution:
Set the Use Ensure Visible property of the corresponding repository items (and their parent folders) to False as
described in the chapter Repository Item Properties.
There are a few reasons causing Windows 8 UI based applications not to be recognized correctly:
Reason #1:
Test execution is started using a Ranorex tool and the setting Use UiaLauncher to elevate privileges for processes
started by tools (General Settings dialog -> Advanced tab) is disabled.
Solution:
Enable the mentioned setting.
Reason #2:
384
Technology Instrumentation
Solution:
Install Ranorex to Program Files or Program Files (x86).
Reason #3:
Solution #1:
Start the test suite using the TestSuiteRunner.
Solution #2:
Use the Ranorex UiaLauncher (<Ranorex Installation Folder>\bin\Ranorex.UiaLauncher32.exe) to start the test
executable by passing the executable name as the first argument.
E.g. Ranorex.UiaLauncher32.exe <Solution Folder>\bin\debug\<Project Executable>.exe .
Solution #3:
Add the following lines of code to the Program.cs/Program.vb of the main (executable) project:
C#
if ( Ranorex . Core . Util . I s R e s t a r t R e q u i r e d F o r W i n A p p A c c e s s )
return Ranorex . Core . Util . R e s t a r t W i t h U i A c c e s s () ;
VB.NET
If Ranorex . Core . Util . I s R e s t a r t R e q u i r e d F o r W i n A p p A c c e s s Then
Return Ranorex . Core . Util . R e s t a r t W i t h U i A c c e s s ()
End If
Reason #4:
You checked the Run this program as an administrator in the Compatibility settings of a Ranorex Tool EXE file,
e.g. for the RanorexStudio.exe file. Setting this option disables access to Windows 8 UI apps.
Solution:
Do not check the mentioned setting for any of the Ranorex EXE files. Alternatively, if you want to always run the tool
using administrator rights, you can create a shortcut to the EXE file and check the Run as administrator option in
the Shortcut -> Advanced. . . settings of the shortcut properties.
Other Software
Running some antivirus or security software might lead to a limited object recognition with Ranorex tools.
Reason #1:
Solution:
Add an exception for the appropriate Ranorex process or temporarily switch off the specific security application.
385
Technology Instrumentation
By default, Microsoft Windows is automatically adapting the DPI scaling value for each of your physical displays
connected to your machine. This ensures a uniform experience over all displays, even if the displays have a different
physical size.
When using Ranorex, all physical displays have to be set to the same DPI scaling value.
1. On your Windows 8.1 machine, open the Control Panel and switch to section Display. Do not use the
application PC settings. Make sure the option Let me choose one scaling level for all my Displays is
checked.
Figure 425
2. After checking this option, choose the size category you prefer.
386
Technology Instrumentation
Figure 426
Press Apply, sign-out and sign-in again to your machine to activate the new settings.
1. On your Windows 10 machine, open the Windows start menu and choose Settings.
2. Click on System.
387
Technology Instrumentation
Figure 427
3. The section Display should be shown automatically if not, open it manually. Make sure that all your
physically connected displays have the same setting at Change the size of text, apps, and other items. Move
through the list of displays (labelled with numbers) one by one, and check the setting. When changing a
display value, press Apply before moving on to the next display.
388
Technology Instrumentation
Figure 428
4. Once all changes have been applied, you can close the Settings window.
389
RanoreXPath
RanoreXPath
A RanoreXPath expression is primarily used to uniquely identify UI elements within a desktop, web or mobile
application. Generally, a RanoreXPath expression consists of:
Adapters
Attributes
and Values
Screencast: A detailed explanation of RanoreXPath expressions, the elements and the way they work can be
found in our screencast named RanoreXPath. You can watch it here: http://youtu.be/UqiCtDlk0hM
The adapter type specifies the type or classification of a UI element to search for (button, form, text field, listbox,
etc.).
Looking at the first part of the RanoreXPath expression /form[@title=Form 1] the
/form string specifies a search for a UI element of adapter type form. A Ranorex.Form adapter represents
top-level windows such as dialogs or messageboxes on the Windows desktop system.
The attribute value comparison [@title=Form 1] specifies the UI element in detail.
As an example the first part of the RanoreXPath expression shown in the pictures will look for a UI element which is
of type form and has an attribute called title with the value Form 1. This form holds a container witch caption
Container 1, which holds a button with text Button 1.
390
RanoreXPath
Use the Tracking UI Elements tool to get the RanoreXPath for a particular UI object. To edit a RanoreXPath use
the text box in Ranorex Spy or change the path value of a repository item directly in the repository view. A more
comfortable way to edit RanoreXPath is provided by the The Path Editor.
Note: Use the <CTRL> key in combination with the arrow keys to navigate to the previous or the next
token in RanoreXPath. Use the <CTRL> key and the <SHIFT> key in combination with the arrow keys for
selecting specific parts of the RanoreXPath. Use the <SHIFT> key in combination with the <UP> arrow
key to select the current token of the RanoreXPath (tokens can be a values, identifiers, operators . . . ).
Axes
absolute path identifying all buttons that are children of a
/form/button
form
relative path identifying all buttons that are children of the
./button
current element
absolute path identifying all buttons that are descendants of
/form//button
a form, i.e. all buttons in all levels of a form subtree
391
RanoreXPath
Attributes
/form identifies a top level application
/form[@title=Calculator] identifies a top level application with the title Calculator
identifies a top level application with the title Calculator and
/form[@title=Calculator and @instance=2]
an attribute of instance with value two
identifies a top level application with the title Calculator or
/form[@title=Calculator or @class=SciCalc]
by its class
/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
/form/button[@text>sample] identifies a button with a text attribute starting with sample
/form/button[@text<sample] identifies a button with a text attribute ending with sample
identifies a button using a RanoreXPath with Regular Expres-
/form/button[@text7]
sions
identifies a button not matching a RanoreXPath with Regular
/form/button[@text!7]
Expressions
identifies a WinForms control using cascaded attribute names.
/form/control[@items.count=100] The identified control has an Items property that has a
Count property which returns the value 100
/form/*[@text=7] identifies any element with a text attribute value of 7
optional location step fitting a container adapter be-
/form/container?[@caption=Container 1]/button tween form and button; identifies both, /form/con-
tainer[@caption=Container 1]/button and /form/button
identifies button with any attribute containing the substring
/form/button[?add]
add (case-insensitive)
/form/button[@text!=null()] identifies a button where the attribute text is not null
392
RanoreXPath
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
identifies the second element in the current result list (con-
/form/table/row/cell[index()=2] taining cells only) (Note: the result of the index()-function is
one-based)
From the current result list of all element types (everything
beneath the row), the element on the second position will be
/form/table/row/cell[pos()=1]
identified if it is from type cell (Note: the pos()-function is
zero-based)
identifies a top level application with screen coordinates
/form[x()>100 and y()>100]
greater than 100
identifies a button with client coordinates (coordinates of an
/form/button[cx()>10 and cy()>10]
element relative to its parent) greater than 10
identifies a top level application with width and height greater
/form[width()>100 and height()>100]
than 100
If the innertext-attribute is available (web testing), test()
/dom/body/form/button[text()=Clear]
brings back the value of the innertext attribute
/dom/body/form[@id=null()] identifies a form with the id-attribute not being set (=null)
Example: form//button[@enabled=True]
The expression above selects all enabled buttons on all available levels below a Form element.
For picking one element from the entire result set, a Result Set Selector can be specified by using an additional set of
brackets.
393
RanoreXPath
Example: form//button[@enabled=True][2]
From the complete list of enabled buttons (on various levels), the Result Set Selector selects the second element. Note
that the Result Set Selector is only applied after the step where it was specified has been completely evaluated. The
result will be fundamentally different from the result list of the following statement: form//button[@enabled=True
and index()=2]
(This would select all enabled buttons with index equal to 2)
2. Select the corresponding checkbox with a relative path from the name (highlighted red)
/../../ td / input [ @type = checkbox ]
3. Get the full path to the checkbox by combining the two paths.
394
RanoreXPath
The following are special characters that need to be escaped when used in a regular expression by prefixing them
with a backslash \. E.g. when you want to match the text Sample. (with a dot at the end), the dot needs to be
escaped: Sample\..
395
RanoreXPath
Character Description
. The dot will match any single character. For example Sample. matches Sample1, Samplex, etc.
The dollar sign will match the end of the string. The expression abc$ will match the sub-string
$
abc only if it is at the end of the string.
The alternation character allows either expression on its side to match the target string. The
|
expression gr(a|e)y can match gray or grey.
The asterisk indicates that the character to the left of the asterisk in the expression should match
*
zero or more times. For example go*gle matches ggle, gogle, google, gooogle, etc.
The plus is similar to asterisk but there must be at least one match of the character to the left of
+
the + sign in the expression. For example go+gle matches gogle, google, gooogle, etc.
The question mark (?) matches the character to its left 0 or 1 times. For example, colou?r matches
?
both color and colour.
^ Beginning of the string. The expression A will match an A only at the beginning of the string.
() The parenthesis affects the order of pattern evaluation.
Brackets enclosing a set of characters indicate that any of the enclosed characters may match the
[]
target character.
The caret immediately following the left-bracket has a different meaning. It is used to exclude
[^0-9] the remaining characters within brackets from matching the target string. The expression [0-9]
indicates that the target character must not be a digit.
For additional information on regular expressions please consult the corresponding MSDN web site: http://msdn.
microsoft.com/en-us/library/az24scfc.aspx
396
RanoreXPath Weight Rule Library
Rule Library
397
RanoreXPath Weight Rule Library
Using the RanoreXPath Weight Rules can assist you in automatically creating a robust repository which is the base of
a robust test automation framework.
Copy the specific XML rule from below (<CTRL> + <A>, <CTRL> + <C>) and paste it to RanoreXPath Weight
Rules Dialog by pressing <CTRL> + <V> or use the context menu.
398
RanoreXPath Weight Rule Library
Rule Library
XML
< rule
name = " RxWinForms ControlNet11 Classnames "
enabled = " True "
capability = " nativewindow "
attribute = " class "
setweight = " 0 "
c o n d i t i o n s o p e r a t o r = " and " >
< condition
source = " self "
attribute = " class "
match = " ^ Wi ndowsFo rms10 . Window "
negate = " False " / >
</ rule >
XML
< rule
name = " RxWeb YUI ( Yahoo User Interface Library ) "
enabled = " True "
capability = " webelement "
attribute = " id "
setweight = " 0 "
c o n d i t i o n s o p e r a t o r = " or " >
< condition
source = " self "
attribute = " id "
match = " ^ yui ( _ \ d +) "
negate = " False " / >
< condition
source = " self "
attribute = " id "
match = " ^ yui - gen .* "
negate = " False " / >
</ rule >
399
RanoreXPath Weight Rule Library
XML
< rule
name = " RxWeb JS Frameworks ( ExtJS , Sencha , Ozone Widget ,\ dots ) "
enabled = " True "
capability = " webelement "
attribute = " id "
setweight = " 0 "
c o n d i t i o n s o p e r a t o r = " or " >
< condition
source = " self "
attribute = " id "
match = " ^ ext -.*\ d +.* "
negate = " False " / >
< condition
source = " self "
attribute = " id "
match = " ^[ a - z ]+ -\ d {4}( -[ a - z ]*( -\ d *) ?) ? "
negate = " False " / >
</ rule >
RxWeb jQuery
XML
< rule
name = " RxWeb jQuery "
enabled = " True "
capability = " webelement "
attribute = " id "
setweight = " 0 "
c o n d i t i o n s o p e r a t o r = " or " >
< condition
source = " self "
attribute = " id "
match = " ^ ui - id -\ d + "
negate = " False " / >
</ rule >
RxWeb ASP.net
XML
< rule
name = " RxWeb ASP . net "
enabled = " False "
capability = " webelement "
attribute = " id "
setweight = " 0 "
c o n d i t i o n s o p e r a t o r = " or " >
< condition
source = " self "
attribute = " id "
match = " ^ ctl00 (\$\ textpipe _ ) (.*(\$\ textpipe _ ) ) "
negate = " False " / >
</ rule >
400
RanoreXPath Weight Rule Library
RxWeb GWT
XML
< rule
name = " RxWeb GWT "
enabled = " True "
capability = " webelement "
attribute = " id "
setweight = " 0 "
c o n d i t i o n s o p e r a t o r = " or " >
< condition
source = " self "
attribute = " id "
match = " ^ gwt - uid -\ d +.* "
negate = " False " / >
< condition
source = " self "
attribute = " id "
match = " ^ isc_ .+ "
negate = " False " / >
</ rule >
XML
< rule
name = " RxWeb MS Dynamics CRM "
enabled = " True "
capability = " webelement "
attribute = " id "
setweight = " 0 "
c o n d i t i o n s o p e r a t o r = " or " >
< condition
source = " self "
attribute = " id "
match = " [a - zA - Z_ ]+ _ {([0 -9 A - F ]+( -) ?) +} _ \ d + "
negate = " False " / >
</ rule >
XML
< rule
name = " RxWin32 Random ControlIds "
enabled = " False "
capability = " nativewindow "
attribute = " controlid "
setweight = " 0 "
c o n d i t i o n s o p e r a t o r = " or " / >
401
Ranorex UI Adapter
Ranorex UI Adapter
When tracking single UI elements with Lesson 9: Ranorex Spy, Ranorex tries to specify the role and technology of the
element. Ranorex recognizes over 30 of the most commonly used types of UI elements. In Ranorex vocabulary these
types are called adapters. Every single element shown within the element tree of Lesson 9: Ranorex Spy can be
accessed using the Ranorex UI adapters that the element supports. If Ranorex is not able to assign a more specific
type of adapter to a UI element, it will be displayed as Unknown.
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.
402
Ranorex UI Adapter
The section General in Lesson 9: 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. The following example accesses properties of a Ranorex Text adapter:
C#
// Create Text adapter from RanoreXPath
Text textBox = " / form [ @controlname = TestedApp ]/ text [ @controlname = label3 ] " ;
// 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
Create Text adapter from RanoreXPath
Dim textBox As Text = " / form [ @controlname = TestedApp ]/ text [ @controlname = label3 ] "
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
C#
403
Ranorex UI Adapter
VB.NET
Create TreeItem adapter from RanoreXPath
Dim treeItem As TreeItem = " / form [ @title = TreeView Test ]/?/?/?/ treeitem [ @text = TreeItem ] "
Collapse and expand tree item
If treeItem . Expanded Then
treeItem . Collapse ()
Else
treeItem . Expand ()
End If
404
Ranorex UI Adapter
Figure 437: Button of calculator application which provides a Ranorex Button and a Ranorex NativeWindow Adapter
405
Ranorex UI Adapter
Figure 438: Button of a .NET WinForms application which provides an additional Ranorex Control adapter
406
Ranorex UI Adapter
The Control 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 Control adapter as follows:
C#
// Create Button adapter with RanoreXPath
Ranorex . Button button = " / form [ @controlname = TestedApp ]
/ button [ @controlname = button1 ] " ;
// Convert Button adapter to Control adapter
Ranorex . Control winFo rmsButto n = new Ranorex . Control ( button ) ;
// Call GetPropertyValue method provided by the Control adapter
Color color = w inForms Button . GetPropertyValue < Color >( " BackColor " ) ;
VB.NET
Create Button adapter with RanoreXPath
Dim button As Ranorex . Button = " / form [ @controlname = TestedApp ]
/ button [ @controlname = button1 ] "
Convert Button adapter to Control adapter
Dim winForm sButton As New Ranorex . Control ( button )
Call GetPropertyValue method provided by the Control adapter
Dim color As Color = w inForms Button . G et P r o p e r t y V a l u e ( Of Color ) ( " BackColor " )
It is not required to work with Ranorex adapters. Its also possible to write automation code using Ranorex Element
instances (which are used internally by Ranorex adapters) - its just more difficult.
Note: UI objects managed within Ranorex repositories always use Ranorex adapters.
407
Mobile Testing
Mobile Testing
Learn how to automate Android or iOS app testing for different devices and languages. The following sections will
explain how to set up an environment for mobile testing, how to generate and execute a test and what to do if any
problems occur. The mobile apps KeePassDroid for Android and MiniKeePass for iOS are taken as examples on how
to automate mobile applications using Ranorex.
Introduction
To automate apps on mobile devices (both iOS and Android), these devices need to be connected to a computer with
Ranorex installed. The connection can be accomplished either with a USB cable or over Wi-Fi
Getting Started
To get started with mobile application test automation choose your platform below:
Figure 439
Figure 440
Versioning
Versioning ensures that only versions of the automation library and device service compatible with the currently
installed Ranorex Studio version are used.
When using an incorrect version of an automation library/device service, a warning or error message will be shown.
If you are using an automation library/device service that is still compatible but is not the latest version, you will get
a warning. It is always recommended to use the latest version because it includes the most recent bug fixes, meaning
that you will most probably have the best possible automation experience. If for some reason you have to use an older
library/service version, you can disable the technology limitation warning.
If you are using an incompatible version you will get an error. In this case it is recommended to use the latest version
or at least a compatible one. A version becomes incompatible when completely new features are integrated or the
communication protocol is changed.
Here youll find the Mobile Download Archive to download the correct automation libraries matching your Ranorex
version.
For further platform dependent information, have a look at the Android Testing and iOS Testing chapters.
408
Mobile Testing
409
Android Testing
Android Testing
Learn how to automate your Android app testing for different devices and languages. The following sections will
explain how to set up an environment for Android testing, how to generate and execute a test and what to do if any
problems occur. The Android app KeePassDroid is taken as an example how to automate mobile applications using
Ranorex.
Infrastructure
Getting Started
Extended Information
After doing your first steps in mobile testing on Android devices please find the following chapters providing detailed
information on more advanced topics and testing scenarios.
Manage Devices
Troubleshooting
Infrastructure
Before getting started with Android test automation, its necessary to choose the connection type that suits your
needs. The following overview helps you to find out which connection type will work best for you.
Record Replay Start/Stop App Install APK Deploy (unattended) Automate System Apps
USB
Wi-Fi
Even if automating via Wi-Fi it is recommended to have your system under test plugged into a power supply during
test recording and execution.
Note: To automate on a device connected via USB instead of Wi-Fi, have a look at Add a device connected
via USB.
410
Android Testing
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.
In order to ensure that the device connection is as stable as possible, it is recommended to enable the Developer
Mode on your Android device. This mode grants access to some advanced settings which are responsible for a stable
connection. On Android 4.2 and higher, Developer Mode is hidden by default. You can unhide it by navigating to
Settings -> About Phone and tapping Build Number for seven times. Now return to the previous screen and find
Developer options in the main menu:
Inside the Developer options menu, please enable the following settings:
Stay awake which prevents your device from going to Standby during test automation.
Note: Although you might be automating via Wi-Fi, your devices should always be connected to a power
supply to ensure both letting this setting work as well as ensuring to not run out of battery during your
tests. Furthermore it disables any energy saving mechanisms for your Wi-Fi interface and makes the Wi-Fi
connection more stable.
411
Android Testing
Start your first recording by pressing the record button in Ranorex Recorder.
Next to starting a desktop, web or instant recording it is also possible to start a mobile recording.
412
Android Testing
Add Device
Open the Manage Device dialog by pressing the Devices button from the Record Settings dialog. As we there is no
Android device listed open the Add new Device dialog by pressing the Add button.
Choose Android and follow the instructions to install the Ranorex service on your Android device.
413
Android Testing
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.
414
Android Testing
Note: If you have more than one user account activated on your Android device, make sure that the Ranorex
Service app is only installed and running on the owners user account.
Note: If you do not have an internet connection on your device, download the Service app from the Add
New Device dialog, connect your device via USB and copy the apk file to the SD card of the device. Open
the copied apk file using a file explorer to install it (Make sure to allow installation of non-Market apps by
enabling Settings -> Security -> Device Administration -> Unknown Sources).
Note: Another possible way to install the service apk is to download the Service app from the Add New
Device dialog, open the command line and switch to the Ranorex Android Tools directory (<Ranorex
Installation Folder>\bin\RxEnv\Android\tools). First of all, type adb devices. If you installed the devices
USB driver correctly, adb devices should list the connected device properly. Secondly, type adb install
<Download Folder>/<Name of Service App>.apk to install the service app. After performing these steps,
start the installed service app on your 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 by selecting your discovered device and clicking on the Finish button.
415
Android Testing
If you would like to add an USB connected device, an emulator or if you have problems with a device, have a look at
the Manage Devices and the Troubleshooting section.
After setting up the Android device, the app which should be automated has to be instrumented and deployed to
the device. The Instrumentation wizard for instrumenting and deploying an APK file can be started from Manage
Devices dialog, Record Settings dialog, or directly by starting the instrumentation wizard as described in the chapter
Instrumentation Wizard - Android.
416
Android Testing
Note: Note: Its recommended to fresh instrument your app for every new Ranorex release. For further
information have a look at the section Versioning.
Note: The Instrumentation Wizard can be started from command line. For further details have a look at the
section Running Instrumentation Wizard from the Command Line.
Note: You can also instrument and deploy your APK in a recording or from code. For further details have a
look the chapter Types of Action Items and the API documentation of the InstrumentAndDeployAndroidApp
method.
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.
Next to instrumenting and deploying your Android app, the Instrumentation Wizard allows you to update the Ranorex
Service on your device as well as deploy the RXBrowser app, which enables web testing for Android.
After choosing a device to deploy and an APK file to instrument, the process will be started by pressing the Next
button.
Note: Open the Advanced Instrumentation Settings dialog by clicking the Advanced button. Here you can
change the APK signing as well as some instrumentation options. When enabling Full image comparison,
a more robust image comparison mechanism will be used. Enabling this option decreases the apps startup
performance but might be useful when having problems with determining resource ids for images. When
disabling Tree simplification, UI-trees will remain unchanged. This means no post processing will take
place, resulting in larger UI-trees. Disabling this option decreases the apps startup performance but might be
useful when automating 3rd party controls.
417
Android Testing
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.
Note: Because the Ranorex automation lib uses non-public API and adds additional permissions to your
APK, make sure you do not release automated APKs to an app store to avoid biased user experience.
418
Android Testing
Note: If you have problems with instrumenting your APK using the instrumentation wizard or if you want to
integrate the instrumentation into your build process, please have a look at the Instrumentation with Source
Code section.
By pressing the Record 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.
During the recording process, the action table of the Ranorex Recorder will give a good overview over the performed
419
Android Testing
Note: The recommended way to add a value to a text box is to tap on the text box before typing.
Note: Its recommended to wait a short period of time before operating on list elements after scrolling the
list.
Note: Its 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 its 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.
420
Android Testing
After choosing an element, the Validate Element dialog will pop up. In this dialog, the attributes which should be
validated can be selected.
421
Android Testing
Additionally to recording actions, its 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.
422
Android Testing
Action #1 is a Run Mobile App action which starts the instrumented APK file on the selected device.
Note: You can add a launcher activity to your Run Mobile App action by simply adding the activity name to
the Startup Arguments using the following syntax: <fullpackagename>/<fullpackagename.activityname>
Action # 2 is a Touch Event on a button. There are 5 different kinds of touch events recognized by Ranorex:
and Touch Start, Touch Move and Touch End for simulating a drag gesture.
Note: The duration for both, Touch and Long Touch can be defined int the properties pane. You can
open this pane by clicking the context menu item Properties on the Touch Event action item.
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 # 7 is a Validate action as described before.
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.
You can use the invoke action to call user defined methods or get and set user defined members. To call such a user
defined method
423
Android Testing
To get or set a member use GetMember or SetMember instead of CallMethod as action name. For further details
about invoke action have a look at Invoking User-Defined Actions.
User defined methods can also be invoked from code the same way. Here is a short example:
C#
string text = ( string ) repo . App . Text . Element . InvokeAction ( " CallMethod " , " m y C u s t o m G e t T e x t M e t h o d
");
VB.NET
Dim text As String = DirectCast ( repo . App . Text . Element . InvokeAction ( " CallMethod " , "
m y C u s t o m G e t T e x t M e t h o d " ) , String )
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 Close Application action. Close Application actions stop the selected application on the mobile
device.
Note: Make sure to add a Close 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 be stopped by pressing the Stop button.
Run Test
After recording and altering the action table, the test can be executed on the mobile device by pressing the Run
button.
424
Android Testing
Manage Devices
Within the Manage Devices dialog, new Android devices can be added to make them automatable by Ranorex.
Add a device
Add an emulator
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 Add new Device dialog will be shown. Choose Android as target technology
and Network as connection type and follow the instructions to install the Ranorex service on your Android device.
425
Android Testing
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.
426
Android Testing
After downloading and installing, the Ranorex Service app will be started on the device which can now be added to
the list of devices by selecting your discovered device and clicking on the Finish button.
427
Android Testing
If a device cannot be found automatically, it can be added by entering name and IP address manually. to do so, click
on the The device isnt listed button.
The IP address can be found within the service app on the device by opening the settings.
428
Android Testing
429
Android Testing
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.
Add an emulator
To add an emulator, choose Emulator as device type/connection, select the emulator from the list of discovered
devices and set a more readable name.
430
Android Testing
431
Android Testing
Before adding the device you have to enable USB debugging on your device. Additionally the USB driver has to be
installed. Therefore please refer to the website of the manufacturer of your device. For a detailed description please
have a look at Setting up a Device for Development.
To add an USB device, choose USB as device type/connection, select the device from the list of discovered devices
and set a more readable name.
432
Android Testing
433
Android Testing
434
Android Testing
You can access the non-UI testing methods in the action table by adding an invoke action on the mobile app.
435
Android Testing
You can also access the non-UI testing methods within User Code Actions as well as Code Modules.
The code should look something like the following:
C#
var app = repo . AndroidApp . Self . As < AndroidApp >() ;
// get an A n d r o i d D e v i c e I n f o object holding all available device info
var info = app . GetDeviceInfo () ;
// get a list of SMS from the device
var sms = app . GetSms () ;
// get a list of calls from the device
var calls = app . GetCalls () ;
// report the manufacturer of the device
Report . Info ( " Manufacturer : " + info . Manufacturer ) ;
// report the manufacturer of the device
Report . Info ( " SMS : " + sms . ToString () ) ;
// report the manufacturer of the device
Report . Info ( " Calls : " + calls . ToString () ) ;
VB.NET
Dim app = repo . AndroidApp . Self .[ As ]( Of AndroidApp ) ()
get an A n d r oi d D e v i c e I n f o object holding all available device info
Dim info = app . GetDeviceInfo ()
get a list of SMS from the device
Dim sms = app . GetSms ()
get a list of calls from the device
Dim calls = app . GetCalls ()
report the manufacturer of the device
Report . Info ( " Manufacturer : " & info . Manufacturer )
report the manufacturer of the device
Report . Info ( " SMS : " & sms . ToString () )
report the manufacturer of the device
Report . Info ( " Calls : " & calls . ToString () )
436
Android Testing
For further information about code modules and user code actions please have a look at the sections Lesson 7: Code
Modules and User Code Actions.
437
Android Testing
As only the application under test is instrumented for Ranorex Automation you can only record within this application.
To automate outside of the application you have to manually create the needed steps using the Ranorex Spy.
Note: To automate system apps the setting Android OS Automation has to be enabled. The setting can be
found in the mobile section of the plugin specific settings in Plugin Specific Settings.
Note: To speed up the test execution of system app automation you can disable the generation of screenshots
for android. The setting can be found in the mobile section of the plugin specific settings in Plugin Specific
Settings.
438
Android Testing
Restrictions
The following example will show how to validate a text in a received notification.
Create a new recording and open the Ranorex Spy. You will notice a node labeled MobileApp AndroidOS at the
application level in the object tree.
439
Android Testing
To navigate through the element tree you can either use the tree view. Another way to navigate is to use the
image navigator which can be found at the bottom of the Overview/Advanced tab. Clicking a UI element selects it,
double-clicking outside the selected element selects the parent.
To open the notification bar, a swipe action from the top of the screen has to be performed. Navigate to a tree
element including the navigation bar in the representing screenshot and add this element to the repository using the
context menu.
440
Android Testing
Add a swipe action by dragging/dropping the newly created repository item to the actions table and choosing Swipe
Action as action type from the context menu.
441
Android Testing
In the properties pane set the swipe direction to 90 and the start location to 0.5;0.0 which is the top center of the
element.
Manually open the notification bar on your device and switch back to Ranorex Spy. Navigate through the element
tree until youll find the element you want to validate.
442
Android Testing
Add the specific element to the repository and add a validation action on the repository item as described before.
Additionally add a key press on the back button to return to the initial situation.
443
Android Testing
444
Android Testing
Note: Make sure to add a Close 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.
Figure 486: Add a Close Application action to ensure that the recording will be executed on the right device
After doing so, make the Device Display Name of the Run Mobile App action in your recording variable.
Figure 487: Make the Device, the test will be executed, 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.
445
Android Testing
446
Android Testing
Figure 490: And add the device names to the simple data table
After doing so, switch to the Data Binding tab and bind the data source to the variable in your recording.
447
Android Testing
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.
Its also possible to run one test on multiple devices at the same time.
As there is no need to have a data source, disable the previously created data source in the test case properties.
448
Android Testing
449
Android Testing
450
Android Testing
Have a look at Lesson 3: Data-Driven Testing for further details about global parameters and data binding.
In the repository open the RanoreXPath of the mobile app folder using the path editor in Ranorex Spy.
Additional to the title add the device name to the RanoreXPath and choose the variable varMobileDevice as value.
After performing these steps you can build your test suite and execute the test case from command line using the
command line arguments to set the mobile device name as described in section Running Tests without Ranorex
Studio:
451
Android Testing
You can also download and install the RxBrowser app from our Mobile Download Archive directly to your Android
device by following the link above or by using the following QR code and click on the most recent RxBrowser for
Android.
After performing the mentioned steps its possible to access the RXBrowser app as any other instrumented native
Android app from the Record a Mobile Test dialog. Choose Web as app and define the website you want to test.
Continue by following the instructions in Record and Run an Android Test.
452
Android Testing
Note: The Web View in Android 2.3 does face stability problems. Since Ranorex also uses that web view for
Android Web Testing, those instabilities might occur as well.
453
Android Testing
Troubleshooting
Troubleshooting Android USB connections
Troubleshooting Genymotion
The Genymotion device cannot be found by Ranorex when trying to add it as emulator
The Genymotion device cannot be found by Ranorex when trying to add it as emulator)
The Genymotion device cannot be found by Ranorex when using the USB connection option
The Genymotion device with installed Ranorex service application cannot be found when using the network
connection option
The Ranorex RxBrowser gets closed when navigating to the website to automate
For a general troubleshooting please find some General Troubleshooting on connections with Android devices below.
Reason:
Ranorex is using the external ADB (Android Debug Bridge) tool to find all connected USB devices. If the ADB tool is
not able to identify the USB connected devices, also Ranorex wont be able to do so. To check if a USB connection
can be established, open any ADB tool from the command line (see note below). In the command window type adb
devices. If no device is listed, Ranorex also wont find the device since no specific USB driver is installed.
Note: The ADB tool can be found in the sub-folder Bin\RxEnv\Android\tools of the Ranorex installation path
(e.g. C:\Program Files (x86)\Ranorex 5.2).
Note: To quickly open up a command window simply keep the SHIFT key pressed while clicking the menu item
Open command window here in the context menu of Windows explorer.
454
Android Testing
Solution:
First the USB driver for the connected Android device needs to be downloaded. If you are using any Google Nexus
device, please open this website and follow the instructions. For all other devices please visit the manufacturers
website and download the USB driver from there. A small list of different manufacturer OEM drivers can be found
here. After downloading the driver please follow instructions here for the installation process.
For Windows 8 or higher there might be problems with unsigned drivers. Please follow these instructions to disable
the driver signature enforcement. Alternatively any tool can be used that installs the corresponding ADB driver (e.g.
http://adbdriver.com/downloads/) for you.
Problem:
Solution:
Please visit the Genymotion FAQ and check whether your issue is described there. Alternatively the following steps
could be done in order to fix the issue with the Genymotion VM settings:
455
Android Testing
The Genymotion device cannot be found by Ranorex when trying to add it as emulator
Reason:
Solution:
Use the USB or Network connection option to add any Genymotion emulator to the Ranorex known device list.
The Genymotion device cannot be found by Ranorex when using the USB connection
option
Reason #1
Genymotion starts his own ADB process allowing to emulate a USB connection. Thats why a Genymotion ADB
process is required.
Solution
Restart the Genymotion emulator and check the Windows Task Manager for the status of the Genymotion ADB
process.
Reason #2
The Genymotion process and the Ranorex ADB process are in conflict with each other.
Solution
First please make sure that Genymotion is running. Continue with opening the Windows Task Manager and with
killing all ADB processes. Please navigate to any ADB tool on your hard disk (see note below) and open a command
window (see another note below) with the current path. Type in adb connect <IP> whereas <IP> should be
replaced by the Genymotion Emulators IP address. In order to list all currently available devices, open the Genymotion
Shell and type devices show.
Note: The ADB tool can be found in the sub-folder Bin\RxEnv\Android\tools of the Ranorex installation path
(e.g. C:\Program Files (x86)\Ranorex 5.2).
Note: To quickly open up a command window simply keep the SHIFT key pressed while clicking the menu item
Open command window here in the context menu of Windows explorer.
The Genymotion device with installed Ranorex service application cannot be found when
using the network connection option
Reason:
The Genymotion emulator and Ranorex are not running in the same Network.
Solution:
In Genymotion please open the Ranorex Service application. Click on Details so that all available options are shown.
Click on the presented IP address and change it to another one (the one that you are connected with).
456
Android Testing
The Ranorex RxBrowser gets closed when navigating to the website to automate
Reason:
Some Genymotion emulators have some issues with opening websites. To check whether Genymotion will work
correctly with RxBrowser do the following steps:
If the website works correctly with the default web browser, then it will also work with RxBrowser. If you face any
issues please find a Solution below.
Solution:
If you have connection problems try to consider following potential sources of error:
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.
If you have more than one network interface configured on your android device, you can switch between them
by touching the IP address in the service app and choosing the desired address.
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.
457
Android Testing
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.
458
Android Testing
If you have problems with instrumenting your APK using the instrumentation wizard have a look at the
Instrumentation with Source Code section.
459
Android Testing
Note: Note: Its recommended to fresh instrument your app for every new Ranorex release. For further
information have a look at the section Versioning.
1. Link the Ranorex JAR library to your android project. You can find the Ranorex.jar file in your Ranorex
installation directory: <Ranorex install dir>\bin\RxEnv\Android\Ranorex.jar
2. Manually add following code to all your Activities:
Java
@Override
public void onResume ()
{
super . onResume () ;
com . ranorex . android . R a n o r e x A n d r o i d A u t o m a t i o n . Hook ( this ) ;
}
@Override
public void onPause ()
{
super . onPause () ;
com . ranorex . android . R a n o r e x A n d r o i d A u t o m a t i o n . UnHook ( this ) ;
}
@Override
public boolean d i s p a t c h Ke y E v e n t ( android . view . KeyEvent event )
{
com . ranorex . android . R a n o r e x A n d r o i d A u t o m a t i o n . Key ( event ) ;
return super . d i s p a t c h K e y E v en t ( event ) ;
}
XML
< uses - permission android:name = " android . permission . INTERNET " / >
< uses - permission android:name = " android . permission . INJECT_EVENTS " / >
XML
< meta - data android:name = " RxVersion " android:value = " 5.0.0 " / >
< meta - data android:name = " RxLibVersion " android:value = " 1.5.0 " / >
460
Android Testing
C#
using Ranorex . Core . Remoting ;
VB.NET
Imports Ranorex . Core . Remoting
Add the following code to add a device connected via Wi-Fi and start the first Ranorex instrumented app found
on the device:
C#
var device = R e m o t e S e r v i c e L o c a t o r . Service . AddDevice (
" DeviceName " ,
Remo tePlatfo rm . Android ,
R e m o t e C o n n e c t i o n T y p e . WLAN ,
" IPAddress " ) ;
device . WaitFor ( ChannelState . De vi ce C on ne ct e d ) ;
var firstApp = device . R a n o r e x C o m p a t i b l e A p p s [0];
device . S t a r t A p p l i c a t i o n ( firstApp ) ;
device . WaitFor ( ChannelState . AppConnected ) ;
VB.NET
Dim device = R e m o t e S e r v i c e L o c a t o r . Service . AddDevice (
" DeviceName " ,
Remo tePlatfo rm . Android ,
R e m o t e C o n n e c t i o n T y p e . WLAN ,
" IPAddress " )
Choose a proper device name and set the IP address of your device when using a network connection.
When using a USB connection set the remote connection type to RemoteConnectionType.USB instead of
RemoteConnectionType.WLAN and the serial of the device instead of the IP address.
461
Android Testing
Prerequisites
Install adb: The Android Debug Bridge (adb) is a versatile command line tool that lets you communi-
cate with an emulator instance or connected Android device. You can find it at <Ranorex Installation
folder>\Bin\RxEnv\Android\tools.
Connect with the phone: Download the Android Wear app on your phone and pair the watch with your phone.
You can find detailed information on how to do so here: https://support.google.com/androidwear#topic=6056405
Enable the debug mode: On the smartphone go to Developer Options and enable USB Debugging. On
the watch got to Developer Options and enable ADB Debugging as well as Debug over Bluetooth.
Finally, open the Android Wear app on your smartphone, press the Settings button on the top right and check
the Debugging over Bluetooth. The target should be shown as connected.
Note: If the target is still disconnected, try to restart both the smartphone and the watch.
Getting Started
Connect the device via USB to your computer and call adb via command line by typing adb devices.
It should print something like this: List of devices attached 08937p69d0518aac device
This means you have successfully connected your phone to your computer. Now we need to connect the watch too.
Type the following commands: adb forward tcp:6666 localabstract:/adb-hub adb connect localhost:6666
Type once again adb devices. You should now see a new device called localhost:6666: 08937p69d0518aac
device localhost:6666 device
In your Android Wear App, Host and Target should now show up as connected.
Note: Connecting host and target does not always work at first go. Try restarting both devices in different
order and be patient.
Now you can Add Device, Instrument and Deploy your Android App and Record and Run an Android Test.
The following instructions explain how to connect a Genymotion emulated smartphone with a Google emulated watch.
462
Android Testing
First, download Genymotion setup and start any Genymotion emulator with Android 4.3 or later. For Googles
emulated watch you need the AVD Manager.
Start the Android Studio, go to Tools -> Android -> AVD Manager. Create a new Virtual Wear device and start it.
Next, install Google Apps or Gapps on the Genymotion smartphone. With Gapps, also the Play Store will be installed,
which is needed for downloading the Wear App.
Go to http://wiki.cyanogenmod.org/w/Google Apps and download the correct Gapps for your emulator. To install
Gapps on Genymotion, please follow these instructions.
Follow the steps explained in Prerequisites and list your devices via adb as described in Getting Started.
It should print something like this:List of devices attached 192.168.154.102:5555 device
This means you have successfully connected your emulated phone to your computer. Now you need to connect the
watch too. Type the following command into the command line:adb -s {genimotion ip}:{genimotion port} -d forward
tcp:5601 tcp:5601
Type once again the adb devices command. You should see a new device called emulator-5600.
You can now Add Device, Instrument and Deploy your Android App and Record and Run an Android Test.
463
iOS Testing
iOS Testing
Learn how to automate your iOS app testing for different iPhone/iPad devices and languages. The following sections
will explain how to set up an environment for iOS testing, how to generate and execute a test and what to do if any
problems occur. The iPhone/iPad app MiniKeePass is taken as an example of mobile application automation using
Ranorex.
Infrastructure
Getting Started
Extended Information
After doing your first steps in mobile testing on iOS devices please find the following chapters providing detailed
information on more advanced topics and testing scenarios.
Infrastructure
Before getting started with iOS test automation, its necessary to choose the connection type that suites your needs.
The following overview helps you to find out which connection type will work best for you.
Note: To make an iOS app testable with Ranorex, it is necessary to instrument the app. However, for a
quick start you can take your first steps with the pre-instrumented KeePass app (see Getting Started) that is
provided for download.
USB Requirements
iTunes is necessary to establish a USB connection (debug mode and non-debug mode) because iTunes installs the
USB driver on the Windows machine to connect to iOS devices.
464
iOS Testing
Network Requirements
When choosing Wi-Fi as connection type, it is recommended that you have your system under test plugged into a
power supply during test recording and execution. Additionally make sure that the system under test (the mobile
devices) and the machine running the tests (where Ranorex is installed) are on the same network.
Getting Started
Although at the end of the day you might want to test your own mobile application, you can also take your first steps
with the pre-instrumented MiniKeePass app. Please scan the QR code with your device and follow the link to the
mobile download archive. From there the app can easily be installed.
Note: In order to automate your own mobile app it needs to be instrumented guided by the instructions in
the section Instrumentation and Preparation.
The following steps are needed to get started with the sample application:
1. Connect your iOS device (Wi-Fi or USB). See Infrastructure for pros and cons.
2. Go to the mobile download archive on your device using the QR Code above or the url bitly.com/mArchive.
3. Download and install the iOS service app and make sure it is started on your device.
4. Download and install the sample app and initially start it to let the service app recognize it.
5. Add the device in Ranorex using the Device Wizard. Youll find more details in the section Adding Your iOS
Device
6. Start your mobile recording
Note: There is a small sample delivered with Ranorex Studio (can be found on the start page) that shows
how the iOS MiniKeePass app can easily be tested with Ranorex.
465
iOS Testing
By pressing the Record button, a notification on the desktop will inform you, that actions will be recorded directly
on the mobile device.
466
iOS Testing
During the recording process, the action table of the Ranorex Recorder will give a good overview of the steps performed
as the table is updated live.
467
iOS Testing
During recording, it is possible to add validations using the Validation button. By pressing this button, a dialog will
open where the element which is to be validated can be selected.
468
iOS Testing
After choosing an element, the Validate Element dialog will pop up. In this dialog, the attributes to be validated can
be selected.
469
iOS Testing
In addition to recording actions directly, it is also possible to add actions to the action table at a later time. This can
be done by dragging a repository item to the action table and choosing the action which should be performed from
the menu.
470
iOS Testing
If your device is connected via USB you can also add a Deploy iOS App action to automatically deploy the current
version of your application under test for each test run. Choose the device, the file location of the app archive and
the app id to enable automated deployment.
After recording and adding actions manually, the action table might look something like the following.
471
iOS Testing
Action #1 is a Deploy iOS App action which deploys the given app to the selected device.
Action #2 is a Run Mobile App action which resets the instrumented app on the selected device.
Action #3 is a Touch Event on a button. There are two different kinds of touch events recognized by Ranorex:
Note: The duration for both Touch and Long Touch can be defined in the properties pane. You can open
this pane by clicking the context menu item Properties on the Touch Event action item.
Action #4 is a Set Value action, which is typically used for keyboard input.
Action #5 is a Mobile Key Press action. With a Mobile Key Press action you can simulate the Enter button on
your devices keyboard.
Action #6 is a Wait For Not Exists action, which is useful for cases where an item indicates a loading process and
the automation should continue after the item has disappeared.
Action #10 is an Invoke Action which performs a scroll action on a table control to its index 0. Invoke actions
directly call the corresponding method of the selected adapter.
You can use the invoke action to call user-defined methods or get and set user-defined members. To call such a
user-defined method
1. Type CallMethod into the action name field of the invoke action
2. Add the method name to the first argument field
3. In the following argument field enter a value or choose a variable you want to pass to the method
4. Repeat the previous step for all additional arguments
472
iOS Testing
To get or set a member, use GetMember or SetMember instead of CallMethod as the action name. For further
details about invoke action, have a look at Invoking User-Defined Actions.
User-defined methods can also be invoked from code in the same way. Here is a short example:
C#
string text = ( string ) repo . App . Text . Element . InvokeAction ( " CallMethod " , " m y C u s t o m G e t T e x t M e t h o d
");
VB.NET
Dim text As String = DirectCast ( repo . App . Text . Element . InvokeAction ( " CallMethod " , "
m y C u s t o m G e t T e x t M e t h o d " ) , String )
Action #11 is a Close Application action. Close Application actions stop the selected application on the mobile
device.
Stop Recording
After performing the test on the mobile device, the recording process can be stopped by pressing the Stop button.
Run Test
After recording and altering the action table, the test can be executed on the mobile device by pressing the Run
button.
473
iOS Testing
Its recommended to disable the Auto-Lock functionality during your test executions. To do this, open the Settings
app, tap the General settings, choose Auto-Lock settings and set Auto-Lock to Never.
In order to ensure that the instrumentation and deploying will work correctly, it is recommended to do the steps
described below.
Note: Ranorex studio cannot instrument iOS applications, which have been already instrumented with Xcode
using the Ranorex libs.
474
iOS Testing
Note: If the Deployment target doesnt match, between the iOS device and the iOS application, Ranorex
Studio will show you an error message that will tell you why the application could not be deployed.
Make sure that the Architecture (armv7 or arm64) match with the iOS device, which will be used for testing.
All iOS applications must be correctly signed with P12 certificate and matching provisioning profile.
Because the instrumentation will make some changes to the application package (IPA file), the application must be
signed again.
Note: For more information about signing and distribution, refer to the official Apple documentation.
475
iOS Testing
Note: Make sure that you have chosen a valid Developer certificate.
The mobile provisioning profile can be obtained with Xcode or on the iOS Dev Center website.
476
iOS Testing
With the right mouse click select your Provisioning Profile and choose Show in Finder
477
iOS Testing
If you are using the iOS dev center website, please make the following steps:
Navigate to https://developer.apple.com/devcenter/ios/index.action
Go to Member Center
478
iOS Testing
Note: The development provisioning profile should be used for testing your app and not the distribution
provisioning profile.
Note: When using Wi-Fi as the connection type, make sure that your iOS device or simulator is reachable
over Wi-Fi.
Start your first recording by pressing the Record button in Ranorex Recorder.
Next to starting a desktop, web or instant recording it is also possible to start a mobile recording.
Open the Manage Device dialog by pressing the Add device button in the Record Settings dialog.
479
iOS Testing
Choose iOS (iPhone, iPad) and follow the instructions to install the service app on your device shown in the following
dialog.
480
iOS Testing
When choosing USB as the connection type, the connected device should be discovered automatically. Choose the
device from the list to finish the process.
481
iOS Testing
If the device cannot be found automatically click the The device isnt listed button.
Enter the name of the device and choose the corresponding device serial.
When choosing Wi-Fi as the connection type the device should be visible in the list of devices. Choose the device to
add it to your list of devices.
If the device cannot be found automatically, click the The device isnt listed button.
Enter a name and IP address of the device and click Finish to add the device manually.
482
iOS Testing
Apart from Instrumentation with Source Code on iOS the recommended way is to instrument iOS application packages
(IPA files) with Ranorex Studio on a Windows machine.
Note: Note: Its recommended to fresh instrument your app for every new Ranorex release. For further
information have a look at the section Versioning.
483
iOS Testing
After setting up the iOS device, the app which should be automated has to be instrumented and deployed to the
device. The Instrumentation wizard for instrumenting and deploying an IPA file can be started from Manage Devices
dialog or directly by starting the instrumentation wizard as described in the section iOS.
Before instrumenting any IPA file, the iOS signing must be configured first. To do so, press Settings button in the
Instrumentation wizard for iOS. In the iOS instrumentation Settings dialog choose your P12 certificate, type the
correct password and choose the mobile provisioning profile. To get the P12 certificate and mobile provisioning
profile, please read the chapter Obtaining the P12 Certificate and the Mobile Provisioning Profile.
484
iOS Testing
After choosing an iOS USB connected device to deploy and an IPA file to instrument, the process will be started by
pressing the Next button.
485
iOS Testing
To enable this feature you have to additionally link the library Mobile Download Archive as well as the following
libraries:
AVFoundation.framework
CoreTelephony.framework
SystemConfiguration.framework
ExternalAccessory.framework
Now you are able to get the info on your iOS device directly by right-clicking the mobile device in Ranorex Spy.
You can access the device information during your test automation within User Code Actions as well as Code Modules.
C#
var app = repo . iOSApp . Self . As < IosApp >() ;
// get an iOSDeviceInfo object holding all available device info
486
iOS Testing
VB.NET
Dim app = repo . iOSApp . Self .[ As ]( Of IosApp ) ()
get an iOSDeviceInfo object holding all available device info
Dim info = app . GetDeviceInfo ()
Report e . g . the IP address of the device
Report . Info ( " IP address : " & Convert . ToString ( info . IpAddress ) )
For further information about code modules and user code actions please have a look at the sections Lesson 7: Code
Modules and User Code Actions.
487
iOS Testing
If the app will be instrumented manually, please do the following steps to register the custom URL scheme so that
the starting and stopping will work correctly:
Follow the instructions in the section Instrumentation with Source Code on iOS
Expand URL schemes with Item0 and write the app activity name as value
Note: If no URL scheme is set, the app under test cannot be launched and you will get an error message
when you try to start the app with Ranorex. In the app list of the iOS RxServiceApp there will be also a
warning message Cant launch.
After Instrumenting and deploying the app for the first time, start the app manually once.
488
iOS Testing
Note: The newly instrumented and deployed app, needs to be started manually for the first time, so that it
gets registered at the RxServiceApp.
Note: If the app is instrumented with Ranorex Studio on the Windows machine, the correct URL scheme will
be set automatically.
To use the new start/stop functionality via USB or WiFi, make sure that the RxServiceApp is running and is active
on the device. You can either use the instrumentation wizard to deploy the service app as described in iOS, or
download and install the service app on your device from our mobile download archive by scanning the following QR
Code or the using the following short URL:
Figure 534: Use the QR Code above or the url <a href=https://bitly.com/mArchive>bitly.com/mArchive</a> to
directly access the download archive on your mobile device.
Note: Start/Stop functionality can not be used from the home screen of the device, even if the RxServiceApp
is running in the background.
You can still create automated tests without the iOS RxServiceApp. Please note that without the RxServiceApp the
start/stop functionality wont work.
To add a device without the service app, make sure that an instrumented app is running and active on the device.
Note: When using the start functionality, the app under test will be launched multiple times, because it
needs to be reseted into initial state.
489
iOS Testing
Note: If you want to create automated test on an instrumented app that has no URL Scheme, please make
sure, that the RxServiceApp is not installed on the device and that the testing app is active on the device.
490
iOS Testing
After making the device name value variable, open the Data Source dialog of the test case with your recording and
add a new simple data table containing the names of the devices on which you want to run the test on.
491
iOS Testing
Figure 537: Add the device names to the simple data table
492
iOS Testing
After doing so, switch to the Data Binding tab and bind the data source to the variable in your recording.
See Lesson 3: Data-Driven Testing if you want to learn more about the data-driven approach to testing.The test suite
is now prepared for running the recording on different devices. After successfully running the test, the test report
should look like the figure below.
493
iOS Testing
Note: If you want to run one test on multiple devices at the same time, have a look at the section Run
Tests in parallel.
494
iOS Testing
Download and extract the RxBrowser Xcode project (RxBrowser.zip) from the Mobile Download Archive to
your Mac.
Either deploy the app from Xcode to the device or create an IPA file to deploy it from a Windows machine to
the device.
495
iOS Testing
Figure 541: Build and deploy the project to your iOS device or simulator
After performing the steps above, its possible to access the RxBrowser app just like any other instrumented native
iOS app. Continue by following the instructions in the Adding Your iOS Device section.
496
iOS Testing
Note: Note: Its recommended to fresh instrument your app for every new Ranorex release. For further
information have a look at the section Versioning.
This can be done by either following along with the video instructions or by following the textual description below.
497
iOS Testing
Download the automation lib from the Mobile Download Archive on your Mac.
Note: The file size of Ranorex Automation Library is about 30 megabytes. This doesnt automatically make
your app 30 megabytes bigger, since it is a universal library and only the parts essential for your app will
dynamically be added when compiling it.
In order to avoid shipping an instrumented app to your customers it is recommended to create a separate target
for your app under test. You should select the project file and duplicate the existing target.
498
iOS Testing
Note: As XCode does not automatically update all necessary files, you have to rename them manually.
You will have to alter the target itself, the targets .plist file (in workspace as well as in Build Settings
-> Packaging), the targets project name (Build Settings -> Packaging) and the schemes name (Product
-> Manage Schemes).
Add the previously downloaded automation lib to your newly created target.
499
iOS Testing
500
iOS Testing
Figure 549: Choose the lib file and specify the target, i.e. where the lib will be added
501
iOS Testing
After doing this, the automation lib will be listed in the Linked Binary With Libraries list in the Build Phases
pane of the test target.
502
iOS Testing
503
iOS Testing
Note: With iOS 8.3 you additionally have to add the IOKit.framework.
In the Build Settings pane of the test, add the switches -ObjC -all load to the option Other Linker Flags.
After performing these steps, your project can be built using the newly created target and scheme for your iOS devices
as well as simulators.
Note: If you see the debug output RxAutomationEngine init in the console pane, your app has been
instrumented successfully.
Note: Because the Ranorex automation lib uses non-public APIs, make sure that you do not submit a
Ranorex instrumented app to the app store as your app might be rejected and you might be banned from
submitting apps to the app store for a period of time.
504
iOS Testing
Note: To add your device via Wi-Fi, its necessary that the application under test is started on your iOS
device or simulator.
Note: The development provisioning profile should be used for testing your app and not the distribution
provisioning profile.
Note: To improve the object recognition of your app under test set the accessibility label attribute of your
controls.
505
Web Testing
Web Testing
The Ranorex Web Plugins (for Microsoft Internet Explorer, Mozilla Firefox, Google Chrome and Apple Safari) allow
you to test the UI of web applications in the same way you would automate standard desktop applications.
Cross-Browser Testing
Handling of AJAX
506
Web Testing
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.
The following sample shows how to use these features:
C#
// 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 . W a i t F o r D o c u m e n t L o a d e d () ;
// Execute a javascript code
webDocument . ExecuteScript ( " history . back () ; " ) ;
VB.NET
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 . W a i t F o r D o c u m e n t L o a d e d ()
Execute a javascript code
webDocument . ExecuteScript ( " history . back () ; " )
507
Web Testing
C#
// 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
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 Instrumentation Wizard. Creating
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.
Handling of browser specific UI controls requires a separate RanoreXPath for each browser specific element. That
means if you would like to click on a Pop-Up dialog in different browser, you will have to add a separate repository
item for each dialog.
The Ranorex Automation library provides you with a property called BrowserName which tells you the current
browser of the web site under test:
C#
// 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 ] " ;
508
Web Testing
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
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
509
Web Testing
The following example shows how to access the methods of the WebDocument using a repository:
C#
// Load repository
P r o j e c t R e p o s i t o r y repo = P r o j e c t R e p o s i t o r y . Instance ;
// Open a website
repo . WebPage . Self . Navigate ( " http :// www . ranorex . com " ) ;
// Wait until the document is loaded
repo . WebPage . Self . W a i t F o r D o c u m e n t L o a d e d () ;
VB.NET
Load repository
Dim repo As P r o j e c t R e p o s i t o r y = P r o j e c t R e p o s i t o r y . Instance
Open a website
repo . WebPage . Self . Navigate ( " http :// www . ranorex . com " )
Wait until the document is loaded
repo . WebPage . Self . W a i t F o r D o c u m e n t L o a d e d ()
510
Web Testing
Samples
The following web testing examples show how to access typical web elements of a web page.
Handling of AJAX
The Ranorex web site provides a small page especially for web testing purposes:
http://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)
511
Web Testing
512
Web Testing
Handling of AJAX
C#
G l o b a l R e p o s i t o ry repo = G l o b a l R e p o s i t o r y . 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 () ;
// Wait for the ajax request for max 10 seconds (10000 milliseconds )
PreTag result = webDocument . FindSingle ( " .// div [ @id = ajax_response ]/ div / pre " , 10000) ;
VB.NET
Dim repo As G l o b a l R e po s i t o r y = G l o b a l R e p o s i t o r y . 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#
G l o b a l R e p o s i t o ry repo = G l o b a l R e p o s i t o r y . Instance ;
WebDocument webDocument = repo . WebPage . Self ;
// List all elements of a table
foreach ( TrTag row in repo . WebPage . DivTagContent . T a b l e T a g S i m p l e t a b l e . Find ( " ./ tbody / tr " ) )
{
string rowInfo = " " ;
TdTag rowNameCell = row . FindSingle ( " ./ td [2] " ) ;
rowInfo += " Row index : " + rowNameCell . Pr e vi ou sS i bl in g . InnerText + " , " ;
rowInfo += " Row name : " + rowNameCell . InnerText + " , " ;
rowInfo += " Row value : " + rowNameCell . NextSibling . InnerText + " , " ;
513
Web Testing
VB.NET
Dim repo As G l o b a l R e po s i t o r y = G l o b a l R e p o s i t o r y . Instance
Dim webDocument As WebDocument = repo . WebPage . Self
List all elements of a table
For Each row As TrTag In repo . WebPage . DivTagContent . T a b l e T a g S i m p l e t a b l e . Find ( " ./ tbody / tr " )
Dim rowInfo As String = " "
Dim rowNameCell As TdTag = row . FindSingle ( " ./ td [2] " )
rowInfo += " Row index : " & rowNameCell . Pr e vi ou sS i bl in g . 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 " , " #33 ff00 " )
Next
Report . Info ( rowInfo )
Next
C#
// Use mouse and keyboard to set Name
repo . WebPage . TestForm . I n p u t T a gT e s t n a m e . Click () ;
Keyboard . Press ( " Test Name " ) ;
// Set email address directly via Value
repo . WebPage . TestForm . I n p u t T a g T e s t e m a i l . Value = " test@ranorex . com " ;
// Open calendar form
repo . WebPage . TestForm . B u t t o n T a g C a l e n d a r . Click () ;
// Select the 22 th of the current month
repo . WebPage . TdTag_22nd . Click () ;
// Select each item of list box
foreach ( OptionTag option in repo . WebPage . TestForm . S e l e c t T a g T e s t m u l t i p l e . Find ( " .// option " ) )
{
option [ " selected " ] = " selected " ;
}
// Perform a click without moving the mouse to the button
repo . WebPage . TestForm . Input TagSubmi t . PerformClick () ;
VB.NET
Use mouse and keyboard to set Name
repo . WebPage . TestForm . I n p u t T a gT e s t n a m e . Click ()
Keyboard . Press ( " Test Name " )
Set email address directly via Value
repo . WebPage . TestForm . I n p u t T a g T e s t e m a i l . Value = " test@ranorex . com "
Open calendar form
514
Web Testing
C#
webDocument . ExecuteScript ( " history . back () ; " ) ;
VB.NET
webDocument . ExecuteScript ( " history . back () ; " )
C#
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
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
515
Source Control
Source Control
Important notice
This User Guide section provides information on the software prerequisites for each of the supported version control
systems and how they can be used within Ranorex Studio.
As a precondition we assume you have knowledge about version control in general, as well as your specific version
control system. Setting up and configuring the version control system of your choice is not in the scope of this
documentation.
Git
Subversion
516
Source Control
Git
Git is a distributed version control system which is free and open source.
In order to use Git as a source control provider in Ranorex Studio, the following preconditions have to be fulfilled in
the given order:
Git needs to be installed Download Git for Windows here: https://git-scm.com/download/win Please make
sure you choose to Use Git from the Windows Command Prompt during Git installation!
Figure 559
517
Source Control
Ranorex Studio will assist you with this dialog in case the required prerequisite is not present on the machine:
Figure 560
To add an existing Ranorex Solution to Git, open the context menu of the solution. Go to Source Control and
select Add Solution to Source Control.
518
Source Control
Figure 561
To add a new Ranorex Solution to Git, check the option Add to Source Control in the New Project dialog.
519
Source Control
Figure 562
The Source Control Wizard will be opened. Please follow these instructions:
520
Source Control
Figure 563
2. The Ranorex Solution is automatically configured as a new local Git repository. All files are indicated with a
plus sign in Projects View.
521
Source Control
Figure 564
3. To commit the current state to the local repository click on Commit. . . in the context menu of the solution.
522
Source Control
Figure 565
523
Source Control
Figure 566
1. Open the Tools menu, move to Source Control and click on Checkout.
524
Source Control
Figure 567
525
Source Control
Figure 568
3. TortoiseGit will ask you for the path to the repository and where you would like to store the files on your local
machine. Fill in the URL to the Git repository as well as the path to the local directory and press OK.
526
Source Control
Figure 569
4. The whole repository will be cloned to the local folder. After a successful clone this dialog will be shown.
527
Source Control
Figure 570
5. In case your repository includes a Ranorex Solution in its root, this solution will be opened automatically. If
this is not the case, you have to open the Ranorex Solution manually from the file System. After opening the
Ranorex Solution from the local folder you see the icon overlays in Projects View.
528
Source Control
Figure 571
Overlay icons are added to the items in the Projects View in Ranorex Studio, as the solution is under source control.
Icon overlays
Normal Not locally modified, no changes waiting for commit.
Conflicted Indicates a conflict.
Modified Modified, changes are waiting to be committed.
Added Marked for addition, waiting to be committed.
529
Source Control
Subversion
Options
TortoiseSVN It is a Windows shell extension for Subversion and provides the icon overlays showing the file
status in Ranorex Studio.
Ranorex Studio will assist you with this dialog in case the required prerequisite is not present on the machine:
Figure 572
530
Source Control
Figure 573
To add a new Ranorex Solution to Subversion, check the option Add to Source Control in the New Project
dialog.
531
Source Control
Figure 574
532
Source Control
Figure 575
Figure 576
533
Source Control
Figure 577
4. Choose the folder in the repository you want to add your solution to.
534
Source Control
Figure 578
5. Check the files you want to have under source control and uncheck the files you dont want to have under
source control respectively.
535
Source Control
Figure 579
536
Source Control
Figure 580
537
Source Control
Figure 581
538
Source Control
Figure 582
After performing these steps, your solution is under source control and your local copy is up to date.
Figure 583
539
Source Control
Figure 584
540
Source Control
Figure 585
3. Enter the URL of your repository and specify the checkout directory.
541
Source Control
Figure 586
542
Source Control
Figure 587
Overlay icons are added to the items in the Projects View in Ranorex Studio, as the solution is under source control.
Icon overlays
Normal Not locally modified, no changes waiting for commit.
Conflicted Indicates a conflict.
Modified Modified, changes are waiting to be committed.
Added Marked for addition, waiting to be committed.
Options
543
Source Control
Figure 588
In order to use another version of TortoiseSVN and SharpSvn than the preinstalled ones, you have to download and
install the version you want to use:
After that download, the corresponding package for SharpSvn from https://sharpsvn.open.collab.net. Please
make sure you choose the right version of SharpSvn, which matches the TortoiseSVN version.
Extract the downloaded Version.
Once you restart Ranorex Studio, the correct version of SharpSVN will be automatically chosen.
544
Source Control
Options
Team Foundation Version Control (TFVC) is a centralized version control system by Microsoft included in Team
Foundation Server.
In order to work with TFVC in Ranorex Studio either Microsoft Visual Studio or Team Explorer for Microsoft Visual
Studio have to be installed on the same machine. These programs come with the required Team Foundation Server
MSSCCI Provider.
Ranorex Studio will assist you with this dialog in case the required prerequisite is not present on the machine:
Figure 589
The MSSCCI interface supports single byte character sets (SBCS) only. Here you can find a description on how to
change the code page. This means there is no MBCS support.
Please make sure your Team Foundation Server infrastructure is set up and working.
545
Source Control
For adding anexisting Ranorex Solution to TFVC open the context menu of the solution. Go to Source Control
and click on Add Solution to Source Control.
Figure 590
To add a new Ranorex Solution right from the beginning to TFVC check the option Add to Source Control in the
New Project dialog.
546
Source Control
Figure 591
547
Source Control
Figure 592
548
Source Control
Figure 593
549
Source Control
Figure 594
550
Source Control
4. Select the files you want to have under source control and deselect the files you dont want to have under
source control respectively and perform a check in.
Figure 595
After performing these steps, your solution is under source control and your local copy is up to date.
551
Source Control
Figure 596
Please make sure your Team Foundation Server infrastructure is set up and working.
Figure 597
2. Choose Microsoft Team Foundation Server as Source Control provider in Source Control Wizard.
552
Source Control
Figure 598
553
Source Control
Figure 599
Figure 600
5. Choose the folder in the repository you want to check out from server.
554
Source Control
Figure 601
555
Source Control
Overlay icons are added to the items in the Projects view in Ranorex Studio as the solution is under source control.
Icon overlays
Checked In File under source control, not checked out for editing.
Checked out File under source control, checked out, not dirty.
Checked out Modified File under source control, checked out, dirty.
Added File added to project, not checked in.
Options
If you are working with TFVC and running into performance problems with big solutions, uncheck Enable file state
Modified check.
556
Source Control
Figure 602
557
Integration
Integration
Introduction
Ranorex can perfectly be used as a standalone tool in order to launch automated tests manually on local and/or
remote machines. However it might be more powerful and comprehensive to integrate Ranorex with other tools.
These tools could be Continuous Integration (CI) tools, Test Management (TM) tools or simply with Task Scheduling
tools. This comes with the main benefit that automated tests get launched automatically. This launch could be
triggered by a specific action (e.g. source code commit from a developer), a periodical build (e.g. nightly build), a
test case with underlying test automation or simply triggered by a scheduled task for a specific (e.g. every midnight).
Figure 603
Continuous Integration
There are a lot of brilliant and useful Continuous Integration tools around. See how to integrate Ranorex into a
typical Continuous Integration process which is explained in detail in our general blog post:
Integrate Ranorex into Any Continuous Integration Process
For several widely spread Continuous Integration tools please find the a specific blog post here:
For a deeper integration of your Ranorex Report into a common CI tool (e.g. Jenkins) using xUnit/jUnit please see
the blog post:
Fully integrate your Ranorex Report with CI tools like Jenkins using xUnit
558
Integration
This blog post also contains explanations and downloadable samples for the XSL transformation of the Ranorex report
to xUnit/jUnit format.
There is a lot of excellent tool support. For the integration of Ranorex into two widely spread test management tools
and ALM tools respectively please read the blog posts:
Although Coded UI Tests as well as VAPI-XP tests might be specific for the particular tool, the common idea of
integrating Ranorex with TM/ALM tools might be pretty much the same for all other tools around. It all breaks
down to the usage of command line arguments for tailored automated test runs with Ranorex.
There is a comprehensive article about the Microsoft Team Foundation Server, Visual Studio and Microsoft Testmanager
and the Integration with Ranorex. Please find the documentation here:
Atlassian Jira
There is a very informative blog post on how to integrate Ranorex Test Cases into the issue and defect management
tool Jira. Please find it here:
559
Ranorex Studio IDE
Create
Build
Run
Solution Explorer
Debugging
Code Completion
Code Conversion
Code Navigation
Code Generation
Refactoring
560
Ranorex Studio IDE
Create
The chapter Recording a Test already explains how to create a new Ranorex Solution. Within a Ranorex Solution
different kinds of projects can be created.
A project holding a Ranorex Test Suite which may contain recordings and
Ranorex Test Suite code modules. This might be your first choice when starting with Ranorex
Studio
Ranorex Test Suite Module Library A project holding recordings and code modules which can be shared and
reused
Ranorex Class Library A project for creating classes which are used in other applications
Ranorex Console 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.
561
Ranorex Studio IDE
562
Ranorex Studio IDE
Build
After creating your application, it can be built using the Build menu.
Within this menu, either the whole solution, or a specific project in the solution can be built, rebuilt or cleaned.
Build messages will be shown in the Output window.
Project specific settings can be defined in the Project Options dialog, which can be accessed from the Project
menu.
563
Ranorex Studio IDE
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 CPU and framework or the output path in the Compiling tab.
564
Ranorex Studio IDE
565
Ranorex Studio IDE
Run
After building the project successfully, it can be executed from the Debug menu either with or without debugger.
566
Ranorex Studio IDE
567
Ranorex Studio IDE
Figure 614: Adding new item through Project Explorer context menu
568
Ranorex Studio IDE
Code Module,
Module Groups,
Repository
Class,
Interface,
Struct and
Form
text files.
After adding a Form its 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 Community Blog.
569
Ranorex Studio IDE
Solution Explorer
Besides adding new items to the project, the Solution Explorer allows to perform some other assistant options to
edit your solution.
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.
570
Ranorex Studio IDE
571
Ranorex Studio IDE
572
Ranorex Studio IDE
Debugging
Ranorex provides the possibility to debug code directly in the development environment.
To enable the debugger press the Enable Debugging button in the toolbar.
To make the Debugger stop at a specific position in your code, you can set breakpoints. Breakpoints can either be set
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.
573
Ranorex Studio IDE
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, its 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 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
574
Ranorex Studio IDE
To skip several lines of code and continue debugging on a specific line, the context menu item Set Current Statement
can be chosen by right-clicking on the line and choosing Set Current Statement from the context menu.
575
Ranorex Studio IDE
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.
576
Ranorex Studio IDE
Local Variables Shows variables defined in the function currently being executed, arguments passed into the
current function and fields and properties of the class where the function is defined.
Shows all expressions added to the watch list. Expressions can be added by right-clicking on the
Watch window, choosing Add from context menu and entering the expression. Expressions can also be
added by selecting them in code and dragging them into the Watch window.
Additionally to the different views its also possible to diagnose individual objects directly in code using the tool tips
popping up when moving the mouse over them.
577
Ranorex Studio IDE
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.
578
Ranorex Studio IDE
Code Completion
Ranorex supports code completion as you type.
Further details about how this works can be found in the article Code Completion posted at SharpDevelop Community
Blog.
579
Ranorex Studio IDE
Code Conversion
With Ranorex Studio it is possible to convert a single code file as well as whole projects from C# to VB.NET and
vice versa.
This can be performed by right-clicking on the specific element in the Project Explorer and choosing Convert from
the context menu.
580
Ranorex Studio IDE
Code Navigation
With Ranorex Studio several features for an intuitive and quick navigation in code are supported. Further details can
be found in the article Code Navigation posted at SharpDevelop Community Blog.
581
Ranorex Studio IDE
Code Generation
Ranorex Studio can help you saving time with providing you auto generated code and code templates as described in
the article Code Generation posted at SharpDevelop Community Blog.
582
Ranorex Studio IDE
Refactoring
Ranorex Studio supports several mechanisms to refactor code. Further details can be found in the article Refactoring
posted at SharpDevelop Community Blog.
583
Visual Studio Integration
Note: The sample works with both Microsoft Visual Studio 2005 and 2008.
Figure 629: Create a new Console Application with Microsoft Visual Studio
584
Visual Studio Integration
C#
using System . Drawing ;
using Ranorex ;
VB.NET
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#
[ STAThread ]
static int Main ( string [] args )
585
Visual Studio Integration
VB.NET
< STAThread > _
Public Shared Function Main ( args As String () ) As Integer
Add the following code lines to the Main routine of the class Program:
C#
int error = 0;
try
{
System . Diagnostics . Process pr = System . Diagnostics . Process . Start ( " calc . exe " ) ;
Form form = Host . Local . FindSingle < Ranorex . Form >( " form [ @processname = " + pr . ProcessName + " ] "
);
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 ( R a n o r e xE x c e p t i o n e )
{
Console . WriteLine ( e . ToString () ) ;
error = -1;
}
return error ;
VB.NET
Dim returnError As Integer = 0
Try
Dim pr As System . Diagnostics . Process = System . Diagnostics . Process . Start ( " calc . exe " )
Dim form As Form = Host . Local . FindSingle ( Of Ranorex . Form ) ( " form [ @processname = " & pr .
ProcessName & " ] " )
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 R a no re x E x c e p t i o n
Console . WriteLine ( e . ToString () )
returnError = -1
End Try
Return returnError
586
System Requirements
System Requirements
The following system requirements are valid for all Ranorex components including Studio, Runtime, Spy, Recorder,
License Manager and Agent.
Software Requirements
Hardware Requirements
Firewall Configuration
Windows XP
Windows Vista
Windows 7
Windows 8
Windows 8.1
Windows 10
587
System Requirements
Software Requirements
The following software requirements are needed to run all Ranorex components (Runtime, Spy, Recorder, License
Manager and Agent). They are usually automatically installed when running the Ranorex setup:
Microsoft Visual C++ 2008 x64 (required for 64 bit Windows versions only)
Microsoft Visual C++ 2010 x64 (required for 64 bit Windows versions only)
Hardware Requirements
The hardware requirements depend on the .NET Framework version that needs to be installed for the respective
Ranorex package. Ranorex (Runtime, Spy, Recorder, License Manager, Studio and Remote Agent) requires the
installation of the .NET Framework 4.0 or higher. The minimum system requirements for running Ranorex
(Runtime, Spy, Recorder, License Manager, Studio and Agent) are the same as those for the .NET Framework
4.0: https://www.microsoft.com/en-US/download/details.aspx?id=17718
The recommended minimum system requirements for running Ranorex (Runtime, Spy, Recorder, License Manager,
Studio and Remote Agent) are:
Processor: 2 GHz
Memory: 512 MB
Minimum installation: Approximately 80 megabytes (MB) free disk space are needed to install the Ranorex
runtime environment.
Ranorex Agent: A Ranorex Agent requires approximately 25 megabytes (MB) free disk space. Please keep in
mind that a Ranorex Runtime License is needed per Ranorex Agent.
588
System Requirements
Additionally, for automating WPF applications (since Ranorex 5.3) and running Ranorex Studio the following
prerequisites are required:
Hardware Requirements
The hardware requirements depend on the .NET Framework version that needs to be installed for the respective
Ranorex package. Ranorex (Runtime, Spy, Recorder, License Server) requires the installation of the .NET Framework
2.0 or higher. Ranorex Studio requires the .NET Framework 3.5. Consequently: 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 recommended minimum system requirements for running Ranorex (Runtime, Spy, Recorder, License Server):
Processor: 2 GHz
Memory: 512 MB
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
The recommended minimum system requirements for running Ranorex Studio:
Full installation: Approximately 200 megabytes (MB) free disk space are required to install the full Ranorex
package (includes Ranorex Studio, main components, documentation, etc.)
589
System Requirements
Minimum installation: Approximately 80 megabytes (MB) free disk space are needed to install the Ranorex
runtime environment.
590
64-bit Platforms
64-bit Platforms
Ranorex handles testing of 32/64 bit based applications on 64 bit operating systems automatically. It is possible, but
recommended only for advanced users, to turn off the bit bridge feature within the Ranorex Settings dialog.
Note: 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 or (32 bit) 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 Compiling tab in the project properties. .NET applications are by
default started as 64 bit processes on 64 bit operating systems unless the target CPU is explicitly set to the 32 bit
(x86) architecture. Consequently, set the Target CPU property to Any processor for automating 64 bit applications
and to 32-bit Intel-compatible processor for 32 bit applications.
591
Remotely Working with Ranorex
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 Console as these tools will not lock the screen when
closing or minimizing the remote client window.
592
Remotely Working with Ranorex
C#
Keyboard . Enabled = false ;
and
C#
Mouse . Enabled = false ;
C#
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, dont 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.
593
Silent Installation of Ranorex
Installation Packages
Installation Packages
Ranorex uses the Microsoft/Windows Installer (MSI) for its setup. Consequently, 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 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.
The silent installation will not work for any prerequisites (a message will pop-up asking whether you want to install the
required components) due to legal limitations. If you want to make sure that all System Requirements are installed
silently as well, you need to install them separately, e.g. using a batch file.
If you do not want to install all Ranorex features, you can (de)select these features using the command line options
ADDLOCAL and REMOVE.
For example, the following command line will install all Ranorex components except for Ranorex Studio:
msiexec /i Ranorex-x.x.x.x.msi ADDLOCAL=ALL REMOVE=RanorexStudioFeature or: Ranorex-
x.x.x.exe ADDLOCAL=ALL REMOVE=RanorexStudioFeature
Possible feature names used as parameter to ADDLOCAL or REMOVE (separated by commas) are:
RanorexSamples
RanorexStudioFeature
RanorexFirefoxExtension
RanorexIEAddon
RanorexDocumentation
594
Silent Installation of Ranorex
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 would 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 machines 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 Ranorex3.x installations) or Ranorex2.lic (for Ranorex 2.x installations) and copy it to the folder
%ALLUSERSPROFILE% by using the XCOPY command in a batch file.
595
XCOPY Deployment
XCOPY Deployment
Opening Note: The way of deploying tests without Ranorex Installation described below is possible but
not recommended. Still this approach is documented since it allows to overcome internal policies and/or
restrictions inhibiting installations on runtime environments, e.g. due to group policies within domains.
Note: It is crucial to deploy the Ranorex Assemblies with exactly the same version that was used to compile
the test executable
596
XCOPY Deployment
597
XCOPY Deployment
Note: You can directly access this folder by right-clicking the current project and choosing Open Output
Folder in the context menu.
Next to files needed for test execution, additional files are created in the output folder during test execution (e.g.
Reports, Screenshots etc.). Those files do not have to be copied. Its recommended to clear your output folder before
and then trigger a new build (Build -> Build Solution or hot key F8).
Ranorex Module Group (*.rxtmg), only necessary if modules groups are in use
Test Data (*.xlsx, *.xlsb, *.xls, *.csv, *), only necessary for data driven tests and if data source files were added
to project
Module Libraries (*.dll), only necessary if module libraries are linked and embedded functionality is referenced
in the Test Suite
Sub folder RepositoryImages including all files, if exists
Finally copy the files needed to the target machine and place them in the folder where all Ranorex Libraries and Assem-
blies are already located (<TargetFolder>). Of course, by copying the whole output folder (bin\debug by default),
you will ensure you have everything possibly required for running your test. xcopy <RanorexProject>\bin\debug\*.*
<PortableMedia>xcopy <PortableMedia> <TargetFolder>
Note: For executables being explicitly compiled against 64bit CPUs, place these files in the sub folder x64
of the target folder.
598
Licensing
Licensing
In general Ranorex provides two different types of licenses to install:
The node locked license type is bound to the machines 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.
If you are going to transfer a license to another machine, have a look at the section Transfer Licenses.
License Registration
In order to register a Ranorex license, start the Ranorex Licensing tool, which is available in the Ranorex start menu
folder.
Simply type or paste in the Ranorex license key which has been delivered to you by email and press Install.
599
Licensing
If there is no internet connection available Ranorex allows to register the target machine using a license activation
web site on a computer with an internet connection.
The web site address 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 machines
host name. After clicking the Authenticate button youll 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.
600
Licensing
In order to use a Ranorex Floating License it is required to install and run the Ranorex license manager application on
a computer within a network. The download link for the license manager setup package is part of the license delivery
email. Simply install the package on a system which is reachable from computers which intend to use a Ranorex
floating license.
Note: To prevent firewalls from blocking communication between license manager and client, it is required
to open port 7266 for TCP and UDP access on the machine running the license manager.
Note: By installing a Ranorex license manager its required to use a Ranorex license manager installation
package at least as current as your Ranorex client installation.
Note: The Ranorex license manager can be used in IPv4, IPv6 and mixed networks.
601
Licensing
Open the Ranorex license manager configuration tool. Add the floating license keys to the text box and press Install.
These licenses are now ready to use.
To get more information about the clients leasing a license you can select the specific license in license manager
configuration tool and open the Clients tab.
Using the Save Log button allows you to export all actions processed by the license manager as CSV- or XML-file
for further processing.
Note: It is recommended to have an internet connection available in order to install a new license.
Figure 640: No internet connection available - license needs to be registered on a computer with internet connection
If there is no internet connection available, authenticate the floating license using the license authentication web site.
The web site address 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 machines
host name. After clicking the Authenticate button youll 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.
602
Licensing
In order to use an installed floating license, open the Ranorex license tool on the client and select the option Floating.
Figure 641: Using license manager for automatically requesting an appropriate license
Press the button Detect to request a list of the currently available license managers within the local network.
The license type specifies which license (Runtime, Premium) should be used on the client. By selecting Auto, the
client automatically requests the appropriate license. In case of running Ranorex tests via the standalone test suite
runner or from command line, only a Runtime floating license will be used. When starting Ranorex Spy tool a Premium
floating license will be leased on the manager. 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
manager. If the type of the required license is available, it will be assigned to the requesting client. By being idle,
closing Ranorex Studio or finishing a test run the license will be automatically released and can then be used by other
clients.
For this reason a reliable network environment is required when working with floating licenses.
Note: If a floating license has not been released correctly (based on a network problem for example), it will
be locked for a time-out of 5 minutes.
Uninstall License
In order to uninstall a floating license right-click the license you are going to uninstall and choose Uninstall License(s)
from the context menu in the Ranorex license manager tool.
603
Licensing
In order to uninstall a node-locked license from a machine, please use the uninstall button in the Ranorex License
Tool.
604
Licensing
Transfer Licenses
In order to transfer a license, you have to uninstall the license from the machine you want to transfer it from as
described in the section above. After that, the license will be available for installation on a different machine.
605
How to instructions
How to instructions
This library includes instructions for often needed tasks in a short and practical format:
606
How to instructions
A solution can have one solution settings file, named Ranorex.rxsettings. It stores the value of so called solution
settings in it. Find out more about solution settings here: Solution settings
Figure 646
4. A folder named Solution Items, including the solution settings file Ranorex.rxsettings is automatically created.
Figure 647
607
FAQ
FAQ
How does Ranorex identify UI elements?
Is it possible to run the same Ranorex test code on Vista and XP?
What shall I do with unexpected dialogs and popup windows during test automation?
What are the system requirements for developing and running Ranorex tests?
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: /form[@title=WordPad]/.//button[@text=&No or @text=Do&nt Save] The RanoreXPath searches for a
button, whether it contains the text &No or Do&nt Save.
608
FAQ
A general description of how to create data driven test cases can be found here:
Lesson 3: Data-Driven Testing
1. Search timeout: Each element and each folder stored within the objects repository defines is its own timeout
used for search. In many cases it is required to wait for a dialog before continuing automation. Use the Waiting
for UI Elements - Repository Timeouts 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.
Check the objects 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. Compare
the absolute path, shown within the object repositorys 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.
609
FAQ
What shall I do with unexpected dialogs and popup windows during test
automation?
Ranorex provides the dedicated class PopupWatcher to watch for and to handle popup windows. By using this
class, not only simply click actions to close popup dialogs can be called. Even more complex scenarios can be handled
in custom callback routines being called at the time the popup appears.
Read more about how to handle popup dialogs with Ranorex in the section Handling unexpected Dialogs.
What are the system requirements for developing and running Ranorex
tests?
The following link to our online documentation shows what is needed to develop or to simply run Ranorex tests.
System Requirements
610
FAQ
611