Ranorex Tutorial

Ranorex Tutorial Test Automation Guide
Copyright 2013 Ranorex GmbH Created on: August 8, 2013 Ranorex Version: 4.1 Authors: Roland Enzinger, Christoph Preschern, Tobias Walter Special Thanks to: Michael Gissing, Alexander Hoisl
Contents
Ranorex Studio - The Layout #1 - Project View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . #2 - Module Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . #3 - File View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lesson 1: Getting Started Preparing to Record User Actions . . . . . System Under Test: KeePass Password Safe Recording a Test . . . . . . . . . . . . . . Analyzing Recorded Steps . . . . . . . . . . Executing the Test . . . . . . . . . . . . . Lesson 2: Ranorex Modules - Test Actions Lesson 3: Data-Driven Testing Using Variables within Recordings . . Using Variables within the Repository Creating Test Data . . . . . . . . . . Combining Variables with Test Data . Combining Variables with Parameters Invoking Actions: Selection . . . . . . Executing Data Driven Tests . . . . . 1 1 2 2
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
5 . 5 . 5 . 6 . 16 . 16 19 21 21 22 24 28 28 31 34 36 36 42 47 52 53 56 58 61 64 67 71 77 80 83 87 94 109 114 115 122 128 132 135 138 140 143 143 146 148
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
Lesson 4: Ranorex Test Suite Test Suite Editor . . . . . . . . . . . . . . . Module Group Editor . . . . . . . . . . . . . General Structure of a Test Suite and its Test Running a Test Suite . . . . . . . . . . . . . Running Tests without Ranorex Studio . . . . Test Suite Settings . . . . . . . . . . . . . . Test Case Settings . . . . . . . . . . . . . . Using Data in Test Suites . . . . . . . . . . . Lesson 5: Ranorex Recorder Before Starting to Record . During Recording . . . . . After Recording . . . . . . Replay and Debug Actions Recorder Variables . . . . . User Code Actions . . . . . Additional Editing Options Image-Based Automation .
. . . . . . . . Cases . . . . . . . . . . . . . . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
Lesson 6: UI Mapping with Ranorex Repository Adapting an Existing Repository . . . . . . . . Adding Repository Items . . . . . . . . . . . . Waiting for UI Elements - Repository Timeouts Editing RanoreXPath . . . . . . . . . . . . . . Repository Separation . . . . . . . . . . . . . . Repository Settings Dialog . . . . . . . . . . . Repository Item Properties . . . . . . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
Lesson 7: Code Modules Creating Code Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Repository within Code Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Screen Shots within Code Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Variables with Code Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Using Code Modules within Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Lesson 8: Reporting Reading Ranorex Reports . . . . . . Report Levels . . . . . . . . . . . . Logging Individual Information . . . Updating the Custom Report Format Create a Custom Report Template . 154 154 156 158 164 165 168 171 172 176 178 181 201 204 205 207 208 208 208 209 210 210 212 213 214 214 215 216 216 217 218 219 219 222 222 225 226 228 229 232 233 235 237 240 244 247 251 254 257
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
Lesson 9: Ranorex Spy Short Introduction to the Structure of RanoreXPath . Capture Screenshot Files for Image-Based Search . . Tracking UI Elements . . . . . . . . . . . . . . . . . RanoreXPath Edit Mode . . . . . . . . . . . . . . . The Path Editor . . . . . . . . . . . . . . . . . . . . Creating Ranorex Snapshot Files . . . . . . . . . . . General Ranorex Settings General settings . . . . . Advanced Settings . . . . Recorder Settings . . . . Repository Settings . . . Imaging Settings . . . . . Plug-In Specific Settings
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
Code Examples Using Repository in Code . . . . . . . . . . . . . . . . . Wait for UI Elements Using Repository . . . . . . . . . . Create Adapters to Access More Properties and Methods Create a List of Adapters From a Repository Element . . Using Validate Class . . . . . . . . . . . . . . . . . . . . Forcing a Test Case to Fail . . . . . . . . . . . . . . . . Set Up Automation Speed . . . . . . . . . . . . . . . . Accessing Test Case & Test Suite Context . . . . . . . . Advanced Code Examples . . . . . . . . . . . . . . . . . How to do image based automation . . . . . . . . . . . How to find and compare images . . . . . . . . . . . . . Handling unexpected Dialogs . . . . . . . . . . . . . . . Data Connectors Manage Data Sources . . Kind of Data Connectors Simple Data Table . . . CSV File . . . . . . . . . SQL Connector . . . . . Excel File . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
Instrumentation Wizard Running Instrumentation Wizard from the Command Line Java AWT/Swing . . . . . . . . . . . . . . . . . . . . . . Adobe Flash/Flex . . . . . . . . . . . . . . . . . . . . . . Mozilla Firefox . . . . . . . . . . . . . . . . . . . . . . . . Google Chrome . . . . . . . . . . . . . . . . . . . . . . . Apple Safari . . . . . . . . . . . . . . . . . . . . . . . . . Android . . . . . . . . . . . . . . . . . . . . . . . . . . . iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
II
Working with 2.X Projects in 3.X Test Suites Adding 2.X Projects to 3.X Projects . . . . . Using 2.X Recording Modules . . . . . . . . . Adapting 2.X Data-Driven Recording Modules Using 2.X Code Modules . . . . . . . . . . . Breaking Changes . . . . . . . . . . . . . . . Technology Instrumentation Flash/Flex Testing . . . . . . Testing of Java Applications . Qt Testing . . . . . . . . . . . Testing of Legacy Applications Testing of SAP Applications . General Troubleshooting . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
260 260 261 261 262 263 265 266 271 272 274 277 278
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
RanoreXPath 283 RanoreXPath Syntax Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 Advanced RanoreXPath Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 RanoreXPath with Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 Ranorex UI Adapter 289 Multiple Adapters for one GUI element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Android Testing Infrastructure . . . . . . . . . . . . Getting Started . . . . . . . . . . . Record your Android test . . . . . . Run your test on any Android device Manage Devices . . . . . . . . . . . Troubleshooting . . . . . . . . . . . Instrumentation with Source Code . iOS Testing Infrastructure . . . . . . . . . . Getting Started . . . . . . . . . Record your iOS Test . . . . . . Run your test on any iOS device Testing of mobile web sites . . . Web Testing Architecture of Websites in the Find or filter Web Elements . . Cross-Browser Testing . . . . Recordings & Repositories . . Samples . . . . . . . . . . . . 295 295 295 303 308 315 325 327 328 328 328 346 353 356 358 358 359 360 361 363 367 368 378 381 383 385 386 388 391 392 395
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
Ranorex Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
Source Control Add a Solution to Source Control . . . . . . . . . . . . . . Check Out a Solution from Source Control . . . . . . . . . Open an existing Ranorex TFS Solution with Visual Studio Open existing Visual Studio TFS Solution with Ranorex . . Ranorex Studio IDE Create . . . . . . Build . . . . . . . Run . . . . . . . Adding New Items Solution Explorer
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
III
Debugging . . . . Code Completion Code Conversion . Code Navigation . Code Generation . Refactoring . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
398 403 404 405 406 407
Visual Studio Integration 408 Create a new Visual Studio project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 Add Ranorex core assemblies as references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 Write some Ranorex automation code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 System Requirements 64-bit Platforms Remotely Working with Ranorex Do not Automate via Remote Desktop Window . . . . . . Do not Close or Minimize the RDP Window . . . . . . . . Disable Mouse/Keyboard Activities . . . . . . . . . . . . . Use same Color and Resolution Settings . . . . . . . . . . Increase Timeouts on Virtual Machines . . . . . . . . . . . Disable Asynchronous Dispatching of Mouse and Keyboard 411 412 413 413 413 413 414 414 414
. . . . . . . . . . . . . . . . . . . . Events
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
Silent Installation of Ranorex 416 Installation Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 Installation Command Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 Install Ranorex License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 Licensing License Registration . . . . . . . Installing a Node Locked License Installing a Floating License . . . Transfer Licenses . . . . . . . . Uninstall License . . . . . . . . . 418 418 418 420 423 425 428 428 428 428 429 429 429 429 429 430 430 430 430 430 430
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
FAQ How does Ranorex identify UI elements? . . . . . . . . . . . . . . . . . . . . . . . . . Is it possible to run the same Ranorex test code on Vista and XP? . . . . . . . . . . . Is it required to use RanoreXPath for test automation? . . . . . . . . . . . . . . . . . Does Ranorex support data driven testing? . . . . . . . . . . . . . . . . . . . . . . . . What to do when items cant be found during Ranorex test execution? . . . . . . . . . Is it possible to extend recordings with user specified code actions? . . . . . . . . . . . What is the difference between Adapter and Element? . . . . . . . . . . . . . . . . . Is it possible to trigger Ranorex tests from an existing test or build environment? . . . Can I use Ranorex libraries within Visual Studio? . . . . . . . . . . . . . . . . . . . . What shall I do with unexpected dialogs and popup windows during test automation? . Is it possible to test Silverlight applications with Ranorex? . . . . . . . . . . . . . . . Is it possible to automate a webpage without moving the mouse pointer? . . . . . . . What are the system requirements for developing and running Ranorex tests? . . . . . Are there known incompatibilities with other software? . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
IV
Ranorex Studio - The Layout

This initial lesson will introduce the main components of the Ranorex Studio environment. Before you start creating your first test case with Ranorex Studio you should know about the main views and layout of Ranorex Studio.
Figure 1: Ranorex Studio main views
#1 - Project 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: Test Suite Module Group Repository Recording Code Files Represents the projects test suite (*.rxtst) Represents the projects module groups (*.rxtmg) Used to manage UI elements (*.rxrep) Represents an automation module based on capture/replay (*.rxrec) Any type of C# or VB.NET code; typically used to create code based automation modules
The project view is mainly used to add new items like Lesson 5: Ranorex Recorder, Lesson 6: UI Mapping with Ranorex Repository, Module Groups, or Lesson 7: Code Modules.
#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.
Figure 2: Working with the projects test suite
Figure 3: Working with the projects module groups
Figure 4: Creating or adapting a recording module
Figure 5: Working with the repository
Figure 6: Writing code modules
Figure 7: Viewing a test report
Lesson 1: Getting Started

In this lesson you will gain a deeper understanding of the recorder. The first recording will capture a set of user actions (mouse clicks, keystrokes) done while working with the tool KeePass which is delivered with Ranorex Studio. KeePass is a widely available and easy to use open source password manager. The easiest way to create a first test with Ranorex is to record a manually executed test scenario. The recorded actions like mouse clicks or keyboard actions are the base for building a robust test case. In this lesson you will learn about:
Preparing to Record User Actions System Under Test: KeePass Password Safe Recording a Test Analyzing Recorded Steps Executing the Test
Preparing to Record User Actions

Before you start recording you need to ensure that your system under test (SUT) is ready to start with the manual test execution. In addition, consider the following points in order to avoid too much work 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 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.
System Under Test: KeePass Password Safe

As mentioned in the overview section, this tutorial uses the open source tool KeePass to demonstrate Ranorex functionality for automating an application in order to build up a testing framework. KeePass is a powerful and easy to use tool for managing passwords and other private information. For more information about KeePass, please have a look at the following URL: http://keepass.info/.
Figure 8: Open source tool KeePass Since version 3.3, KeePass is included with Ranorex Studio along with a sample database file.
Note: The password to open this database file is rx.
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.
Start Ranorex Studio and open the empty recording file.

Open Ranorex Studio by choosing Start>Programs>Ranorex>Ranorex Studio. Click the New Test Solution. . . button to create a blank test suite project.
Figure 9: 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.
Figure 10: Specify programming language and project name
Figure 11: 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.
Figure 12: Empty Recording
Start recording a test for the KeePass application.
Note: Its recommended to copy the KeePass application folder from the sample directory within the Ranorex installation folder (<Ranorex Installation Folder>\Samples\KeePassSample\C#\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
Figure 13: Open project folder in explorer to copy the sample application to the project folder
Click the Record button in order to start. The Recorder assists you in preparing the application under test. Simply select Run an Application and specify the directory and file name of the application under test. After copying the KeePass application folder to your project folder, you can set the File Name by choosing the file KeePass.exe using the Browse button.
Figure 14: New Recording dialog - Ranorex automatically starts the specified application Click on Start in order to record the test. The KeePass application opens and the Ranorex Recorder starts running.
Figure 15: Recording actions for the KeePass application
Enter the default Password.

Click on the text field next to the Master Password check box Type in the default password (rx)
10
Figure 16: KeePass application
Open the Add new Entry Form.

Click on Edit in the main tool bar Click on the Add Entry menu item
Figure 17: KeePass application with sub menu Edit (Menu item Add Entry is selected)
Add a new entry to the KeePass application.

Click on the Title text box and type in WordPressDemo Click on the icon button (with the key symbol)
Choose any icon (e.g. the second one) Click on Close

Click on the User name text box and type in admin Click on the Password text box Click again with the right mouse button Choose Select All
11

Type in demo123 Repeat the same for Repeat text box Click on the URL text box and type in http://bitly.com/wp demo Click the Expires button on the right (watch symbol)
Choose 1 Year menu item

Click on OK button
Figure 18: KeePass form for adding a password entry
12
Figure 19: KeePass form for choosing an icon
Figure 20: KeePass expiration sub menu
13
Validate the result.

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.
Figure 21: KeePass form with highlighting frame for validation 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.
Figure 22: Choose UI element to validate
14
Figure 23: Choose attribute to validate
Delete added item and close application.

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 24: Screenshot indicating the save button in the tool bar Stop the recording by pressing the Stop button in the recorder tool bar.
15
Analyzing Recorded Steps

The Recorder created single steps for each operation you performed on the application. These steps are represented within the actions table. In addition each action item is connected to a repository item which represents a UI element (text boxes, radio buttons, buttons, etc.) used during recording.
Figure 25: Recorded steps shown within the actions table You can read more about different action types within Ranorex Recorder in Lesson 5: Ranorex Recorder - Additional Editing Options.
Executing the Test

In order to execute the recorded test you need to switch back to the Ranorex Test Suite file. Just click on Run to execute the test suite with your first recorded test. During the execution Ranorex simulates all user actions (mouse movements and keyboard events) in order to test the application in the same way a tester would successfully do it.
Figure 26: Start the test by clicking the Run button
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.
16
Figure 27: Test run succeeded
Figure 28: Test run failed 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 29: 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.
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.
17
Figure 30: 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.
18
Lesson 2: Ranorex Modules - Test Actions

This lesson will show you the benefits of splitting your recordings into smaller pieces (to provide for reusability) and how your projects can be easily assembled afterwards using drag and drop functionality in Ranorex Studio.
Refactoring: Why you should Separate Recordings

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.
Identifying Modules
In your first recording, you did the following from a keyword driven perspective:
Started the application KeePass Logged in Added a new entry
Set the attributes for title, username, password, URL Chose an icon Set the expiration value
Validated the existence of the newly created entry in the grid Deleted the entry Saved the changes Closed the application
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.
Figure 31: Move login actions to a new recording
19
Figure 32: Create a new recording named LogIn 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 Recording1.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 33: Use the drag and drop feature to specify your test case within the test suite view Separating a recording into smaller modules is the first step in building robust and reusable automation modules. In addition replace constant values used within these modules with variables in order to enable parameterization. Read more about how to use variables in Lesson 3: Data-Driven Testing.
20
Lesson 3: Data-Driven Testing

In this lesson you see how tests can be done using internal (simple data tables) or external data sets (Excel files, CSV files, SQL Databases) to do a data-driven automated test. You can use variables in recordings and even in the repositories which are connected to internal or external data sources. Additionally, you will see how a select action can be invoked for UI elements which are not visible by default in order to ensure your data-driven test case does not fail. When you test an application it might be necessary to run the same test with different input data. Next youll learn about:
Using Variables within Recordings Using Variables within the Repository Creating Test Data Combining Variables with Test Data Combining Variables with Parameters Invoking Actions: Selection Executing Data Driven Tests
Using Variables within Recordings

According to the KeePass application we can identify six variable input actions:
Title (WordPressDemo) Username (admin) Password (demo123) URL (http://bitly.com/wp demo) Expires (1 Year) IconIndex (1)
All these input actions are done within the AddNewEntry recording. You need to open the recording file and identify the actions which have to be variable. To make the input of the title variable, open the combo box as shown below and select As new Variable to create a new variable.
Figure 34: Create a new variable for a key sequence action item
21
Figure 35: Create a new variable 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.
Using Variables within the Repository

Within the recording AddNewEntry the variables varTitle, varUsername, varPassword and varURL are used for key sequence 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 AddNewEntry 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.
Figure 36: Make Item Variable menu item from context menu in Recorder
22
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 37: 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.
Figure 38: Variable repository item Also rename the repository item MenuItem1Year to MI Expires to clarify that this repository element is not pointing to a specific menu item anymore but instead uses a variable to choose one of the menu items in a data-driven way. Repeat the same procedure to add a new variable varIconIndex into the repository item which is connected to the icon list view. The recording AddNewEntry now uses six variables. Four of them are used for key sequences directly within the recording while the others are used within the repository. To get an overview of all variables used within the recording simply click the Variables button as shown below.
23
Figure 39: Open the recordings variable dialog
Figure 40: Variables currently used by the recording and repository
Creating Test Data

The sample recording now uses six variables. In this section you will learn how to connect a simple Excel table to provide the values for these variables. To create a new Ranorex data source you need to open the test suite view. Select the test case which uses the AddNewEntry recording and open the Data Source dialog by clicking the Manage Data Sources button in the tool bar.
24
Figure 41: Open the Manage data sources . . . dialog 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.
Figure 42: Use an Excel file for data-driven testing Now create a new data connector by clicking on Use Excel file. . . .
25
Figure 43: Create a new Excel connector
26
Figure 44: Specify the filename from the Excel file
27
For further information about different Ranorex data connector types have a look at Data Connectors.
Combining Variables with Test Data

In order to combine your Excel file with the current test case - and finally with the AddNewEntry recording which is used by the test case - you need to open the data binding dialog using the context menu as shown below.
Figure 45: Open data binding dialog
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 AddNewEntry module.
Figure 46: Connect data columns with module variables
Combining Variables with Parameters

Parameters can be useful when automated tests are executed under different environment-related conditions. An automated test on Windows 7, for example, may need different path values in comparison to a test execution on Windows XP. Parameters can be created in Ranorex Studio in order to be connected with variables. 28
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 47: 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.
Figure 48: Open global parameters dialog
29
Figure 49: 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.
30
Figure 50: Bind global parameter to the variable used within recording StartSystemUnderTest Before you execute the data driven test case, you have to make sure that the values specified within the Excel file can be used correctly within the AddNewEntry recording. The values for the title, username, password, URL and expiration will not cause any problems during automation. 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.
Invoking Actions: Selection

KeePass offers a list of icons which can be accessed via the button next to the label Icon:
31
Figure 51: Button to open the Icon Picker
Figure 52: Form for choosing an icon for a password entry
32
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.
Figure 53: Adding a new Invoke Action to the recording After adding the new item you need to specify for which repository element the invoke action should be used. Simply open the Select Repository Item dialog as shown below and select IconItem.
Figure 54: 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.
33
Figure 55: Choose Select method 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.
Executing Data Driven Tests

Note: Before executing the test suite, its necessary to modify the recording ValidateEntry in order to be independent from the constant values used during recording. Therefore the constant value WordPressDemo should be replaced by variables (match-value in validation action and text-attribute-value in RanoreXPath for the assigned repository item) as you learned in the previous sections. Dont forget to bind the variables to the excel-column.
Now switch back to the test suite view and start your data driven test by clicking the Run button.
34
Figure 56: Report file showing two iterations of the test case 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.
35
Lesson 4: Ranorex Test Suite

As was already mentioned in Lesson 2: Ranorex Modules - Test Actions, it is recommended to separate a test case into reusable and parameterizable test automation modules. Within the Ranorex test suite you can not only easily create new test cases by combining already existing automation modules - you can also specify global parameters and data connectors to set up data-driven test cases. Within the following lesson you will learn about:
Test Suite Editor Module Group Editor General Structure of a Test Suite and its Test Cases Running a Test Suite Running Tests without Ranorex Studio Test Suite Settings Test Case Settings Using Data in Test Suites
Test Suite Editor

After the creation of a new test suite project, a Ranorex Studio project automatically contains a <ProjectName>.rxtst file. By default the test suite file is opened automatically.
36
Figure 57: Ranorex Test Suite file 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.
Figure 58: Ranorex Studio tool bar
Add a New Test Case

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 Folders
Select the Test Case item to create a new test case at the current position.
37
Figure 59: Add a new test case
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.
Figure 60: Rename the test case
Reuse of Existing Modules

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.
38
Figure 61: Add an existing recording module
Figure 62: Select StartSUT module from the list
39
Press OK to add the record module to the test case. Repeat the steps to add the record items LogIn and CloseSUT to the test case.
Insert a New Recording Module

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.
Figure 63: Insert a new recording module Before starting the new recording, you should confirm that KeePass is running - you could start the application manually if it is not running. The new recording module ValidateVersionNumber should cover the following steps:
open the about dialog validate the version number close the about dialog
Keep in mind that you need to select the Global Recording option because the system under test will be started by the reused recording module StartSUT.
40
Figure 64: Newly created recording scenario 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 65: Click the Edit in Spy button open the path editor
41
Figure 66: 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. Now the test case ValidateVersionNumber is ready to be executed. Use the context menu item Run Selected Test Case to run it and see whether it works or not.
Figure 67: Run selected test case
Module Group Editor

It can be useful to combine modules which belong together into groups to reuse them more easily. For example combining the modules StartSUT and LogIn into a module group StartAndLogin within the KeePass sample project could be useful, because these two modules are needed to start the system under test. The same applies to the modules Save and CloseSUT which can be combined with the module group SaveAndClose. This can be done using the module group editor. In addition to the test suite file, the test suite project also contains a file defining the module groups existing in the project. This module group file is generated automatically as <Project-Name>.rxtmg. Double-clicking this file in the project view will open it in the module group editor. 42
Figure 68: Open module group editor After creating a new solution an empty module groups file is created.
43
Figure 69: Module group editor You can add module groups to your project in the following ways:
Press the New Module Group button in the module group editor Use the context menu in the test suite editor to add a module group to a test case Use the context menu in the test suite editor to group selected modules into a module group
Figure 70: Adding a module group to a test case using the context menu in the test suite editor
44
Figure 71: 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. 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 72: 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.
45
Figure 73: Drag and drop module into a module group 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 74: 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.
46
Figure 75: Define which module variables should get their values passed from outside the module group and which module variables should have constant value After defining a module group and its data binding, it can be added to a test case the same way a module is added. The data binding for module groups works exactly the same way as it works for modules. Further details about working with modules and data binding can be found in Lesson 2: Ranorex Modules - Test Actions and Lesson 3: Data-Driven Testing.
Figure 76: Adding a module group to a test case
General Structure of a Test Suite and its Test Cases

In the last section you learned how to add new test cases to a test suite by combining existing modules with a newly created recording. To see the different ways of organizing a more complex test suite project, open the sample test suite project KeePassTestSuite from the Ranorex Studio start page.
47
Figure 77: Opening the sample test suite project KeePassTestSuite This sample includes different types of elements which can be used within a test suite and covers all possible combinations.
48
Figure 78: Ranorex test suite structure
#1 Folder #2 Test case #3 Setup region #4 Module group #5 Teardown region #6 Code module #7 Recording module
Used to group multiple test cases Represents a test case which can contain modules, a setup or teardown region or other test cases Groups modules used to prepare a test case (e.g. start system under test, initialize a database, etc.) Used to group several modules into a reusable set Groups modules used to clean up a test case (e.g. deleting files generated during test execution, closing application, etc.) Automation module written in code Automation module generated by recording
49
Setup and Teardown Regions

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.
Figure 79: Add module to a setup region
Note: If you want to define one setup and one teardown region for a set of test cases, simply nest your test cases as shown in the following picture
50
Figure 80: Nested test case for a general setup and teardown region
Note: In order to define global setup and teardown regions click on Show 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 81: Show setup and teardown region for test suite node
51
Figure 82: Drag and drop modules to global setup region In order to quickly deactivate a certain module, instead of deleting it from the test case, use the context menu item Disable.
Searching For Elements

Use the Search text box to find elements in the Test Suite.
Figure 83: Search result for text Add
Running a Test Suite

To run a test suite click the RUN button shown in the test suite editors toolbar. Use the check boxes to specify whether single test cases or a group of test cases should be part of a test suite run. Create different test suite run configurations using the drop-down box from the toolbar. These test suite run configurations define if a specific test case will be executed or not.
52
For example one test suite run configuration can be defined where the data driven tests stored in your test suite will be executed and one test suite run configuration can be defined where they wont.
Figure 84: Activate different test suite run configurations
Figure 85: Add or remove test suite run configurations
Running Tests without Ranorex Studio

As you already learned in Lesson 1: Getting Started, Ranorex Studio creates an executable file from your test suite project. In order to execute the test suite in a runtime environment, you have to have the generated executable (*.EXE) and the test suite file (*.RXTST) in the same directory. 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, to deploy a Ranorex test to a runtime machine its required to copy the complete output folder (e.g. bin/debug) to the target machine. You can execute the test suite outside Ranorex Studio using one of the following:
Ranorex Test Suite Runner Running Tests via Command Line
Ranorex Test Suite Runner

Simply double-click the *.RXTST file from the projects output folder to open the Ranorex Test Suite Runner.
53
Figure 86: External 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.
Running Tests via Command Line

Using the following, you can execute the test suite from the command line: <GeneratedTestSuite>.exe /<argument> Allowed arguments: help|? Prints this help text. listconfigparams|lcp Lists all settable configuration parameters and their values. config|cfg:<config parameter name>=<value> Set values for configuration parameters. 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).
54
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
listglobalparams|lp Lists all global parameters and their values. listtestcaseparams|ltcpa:<name or guid of test case> Lists all testcase parameters and their values. testcase|tc:<name or guid of test case> Runs this test case only. 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 or the first rxtst file in the same folder as <TestSuiteExe>.
runconfig|rc:<configuration name> Runs the test cases of the specified configuration defined by the rxtst file. 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.
55
param|pa:<global parameter name>=<value> Creates or overrides values for global parameters specified in the test suite. testcaseparam|tcpa:<name or guid of test case>:<parameter name>=<value> Creates or overrides values for testcase parameters specified in the test suite. runlabel|rul:<custom value> Sets a custom runlabel for the test run. testcasedatarange|tcdr:<name or guid of test case>=<data range> Sets the data range for a testcase.
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.
Some Examples for using Command Line Arguments

Using the KeePass sample test suite - included in Ranorex installation - as reference, the following samples will fulfill the following use cases: Start the test suite with setting a global parameter: KeePassTestSuite.exe /pa:GlobalExecutionPath=.\KeePass\KeePass.exe Start only a specific test case of the test suite: KeePassTestSuite.exe /tc:TC OpenLoginAndClose Start the test suite with generating a zipped report called report.rxzlog: KeePassTestSuite.exe /zr /zrf:report.rxzlog Start a specific run configuration of the test suite: KeePassTestSuite.exe /rc:SmokeTest
Test Suite Settings

Open the test suites settings dialog by selecting the context menu item Properties on the test suite root node.
56
Figure 87: General settings of a test suite
Figure 88: Global parameters table
General Test Suite Settings
57
Name Description Show Progress Dialog Capture Tracing Screenshots Report Level Warn for unbound variables
Specifies the name of the test suite (same as shown within the test suite editor) Description of the test suite (same as shown within the description column of the test suite editor) Specifies whether a progress dialog should be shown during test suite execution Specifies whether tracing screenshots should be captured or not in the case of an error Specifies the minimum report level of messages shown with the report file Specifies whether a warning should be shown for unbound variables
Additional Report Settings Report Enabled Report File Directory Report File Compressed Copy Report Template Folder Auto Save Interval Place screenshots in folder Specifies whether a test report should be generated Specifies the directory for the generated report files Specifies the filename generated by the report; move the mouse over the Description label to see available placeholder values Specifies whether the report should be generated as compressed 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 by pressing the button Create Custom Template as explained in Create a Custom Report Template Specifies how often the report file is saved during execution Specifies whether the created screenshots will be stored in a specific folder for each report or directly in the report folder
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.
Test Case Settings

The General tab of the test cases properties dialog is mainly used to setup how a broken test case impacts other test cases within the test suite. Name Description Report Level Error Behavior Name of the test case Specifies the filename generated by the report; move the mouse over the Description label to see the variable values Specifies the level of messages written to the report file 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.
The following figures try to illustrate several Error Behavior settings: 58

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
Figure 89: Continue with Iteration
Figure 90: Continue with Sibling
Figure 91: Continue with Parent
59
Figure 92: Stop
Figure 93: Test case properties dialog Use the context menu to change the report level or the error behavior for multiple test cases.
60
Figure 94: Specifying error behavior for multiple test cases
Using Data in Test Suites

As already explained in Lesson 3: Data-Driven Testing you can make your automation data-driven by using variables in your modules (recordings, code modules) as well as in your repositories. These variables can be connected to internal or external data sources and parameters.
Different kinds of Data Container

Lets have a look at the different kinds of data container: 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
recoding modules (as described in section Using Variables within Recordings), code modules (as described in section Using Variables with Code Modules) and repositories (as described in section Using Variables within the Repository).
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. 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. 61
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.
Scope of Data Container

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.
Figure 95: Scope of data containers The green rectangle illustrates the scope of global parameters, the blue rectangle the scope of local parameters and 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.
62
Figure 96: Data binding dialog of Test-Case-1 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.
Modify Parameter and Data Column Values

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.
63
Lesson 5: Ranorex Recorder

The Ranorex Recorder is used to record and replay the users keyboard and mouse actions during a manually executed test of the user interface. In addition the Recorder can validate current states, properties like Text or Visibility and compare images of UI elements. The Recorder is a capture replay editor which is available both as stand-alone tool and as an integrated editor within Ranorex Studio.
Figure 97: Ranorex Recorder integrated in Ranorex Studio
Figure 98: Ranorex Recorder as standalone tool 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.
64
Figure 99: 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.
Figure 100: Add a new recording to an existing test case
65
Figure 101: Add a new recording to the selected test case During the next chapters you learn about the following:
Before Starting to Record During Recording After Recording Replay and Debug Actions Recorder Variables User Code Actions Additional Editing Options Image-Based Automation
66
Before Starting to Record

Regardless whether you use Ranorex Recorder within Ranorex Studio or as a stand-alone tool, both the Recorder and the system under test have to be prepared.
Prepare to Record
Before you start recording, you need to ensure that your system under test is ready to start with the manual test execution. In addition, consider the following points in order to avoid too much effort in cleaning up the recording and the repository afterwards.
Do not run multiple instances of your application under test if that is not part of the test case itself By default, mouse movements are not recorded; for this reason please also perform mouse clicks in situations such as navigating through menus (or use Recorder Hotkeys to record mouse movements) Think about which steps should be part of the final test Try to keep recordings small in order to make them modular
Recorder Settings Dialog

Before running a new recording session, you can configure Ranorex Recorder using the settings dialog. Click the Settings button to open the settings dialog.
Figure 102: Settings for current recording file
67
Figure 103: Default values used for every recording
Current Recording
This tab primarily contains configuration parameters for code generation specific to the current recording. All settings on this tab page are stored within each recording. Recording namespace: Specifies the namespace used for the generated code. Recording class name: Specifies the class name used for the generated code. Replay speed factor (%): The speed factor is used to increase or decrease the replay overall speed by a specific factor value. Replay repeat count: The repeat count is used to specify the number of iterations. 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). Enable turbo mode for replay and generated code: Is used to specify whether recorded delays between actions should be part of the generated code. Generate replay reports: This setting is used to turn the generation of reports during replay on and off. Use item logging by default:
68
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 clicked elements: Specifies whether objects clicked during a recording should be highlighted. 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
Timings for new actions 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. 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.
69
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.
70
During Recording
Click the Record button to trigger a new recording.
Figure 104: Click Record to start 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 global recording its on you to start the application under test.
Figure 105: New recording dialog After clicking the Start button, the Recorder or Ranorex Studio will be minimized. A running recording session is indicated in the Ranorex Recorder tool bar.
71
Figure 106: Ranorex Recorder toolbar 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.
Validation
The Ranorex Recorder provides two different types of validation during a running recording session:
Validation based on attribute values of a UI element Image-based validation
Validating States or Attributes 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.
Figure 107: Validation mode is active 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.
72
Figure 108: The highlight frame specifies the element to validate 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.
Figure 109: Select the UI element you want to validate
73
Figure 110: Select the attributes of the UI element to validate 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.
Figure 111: Validation of menu items using shortcuts
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.
74
Figure 112: Validate whether a specific listitem contains a specified image or not
Recorder Hotkeys
Ranorex Recorder provides useful hot keys for triggering special features like validation or the recording of simple mouse movements. When you start a new recording session, the hot key functionality is turned off. To activate the 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.
75
Figure 113: Available hot keys during a recording session V: Press the hot key V to turn on Validation - 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. I 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 Mouse Wheel Roll the mouse wheel during validation mode to change the level of UI element selection.
76
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.
Figure 114: Recorded actions listed in the recorders 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.
Figure 115: Recorded key sequence action
Figure 116: Recorded mouse click action 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.
77
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 117: 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.
Figure 118: Merging selected keyboard items 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.
78
Figure 119: 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.
Figure 120: Automatically generated repository
Figure 121: New structured and renamed repository 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.
79
Replay and Debug Actions

In order to replay all actions as fast as possible, activate Turbo Mode by clicking the button on the tool bar. Simply click the Play button in the recording to replay all actions.
Figure 122: Replay recorded actions
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 123 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 during replaying.
80
Figure 124: Test run progress 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.
Figure 125: Report after replay 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
81
Figure 126: Play a selected item
82
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.
Figure 127: Variables used for key sequence actions 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.
Figure 128: Make a key sequence action variable
Figure 129: Create a new variable 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. 83
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 130: Creating a new variable for use within the path of the repository item
84
Figure 131: Create a new variable for selecting a menu item Another option is to open the variables dialog where you can add new or change existing variables already used by the recording. Moreover, you can see which variables are In use, Not in use or In use from Repository.
Figure 132: Open the variables dialog in the Recorder
85
Figure 133: Variable dialog of a recording with different levels of usage 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.
86
User Code Actions

A user code action is used in situations where standard out-of-the-box features provided by the recorder are not enough. Here are some examples where user code actions could be convenient.
User-specific Validation Accessing test case related data and parameters Extended reporting
Looking at a recording file in the projects view you will see that each recording has two associated code files.
Figure 134: Recording AddNewEntry has two code file items
Note: User code actions are not available within the standalone Recorder.
Within Ranorex Studio, each recording manages two types of source code files:
Automatically generated main recording source code file <RecordingName>.<CodeFileExtension> User specific source code file <RecordingName>.UserCode.<CodeFileExtension>
You can jump to the generated code of a recorded action by right-clicking the action and choosing View Code from the context menu.
87
Figure 135: Jump to generated code of a recorded action Every time you change and save a recording, the main code file AddNewEntry.cs is newly generated. Any change of code should always be made within the recordings UserCode.cs file.
Create User Code Actions

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.
Figure 136: Convert an existing action item to a code action
88
Figure 137: Specify method name used for user code item
Figure 138: 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 MyFirstTestProject { public partial class AddEntry { // / < summary > // / This method gets called right after the recording has been started . // / It can be used to execute recording specific initialization code . // / </ summary > private void Init () { // Your recording specific initialization code goes here . } public void ClickOnPasswordField () { Report . Log ( ReportLevel . Info , " Mouse " , " Mouse Left Click item FormAdd_Entry . TabPageList . InputFields . TextPassword at 175;9. " , repo . FormAdd_Entry . TabPageList . InputFields . TextPasswordInfo ) ; repo . FormAdd_Entry . TabPageList . InputFields . TextPassword . Click ( " 175;9 " ) ; } } }
89
VB.NET
Namespace MyFirstTestProject Public Partial Class AddNewEntry < summary > This method gets called right after the recording has been started . It can be used to execute recording specific initialization code . </ summary > Private Sub Init () Your recording specific initialization code goes here . End Sub Public Sub ClickOnPasswordField () Report . Log ( ReportLevel . Info , " Mouse " , " Mouse Left Click item FormAdd_Entry . TabPageList . InputFields . TextPassword at 175;9. " , repo . FormAdd_Entry . TabPageList . InputFields . TextPasswordInfo ) repo . FormAdd_Entry . TabPageList . InputFields . TextPassword . Click ( " 175;9 " ) End Sub End Class End Namespace
User Code Actions and Parameters

Since Version 3.3 it is possible to use parameters for user code actions. You can pass (string) values to your user code methods to gain more flexibility in your testing environment. To use parameters for a new user code action, simply click the cell next to the methods cell and type in a value to be used as a parameter (e.g. WordPressDemo).
Figure 139: User Code Action with a parameter To enhance flexibility, you can use variables instead of hardcoded values. This can be done in the usual way.
Figure 140: Create a new variable to be used as a parameter Of course you are also able to use more than one parameter for each action. If there are no more columns available (maximum of three in the GUI), you can use the browse button to access the Ranorex Argument Editor.
Figure 141: Browse button to access the Ranorex Argument Editor Youll find an overview of existing parameters in the Ranorex Argument Editor. Here you can also name existing parameters and add additional parameters.
90
Figure 142: Ranorex Argument Editor for handling user code parameters After declaring the parameters with values or variables, you can switch to the user code method and use the passed parameters.. C#
public void AddEntryWithParams ( string aTitle , string aUsername , string aPassword , string aURL ) { MyFirstTestProjectRepository MyRepo = MyFirstTestProjectRepository . Instance ; // Set text fields MyRepo . AddEntry . TabSheetAddEntry . Title . TextValue = aTitle ; MyRepo . AddEntry . TabSheetAddEntry . UserName . TextValue = aUsername ; MyRepo . AddEntry . TabSheetAddEntry . Password . TextValue = aPassword ; MyRepo . AddEntry . TabSheetAddEntry . Repeat . TextValue = aPassword ; MyRepo . AddEntry . TabSheetAddEntry . URL . TextValue = aURL ; }
VB.NET
Public Sub AddEntryWithParams ( aTitle As String , aUsername As String , aPassword As String , aURL As String ) MyFirstTestProjectRepository MyRepo = MyFirstTestProjectRepository . Instance Set text fields MyRepo . AddEntry . TabSheetAddEntry . Title . TextValue = aTitle MyRepo . AddEntry . TabSheetAddEntry . UserName . TextValue = aUsername MyRepo . AddEntry . TabSheetAddEntry . Password . TextValue = aPassword MyRepo . AddEntry . TabSheetAddEntry . Repeat . TextValue = aPassword MyRepo . AddEntry . TabSheetAddEntry . URL . TextValue = aURL End Sub
Additionally to creating method calls in Ranorex Recorder you are able to define your methods in code and just select the intended method in the Recorder Table. Here you are also able to choose overloaded methods.
Figure 143: Choose one of the overloaded method calls
91
Figure 144: Ranorex Argument Editor with arguments and variable binding from overloaded method
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 145: 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#
92
public void DeleteItemIfFocused () { if ( repo . MainForm . Entry . HasFocus ) { Report . Log ( ReportLevel . Info , " Mouse " , " Mouse Right Click item MainForm . Entry at 127;1 . " , repo . MainForm . EntryInfo ) ; repo . MainForm . Entry . Click ( System . Windows . Forms . MouseButtons . Right , " 127;1 " ) ; Report . Log ( ReportLevel . Info , " Mouse " , " Mouse Left Click item KeePass . DeleteEntry at 168;14. " , repo . KeePass . DeleteEntryInfo ) ; repo . KeePass . DeleteEntry . Click ( " 168;14 " ) ; } }
VB.NET
Public Sub DeleteItemIfFocused () If repo . MainForm . Entry . HasFocus Then Report . Log ( ReportLevel . Info , " Mouse " , " Mouse Right Click item MainForm . Entry at 127;1 . " , repo . MainForm . EntryInfo ) repo . MainForm . Entry . Click ( System . Windows . Forms . MouseButtons . Right , " 127;1 " ) Report . Log ( ReportLevel . Info , " Mouse " , " Mouse Left Click item KeePass . DeleteEntry at 168;14. " , repo . KeePass . DeleteEntryInfo ) repo . KeePass . DeleteEntry . Click ( " 168;14 " ) End If End Sub
93
Additional Editing Options

As you have learned in the previous lesson, the Recorder is usually used to record user actions. After making a recording, it might be necessary to edit the recorded data, for example to merge split key sequences or to delete single actions recorded by mistake. You can also add new actions like a new validation step which was not considered during the recording. In the following section youll learn about:
Adding New Actions Recorder Variables Splitting Recordings
Adding New Actions

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 shown below:
To add a new action item, open the Add New Action drop-down menu as
Figure 146: Add a new action item to the actions table By selecting one of the items a new action is added after the current selection within the actions table.
94
Figure 147: New mouse move action added 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.
Figure 148: Select a repository item to be used by the action Alternatively it is possible to assign the repository item to the action by dragging and dropping a repository item directly onto the newly created action in the column Repository Item.
95
Figure 149: 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.
Figure 150: Available sub-actions for mouse action
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.
96
Figure 151: 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. Types of Action Items Mouse Mouse Wheel Touch Event Key Shortcut Key Sequence Mobile Key Press Validation Invoke Action Get Value Set Value Open Browser Run Application Run Mobile App Deploy Android/iOS App Close Application Wait For Not Exists Adds a new mouse action item at the current position Adds a new mouse wheel action item Adds a new touch event action item at the current position Adds a new key shortcut action item (e.g. CTRL+C or CTRL+V) Adds a new key sequence action item (e.g. Hello) Adds a new mobile key press action (e.g. {BACK}, {MENU}) Adds a new validation action item Adds a new invoke action item (e.g. call method Select for a UI element of type list item) Adds a new get value action item (e.g. get Text for a UI element of type button) Adds a new set value action to set an attribute value (e.g. Text for a UI element of type text) Opens a browser and navigates to the given URL Runs an application at the given directory and file path Runs an application on a mobile device Instruments the given Android application and deploys it on the given mobile device or deploys the already instrumented iOS application on the given mobile device Closes an application or web site containing the given repository item Waits for given repository item to disappearance Note: This action can be used for any type of UI element
97
Report Separator Delay User Code
Adds a new report action item Note: In addition to the standard report levels, you can define custom report levels by changing the level from Info to Custom Inserts a separation line on the currently selected position in the actions table Adds a new delay action item Adds a new user code action item which is used, for example to implement a user specific validation in code
Note: Keep in mind that most types of 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.
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. 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 your Android test.
98
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. AttributeContains: This validation checks whether a specific attribute (column Match Name) of a specific repository item contains a match value. The match value can either be a user-defined constant value or it can also be the content of a module variable. As above this validation assumes the assignment of a repository item. Example: A user can validate whether the title of the KeePass application contains the constant value kdbx, which is the file extension of the database used by KeePass. The match name would thus be set to Title and the match value would be set to kdbx. As a result the validation would succeed if the title actually contains the constant kdbx. AttributeNotContains: This validation can be thought of as the opposite of AttributeContains. It checks whether an attribute (column Match Value) does not contain a match value. Example: One can validate whether the content of a specific cell (URL) in KeePass does not contain the constant value http://. Match Name would therefore be set to Text and Match Value would be set to http://. This validation would lead to a positive result if the URL does not contain the constant value http://. ContainsImage: This validation checks whether the assigned repository item contains a specified screenshot. This screenshot can be easily created within the Edit Image Validation dialog which can be accessed via a button in the Screenshot column. For more information about image-based validation please have a look at the section entitled Image-Based Automation later in this chapter. Example: 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 more information about image-based validation please see Image-Based Automation later in
99
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. 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).
100
Figure 152: Submenu for Get-Value action 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>.
101
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.
Figure 153: Text value of a button stored in a variable 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 154: 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.
102
Figure 155: Submenu for Set Value Action 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 some arguments (column Arguments) and define whether the application should be started in maximized window state (column Maximized, see explanation for open browser action to find out more about this parameter). Run Mobile App When using this action you can specify a Device and an App. For more information see Android Testing - Record your Android test. Deploy Android App When using this action, you can specify a Device and an APK file. The given Android application will be instrumented and deployed to the given Android device. 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. 103
Wait For Not Exists You can use the Wait for not exists action to wait until the assigned repository item does not exist anymore. 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. Example: One could report the current value of a variable or UI element. Screenshot: This action adds a screenshot of a specific repository item and some user-defined text to the test report. If no repository item is assigned, a screenshot of the whole desktop is created and will be passed to the report. Example: One could report a screenshot to make the report file clarify the current state of the system under test in the report file. Snapshot: This action adds a snapshot file of a specific repository item and some user-defined text to the test report. The snapshot file can be opened directly from the report file. 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
Invoking User-Defined 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.
104
Figure 156: Example (in initial state) with public functionality which will be invoked C#
public void MyInvokedAction ( string MyMessage ) { edProtectedText . Text = MyMessage ; } private void btSetValue_Click ( object sender , EventArgs e ) { edProtectedText . Text = " This text was set from GUI " ; }
The protected text can only be set by clicking the button. The application then sets the text field to a constant value.
Figure 157: 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.
105
Figure 158: Submenus for available invoke actions Even parameters can be easily set in the Ranorex Recorder table.
Figure 159: Setting a parameter for an invoked action You can also access an attribute editor using the Browse (. . . ) button in the last argument column to get an overview of available parameters.
106
Figure 160: Browsing available arguments Invoking this method causes the text fields content to be set to the desired value.
Figure 161: Example after invoking a method from Ranorex
Continue On Fail and Disable

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 162: 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.
107
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.
Figure 163: Creates a new Recording from the selected items 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.
Changing the Repository of a Recording Module

By default each newly created recording refers to the main repository file. To create a new repository or to refer to another repository simply open the drop-down menu from the repositories toolbar as shown below.
Figure 164: Change referring repository 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.
108
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. 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.
Figure 165: Image based recording activated Now move the mouse pointer over a certain GUI element. Ranorex highlights the last accessible UI element and also highlights a recognized image region within the GUI 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.
109
Figure 166: 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 correspondending repository item.
Figure 167: The Ranorex Studio Image Editor 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 the button in the location cell (see graphic above). In this dialog use the Select image find region toolbar button to
110
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 168: 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. Image-based Location Settings Use the property group to set advanced image search options like Clipping or Best Match If 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. Defines preprocessing steps that can be performed on an image before search.
None: No preprocessing Grayscale: Convert the image to a grayscale image. Edges: Detect object edges in the image using the Laplace edge detection algorithm (includes Grayscale).
Advanced Options
Preprocessing
EdgesSobel: Detect object edges in the image using the Sobel edge detection algorithm (includes Edges). Downsize: Downsize the image. Threshold: Convert the image to a black/white image using a threshold (includes Grayscale).
Screenshot Name Selection Rectangle Similarity
Specifies the name of the screenshot used in the search. Defines the image selection region (= what to search for). 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.
111
To set up the default values for image-based recording, open up the Settings dialog and continue with activating the Imaging tab.
Figure 169: Settings dialog for image-based recording
Image Editor
Use the context menu item Edit Location. . . to open the image editor and to change the click location options. The editor provides a more detailed view of the captured image information. In addition, it offers some useful features for changing the image rectangle to be searched for.
Figure 170: Click location dialog to change the settings of image-based mouse actions
112
Image Editor Functionality Image Based Select Image Find Region Select Click Location Autoselect Image Find Region Zoom Out Zoom 100% Zoom In Capture New Screenshot Specifies whether the click is based on image information or not Specifies the region to search within the image Defines the click position in relation to the searched region Helps to specify the search region within the image Zooms out Switches to 1:1 view Zooms in Captures a new screenshot from the related repository item
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.
Figure 171: Set relative or absolute mouse action location 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 or automation actions.
Figure 172: Add a new image or select an existing image to specify the location/graphic to search
113
Lesson 6: UI Mapping with Ranorex Repository

The Ranorex Element Repository is used to separate identification information (RanoreXPath) from Ranorex test automation modules. For test maintenance, it is recommended that you also use Ranorex repositories within code modules to reduce the effort in adaptation necessary when the UI under test changes. In the following lesson youll learn about:
Adapting an Existing Repository Adding Repository Items Waiting for UI Elements - Repository Timeouts Editing RanoreXPath Repository Separation Repository Settings Dialog Repository Item Properties
114
Adapting an Existing Repository

During lessons one through three you created a repository by recording a manual test scenario. For each UI element used during recording, a new item was created within the repository. By default a new Ranorex Studio project contains one repository file (*.rxrep) which can be used by multiple recording or code modules.
Figure 173: File view of a repository
Figure 174: Integrated repository view within the Recorder You can access and edit the repository (directly) in the recorder view by double clicking the file (MyFirstTestProjectRepository.rxrep) in the projects view as shown in the figures above. Renaming Repository Items 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.
115
Figure 175: Renaming of repository items Creating Logical Folders 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.
Figure 176: Adding a Simple Folder to the repository
Figure 177: Repository using two logical folders to group input fields and buttons
Repository Structure - Types of Elements A repository can have the following types of items:
116
Figure 178: Ranorex repository structure
Application Folder #1 Rooted Folder #2 Simple Folder #3 Adapter Item #4
Represents a top level application, a dialog or a context menu Contains GUI elements having the same parent (i.e. RanoreXPath prefix) Used to group items Represents a Ranorex adapter (Button, ListItem, TextBox, ComboBox, etc.)
Use the Add New Item button in the toolbar to add new items manually.
Searching For Elements

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.
Figure 179: Specify whether to search in Names, Paths or to Search All elements
117
Figure 180: 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.
Figure 181: The Cleanup button In the Cleanup dialog unused repository items are listed and checked automatically. Uncheck items if you do not want to delete them.
118
Figure 182: 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
119
Find Repository References

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 183: Search for references of repository item KeePass
Figure 184: 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.
Figure 185: Search for references of a repository item in all test modules
120
Figure 186: Search result - simply click a result to open the test module
121
Adding Repository Items

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 187: 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 188: Track and identify the Find button with Ranorex Spy As a third step, add the button to the repository as shown in following figure.
122
Figure 189: Add the item to the currently open repository
Note: Alternatively you can drag and drop the item from Ranorex Spy directly into the repository from Ranorex Studio.
123
Figure 190: Newly created item in the repository
Note: It is also possible to track UI elements directly from the repository using the Track button.
Figure 191: Tracking directly from the 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 192: 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).
124
Figure 193: 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.
Open the Ranorex Spy tool (if not already opened) Track the Find What text field in KeePass using the Track button in Ranorex Spy Add the tracked text field to the repository (either with the context menu or with drag and drop) Rename this repository item to something meaningful (e.g. FindText) Add a new action (Mouse) to the recording in Ranorex Studio Connect this action to the repository item FindText Add a new action (Key Sequence) to the recording Change the value in the column Sequence to a text phrase that you want to search for (e.g. WordPressDemo) Connect this action to the repository item FindText Open the Ranorex Spy tool (if not already opened) Track the Find button from KeePass Search form using the Track button in Ranorex Spy Add the tracked button to the repository (choosing one of the already mentioned methods) Add a new action (Mouse) to the recording in Ranorex Studio Connect this action to the repository item Button Find
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.
125
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 194: 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.
A More Advanced Test Case Example

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 195: 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.
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.
Repository Items Representing Multiple Elements

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. 126
Use the Ranorex Spy to prepare a RanoreXPath with multiple result elements and add it to the repository as described in the previous section.
Figure 196: RanoreXPath delivering multiple results (All buttons from the toolbar in KeePass) 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.
127
Waiting for UI Elements - Repository Timeouts

As was already mentioned, KeePass is not only able to work with local databases but also with databases stored on a FTP server.
Figure 197: KeePass application opening a new database from a URL 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.
128
Figure 198: Open properties of LoginWindow application folder 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.
129
Figure 199: 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.
Waiting for a Particular UI Element State - Event Handling

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. ClipBoardTestCase) containing the recording modules StartSUT, Login as well as Save and CloseSUT. Between those two blocks insert a new recording module ValidateClipBoard.
Figure 200: 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 Global Recording and complete the following steps) 130

Click the Validate button in the Ranorex Recorder tool window Validate the status text Ready after the highlight frame appears Confirm the Validation dialog Click on any item in KeePass Open the context menu and choose Copy Password Click the Stop button in the Ranorex Recorder tool window
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.
131
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.
Figure 201: RanoreXPath separation Press <ENTER> to change the RanoreXPath expression of an item using the edit mode or open the Path Editor by clicking the Edit button.
Figure 202: Edit button opens Ranorex Spy
132
Figure 203: Path Editor to to change attributes used for identification 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 204: Highlight the modified element to check the modified path
133
Figure 205: Save button as highlighted element
134
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:
Testing Different User Interfaces Common Repositories for Common Modules Advanced RanoreXPath Repositories for Complex Identification Multiple Testers Working on the Same Test Automation Project
Testing Different User Interfaces If your test suite contains, for example test cases for a web application and tests for a user interface of a client application, it might be useful to have two repositories. One is used to manage the UI elements of the web application while the other exclusively stores the elements from the client hosted application. Although you can separate things within one repository using simple folders for grouping, it makes sense to divide it up - especially when working in teams. Common Repositories for Common Modules Repositories can (and should) be modularized and reused in the same way recordings and code modules are. For example when you think about a rich client application using main menus, ribbons or toolbars you would create small reusable recordings for clicking on the main menu File |Open |Handle the Open File Dialog |etc. All these reusable modules work with a main menu, a main tool bar or similar, commonly available controls, and should be based on a repository which exclusively represents commonly used controls on the user interface. Advanced RanoreXPath Expressions 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.
Adding a New Repository

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.
135
Figure 206: Create a new repository file
Figure 207: New repository representing the complex options dialog in KeePass
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.
Using Multiple Repositories in Code Modules 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. C#
136
[ TestModule ( " C5B C 11 -274 A -4 E54 -83 DB - CE28DB955 9 " , ModuleType . UserCode , 1) ] public class OptionsCodeModule : ITestModule { // Repository object to access UI elements of KeePass Application MyFirstTestProjectRepository repo = MyFirstTestProjectRepository . Instance ; // Repository object to access UI elements of KeePass Options Dialog KeePassOptionsRepository OptionsRepo = KeePassOptionsRepository . Instance ; // / < summary > // / Constructs a new instance . // / </ summary > public OptionsCodeModule () { // Do not delete - a parameterless constructor is required ! } // / < summary > // / Performs the playback of actions in this module . // / </ summary > // / < remarks > You should not call this method directly , instead pass the module // / instance to the < see cref =" TestModuleRunner . Run ( ITestModule ) " > method // / that will in turn invoke this method . </ see > </ remarks > void ITestModule . Run () { Mouse . DefaultMoveTime = 3 ; Keyboard . DefaultKeyPressTime = 1 ; Delay . SpeedFactor = 1. ; // Click the Save - Button in KeePass MainForm repo . KeePass . ButtonSave . Click () ; // Check the option to AutoClear the Clipboard OptionsRepo . FormOptions . TabSecurity . CheckBoxClipboard_auto_clear . Checked = true ; } }
VB.NET
< testmodule ( " baa6 b6c -5 dd1 -4 eb5 - bc39 - fdfd65775742 " , moduletype . usercode ,= " " 1) = " " > _ Public Class UserCodeModule1 Implements ITestModule Repository object to access UI elements of KeePass Application Private repo As MyFirstTestProjectRepository = MyFirstTestProjectRepository . Instance Repository object to access UI elements of KeePass Options Dialog Private OptionsRepo AS KeePassOptionsRepository = KeePassOptionsRepository . Instance < summary > Constructs a new instance . </ summary > Public Sub New () Do not delete - a parameterless constructor is required ! End Sub TestRepository repo = TestRepository . Instance ; < summary > Performs the playback of actions in this module . </ summary > < remarks > You should not call this method directly , instead pass the module instance to the < see cref =" TestModuleRunner . Run ( Of ITestModule ) " > method that will in turn invoke this method . </ see > </ remarks > Sub Run () Implements ITestModule . Run Mouse . DefaultMoveTime = 3 Keyboard . DefaultKeyPressTime = 1 Delay . SpeedFactor = 1. Click the Save - Button in KeePass MainForm repo . KeePass . ButtonSave . Click Check the option to AutoClear the Clipboard OptionsRepo . FormOptions . TabSecurity . CheckBoxClipboard_auto_clear . Checked = true End Sub End Class </ testmodule ( " baa6 b6c -5 dd1 -4 eb5 - bc39 - fdfd65775742 " ,>
137
Repository Settings Dialog

There are two ways to open the Settings dialog for the repository:
Clicking the Settings button within Ranorex Spy Clicking the Settings button within Ranorex Recorder
Figure 208: Open Settings from Recorder
Figure 209: Open Settings from Spy 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.
Figure 210: Current settings of a repository
138
Figure 211: Default repository configuration
Repository Troubleshooting - Folder Caching

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.
139
Repository Item Properties

Each repository item (app folder, rooted folder, simple folder and item) held by a repository has a number of properties. These properties can be altered by opening the properties tab which can be accessed by right-clicking the desired repository item and choosing Properties in the context menu.
Figure 212: Opening the repository items properties
140
Figure 213: Repository item properties Within the properties tab the following properties are available: Absolute Path Adapter Type Effective Timeout Comment Live Element Name Search Timeout Use Ensure Visible The Absolute Path represents the path to the repository item including the paths of all parent folders. This property is read-only. With the Adapter Type property the adapter type of the repository item can be changed. The best fitting adapter will be chosen by setting this property to default. The Effective Timeout property represents the sum of the search timeouts for the specific repository item and all its parent folders. This property is read-only. Using the comment property, the repository item can be described textual. The Live Element represents the element specified by the repository item found in the live system as it is shown in Ranorex Spy. The Name property defines the name of the repository item. The Search Timeout property defines the amount of time an element will be searched for before an exception is thrown. 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:
141
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.
142
Lesson 7: Code Modules

Though a Ranorex Recording with only smart actions, variables and user code capabilities is good enough to create robust test automation modules, it might be useful or preferable to write pure Ranorex automation code. In the following section you learn how to create a new code module which automates the process of adding a new credential data set to the KeePass application.
Creating Code Modules Using Repository within Code Module Accessing Screen Shots within Code Modules Using Variables with Code Modules Using Code Modules within Test Cases
Creating Code Modules

Create a new code module by clicking the Add Code Module button at the toolbar.
Figure 214: 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.
143
Figure 215: Adding a new code module using the context menu
Figure 216: Specifying the name used for the code module
144
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 AddCredentialEntry . // / </ summary > [ TestModule ( " 3 F56 3B - DDC -49 AA -8 C26 -4 D8 8826 C66 " , ModuleType . UserCode , 1) ] public class AddCredentialEntry : ITestModule { // / < summary > // / Constructs a new instance . // / </ summary > public AddCredentialEntry () { // Do not delete - a parameterless constructor is required ! } // / < summary > // / Performs the playback of actions in this module . // / </ summary > // / < remarks > You should not call this method directly , instead pass the module // / instance to the < see cref =" TestModuleRunner . Run ( ITestModule ) "/ > method // / that will in turn invoke this method . </ remarks > void ITestModule . Run () { Mouse . DefaultMoveTime = 3 ; Keyboard . DefaultKeyPressTime = 1 ; Delay . SpeedFactor = 1. ; } } }
VB.NET
Namespace KeePass < summary > Description of AddCredentialEntry . </ summary > < TestModule ( " 3 F56 3B - DDC -49 AA -8 C26 -4 D8 8826 C66 " , ModuleType . UserCode , 1) > _ Public Class AddCredentialEntry Implements ITestModule < summary > Constructs a new instance . </ summary > Do not delete - a parameterless constructor is required ! Public Sub New () End Sub < summary > Performs the playback of actions in this module . </ summary > < remarks > You should not call this method directly , instead pass the module instance to the < see cref =" TestModuleRunner . Run ( ITestModule ) "/ > method that will in turn invoke this method . </ remarks > Private Sub ITestModule_Run () Implements ITestModule . Run Mouse . DefaultMoveTime = 3 Keyboard . DefaultKeyPressTime = 1 Delay . SpeedFactor = 1. End Sub End Class End Namespace
145
Using Repository within Code Module

In the same way you use a repository in the recording to identify UI elements for automation, you can also use it in code. Simply add a new private member which represents the repository to your code module class as shown below:
C#
public class AddCredentialEntry : ITestModule { // Repository object to access UI Elements MyFirstTestProjectRepository MyRepo = MyFirstTestProjectRepository . Instance ; // / Constructs a new instance . public AddCredentialEntry () { // Do not delete - a parameterless constructor is required ! } void ITestModule . Run () { Mouse . DefaultMoveTime = 3 ; Keyboard . DefaultKeyPressTime = 1 ; Delay . SpeedFactor = 1. ; // Click Add Entry Button MainMenu MyRepo . MainForm . Edit . Click () ; MyRepo . KeePass . AddEntry . Click () ; // Set text fields MyRepo . AddEntry . TabSheetAddEntry . Title . TextValue = " WordPressDemo " ; MyRepo . AddEntry . TabSheetAddEntry . UserName . TextValue = " admin " ; MyRepo . AddEntry . TabSheetAddEntry . Password . TextValue = " demo123 " ; MyRepo . AddEntry . TabSheetAddEntry . Repeat . TextValue = " demo123 " ; MyRepo . AddEntry . TabSheetAddEntry . URL . TextValue = " bitly . com / wp_demo " ; // Choose an icon MyRepo . AddEntry . TabSheetAddEntry . MBtnIcon . Click () ; MyRepo . IconPicker . LI_Icon . Click ( Location . CenterLeft ) ; MyRepo . IconPicker . ButtonClose . Click () ; // Set Expires MyRepo . AddEntry . TabSheetAddEntry . MBtnStandardExpires . Click () ; MyRepo . KeePass . MI_Expires . Click () ; // Save Credential Entry MyRepo . AddEntry . ButtonOK . Click () ; } }
VB.NET
Public Class AddCredentialEntry Implements ITestModule Repository object to access UI Elements Private MyRepo As MyFirstTestProjectRepository = MyFirstTestProjectRepository . Instance Constructs a new instance . Do not delete - a parameterless constructor is required ! Public Sub New () End Sub Private Sub ITestModule_Run () Implements ITestModule . Run Mouse . DefaultMoveTime = 3 Keyboard . DefaultKeyPressTime = 1 Delay . SpeedFactor = 1. Click Add Entry Button MainMenu MyRepo . MainForm . Edit . Click () MyRepo . KeePass . AddEntry . Click () Set text fields MyRepo . AddEntry . TabSheetAddEntry . Title . TextValue = " WordPressDemo " MyRepo . AddEntry . TabSheetAddEntry . UserName . TextValue = " admin " MyRepo . AddEntry . TabSheetAddEntry . Password . TextValue = " demo123 " MyRepo . AddEntry . TabSheetAddEntry . Repeat . TextValue = " demo123 " MyRepo . AddEntry . TabSheetAddEntry . URL . TextValue = " bitly . com / wp_demo "
146
Choose an icon MyRepo . AddEntry . TabSheetAddEntry . MBtnIcon . Click () MyRepo . IconPicker . LI_Icon . Click ( Location . CenterLeft ) MyRepo . IconPicker . ButtonClose . Click () Set Expires MyRepo . AddEntry . TabSheetAddEntry . MBtnStandardExpires . Click () MyRepo . KeePass . MI_Expires . Click () Save Credential Entry MyRepo . AddEntry . ButtonOK . Click () End Sub End Class
Note: By default the class name of a repository is the same as the repository file name (*.rxrep) shown in the 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.
Figure 217: Repository used within code example 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. 147
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.
Accessing Screen Shots within Code Modules

With Ranorex 3.3 its possible to access screen shots directly in code using the Info object of a repository item. This can be useful if you are going to compare a captured screen shot with the actual appearance of your application under test, for example.
Figure 218: Screen shot captured in repository
C#
// get the screenshot from the repository Bitmap MyScreenshot = MyRepo . IconPicker . LI_IconInfo . GetScreenshot_Icon () ; // create FindOptions with similarity set to 95% Imaging . FindOptions MyFindOptions = new Imaging . FindOptions ( .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 . GetScreenshot_Icon () create FindOptions with similarity set to 95% Dim MyFindOptions As New Imaging . FindOptions ( .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.
Using Variables with Code Modules

In order to use values provided by a data connector within your code modules, you need to add variables to the code. Use the context menu item Insert Module Variable. 148
Figure 219: Add a new variable to your code module
Figure 220: 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 -8 B6 -4 A2B -9 CBF - 276 A236AA3E " ) ] public string varTitle { get { return _varTitle ; } set { _varTitle = value ; } }
VB.NET
Private _varTitle As String = " Wordpress Credentials " < TestVariable ( " 9348 A7E6 -8 B6 -4 A2B -9 CBF - 276 A236AA3E " ) > _ Public Property varTitle () As String Get Return _varTitle End Get Set _varTitle = value End Set End Property
149
Now create additional variables for the Username, Password and URL. All the module variables will appear immediately in the module browser.
Figure 221: Module variables are shown in the module browser
Accessing Repository Variables with the Use of Setter Methods 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 _varRepoIconIndex = " 1 " ; [ TestVariable ( " EF 9BC93 -3447 -4 AC2 -9 DEB - FE3D78ED5538 " ) ] public string varRepoIconIndex { get { return _varRepoIconIndex ; } set { _varRepoIconIndex = value ; // Additionally set the Repository Variable in Setter - Method MyRepo . varIconIndex = _varRepoIconIndex ; } } string _varRepoExpires = " 1 Year " ; [ TestVariable ( " D A54427 -68 FF -4 B9D - B861 -4882 BCEC846B " ) ]
150
public string varRepoExpires { get { return _varRepoExpires ; } set { _varRepoExpires = value ; // Additionally set the Repository Variable in Setter - Method MyRepo . varExpires = _varRepoExpires ; } }
VB.NET
Private _varRepoIconIndex As String = " 1 " < testvariable ( " ef 9bc93 -3447 -4 ac2 -9 deb - fe3d78ed5538 " ) > _ Public Property varRepoIconIndex () As String Get Return _varRepoIconIndex End Get Set _varRepoIconIndex = value Additionally set the Repository Variable in Setter - Method MyRepo . varIconIndex = _varRepoIconIndex End Set End Property Private _varRepoExpires As String = " 1 Year " < testvariable ( " d a54427 -68 ff -4 b9d - b861 -4882 bcec846b " ) > _ Public Property varRepoExpires () As String Get Return _varRepoExpires End Get Set _varRepoExpires = value Additionally set the Repository Variable in Setter - Method MyRepo . varExpires = _varRepoExpires End Set End Property </ testvariable ( " d a54427 -68 ff -4 b9d - b861 -4882 bcec846b " ) > </ testvariable ( " ef 9bc93 -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.
Using Code Modules within Test Cases

The code module implemented above is now ready to be run by a test case. Add a new test case (TC AddEntryFromCode) to your test suite and reuse already existing modules to start KeePass, login at the beginning and to validate, delete, save and close it at the end of the test case. You can use drag and drop to quickly insert the newly created code module into the test case.
151
Figure 222: 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 223: Reuse the existing data connector by choosing the item from the drop-down
152
Figure 224: Bind the newly created variables to the data connectors columns, i.e. columns from the Excel file
153
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:
Reading Ranorex Reports Report Levels Logging Individual Information Updating the Custom Report Format Create a Custom Report Template
Reading Ranorex Reports

After executing a test suite in Ranorex Studio the generated report file is opened in a file view as shown below.
Figure 225: Ranorex report after running a test suite
154
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.
Figure 226: Detailed view of a test case report 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.
Jump to Item/Testcase and Analyze with Spy

Expand the report as shown above and move the mouse pointer over the first log message.
Figure 227: 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 correspondending 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 testcase and click on Jump to Testcase to select the correspondending test case in the test suite.
155
Lesson 8: Reporting
Filter Log Messages

Use the checkboxes shown at the top of each module to filter log messages.
Figure 228: Filter for different log levels
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.
Figure 229: Log file history within Ranorex Studio project
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.
156
Lesson 8: Reporting
Predefined Report Levels 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.
Figure 230: Report indicating a failed module Additionally, at the top of a test case, warnings are indicated using a message with a yellow background.
Figure 231: 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.
User-defined Report Levels 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). 157
Lesson 8: Reporting
Logging Individual Information

Individual information can be sent to the report either by using usercode (i.e. code modules) or by using the recorder action Report. Logging Information via Code You can use one of the following methods from the Ranorex Report class in order to report information at a specific level:
Ranorex.Report.Debug (Debug Message); Ranorex.Report.Info (Information Message); Ranorex.Report.Warn (Warning Message); Ranorex.Report.Error (Error Message); 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 . DefaultCategory = " My new default category " ; // Reporting information ( success , failure ) using the new default category Ranorex . Report . Success ( " This is a success information " ) ; Ranorex . Report . Failure ( " This is a failure Information " ) ;
VB.NET
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 . DefaultCategory = " My new default category " Reporting information ( success , failure ) using the new default category Ranorex . Report . Success ( " This is a success information " ) Ranorex . Report . Failure ( " This is a failure Information " )
158
Lesson 8: Reporting
Figure 232: 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.
User-defined Report Levels You are able to define your own report levels with a custom name and a value for the level:
C#
Ranorex . ReportLevel MyNewReportLevel = new ReportLevel ( " My low Report Level " , 25 , null ) ; Ranorex . Report . Log ( MyNewReportLevel , " This is unimportant information " ) ;
VB.NET
Dim MyNewReportLevel As Ranorex . ReportLevel = New ReportLevel ( " My low Report Level " , 25 , Nothing ) Ranorex . Report . Log ( MyNewReportLevel , " This is unimportant information " )
Depending on the current Report Level (see next chapter), the report information with the user-defined report level should appear in the report as follows:
159
Lesson 8: Reporting
Figure 233: Report with information for a user-defined level Current Report Level Report information only appears in the report if the parent test case has a report level setting lower than or equal to the current report information level. The current report level can also be set using code:
C#
Ranorex . Report . CurrentReportLevel = Ranorex . ReportLevel . Parse ( " Only Highest Importance ;9 " ) ;
VB.NET
" Ranorex . Report . CurrentReportLevel = Ranorex . ReportLevel . Parse ( " Only Highest Importance ;9 " )
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.
Figure 234: Report with a current report level of 90
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 " ) ;
160
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 )
Figure 235: Screenshot of KeePass toolbar opened directly in Ranorex report 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).
161
Lesson 8: Reporting
Reporting System Summary The Ranorex reporting class provides a way to simply report a system summary:
C#
Ranorex . Report . SystemSummary () ;
VB.NET
Ranorex . Report . SystemSummary ()
Figure 236: System summary provided by Report.SystemSummary()
Logging Information from Recorder 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 Report Action.
162
Lesson 8: Reporting
Figure 237: Add a new report action to your recording
163
Lesson 8: Reporting
Predefined Report Level Just like a call from code, you can specify one of the predefined report levels directly within the recorders actions table.
Figure 238: Define the report level
Custom Report Level Report messages with a custom report level can also be submitted. Simply choose the Custom report level in the drop-down.
Figure 239: Define a report message with a custom level
Screenshots and Snapshots 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 240: Usage of the report action using the screenshot and the snapshot action type
Updating the Custom Report Format

With Ranorex 4.0.0 the custom report format has been changed from one single file to a template folder holding all necessary files. After upgrading to Ranorex 4 and opening a solution using custom reports, a warning will appear in the Error pane.
164
Lesson 8: Reporting
Figure 241: ReportXmlFile is no longer supported 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.
Figure 242: Choose resolve option
Create a Custom Report Template

To create a custom report template, open the test suites settings dialog and click the Create Custom Template button in the Report Settings area from General tab.
165
Lesson 8: Reporting
Figure 243: Create a custom report template 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.
Figure 244: Show all files in project view Open the file RanorexReport4.css to edit the style of the report according to your wishes.
Note: Its recommended to make customizations at the end of the file.
Open the file RanorexReport4.xsl to edit the structure of the report according to your wishes. 166
Lesson 8: Reporting
Open the file View.rxlog to get a preview of your customizations using some sample data.
Figure 245: Preview of customizations
167
Lesson 9: Ranorex Spy

As a stand-alone tool the Ranorex Spy provides all the functionality needed to explore and analyze desktop and mobile applications or websites under test - including their controls and UI elements. After starting Ranorex Spy, the element browser contains all currently running applications from your Windows desktop and mobile devices.
Figure 246: Ranorex Spy - applications and their UI elements

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
168
Figure 247: 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.
Logical adapters like Form, Button or Text

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.
Technology related adapters like Control, Accessible or NativeWindow

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 169
attribute values at Create Adapters to Access More Properties and Methods. In addition all attributes can be used within the RanoreXPath. By default the attribute in the overview tab written in bold is automatically used to identify the UI element.
Figure 248: Attribute controlname is used to identify the button 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.
170
Figure 249: Image navigator 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. Double-clicking a UI element selects it, double-clicking outside the selected element selects the parent.
Short Introduction to the Structure of RanoreXPath

The RanoreXPath is built up in a hierarchical way where all the UI levels are separated with a forward slash (/). The following figure shows an abstract illustration of how UI levels are represented by so called adapters (e.g. form, button, etc.). Since there may be more than one UI element of a specific type (adapters) on the current level of the path, the desired adapter itself is commonly specified in more detail; this is done using one or more predicate expressions. You can also specify the intended adapter with the use of an index (e.g. button[2]). As already mentioned, search specification is commonly done with one or more attributes, where the attribute is prefixed with an @ sign followed by a comparison operator (=, !=, , > as well as >, >=, <, <=) and an attribute.
171
Figure 250: Abstract illustration of the structure of RanoreXPath Attribute comparisons may also be combined with and and or operators (e.g. button[@text=OK and @enabled=true]).
Capture Screenshot Files for Image-Based Search

Use the context menu item Capture Screenshot to create an image file (PNG format) which can be used to search for images in test automation code as explained in How to find and compare images.
172
Figure 251: Capture a screenshot from a UI element to save as PNG file 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.
173
Figure 252: Select an image region to save
Toolbar shortcuts Browse Local Host Connect to a Mobile Device Refresh Load from Snapshot Save as Snapshot Highlight Elements Update Path Shows currently running host applications Opens the Manage Devices dialog Updates the current state of applications Loads an existing Ranorex snapshot file Saves the currently selected node and all its descendants to a Ranorex snapshot file When switched on, highlights selected UI elements on the users desktop Sets the path from the currently selected element
174
Context menu Update Path Set Element as Root Highlight Element Add to Repository Add to Repository (incl. Children) Add Matching Children to Repository Update Element Data Save as Snapshot. . . Capture Screenshot. . . Expand All Collapse All Sets the path from the currently selected element Sets the currently selected element as root element Highlights the current element Adds the current element to a Ranorex Repository Adds the current element and the elements children to a Ranorex Repository Adds all UI elements matching the given RanoreXPath to the Repository Updates all attributes of the specified UI element Saves the current UI element including the child structure to a Ranorex snapshot file Captures a screenshot from the current element to be used for further image-based validation Expands all child elements of the selected UI element in the element browser Collapses all child elements of the selected UI element in the element browser Specifies whether the elements class or process name should use the GDI plug-In to turn on text-based object recognition Based on the type of the UI element a list of different actions to perform on the UI element is available
Add Class or Process Name to GDI Capture List
Actions to perform
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.
175
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:
Using the TRACK Button Instant Tracking
Using the TRACK Button

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.
Figure 253: Click the Track button to start element tracking
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.
176
Figure 254: Always On Top checkbox within 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.
Figure 255: Instant tracking of menu items
177
RanoreXPath Edit Mode

There are two ways to change the RanoreXPath expression. One is to work with the The Path Editor. The second option is to edit the path directly in the textbox of Ranorex Spy; this is described in the following section. To support the editing of RanoreXPath expressions, the editor textbox provides an auto completion feature which helps to avoid syntax errors and to help with text entry. By pressing the key combination <CTRL>+<SPACE> at any time, the RanoreXPath editor suggests a list of suitable keywords, attributes or operators.
Figure 256: RanoreXPath auto completion 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:
Figure 257: Use of RanoreXPath as a filter to search for buttons 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.
178
Figure 258: Add matching items to the repository To stop the edit mode, click the red cancel button which is located in the RanoreXPath edit box or press the <ESC> key.
179
Figure 259: Leave RanoreXPath edit mode
180
The Path Editor

In this section you will learn about
How to Access the Path Editor Layout of the Path Editor The Tree View Section The Attribute Comparison Section Types of Comparisons Relationship Operators Adapter Types Optional Path Elements Defining Variables Live View with Dynamic Capabilities and Offline View
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.
How to Access the Path Editor

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 260: 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.
181
Figure 261: Switch to path editor tab
Layout of the Path Editor

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).
182
Figure 262: Overview of path editor 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.
183
Figure 263: Tracking area limited to the KeePass application
The Tree View Section

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:
Figure 264: KeePass with one cell being tracked by Ranorex Spy
184
Figure 265: RanoreXPath structure in path editor for a cell in second row
The Attribute Comparison Section

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 \ _splitHorizontal ] // 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.
185
Figure 266: Uncheck the index attribute in the row node
/ form [ @controlname = MainForm ]/ container [ @controlname = m \ _splitHorizontal ] // table [ @controlname = m \ _lvEntries ]/ row / cell [ @text = Ranorex ]
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.
186
Figure 267: Check the column index attribute
/ form [ @controlname = MainForm ]/ container [ @controlname = m \ _splitHorizontal ] // table [ @controlname = m \ _lvEntries ]/ row / cell [ @text = Ranorex and @columnindex = 1 ]
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.
187
Figure 268: The current path leads to two elements To find out which elements are found with the current RanoreXPath, simply click on the Highlight button on the bottom of path editor.
188
Figure 269: The underlying path leads to two elements in KeePass 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):
=: The value of the attribute must be equal to the given value : The value of the attribute must match the given regular expression !: The value of the attribute must not match the given regular expression !=: The value of the attribute must not be equal to the given value >: The value of the attribute must start with the given string
Numerical Comparisons Ranorex Version 3.3):
The following types of comparisons are defined for numerical comparisons (starting with
>: 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.
Example for Regular Expression The following example shows how to use a regular expression operator ().
189
Figure 270: Matches all entries ending with the text fragment rex using a regular expression
Figure 271: Result from the comparison above
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 272: Matches all entries that are not equal to Ranorex
190
Figure 273: Result from the comparison above Example for Starts With The following example shows how to use the starts with operator (>).
Figure 274: Matches all entries that start with adm
Example for Numerical Comparisons The following examples demonstrates how numerical operators (>, >=, <and <=) can be used in the path Editor.
191
Figure 276: 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.
192
Figure 278: Available relationship operators in path editor

child: Refers to all children of the current node 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 self: Refers to the current node descendant: Refers to all descendants (children, grandchildren, etc.) of the current node parent: Refers to the parent 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 following-sibling: Refers to all siblings after 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 \ _splitHorizontal ] // table [ @controlname = m \ _lvEntries ]/ row [ @index = 2 ]/ cell [ @text = Amazon ]
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. 193
/ form [ @controlname = MainForm ]/ container [ @controlname = m \ _splitHorizontal ] // 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 279: 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 280: Highlighting the element from the newly created path
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. 194
Figure 281: Changing the adapter to a specific type of element 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.
Optional Path Elements

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.
195
Figure 282: Windows node located at the root level (left) or. . .
Figure 283: . . . in a sub-node of the tree (right) in KeePass In general, the path to the Windows node on the left side of the figure would not include the General folder because this folder can be seen as a sibling. The path to the Windows node on the right side, which can be seen as child element of the General node, would therefore include this element in the path. Thus, the General folder can 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.
196
Figure 284: Marking one level of the path as optional
/ form [ @controlname = MainForm ]// treeitem [ @accessiblename = NewDatabase ]/ treeitem ?[ @accessiblename = General ]/ treeitem [ @accessiblename = Windows ]
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.
197
Figure 285: Buttons for creating a new variable for every selected attribute
Figure 286: Variables can also be created using the As new Variable entry in the dropdown menu
198
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.
Live View with Dynamic Capabilities and Offline View

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. 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).
Figure 287: Path editor window in live view having dynamic capabilities
199
Note: Dynamic capabilities can only be accessed for certain types of technologies (WinForms, Flash/Flex, Web and Java).
200
Creating Ranorex Snapshot Files

With the Ranorex snapshot feature, you can not only save graphic but also UI structure information into an XML file (*.rxsnp). Create and send a snapshot by email to support@ranorex.com to request application specific assistance from the Ranorex team. Based on the information stored in the snapshot, the support team will be able to analyze your application under test offline and give advice on how to optimize unique object identification with RanoreXPath.
Figure 288: Saving the UI structure of KeePass as a snapshot file
201
Figure 289: Ranorex Spy tool with opened snapshot file from KeePass 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.
Snapshots from pop-up windows, drop-down combo boxes or drop-down menus 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: 1. Open Ranorex Spy and activate Highlight Elements. 2. Start the KeePass application and open the File menu. 3. Track the parent menu container window of the menu items: Track the pop-up frame by positioning the mouse over the edge of the window and pressing <CTRL>+<Win>. 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: 1. Open Ranorex Spy and activate Highlight Elements. 2. Start the KeePass application.
202
3. Press the TRACK button. 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.
Figure 290: Track menu container window using instant tracking (<CTRL>+<Win>)
203
General Ranorex Settings

There are four ways to open the Settings dialog to change general Ranorex automation and identification settings:
Clicking on the Settings button within Ranorex Spy Clicking on the Settings button within Ranorex Recorder Clicking on the Global Settings button within Ranorex Studio Starting the external Ranorex Settings executable(which especially is useful on runtime machines with no Ranorex Tools installed)
Figure 291: Open Settings from Spy
Figure 292: Open Settings from Recorder
Figure 293: Open Global Settings from Ranorex Studio
204
Figure 294: Start external Settings executable from Ranorex installation bin folder
General settings
205
Figure 295: General Ranorex settings Use Ensure Visible by default 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. Enable search by unique ID (if available) Specifies whether web elements should be identified using their unique id or not. On mouse/pointer move check if location is within visible desktop bounds Specifies whether an exception should be thrown if the mouse/pointer tries to move outside the visible desktop bounds or not. Maximum length of text values in RanoreXPaths Specifies the maximum length of attribute values used within RanoreXPath. 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.
Reset not shown technology specific limitations 206
Resets the Do not show again checkbox used to suppress the assistance dialog for technology limitations. Click Reset to show the dialog again for not instrumented technologies or applications. GDI Capture Settings. . . 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
Figure 296: Advanced 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. Enable 32/64 Bit Bridge 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. Use hidden screenshot capturing (if possible)
207
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. Let snapshot contain complete ancestor subtree 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. Use asynchronous dispatching of mouse and keyboard events 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. Disable expensive attribute in tools 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. Use UiaLauncher to elevate privileges for processes started by tools Specifies whether test execution is started with elevated privileges or not. Delay before pressing a key sequence (ms) Specifies the time to wait in milliseconds before performing a key sequence simulation. RanoreXPath generation mode: Defines how RanoreXPaths will be build during recording actions or tracking elements using the Ranorex tools (by default, the mode StepCostReduce is selected). Edit Path Weights. . . In order to get assistance with editing RanoreXPath weights, have a look at the blog post Automated Testing and Dynamic IDs. Edit Path Build Options Specifies the parameters for StepCostReduce RanoreXPath generation mode.
Recorder Settings
The description of the settings regarding the Ranorex Recorder can be found in the Recorder Settings Dialog in Lesson 5: Ranorex Recorder.
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.
208
Plug-In Specific Settings
Figure 297: Plug-in specific settings Plug-in specific settings can be used to alter the behavior of individual Ranorex plug-ins, for example, to achieve backwards compatibility with older versions. For more information on each setting, read the description shown when you click on a particular setting in the property grid.
209
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.
Using Repository in Code Wait for UI Elements Using Repository Create Adapters to Access More Properties and Methods Create a List of Adapters From a Repository Element Using Validate Class Forcing a Test Case to Fail Set Up Automation Speed Accessing Test Case & Test Suite Context Advanced Code Examples How to do image based automation How to find and compare images Handling unexpected Dialogs
Using Repository in Code

C#
[ TestModule ( " D451F1D1 - C347 -4 B58 -939 F - F6187642EB56 " , ModuleType . UserCode , 1) ] public class UsingRepository : ITestModule { // Repository object to access UI elements MyFirstTestProjectRepository repo = MyFirstTestProjectRepository . Instance ; // / < summary > // / Constructs a new instance . // / </ summary > public UsingRepository () { // Do not delete - a parameterless constructor is required ! } void ITestModule . Run () { Mouse . DefaultMoveTime = 3 ; Keyboard . DefaultKeyPressTime = 1 ; Delay . SpeedFactor = 1. ; // 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
210
Code Examples
// 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 UsingRepository Implements ITestModule Repository object to access UI elements Private repo As MyFirstTestProjectRepository = MyFirstTestProjectRepository . Instance < summary > Constructs a new instance . </ summary > Do not delete - a parameterless constructor is required ! Public Sub New () End Sub < summary > Performs the playback of actions in this module . </ summary > < remarks > You should not call this method directly , instead pass the module instance to the < see cref =" TestModuleRunner . Run ( ITestModule ) " > method that will in turn invoke this method . </ see > </ remarks > Private Sub ITestModule_Run () Implements ITestModule . Run Mouse . DefaultMoveTime = 3 Keyboard . DefaultKeyPressTime = 1 Delay . SpeedFactor = 1. Using Ranorex . Form adapter represented by MyApp MyApp is used as a folder within the repository ; the Self property returns a Ranorex . Form object Activates application repo . MyApp . Self . Activate () Log Active state Report . Info ( repo . MyApp . Self . Active . ToString () ) Maximize , Minimize and Restore repo . MyApp . Self . Maximize () repo . MyApp . Self . Minimize () repo . MyApp . Self . Restore () Closes application repo . MyApp . Self . Close () 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
211
Code Examples
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
Wait for UI Elements Using Repository

Each item and each folder type provides an additional object item declared with <objectname>Info. It is used to access item related attributes without accessing the UI element directly in order to prevent Ranorex from throwing exceptions. The info object is mainly used to check whether an item or a folder path is valid or not. In combination with the timeout set for the item, you can use it to wait for UI elements like dialogs, text values and web content.
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 [ @accessiblename = Online ] // This way you can wait with the timeout specified for // the item within the repository for the text Online bool statusTextConnected = repo . MyApp . TextOnlineInfo . Exists () ; // Using Info objects for validation // Throws a Ranorex . ValidationException if validation // fails . Automatically reports success or failed message // to log file Validate . Exists ( repo . SaveDialog . ButtonOKInfo ) ; // Validates the existence of the repository item , // but does not throw any exception Validate . Exists ( repo . SaveDialog . ButtonOKInfo , " Check Object { } " , false ) ;
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 [ @accessiblename = Online ] This way you can wait with the timeout specified for the item within the repository for the text Online Dim statusTextConnected As Boolean = repo . MyApp . TextOnlineInfo . Exists () Using Info objects for validation Throws a Ranorex . ValidationException if validation fails . Automatically reports success or failed message to log file
212
Code Examples
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 { } " , False )
Create Adapters to Access More Properties and Methods

If you analyze the VIP Database application form with Ranorex Spy, you see that that the application window provides three adapters (Form, Control and NativeWindow). The Ranorex.Form adapter with all attributes and methods is directly available using the repositorys application folder MyApp. If you want to access properties like ProcessName or invoke methods exposed by a .NET WinForms control you need to convert the Form adapter to NativeWindow or Control. As you can see in the code section below the . . . Info object is used to create the desired adapter.
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 winFormsControl = repo . MyApp . SelfInfo . CreateAdapter < Ranorex . Control >( false ) ; // Set background color of VIP application to Color . Black using the // exposed property BackColor winFormsControl . SetPropertyValue ( " BackColor " , Color . Black ) ; // Report screenshot after changing the background color Report . Screenshot ( repo . MyApp . Self ) ; // Closes VIP Database by invoking the Close method // exposed by the System . Windows . Forms . Form class winFormsControl . InvokeMethod ( " Close " ) ;
VB.NET
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 winFormsControl As Ranorex . Control = repo . MyApp . SelfInfo . CreateAdapter ( Of Ranorex . Control ) ( False ) Set background color of VIP application to Color . Black using the exposed property BackColor winFormsControl . SetPropertyValue ( " BackColor " , Color . Black ) Report screenshot after changing the background color Report . Screenshot ( repo . MyApp . Self ) Closes VIP Database by invoking the Close method exposed by the System . Windows . Forms . Form class winFormsControl . InvokeMethod ( " Close " )
Note: In order to access properties or methods exposed by a WinForms control you need to know their names. If youre not familiar with the controls API ask the developer of your application for assistance.
213
Code Examples
Create a List of Adapters From a Repository Element

If multiple elements match a RanoreXPath of a single repository item use the CreateAdapters method to create a list of adapters.
C#
// Create a list of adapters using the " Info " object IList < Ranorex . Button > buttonList = repo . MyApp . EnabledButtonsInfo . CreateAdapters < Ranorex . Button >() ; // Move the mouse pointer to each button of the list // and add a screenshot for each to the report foreach ( Ranorex . Button button in buttonList ) { button . MoveTo () ; Report . Screenshot ( button ) ; }
VB.NET
Create a list of adapters using the " Info " object Dim buttonList As IList ( Of Ranorex . Button ) = repo . MyApp . EnabledButtonsInfo . CreateAdapters ( Of Ranorex . Button ) () Move the mouse pointer to each button of the list and add a screenshot for each to the report For Each button As Ranorex . Button In buttonList button . MoveTo () Report . Screenshot ( button ) Next
Learn more about how to create repository items delivering multiple elements here: Repository Items Representing Multiple Elements
Using Validate Class

The Ranorex.Validate class is used to check values from UI elements, but it can also be used to simply compare non UI related objects in code. In comparison to a simple IF statement the methods provided automatically log fail or success messages to the report.
C#
// Validate for Existence // Using Info objects for validation // Throws a Ranorex . ValidationException if validation // fails . Automatically reports success or failed message // to log file Validate . Exists ( repo . SaveDialog . ButtonOKInfo ) ; // Validates the existence of the repository item , // but does not throw any exception bool exists = Validate . Exists ( repo . SaveDialog . ButtonOKInfo , " Check Object { } " , 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 ) ;
214
Code Examples
VB.NET
Validate for Existence Using Info objects for validation Throws a Ranorex . ValidationException if validation fails . Automatically reports success or failed message to log file Validate . Exists ( repo . SaveDialog . ButtonOKInfo ) Validates the existence of the repository item , but does not throw any exception Dim exists As Boolean = Validate . Exists ( repo . SaveDialog . ButtonOKInfo , " Check Object { } " , 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.
Forcing a Test Case to Fail

Ranorex uses exception handling to determine whether a test case run failed or succeeded. As long as no exception is thrown by any of the Ranorex methods (e.g Ranorex.Validate method or use of not valid repository item) the test run will be successful. If you want to prevent Ranorex from throwing exceptions but at the same time decide on your own whether a test case fails or not, you need to throw Ranorex exceptions programmatically.
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] " , 2 , out cellObject ) ; found = Host . Local . TryFindSingle < Ranorex . Cell >( " / form // table / row / cell [4] " , 2 , out cellObject ) ; // If none of the expressions returns an object // throw new ElementNotFoundException and test case fails if (! found ) { throw new Ranorex . ElementNotFoundException ( " 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 == " MyExpectedTextValue " ) { Report . Success ( " User Specific Validation " ," Text validation of cell object succeeded " ); } else { throw new Ranorex . ValidationException ( " Text validation of cell object succeeded failed " ) ; } }
215
Code Examples
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] " , 2 , cellObject ) found = Host . Local . TryFindSingle ( Of Ranorex . Cell ) ( " / form // table / row / cell [4] " , 2 , cellObject ) If none of the expressions returns an object throw new ElementNotFoundException and test case fails If Not found Then Throw New Ranorex . ElementNotFoundException ( " Both RanoreXPath with no return " , Nothing ) Else If the value of attribute Text does not equal to the expected value throw new ValidationException to break the test case If cellObject . Text = " MyExpectedTextValue " Then Report . Success ( " User Specific Validation " , " Text validation of cell object succeeded ") Else Throw New Ranorex . ValidationException ( " Text validation of cell object succeeded failed " ) End If End If
Set Up Automation Speed

You can optionally specify and change the automation speed at any time in the code. The code generated by a recording uses the same properties to define replay speed as used within a code module. A newly created code module already contains three lines of code specifying the automation speed in the Run method.
C#
void ITestModule . Run () { Mouse . DefaultMoveTime = 3 ; Keyboard . DefaultKeyPressTime = 1 Delay . SpeedFactor = 1. ; }
VB.NET
Private Sub ITestModule_Run () Implements ITestModule . Run Mouse . DefaultMoveTime = 3 Keyboard . DefaultKeyPressTime = 1 Delay . SpeedFactor = 1. End Sub
Accessing Test Case & Test Suite Context

Sometimes its necessary to forward values read from the UI in a code module or recording to the module executed next in the scope of a test case. The example code shown below uses the module variables varDialogTextA (Code Module A) and varDialogTextB (Code Module B) which are both bound to a parameter specified within the test cases data binding dialog to transfer data within a test case.
216
Code Examples
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 varDialogTextA = 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 ( varDialogTextB ) ; // Get the current data context and log // the current row index of a data driven run Report . Info ( TestCase . Current . DataContext . CurrentRow . ToString () ) ;
VB.NET
----------------- 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 varDialogTextA = 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 ( varDialogTextB ) Get the current data context and log the current row index of a data driven run Report . Info ( TestCase . Current . DataContext . CurrentRow . ToString () )
Advanced Code Examples

You can also use RanoreXPath expressions directly in code in order to search for items using different Find methods offered by the API. Start searching for elements directly at the root level using Host.Local or reuse existing adapters like repository items to start searching from there.
C#
// Create Ranorex . Button adapter using FindSingle method // from Host . Local ( starting at root node ) with absolute RanoreXPath // Note : ElementNotFound exception is thrown if item is not found within // the specified timeout of 2 ms . Ranorex . Button addButtonVar1 = Host . Local . FindSingle < Ranorex . Button >( " / form [ @controlname = formVipApplication ]/ button [ @controlname = btAdd ] " ,2 ); addButtonVar1 . MoveTo () ; // Alternatively you can use the TryFindSingle method to prevent // a test case from failing because of an exception thrown if // the element is not found within the specified timeout of 2 ms Ranorex . Button addButtonVar2 = null ; bool found = Host . Local . TryFindSingle < Ranorex . Button >( " / form [ @controlname = formVipApplication ]/ button [ @controlname = btAdd ] " , 2 , out addButtonVar2 ) ; // Move mouse pointer to button addButtonVar2 . MoveTo () ; // Request a list of buttons shown from the VIP Database application // and create a screenshot for each button in the report file IList < Ranorex . Button > buttonList = Host . Local . Find < Ranorex . Button >( " / form [ @controlname = formVipApplication ]/ button " ,5 ) ; foreach ( Ranorex . Button bt in buttonList ) {
217
Code Examples
Report . Screenshot ( bt ) ; } // Using find methods in combination with existing Ranorex repository items Ranorex . Button btAdd = repo . MyApp . Self . FindSingle < Ranorex . Button >( " button [ @controlname = btAdd ] " ,2 );
VB.NET
Create Ranorex . Button adapter using FindSingle method from Host . Local ( starting at root node ) with absolute RanoreXPath Note : ElementNotFound exception is thrown if item is not found within the specified timeout of 2 ms . Dim addButtonVar1 As Ranorex . Button = Host . Local . FindSingle ( Of Ranorex . Button ) ( " / form [ @controlname = formVipApplication ]/ button [ @controlname = btAdd ] " , 2 ) addButtonVar1 . MoveTo () Alternatively you can use TryFindSingle method to prevent a test case from failing because of an exception thrown if the element is not found within the specified timeout of 2 ms Dim addButtonVar2 As Ranorex . Button = Nothing Dim found As Boolean = Host . Local . TryFindSingle ( Of Ranorex . Button ) ( " / form [ @controlname = formVipApplication ]/ button [ @controlname = btAdd ] " , 2 , addButtonVar2 ) Move mouse pointer to button addButtonVar2 . MoveTo () Request a list of buttons from the VIP Database application and create a screenshot for each button in the report file Dim buttonList As IList ( Of Ranorex . Button ) = Host . Local . Find ( Of Ranorex . Button ) ( " / form [ @controlname = formVipApplication ]/ button " , 5 ) For Each bt As Ranorex . Button In buttonList Report . Screenshot ( bt ) Next Using find methods in combination with existing Ranorex repository items Dim btAdd As Ranorex . Button = repo . MyApp . Self . FindSingle ( Of Ranorex . Button ) ( " button [ @controlname = btAdd ] " , 2 )
How to do image based automation

If Ranorex is not able to clearly identify some of your GUI elements, it may be helpful to automate them using the implicit image search mechanism of the Click method.
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% = .95) . myRepo . WinFormsApp . Self . Click ( new Location ( bmp , new Imaging . FindOptions ( .95) ) ) ; // OR Set the default Similarity value for all following image operations Imaging . FindOptions . Default . Similarity = .95; myRepo . WinFormsApp . Self . Click ( bmp ) ; Report . Success ( " Image found and clicked successfully " ) ;
218
Code Examples
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 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% = .95) . myRepo . WinFormsApp . Self . Click ( new Location ( bmp , new Imaging . FindOptions ( .95) ) ) OR Set the default Similarity value for all following image operations Imaging . FindOptions . Default . Similarity = .95 myRepo . WinFormsApp . Self . Click ( bmp ) Report . Success ( " Image displayed successfully " )
How to find and compare images

To compare an image simply search for it within an existing Ranorex element using the Contains method.
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.
Handling unexpected Dialogs

A common problem in UI testing is the appearance of an unexpected dialog - e.g. the Update-Check dialog in KeePass.
219
Code Examples
Figure 298: Update-Check dialog To overcome this issue, you can use the PopupWatcher class. Using this class you can add watches for each dialog which might pop up during test execution. In this watches you can specify a RanoreXPath or a Repository item the PopupWatcher should keep watching for, as well as a method which should be triggered or a repository item which should be clicked.
C#
void ITestModule . Run () { // Create PopupWatcher PopupWatcher myPopupWatcher = new PopupWatcher () ; // Add a Watch using a RanoreXPath and triggering the Method CloseUpdateCheckDialog myPopupWatcher . Watch ( " / form [ @controlname = UpdateCheckForm ]/ button [ @controlname = m_btnClose ] " , CloseUpdateCheckDialog ) ; // Add a Watch using the info object of a button and triggering the Method CloseUpdateCheckDialog // myPopupWatcher . Watch ( repo . UpdateCheckDialog . btCloseInfo , CloseUpdateCheckDialog ) ; // Add a Watch using the info object of the dialog and the info object of the button to click // myPopupWatcher . WatchAndClick ( repo . UpdateCheckDialog . SelfInfo , repo . UpdateCheckDialog . btCloseInfo ); // Add a Watch using a repository folder object and the info object of the button to click // myPopupWatcher . WatchAndClick ( repo . UpdateCheckDialog , repo . UpdateCheckDialog . btCloseInfo ) ; // Start PopupWatcher myPopupWatcher . Start () ; } public static void CloseUpdateCheckDialog ( Ranorex . Core . Repository . RepoItemInfo myInfo , Ranorex . Core . Element myElement ) { myElement . As < ranorex . button >() . Click () ; } public static void CloseUpdateCheckDialog ( Ranorex . Core . RxPath myPath , Ranorex . Core . Element myElement ) { myElement . As < ranorex . button >() . Click () ; }
VB.NET
220
Code Examples
Private Sub ITestModule_Run () Implements ITestModule . Run Create PopupWatcher Dim myPopupWatcher As New PopupWatcher () Add a Watch using a RanoreXPath and triggering the Method CloseUpdateCheckDialog myPopupWatcher . Watch ( " / form [ @controlname = UpdateCheckForm ]/ button [ @controlname = m_btnClose ] " , AddressOf CloseUpdateCheckDialog ) Add a Watch using the info object of a button and triggering the Method CloseUpdateCheckDialog myPopupWatcher . Watch ( repo . UpdateCheckDialog . btCloseInfo , CloseUpdateCheckDialog ) ; Add a Watch using the info object of the dialog and the info object of the button to click myPopupWatcher . WatchAndClick ( repo . UpdateCheckDialog . SelfInfo , repo . UpdateCheckDialog . btCloseInfo ) ; Add a Watch using a repository folder object and the info object of the button to click myPopupWatcher . WatchAndClick ( repo . UpdateCheckDialog , repo . UpdateCheckDialog . btCloseInfo ) ; Start PopupWatcher myPopupWatcher . Start () End Sub Public Shared Sub CloseUpdateCheckDialog ( myInfo As Ranorex . Core . Repository . RepoItemInfo , myElement As Ranorex . Core . Element ) myElement .[ As ]( Of Ranorex . Button ) () . Click () End Sub Public Shared Sub CloseUpdateCheckDialog ( myPath As Ranorex . Core . RxPath , myElement As Ranorex . Core . Element ) myElement .[ As ]( Of Ranorex . Button ) () . Click () End Sub
221
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.
Simple Data Table CSV File SQL Connector Excel File
Manage Data Sources

There are two locations on which you can manage data sources, one for the whole test suite and one for a specific test case. To maintain all data connectors in your test suite, open the data source management dialog by pressing the Manage Data Sources. . . button.
Figure 299: Open Manage Data Sources dialog from test suite view
222
Data Connectors
Figure 300: Manage Data Sources dialog 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.
223
Data Connectors
Figure 301: Set up data sources for a test case
Figure 302: 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-2,4), press the purple marked button, labeled Preview effective data set. . . .
224
Data Connectors
Figure 303: Preview the effective data set In this dialog you can update the effective data set from the data file or database by pressing the green marked button labeled Refresh. You can also export the effective data set to a CSV file by pressing the red marked button, labeled Export CSV.
Kind of Data Connectors

In the following chapters you will learn how to create the different types of data connectors and add them to an existing test case. To do so, select the desired test case and open the data source dialog as described in Creating Test Data. In this dialog choose one of the following data connector types from the combo box labeled New.
Simple Data Table CSV File SQL Connector Excel File
225
Data Connectors
Simple Data Table

This Data Connector allows you to easily generate a data table. After adding this type of data connector you can enter a name for the data table by clicking on the blue area and adding a text value and add new columns and rows by clicking on either the red marked area for columns or the green marked area for rows and adding a text value.
Figure 304: New created simple data table
226
Data Connectors
Figure 305: Add new test data directly to a table of type Simple Data Connector
227
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.
Figure 306: Set up CSV file as external 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.
228
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.
Figure 307: Set up SQL connector - main dialog
Create Connection String

By pressing the red marked Create button in the data source management dialog the connection properties dialog will be opened.
229
Data Connectors
Figure 308: SQL connector - Connection Properties dialog 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.
230
Data Connectors
Figure 309: SQL Query Designer used to create SQL queries 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.
231
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.
Figure 310: Create new Excel file connector
232
Instrumentation Wizard
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
Figure 311: Start Instrumentation Wizard from Ranorex Tools Menu
233
Figure 312: Start Instrumentation Wizard from Technology Limitation
Figure 313: Start Instrumentation Wizard from installation folder 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.
234
Figure 314: Instrumentation Wizard
Running Instrumentation Wizard from the Command Line

Using the following arguments, you can execute the Instrumentation Wizard from the command line. This is required for automated command line based instrumentation. 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.
Note: The default Select is not supported in the command line.
?|help:
Default is False. Displays command line arguments help.
Pagename specific arguments:

android d|device: Required. The name of the device that the APK file should be deployed to. 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.
235
dm|deploymode: Possible Values: WiFi, Usb, NoDeploy. Default is WiFi. Specifies how the apk file will be deployed. Set to NoDeploy if the file should not be deployed to the device. chrome a|activate: Required. Enable this switch to activate the Chrome browser addon. If the switch is disabled the addon will be deactivated. firefox a|activate: Required. Enable this switch to activate the 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: Required. Enable this switch to enable Internet Explorer Flash debug player installation. If the switch is disabled Internet Explorer Flex debug player will not be installed. o|others: Required. Enable this switch to enable Firefox/Chrome/Safari Flash debug player. If the switch is disabled FireFox/Chrome/Safari Flash debug player will not be installed. ft|flextrace: Default is False. Enable this switch to enable the flash tracelog. If the switch is disabled flash trace log will be deactivated. ios u|udid: Required. The unique device identifier for the device where the application should be installed. ip|inputpath: The path to the application archive (*.ipa). ai|appid: The application Id (bundle identifier of the app). This is required so that an application can be uninstalled prior to installing the new archive. java jp|javapath : Required. System path to the JRE that shall be instrumented. e|enable: Default is True. Tells Ranorex if the instrumentation shall be enabled or disabled. safari a|activate: Required. Enable this switch to activate Safari browser addon. If the switch is disabled the addon will be deactivated.
236
Java AWT/Swing
The Java AWT/Swing technology limitation will pop up if your Java installation or application is not instrumented correctly.
Figure 315: Java AWT/Swing Technology Limitation The Instrumentation Wizard tries to add the Plug-In specific files to the Java Runtime Environment (JRE) of your choice and to activate the Java Plug-In for Ranorex. You have 3 different choices:
Select a JRE from a list of running Java applications: Here you can choose the Java runtime based on the application you want to instrument. This is the preferred method, as you can determine exactly which Java runtime is being used by your application under test. Select a JRE from a list of installed Java runtimes: Here you can choose the Java Runtime Environment you want to be instrumented from a list of all installed Java runtimes on your machine. Specify a custom Java runtime directory: Here you can specify the folder holding the Java runtime you want to be instrumented.
237
Figure 316: Java Instrumentation Wizard After activating the Java AWT/Swing instrumentation, Ranorex will not be limited in recognizing UI elements of your Java application. Restart your application under test and your Ranorex tools to ensure that the newly added instrumentation works correctly.
Figure 317: Finished Java Instrumentation If you are using Windows XP SP2, please also make sure that the Windows Update KB884020 is installed, which resolves problems with the local network communication. If the activation of the Java Plug-In was not successful, please make sure that you have installed Ranorex correctly, that you have chosen the right directory of your JRE, and if you have started the Instrumentation Wizard from the bin folder that it has been started with admin rights.
238
Figure 318: Failed Java Instrumentation
239
Adobe Flash/Flex
The Flash/Flex technology limitation will pop up if your Flash/Flex application is not instrumented correctly.
Figure 319: Flash/Flex Technology Limitation
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 either the Flash Debug Player for Internet Explorer or the Flash Debug Player for Mozilla Firefox, Google Chrome and Safari or both Flash Debug Players if you like. Moreover, you can enable the Ranorex Preloader Instrumentation. This allows you in combination with the Flash Debug Player to instrument your application under test without the need to alter your application. Additionally, you can enable logging for the Flash Debug Player. This might be helpful if you have any problems with this kind of instrumentation. In such case you can then simply provide this logging information to our support team.
240
Figure 320: Flash/Flex 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.
Figure 321: Finished Flash/Flex Instrumentation If you still have problems within recognition of Flash/Flex applications, please make sure that your applications are not double instrumented, i.e. make sure that you do not use any Ranorex Library or Ranorex Module within your Flash/Flex application.
Google Chrome
To use the preloader method with Google Chrome, you have to disable the internal Flash Player. This can be done by performing following steps: 241
Open Chromes plugins overview (chrome://plugins/):
Figure 322: Open plug-ins overview

Display the Plug-Ins details:
Figure 323: Plug-In in detail

Disable the internal Flash Player (framed red) and keep the Flash Debug Player (framed green) enabled:
242
Figure 324: Disable the internal Flash Player
243
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.
Figure 325: Mozilla Firefox Technology Limitation 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.
Figure 326: Mozilla Firefox Instrumentation Wizard 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.
244
Figure 327: Finished Mozilla Firefox Instrumentation 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.
Figure 328: Failed Mozilla Firefox Instrumentation 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.
245
Figure 329: Confirm Ranorex Automation Add-On installation
246
Google Chrome
The Chrome technology limitation will pop up if the Ranorex Extension for the Chrome Browser is not installed or enabled.
Figure 330: Google Chrome Technology Limitation The Instrumentation Wizard tries to activate the Google Chrome Extension when checking the checkbox Activate Google Chrome Addon and tries to deactivate the Extension when unchecking the mentioned checkbox.
Figure 331: Google Chrome Instrumentation Wizard 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.
247
Figure 332: Finished Google Chrome Instrumentation 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.
Figure 333: Failed Google Chrome Instrumentation If you still get a limitation when tracking web elements, please assure that the Ranorex Automation Extension is enabled in the Chrome Extensions settings (chrome://settings/extensionSettings).
248
Figure 334: Enable Ranorex Automation Extension If you have removed the Ranorex Automation Extension manually, you have to manually re-add the Extension. Therefore you have to open the file RanorexAutomation.crx, which can be found in the binary folder of your Ranorex installation (..\Ranorex 3.2\bin\RanorexAutomation.crx ), in Chrome and install by following the instructions.
Figure 335: Install Ranorex Automation Extension manually
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
Note: If you want to test file URLs, you have to enable Allow access to file URLs for the Ranorex Automation Extension.
249
Figure 336: Allow access to file URLs
Note: if the NotScript Chrome Extension is installed it has to be disabled to allow from point tracking with Ranorex.
250
Apple Safari
The Safari technology limitation will pop up if the Ranorex Extension for the Safari Browser is not installed or enabled.
Figure 337: Apple Safari Technology Limitation 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.
Figure 338: Apple Safari Instrumentation Wizard After activating the Extension, you have to confirm the installation in Safari.
251
Figure 339: Confirm installation of Ranorex Automation Extension 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.
Figure 340: Finished Apple Safari Instrumentation 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.
252
Figure 341: Failed Apple Safari Instrumentation 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).
Figure 342: Enable Ranorex Automation Extension
Note: Testing file URLs with Apple Safari is currently not supported.
Note: Testing cross domain iframe scripting with Apple Safari is currently not supported.
253
Android
To make an Android app automatable by Ranorex, it is necessary to instrument this application using the Instrumentation wizard.
Note: Have a look at Getting Started to learn how to automate Android applications.
Figure 343: Android instrumentation wizard 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 APK under test before deployment can be unchecked. After processing the instrumentation and deploying the instrumented APK file to the selected device, the installation has to be confirmed on the device.
254
Figure 344: Finished Android instrumentation The instrumented APK file can be found at location referenced by the link Open instrumentation File location. After instrumenting the APK file, the app is available in the Mobile Recording section of Record Setting dialog.
Figure 345: Instrumented APK in Record Settings The Ranorex Service App installed on the mobile device shows an overview of instrumented apps installed on the device.
255
Figure 346: Overview of instrumented APKs
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.
256
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 Getting Started to learn how to instrument iOS applications.
Figure 347: Android instrumentation wizard Choose the instrumented IPA file of the app and the device, the app will be deployed to. More information about setting up a mobile device can be found in section Getting Started. To delete the existing version of the app on your device before deploying a new one, check the corresponding check box.
257
Figure 348: Finished Android instrumentation After deploying the IPA file, the app is available in the Mobile Recording section of Record Setting dialog.
258
Figure 349: Instrumented APK in Record Settings
259
Working with 2.X Projects in 3.X Test Suites

In this section you will learn how to use your 2.X recordings and code modules in Ranorex 3.X test cases within the new test suite editor.
Adding 2.X Projects to 3.X Projects Using 2.X Recording Modules Adapting 2.X Data-Driven Recording Modules Using 2.X Code Modules Breaking Changes
Adding 2.X Projects to 3.X Projects

Ranorex 2.X projects are fully compatible (except for the following Breaking Changes) and can therefore be used within Ranorex 3.X test solutions.
1. Create or open a Ranorex Test Suite Project

In order to use your existing modules within a test suite, it is required to create a new test suite project.
2. Make a backup of your existing 2.X project and add it to the Test Suite Project
Figure 350: Add your existing project
3. Confirm that you want to convert your old project
260
Figure 351: Project version mismatch dialog
Using 2.X Recording Modules

Now you are ready to reuse your existing recording modules. You can simply drag and drop items from the module browser into your test cases or you can add new or existing items using the context menu as follows:
Figure 352: Add an existing recording module
Adapting 2.X Data-Driven Recording Modules

The new Ranorex Recorder allows you to add variables without having to write a line of code. The variables can then be bound to action item properties or can be used within a RanoreXPath expression. Please see following section for more information: Lesson 3: Data-Driven Testing You can easily adapt your existing data-driven test recording modules by doing following:
1. Open your recording file and click on the Variables. . . Recorder view
button in the Ranorex
261
Figure 353: Open the recordings variable dialog
2. Add all variables used in your code
Figure 354: Add variables
3. Open the UserCode file of your recording and remove your existing properties 4. Remove the static keyword from your UserCode methods
Now you are able to bind your module variables to a data column or parameter within a test case.
Using 2.X Code Modules

In order to call your existing test methods within the Ranorex test suite editor we recommend to add a code module to your project as follows:
262
1. Select your project in the projects view and click on Add Code Module
Figure 355: Add a new code module
2. Call your method by adding it to the end of the ITestModule.Run() method C#

namespace MyFirstTestProject { // / < summary > // / Description of AddAndDeleteVip . // / </ summary > [ TestModule ( " A73 AB98 -9 CFE -49 D5 - BDA7 - CAE6C614866 " ) ] public class AddAndDeleteVip : ITestModule { public AddAndDeleteVip () { } void ITestModule . Run () { Mouse . DefaultMoveTime = 3 ; Keyboard . DefaultKeyPressTime = 1 ; Delay . SpeedFactor = 1. ; // Call your existing test method Program . ExistingTest () ; } } }
Now you can add your code module to a test case. Please see following pages for more information about code modules:
Creating Code Modules Using Repository within Code Module Accessing Screen Shots within Code Modules Using Variables with Code Modules Using Code Modules within Test Cases
Breaking Changes
A few changes had to be introduced that can break existing Ranorex 2.X projects when updating to Ranorex 3.X. If your automation project does not work any more after updating to 3.X, please see the following list that explains what has changed and how you need to update your project to make it work with 3.X again: 263

The Delay class has been moved from the Ranorex.Core to the Ranorex namespace. If the Delay class cannot be found, you need to include the Ranorex namespace at the top of the file:
C#
using Ranorex ;
VB.NET
imports Ranorex
The IReportLogger interface has been extended. In particular, the signature of the LogText and LogData methods changed and the PreFilterMessages property was added. If you get compile errors after updating stating that your classes do not correctly implement the IReportLogger interface, please update the implementing classes accordingly. See following blog on how to implement the new IReportLogger interface: Customizing Ranorex Reports The tree structure for MSAA elements has changed under certain circumstances and potentially includes more levels and elements now. If you do not want to use the new elements, set the MSAA Filter compatibility level setting in the Plugins tab of the Ranorex settings to V2X. Otherwise, please, update broken RanoreXPaths accordingly. Text nodes which consist only of white-spaces are no longer appended to Mozilla WebElement.InnerText. Please, update RanoreXPaths and validations that depend on this property and fail accordingly. Some Win32 controls in the tree no longer have the role Form, but a more appropriate role instead. If you want Ranorex to not use the new role, set the Win32 Use legacy Form role setting in the Plugins tab of the Ranorex settings to True. Otherwise, please, update broken RanoreXPaths accordingly. Control.Get/SetPropertyValue now use Reflection instead of the ComponentModel. If a property cannot be found, please check that the used name correctly reflects the API name of the property. The ControlNet11 capability is no longer used as the preferred capability for .NET 1.1 controls. As a consequence, the generated path to items with that capability can change (existing paths will still work). With version 3.0.1 Ranorex added basic support for Delphi controls resulting into different RanoreXPaths being generated for many Delphi controls. If you do not want to use the new functionality, set the Win32 Enable basic Delphi support setting in the Plugins tab of the Ranorex settings to False.
264
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 356: 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 Testing of Java Applications Qt Testing Testing of Legacy Applications Testing of SAP Applications General Troubleshooting
265
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.
Using the Ranorex PreLoader OR including the Ranorex Lib into Adobe Flex: Adobe Flex: Load the Ranorex Lib into your Flex applicationinto 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).
How to read/set attributes and styles
Methods for loading the Automation Lib

Depending on your flash/flex application, you can choose to use one of the following flexible instrumentation methods: Using the Ranorex PreLoader 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
How to load the Ranorex Module into your Flash application 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
266
Module swf has to be copied to the web server
The following table shows you the different instrumentation options available for the supported versions of flash/flex:
Flash CS3 PreLoader Automation Lib Module CS4 CS5
Flex 3.X 4.X
AIR* 2.X 3.X
* Support for Adobe AIR 2 Release in combination with Flex 3.5 and Flex 4 Release = supported = recommended
Test Automation of Flash/Flex controls with Ranorex

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.
Figure 357: Test Automation of Flash/Flex Applications
How to read/set attributes and styles

You can read/set common attributes (e.g. the checkstate of a checkbox) directly by using the adapter as follows: 267
// Set the checked state with the property " Checked " repo . FlexTestPageDom . CheckBox_Control_Example . CheckBoxEggs . Checked = true ;
To access custom attributes and styles, you first have to load your Flex item as a FlexElement in order to read your attributes. Heres an example:
// Load the slider as a Flex element to access flex attributes FlexElement sliderFlex = repo . FlexTestPageDom . ContainerHSlider_Control . SliderHSlider . As < flexelement >() ; sliderFlex [ " value " ] = " 1 " ; FlexElement containerFlex = repo . FlexTestPageDom . Self . FindSingle ( " .// container [ @caption = Tree Control ] " ) ; containerFlex . SetStyle ( " borderColor " ," # ee "); </ flexelement >
Using the Ranorex PreLoader

Please use the Adobe Flash/Flexto enable the PreLoader method on your machine.
Figure 358: Flash/Flex Instrumentation Wizard The wizard will execute following steps for you: 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 and Windows 8 x64)and Firefox/Chrome/Safari. 2. Open your user profile directory %UserProfile%, e.g. by opening Windows Explorer and copying the string %UserProfile% into the address bar. 3. Create a new file called mm.cfg in your user profile directory and insert the following line of code, where C:\FlashFlex\RanorexAutomation.swf needs to be replaced by the preloader location of your Ranorex installation: PreloadSwf= C:\Program Files\Ranorex X.X\Bin\RanorexAutomation.swf Additional to this configuration entry you can enable the logging mechanisms of the Adobe Debug Flash Player, which might be helpful if you have any problems with this kind of instrumentation. In such a case you can then
268
simply provide this logging information to our support team. To enable logging you have to add the following line of code to your mm.cfg file: TraceOutputFileEnable=1 This additional configuration entry forces the Debug Player to create a log file at following location: C:\Users\username\AppData\Roaming\Macromedia\Flash Player\Logs 4. If you run your application from the local drive, add your output directory to the trusted locations of Flash Player as follows: (a) Open following link http://www.macromedia.com/support/documentation/en/flashplayer/help/settings manager04.html#119065 (b) Add your project output directory
Adobe Flex: Load the Ranorex Lib into your Flex application
1. Start Adobe Flex Builder and open your workspace 2. Right-click on your project and choose Properties 3. Under Flex Compiler add theRanorexAutomation.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 / RanorexAutomation . swc "
4. Append following code to your applicationCompleteHandler function:

import Ranorex . RxAutomation ; RxAutomation . Init () ;
5. Save and compile your application 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
Adobe Flash: Load the Ranorex Lib into your Flash application
1. Start Adobe Flash CS4/CS5 and open your application 2. Open the Publish Settings dialog (File->Publish Settings) 3. Include the Ranorex Flash Library in your Flash application under Flash->Script->Settings. . . ->Library Path and choose Browse to SWC file 4. Select RanorexAutomation.swc file in the browse dialog (RanorexAutomation.swc is located in the Bin directory of your Ranorex installation) 5. Insert following code to your ACTIONS (by pressing F9):
import Ranorex . RxAutomation ; RxAutomation . InitFromApp ( stage ) ;
OR add the code to your ActionScript source file as follows:
269
import import import import import import // Add import public {
mx . controls .*; flash . events .*; flash . display .*; flash . ui . Keyboard ; flash . geom . Rectangle ; fl . events . SliderEvent ; Ranorex library Ranorex . RxAutomation ; class Simple extends MovieClip public function Simple () { // Add to your constructor RxAutomation . InitFromApp ( stage ) ; }
6. Run your application in a supported browser (Internet Explorer, Firefox, 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
How to load the Ranorex Module into your Flash application

1. Start Adobe Flash CS3/CS4/CS5 and open your application 2. Insert following code to your ACTIONS (by pressing F9): 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) 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
How to load the Ranorex Module into your Flex/AIR application

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
270
Testing of Java Applications

The Ranorex Java Plug-In allows testing of Java Swing and Java AWT applications. You can setup the Java Plug-In for your application manually or you can walk through the Java AWT/Swing.
Figure 359: Java Instrumentation Wizard If you are using Windows XP SP2, please also make sure that the Windows Update KB884020 is installed, which resolves problems with the local network communication. Manual Setup of Ranorex Java Plug-In 1. First of all close all Ranorex Tools. 2. Now you have todetermine the path of your active Java runtime Environment to know where to copy the necessary files to. Open the Java Runtime Environment Settings which can be found in Java Control Panel (Control-Panel -> Java). There you can see the path of your Java Runtime Environment. If you have more than one Java Runtime Environment installed on your machine, check which one will be used to execute your Java applications by determining which one is activated. 3. After identifying the path you have to copy each of the following files to its corresponding directory based on the root folder of your java runtime installation (e.g. C:\Program Files (x86)\Java\jre6\). The given files are located in the Ranorex installation folder (e.g. C:\Program Files\Ranorex 3.2\Bin)
accessibility.properties to \lib RanorexAutomation.jar to \lib\ext JavaHelper32/64.dll to \bin
After restarting you Java application you should be able to use the Ranorex for your Java application under test.
271
Qt Testing
The Ranorex Automation Framework fully supports test automation of Qt based applications. To ensure that Ranorex can access UI elements and properties in the Qt application, MSAA (Microsoft Active Accessibility) support for your Qt application must be enabled. 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). Loading Accessible Plug-in for your Qt application: 1. Copy the accessibledirectory(and all its contents)from the Qt SDK (used to build the application under test) installation folder to the folder of the automated application (e.g. Program Files/Your-Application/plugins). If you do not have access to the Qt SDK which the Qt application is developed with, please contact the developer of the application and request the accessible directory from him. 2. 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
Figure 360: Without Accessible Plug-in
272
Figure 361: With Accessible Plug-in
273
Testing of Legacy Applications

For some older technologies like VB6.0, Delphi or MFC based applications, Ranorex has only limited support in addressing UI elements in a robust way. With the GDI RawText Plug-In Ranorex increases object recognition for controls which use the Windows GDI drawing mechanism to display text on screen.
Add Class or Process to GDI Capture List

By default the Ranorex GDI Plug-In is not activated. Use the Ranorex Spy tool to activate the Plug-In for a specific control.
Figure 362: Add class name to GDI capture list The pictures below show the different object recognition for a MFC-based menu bar control before and after GDI activation.
274
Figure 363: Before . . .
Figure 364: . . . and after GDI activation You can also add a process name to the GDI capture list by right-clicking on the parent form element of a control in the Ranorex Spy tree.
Remove Classes or Processes from GDI Capture List

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.
275
Figure 365: 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.
276
Testing of SAP Applications

To provide access to SAP GUI windows and elements, SAP Scripting support needs to be enabled in SAP GUI.
Enable SAP Scripting Support

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.
Figure 366: SAP GUI options dialog SAP support is not included in the Ranorex standard developer licenses. sales@ranorex.com for further details. Please contact our sales team at
277
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 Silverlight Flash/Flex Applications Win32 Based Applications Browser (Mozilla Firefox, Google Chrome, Apple Safari) Image Related Automation or Validation Geometry Related Issues Windows Apps (aka Windows 8 UI Apps) Other Software
.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 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.
278
Reason #4: The controls that cannot be identified are implemented in an assembly that targets a particular platform/processor and the automating executable targets a different platform/processor. This can cause problems on 64 bit operating systems, since such assemblies cannot be loaded by the automating process. Solution: Try changing the Target 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 #5: The .NET Framework 4.0 Extended package is needed but not installed. An indication for this problem typically is that controls can correctly be identified by the standalone Ranorex Spy application, but not by the integrated Ranorex Spy or Recorder in Ranorex Studio.The application under test uses the .NET Framework 4.0 and you may get Technology Limitation pop-ups saying that specific assemblies cannot be loaded. Solution: Either install the .NET Framework 4.0 Extended or if that is not possible always use the standalone Ranorex Spy and Recorder tools instead of the integrated ones in Ranorex Studio. Reason #6: If the application under test is built with the .NET Framework 4.0, a <executableName >.exe.config file (where <executableName > has to be replaced by the name of the Ranorex executable) needs to reside in the same folder as the automating Ranorex executable and it needs to contain the configuration below. Solution: 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 useLegacyV2RuntimeActivationPolicy = " true " > < supportedRuntime version = " v4 . " / > < supportedRuntime version = " v2 . .5 727 " / > </ startup > </ configuration >
.NET Silverlight
Ranorex is not able to access UI objects inside your Silverlight application. Solution: Please make sure that the Windowless property of your Silverlight application is set to False.
Flash/Flex Applications
After activating the Flash/Flex Plug-In for your application using the instrumentation wizard Ranorex is still not able to recognize Flash/Flex elements within your application.
279
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.
Win32 Based Applications

There might be several reasons for limited support of Win32 based applications: 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: Please contact Ranorex support team for further assistance. 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: Enable the 32/64 Bit Bridge in the General Ranorex Settings.
Browser (Mozilla Firefox, Google Chrome, Apple Safari)

Mozilla Firefox: UI element identification capabilities for Mozilla Firefox are limited. Solution:Please make sure that you have installed and enabled the Ranorex Addon in your Mozilla browser. Please 280
refer to the Mozilla Firefox for more information. Google Chrome: UI element identification capabilities for Google Chrome are limited. Solution:Please make sure that you have installed and activated the Ranorex Extension in your Goggle browser. Please refer to the Google Chrome for more information. Apple Safari: UI element identification capabilities for Apple Safari are limited. Solution: Please make sure that you have installed and activated the Ranorex Extension in your Apple browser. Please refer to the Apple Safari for more information.
Image Related Automation or Validation

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.
Geometry Related Issues

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.
Windows Apps (aka Windows 8 UI Apps)

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: Ranorex is not installed in a secure location. Solution: Install Ranorex to Program Files or Program Files (x86). Reason #3: The test executable is not started by a Ranorex Tool. 281
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 . IsRestartRequiredForWinAppAccess ) return Ranorex . Core . Util . RestartWithUiAccess () ;
VB.NET
If Ranorex . Core . Util . IsRestartRequiredForWinAppAccess Then Return Ranorex . Core . Util . RestartWithUiAccess () End If
Other Software
Running some antivirus or security software might lead to a limited object recognition with Ranorex tools. Reason #1: The antivirus or security software blocks certain Ranorex functionality. Solution: Add an exception for the appropriate Ranorex process or temporarily switch off the specific security application.
282
RanoreXPath
RanoreXPath
A RanoreXPath expression is primarily used to uniquely identify UI elements within a desktop or web application. Generally, a RanoreXPath expression consists of:
Adapters Attributes and Values
Figure 367: Main components of a RanoreXPath expression The adapter type specifies the type or classification of a UI element to search for (button, form, text field, listbox, etc.). Looking at the first part of the RanoreXPath expression /form[@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.
Figure 368: Hierarchical structure of a 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.
283
RanoreXPath
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 . . . ).
In this section you will learn more about RanoreXPath:

RanoreXPath Syntax Examples Advanced RanoreXPath Example RanoreXPath with Regular Expressions
RanoreXPath Syntax Examples

Each RanoreXPath can return multiple GUI elements which match the path query. RanoreXPath is modeled on W3C XPath .
Axes /form/button ./button //button .//button ../button absolute path identifying all buttons that are children of a form relative path identifying all buttons that are children of the current element identifies all buttons that are descendants of the root element, i.e. all buttons in all levels of the element tree identifies all buttons that are descendants of the current element, i.e. all buttons in the subtree of the current element identifies all buttons that are descendants of the parent of the current element optional location step fitting a container adapter between form and button; identifies both, /form/container/button and /form/button optional location step fitting every adapter between form and button
/form/container?/button
/form/?/button
Attributes /form /form[@title=Calculator] /form[@title=Calculator and @instance=2] /form[@title=Calculator or @class=SciCalc] /form/button identifies a top level application identifies a top level application with the title Calculator identifies a top level application with the title Calculator and an attribute of instance with value two identifies a top level application with the title Calculator or by its class identifies a button in the application 284
RanoreXPath
/form/button[2] /form/button[-2] /form/button[@text=7] /form/button[@text!=7] /form/button[@text7] /form/button[@text!7]
identifies the second button in the application identifies the second-to-last button in the application identifies a button with a text attribute value of 7 identifies a button with a text attribute value that is not 7 identifies a button using a RanoreXPath with Regular Expressions identifies a button not matching a RanoreXPath with Regular Expressions identifies a WinForms control using cascaded attribute names. The identified control has an Items property that has a Count property which returns the value 100 identifies any element with a text attribute value of 7 optional location step fitting a container adapter between form and button; identifies both, /form/container[@caption=Container 1]/button and /form/button identifies button with any attribute containing the substring add (case-insensitive) identifies a button where the attribute text is not null identifies a progress bar with value greater than or equal 13.5 (following comparison operators are also available: >, <=, <) identifies a top level application with title attribute value set to value stored in variable $var identifies the button with index equals the value stored in the variable $var identifies an input element on a web document with unique id search (supported for web testing)
/form/control[@items.count=100] /form/*[@text=7] /form/container?[@caption=Container 1]/button
/form/button[?add] /form/button[@text!=null()] /form/progressbar[@Value>=13.5]
/form[@title=$var] /form/button[$var] /dom//input[#search]
Functions /form/table/row/cell[first()=True] /form/table/row/cell[last()=True] /form/table/row/cell[index()=2] /form[x()>100 and y()>100] /form/button[cx()>10 and cy()>10] /form[width()>100 and height()>100] identifies the first cell of a row identifies the last cell of a row identifies the second cell of a row identifies a top level application with screen coordinates greater than 100 identifies a button with client coordinates (coordinates of an element relative to its parent) greater than 10 identifies a top level application with width and height greater than 100.
285
RanoreXPath
Advanced RanoreXPath Example

The following example describes how to use RanoreXPath to identify a GUI element not having unique attributes. The example shows how to access a HTML checkbox using a relative RanoreXPath expression. Each row in the table represents a user. The users attributes are mapped into separate cells. 1. Identify a user from a list by name (highlighted green)
/ table /*/ tr / td / a [ @InnerText = Username ]
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.
Figure 369: Advanced RanoreXPath example
RanoreXPath with Regular Expressions

button[@textsample[ -9]] listitem[@textsample.*] listitem[@text.*sample$] listitem[@textgr(a|e)y] listitem[@textsample\ 123$]
matches the following button elements: sample0, sample1, . . . sample9, My sample26 matches all elements starting with text value sample matches all elements ending with text value sample matches text value gray or grey matches sample 123 (use backslash to escape special characters like space) matches the regular expression case-insensitive, e.g. mytext, MYTEXT, mYTeXT, . . . 286
listitem[@text(?i:MyTeXt)]
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\..
287
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 the remaining characters within brackets from matching the target string. The expression [0-9] indicates that the target character must not be a digit.
? () []
[ -9]
For additional information on regular expressions please consult the corresponding MSDN web site: http://msdn. microsoft.com/en-us/library/az24scfc.aspx
288
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.
Figure 370: Properties of a Ranorex Text Adapter
289
Ranorex UI Adapter
Figure 371: Properties of a Ranorex TreeItem 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
The following example accesses properties of a Ranorex TreeItem adapter:
C#
290
Ranorex UI Adapter
// Create TreeItem adapter from RanoreXPath TreeItem treeItem = " / form [ @title = TreeView Test ]/?/?/?/ treeitem [ @text = TreeItem ] " ; // Collapse and expand tree item if ( treeItem . Expanded ) treeItem . Collapse () ; else treeItem . Expand () ;
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
Multiple Adapters for one GUI element

In addition to the Ranorex standard adapters which represent the logical view of a UI element, Ranorex provides technology-specific adapters with more information. As an example the Ranorex WinForms Plug-In is able to provide more information about a simple button in a .NET application. This additional information is provided via an additional adapter called Control. The following screenshots compare the information shown by Lesson 9: Ranorex Spy for a Win32 and a WinForms button:
291
Ranorex UI Adapter
Figure 372: Button of calculator application which provides a Ranorex Button and a Ranorex NativeWindow Adapter
292
Ranorex UI Adapter
Figure 373: Button of a .NET WinForms application which provides an additional Ranorex Control adapter
293
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 winFormsButton = new Ranorex . Control ( button ) ; // Call GetPropertyValue method provided by the Control adapter Color color = winFormsButton . 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 winFormsButton As New Ranorex . Control ( button ) Call GetPropertyValue method provided by the Control adapter Dim color As Color = winFormsButton . GetPropertyValue ( Of Color ) ( " BackColor " )
It is not required to work with Ranorex adapters. 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.
294
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 Record your Android test Run your test on any Android device
Infrastructure
Before getting started with Android test automation, its necessary to make sure that the system under test (the mobile devices) and the machine running the tests (where Ranorex is installed) are in the same network.
Figure 374: Automated Android app testing over Wi-Fi As the recording and executing of tests is processed via the network, there is no need for an USB connection between the system under test and the machine running the test. But it is recommended to have your system under test plugged into a power supply during test recording and execution.
Note: To automate on a device connected via USB instead of Wi-Fi, have a look at Add a device connected via USB.
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. 295
Android Testing
Start your first recording by pressing the record button in Ranorex Recorder. Next to starting a Global Recording, Run an Application or Open a Browser it is also possible to start a Mobile Recording.
Figure 375: Record Settings dialog
Add Device
Open the Manage Device dialog by pressing the Devices button from the Record Settings dialog. If no devices have been added yet, the Add new Device dialog will be shown. Choose Android and follow the instructions to install the Ranorex service on your Android device.
Figure 376: Add Android device
296
Android Testing
Figure 377: Install Service App 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.
297
Android Testing
Figure 378: Installation of the Ranorex Service app
Figure 379: using the QR code
298
Android Testing
Note: If you have more than one user account activated on your Android device, make sure hat 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). Type adb devices to connect your device followed by typing adb install <Download Folder>/<Name of App>.apk to install the 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 choosing Network as device connection, selecting your discovered device and clicking on the Add button.
Figure 380: Choose device type/connection
299
Android Testing
Figure 381: Add Android device 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.
300
Android Testing
Figure 382: Added Android device
Instrument and Deploy your Android App

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.
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: Make sure to have JRE 1.6 installed on your machine as this is requested by the system requirements of Android SDK.
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. After choosing a device to deploy and an APK file to instrument, the process will be started by pressing the Next button.
301
Android Testing
Figure 383: Android Instrumentation Wizard After the instrumentation of the APK file, it will be automatically deployed to the selected device.
Figure 384: Successfully finished instrumenting and deploying APK To finish the instrumentation and deployment process, the installation has to be confirmed on the mobile device.
302
Android Testing
Figure 385: Confirm installation of instrumented APK
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.
Record your Android test

After preparing the device and instrumenting the APK, the recording can be started by choosing the device on which the test should be executed and the app which should be tested.
Figure 386: Mobile Recording with chosen device and app By pressing the Start button, the instrumented app will be automatically started on the mobile device and a notification on the desktop will inform the user, that actions will be recorded directly on the mobile device.
303
Android Testing
Figure 387: Record notification During the recording process, the action table of the Ranorex Recorder will give a good overview over the performed steps, as the table is updated live.
Figure 388: Action table updates during recording process
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.
304
Android Testing
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.
Figure 389: Select element to validate After choosing an element, the Validate Element dialog will pop up. In this dialog, the attributes which should be validated can be selected.
305
Android Testing
Figure 390: Choose attribute to validate 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.
Figure 391: Adding actions manually After recording and adding actions manually, the action table might look something like the following.
306
Android Testing
Figure 392: Action table Action #1 is a Run Mobile App action which starts the instrumented APK file on the selected device. Action # 2 is a Touch Event on a button. There are 5 different kinds of touch events recognized by Ranorex:
a normal Touch which is equivalent to a mouse click on a desktop machine, a Long Touch which typically opens a context menu and Touch Start, Touch Move and Touch End for simulating a drag gesture.
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. 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.
307
Android Testing
Figure 393: Stop recording
Run Test
After recording and altering the action table, the test can be executed on the mobile device by pressing the Run button.
Run your test on any Android device

We will show you how easy it is to run your Android test on any device. Therefore add another device and instrument and deploy the application under test, as described earlier in this chapter.
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 394: 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.
308
Android Testing
Figure 395: 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.
Figure 396: Open data source dialog. . .
309
Android Testing
Figure 397: Add a simple data table. . .
Figure 398: And add the device names to the simple data table
310
Android Testing
After doing so, switch to the Data Binding tab and bind the data source to the variable in your recording.
Figure 399: Bind the data source to the variable 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.
Figure 400: Successfully executed test on two devices
Run Tests in parallel

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.
311
Android Testing
Figure 401: Disable data source Add a global parameter and bind it to the variable varMobileDevice.
312
Android Testing
Figure 402: Add global parameter
Figure 403: Bind variable to global parameter 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.
313
Android Testing
Figure 404: Open advanced RanoreXPath editor Additional to the title add the device name to the RanoreXPath and choose the variable varMobileDevice as value.
Figure 405: Add variable device name to RanoreXPath 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: start MobileTest.exe /pa:globalMobileDevice=Galaxy Nexus start MobileTest.exe /pa:globalMobileDevice=GTP7500
314
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 a device manually Add an emulator Add a device connected via USB Show device information
Add a device
The Manage Device dialog can be opened from the Devices pane or from the Record Settings dialog. If no devices have been added yet, the Add new Device dialog will be shown. Choose Android and follow the instructions to install the Ranorex service on your Android device.
315
Android Testing
Figure 407: Install Service app 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.
316
Android Testing
Figure 408: Installation of the Ranorex Service app
Figure 409: using the QR code
317
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 choosing Network as device connection, selecting your discovered device and clicking on the Add button.
Figure 410: Choose device type/connection
Add a device manually

Add a physical device manually 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 pressing the Details button.
318
Android Testing
Figure 412: Ranorex Service app details view
Figure 413: Add mobile device manually
319
Android Testing
After adding a device, it is available within the Manage Devices dialog.
Figure 414: New added device 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.
320
Android Testing
Figure 415: Choose Emulator
Figure 416: Select the emulator
321
Android Testing
Figure 417: Set a readable name
Add a device connected via USB

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.
Figure 418: Choose USB
322
Android Testing
Figure 419: Select the USB connected device
Figure 420: Set a readable name
Show device information

If a device is no longer reachable, it will be marked with a red x-sign. By moving your mouse over the device, a tooltip will appear, giving detailed information about the problem.
323
Android Testing
Figure 421: Failed to connect to mobile device
324
Android Testing
Troubleshooting
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. 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.
Figure 422: Devices details

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.
325
Android Testing
Figure 423: Set device name

If you have problems with instrumenting your APK using the instrumentation wizard have a look at the Instrumentation with Source Code section.
326
Android Testing
Instrumentation with Source Code

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 . RanorexAndroidAutomation . Hook ( this ) ; } @Override public void onPause () { super . onPause () ; com . ranorex . android . RanorexAndroidAutomation . UnHook ( this ) ; } @Override public boolean dispatchKeyEvent ( android . view . KeyEvent event ) { com . ranorex . android . RanorexAndroidAutomation . Key ( event ) ; return super . dispatchKeyEvent ( event ) ; }
3. Add permissions to your manifest file (if not already in place): XML
< uses - permission android:name = " android . permission . INTERNET " / > < uses - permission android:name = " android . permission . INJECT_EVENTS " / >
4. Add the actual Ranorex version number in the manifest so your app is found by the Ranorex service app. Alter following code: XML
< manifest xmlns:android = " http: // schemas . android . com / apk / res / android " package = " YOUR PACKAGE " android:versionCode = " YOUR CODE VERSION " android:versionName = " YOUR VERSION NAME " >
To: XML
< manifest xmlns:android = " http: // schemas . android . com / apk / res / android " package = " YOUR PACKAGE " android:versionCode = " YOUR CODE VERSION " android:versionName = " YOUR VERSION NAME ( RxInstrumented $ < RANOREX - VERSION >) " >
Note: Insert the actual Ranorex version instead of <RANOREX-VERSION>.
327
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 how to automate mobile applications using Ranorex (RXMiniKeePass.zip).
Infrastructure Getting Started Record your iOS Test Run your test on any iOS device Testing of mobile web sites
Next to native iOS apps, its also possible to automate mobile web testing directly on your iOS device or simulator. For more information on how to get started with mobile web testing, have a look at the section Testing of mobile web sites.
Infrastructure
Before getting started with iOS test automation, its necessary to choose the connection type fitting to your needs. The following overview helps you to find out which connection type works best for you. Record USB (debug mode) USB WiFi Replay Start/Stop App Install IPA Deploy (unattended)
Note: To make an iOS app testable with Ranorex, it is necessary to instrument the app using Xcode on a Mac for all three connection types as described later. When choosing USB Debug Mode as connection type, Xcode is also necessary once for bringing the device into debug mode. Choosing the connection type WiFi, the application under test has to be deployed via Xcode on a Mac.
Using the USB debug mode allows you to start and stop the application under test on the device. This is required when following the continuous integration approach.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. Network Requirements: When choosing WiFi as connection type, it is recommended to 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 in the same network.
Getting Started
This quick start guide will show you how easy it is to record your iOS test and execute the test on different iOS devices. 328
iOS Testing
Prepare your iOS device

Its recommended to disable the Auto-Lock functionality during your test executions. To do this, start the Settings app, open the General settings, choose Auto-Lock settings and set Auto-Lock to Never.
Figure 424: Disable Auto-Lock
Instrument and Deploy your iOS app

First of all you have to instrument your iOS app. This can be done by either following the video instructions or by following the textual description below.
329
iOS Testing
Figure 425: Open XCode project and add new target
Figure 426: Add needed libraries to XCode project
330
iOS Testing
Figure 427: Modify linker flags and build project

Download the automation lib (libRxAutomationUni 410.a) on your Mac. Open the XCode project of your application under test.
Figure 428: Open *.xcodeproj file

In order to not ship an instrumented app to your customers it is recommended to create a separate target for your app under test. Therefore select the project file and duplicate the existing target.
331
iOS Testing
Figure 429: Duplicate target

Rename the newly created target.
Figure 430: Rename duplicated target
Note: As XCode does not automatically update all necessary files, you have to rename them manually. You 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.
332
iOS Testing
Figure 431: Add new file to project
333
iOS Testing
Figure 432: Choose the lib file and specify the target, the lib will be added to
334
iOS Testing
After doing so, the automation lib will be listed in the Linked Binary With Libraries list in the Build Phases pane of the test target.
Figure 433: Added automation library

Add the CFNetwork framework to the list.
335
iOS Testing
Figure 434: Add CFNetwork.framework
Figure 435: Added automation lib and network framework
336
iOS Testing
In the Build Settings pane of the test add the switches -ObjC -all load to the option Other Linker Flags.
Figure 436: Set the switches -ObjC and -all-load 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.
Figure 437: Successfully instrumented app
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 get banned from submitting apps to the app store for a period of time.
337
iOS Testing
Note: To add your device via WiFi its necessary that the application under test is started on your iOS device or simulator.
Note: To improve the object recognition of your app under test set the accessibility label attribute of your controls.
Debug Mode: In order to enable starting and stopping of the application under test on the device, it is necessary to establish a debug session. This can be accomplished by simply deploying any app to the device in debug scheme from Xcode. As long as the device is not restarted, the debug session will remain alive.
Note: Only one debugger can be attached at the same time. If you have problems with the debugger session, please try to close all opened apps. If closing all apps does not help, restart the device and establish a debug session again, as described above.
Figure 438: Deploy from Xcode to start debug session In order to deploy the application under test from a Windows machine its required to use a USB connection. The app has to be built on a Mac and archived as iOS App Store Package (IPA) file. Have a look at the section Create an iOS App Store Package to learn how such an IPA file can be created.
Add your iOS device
Note: When using WiFi as connection type, make sure that your iOS device or simulator is reachable over Wi-Fi. Also make sure, that the application under test is started, active and visible on the device or simulator if you do not start the app from a recording (USB debug mode).
338
iOS Testing
Figure 439: WRONG: The app might be started, but is not active
339
iOS Testing
Figure 440: RIGHT: The app is active
340
iOS Testing
Start your first recording by pressing the record button in Ranorex Recorder. Other than starting a Global Recording, Run an Application or Open a Browser, it is also possible to start a Mobile Recording. Open the Manage Device dialog by pressing the Devices button from the Record Settings dialog.
Figure 441: Open Devices dialog Choose iOS (iPhone, iPad) and start your instrumented app on your device.
Figure 442: Choose iOS Choose your preferred connection type.
341
iOS Testing
Figure 443: Choose connection type When choosing USB as connection type, the connected device should be discovered automatically. Choose the device from the list to finish the process.
Figure 444: Add new device If the device cannot be found automatically click the The device isnt listed button. Enter a name of the device and choose the corresponding device serial.
342
iOS Testing
Figure 445: Add device manually When choosing WiFi as connection type, make sure that the app is started and active on the device. 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.
Figure 446: Manually adding device
343
iOS Testing
Figure 447: Added iOS device
Deploy your iOS App (USB connection)

After adding a device, you can deploy the IPA file of your application under test to the device by clicking on Deploy in the new recording dialog and following the instructions as described in section iOS.
344
iOS Testing
Figure 448: Click on deploy button
Figure 449: Choose IPA file
345
iOS Testing
Figure 450: Successfully deployed IPA file
Record your iOS Test

After preparing the device and instrumenting the app, the recording can be started by choosing the device on which the test should be executed and the app which should be tested.
Figure 451: Mobile Recording with chosen device and app By pressing the Start button a notification on the desktop will inform you, that actions will be recorded directly on the mobile device.
346
iOS Testing
Figure 452: Record notification During the recording process, the action table of the Ranorex Recorder will give a good overview over the performed steps, as the table is updated live.
Figure 453: Action table updates during recording process During recording it is possible to add validations using the Validation button. By pressing this button, a dialog will open where the element which should be validated can be chosen.
347
iOS Testing
Figure 454: Select element to validate After choosing an element, the Validate Element dialog will pop up. In this dialog, the attributes which should be validated can be selected.
348
iOS Testing
Figure 455: Choose attribute to validate To automatically start and stop an iOS app, a USB debug session is necessary. To not make your test fail when not running in USB debug mode its recommended to make the Run Mobile App action optional by enabling continue on fail in context menu.
349
iOS Testing
Figure 456: Make Run Mobile App action optional
Figure 457: USB connection with no debug session Reporting
350
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.
Figure 458: Adding actions manually If your device is connected via USB you can additionally 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.
Figure 459: Add Deploy iOS App action After recording and adding actions manually, the action table might look something like the following.
351
iOS Testing
Figure 460: Action Table 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 2 different kinds of touch events recognized by Ranorex:
a normal Touch which is equivalent to a mouse click on a desktop machine, and a Long Touch which can be compared to a right click.
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 #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 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. Action #12 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.
352
iOS Testing
Figure 461: Stop Recording
Run Test
After recording and altering the action table, the test can be executed on the mobile device by pressing the Run button.
Run your test on any iOS device

We will show you how easy it is to run your iOS test on any iOS device. To do so, add a second device as described earlier.First of all convert the Device Display Name value of the Run Mobile App action in a recording variable.
Figure 462: Make the device name value variable After making the device name value variable, open the Data Source dialog of the test case holding your recording and add a new simple data table containing the names of the devices you want to run the test on.
353
iOS Testing
Figure 463: Add a simple data table
Figure 464: Add the device names to the simple data table
354
iOS Testing
After doing so, switch to the Data Binding tab and bind the data source to the variable in your recording.
Figure 465: Bind the data source to the variable Have a look at Lesson 3: Data-Driven Testing if you want to learn more about the data-driven approach of 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 following figure.
355
iOS Testing
Figure 466: Successfully executed test on two devices
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.
Testing of mobile web sites

If you are going to automate web testing on your iOS device or simulator, you can use our already instrumented RXBrowser app. Simply follow the description below:
Download and extract the RXBrowser XCode project (RxBrowser 410.zip) on your Mac. Open the unpacked project with XCode. Clean and build the project. Either deploy the app from Xcode to the device or create an IPA file to deploy it from a Windows machine to the device.
356
iOS Testing
Figure 467: Build and deploy the project to your iOS device or simulator After performing the mentioned steps its possible to access the RXBrowser app as any other instrumented native iOS app. Continue by following the instructions in the Add your iOS device section.
Note: To add your device via WiFi, its necessary that the RXBrowser app is started on your iOS device or simulator.
357
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.
Architecture of Websites in the Ranorex Framework Handling of AJAX Find or filter Web Elements List elements of a table and set css style Cross-Browser Testing Set inputs, tag attributes and perform a click without mouse Recordings & Repositories Execute javascript code Handling of layer menus
Architecture of Websites in the Ranorex Framework

Ranorex is able to access the complete HTML architecture of a web document. Use the Ranorex Spy to analyze the structure and the content of a web application and to see which information is accessible during automation. All open websites are shown as a single Dom node in the spy tree. In addition to standard browser hosted applications, Ranorex is able to see embedded browser objects too (e.g. compiled help files). Additional each tab item within a browser window is presented as a separate Dom node within the spy tree.
Figure 468: Representation of websites
Figure 469: RanoreXPath example 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. 358
Web Testing
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 . WaitForDocumentLoaded () ; // 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 . WaitForDocumentLoaded () Execute a javascript code webDocument . ExecuteScript ( " history . back () ; " )
Find or filter Web Elements

The Ranorex Framework offers a wide range of adapters for each HTML tag elements (e.g.: ATag adapter for <a> tags). Each adapter has specific methods and attributes; the link tag (<a>) for example has additional attributes like HREF, TARGET and REL.
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 ()
359
Web Testing
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.
Automation of browser specific elements (e.g. Pop-Up window)

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 ] " ; 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
360
Web Testing
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
Recordings & Repositories

Lesson 5: Ranorex Recorder provides the same capture and replay functionality, which is used for standard client desktop applications. The recorder automatically creates action items for each recorded user action within the Recorders actions table. The corresponding repositorycontains all required UI web element objects used within the actions table.
Figure 470: Web based recording
Repositories and the WebDocument

The following example shows how to access the methods of the WebDocument using a repository:
361
Web Testing
C#
// Load repository ProjectRepository repo = ProjectRepository . Instance ; // Open a website repo . WebPage . Self . Navigate ( " http :// www . ranorex . com " ) ; // Wait until the document is loaded repo . WebPage . Self . WaitForDocumentLoaded () ;
VB.NET
Load repository Dim repo As ProjectRepository = ProjectRepository . Instance Open a website repo . WebPage . Self . Navigate ( " http :// www . ranorex . com " ) Wait until the document is loaded repo . WebPage . Self . WaitForDocumentLoaded ()
362
Web Testing
Samples
The following web testing examples show how to access typical web elements of a web page.
Handling of AJAX List elements of a table and set css style Set inputs, tag attributes and perform a click without mouse Execute javascript code Handling of layer menus
The Ranorex web site provides a small page especially for web testing purposes: 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)
Figure 471: Ranorex Web Testing reference page
Handling of AJAX
C#
GlobalRepository repo = GlobalRepository . Instance ; WebDocument webDocument = repo . WebPage . Self ; // Fill out the AJAX form InputTag input1 = webDocument . FindSingle ( " .// form [ @id = ajax - form ]/ fieldset // input [ @name = value1 ] " ) ; input1 . EnsureVisible () ; input1 . Value = " Size " ; InputTag input2 = webDocument . FindSingle ( " .// form [ @id = ajax - form ]/ fieldset // input [ @name = value2 ] " ) ;
363
Web Testing
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 1 seconds (1 milliseconds ) PreTag result = webDocument . FindSingle ( " .// div [ @id = ajax_response ]/ div / pre " , 1 );
VB.NET
Dim repo As GlobalRepository = GlobalRepository . Instance Dim webDocument As WebDocument = repo . WebPage . Self Fill out the AJAX form Dim input1 As InputTag = webDocument . FindSingle ( " .// form [ @id = ajax - form ]/ fieldset // input [ @name = value1 ] " ) input1 . EnsureVisible () input1 . Value = " Size " Dim input2 As InputTag = webDocument . FindSingle ( " .// form [ @id = ajax - form ]/ fieldset // input [ @name = value2 ] " ) input2 . Value = " Weight " Dim checkbox As InputTag = webDocument . FindSingle ( " .// form [ @id = ajax - form ]/ fieldset // input [ @name = checkbox2 ] " ) checkbox . Checked = " true " Dim selectColor As SelectTag = webDocument . FindSingle ( " .// form [ @id = ajax - form ]/ fieldset // select [ @name = color2 ] " ) selectColor . TagValue = " blue " Submit data Dim submit As InputTag = webDocument . FindSingle ( " .// form [ @id = ajax - form ]// input [ @id = submit - ajax ] " ) submit . Click () Wait for the ajax request for max 1 seconds (1 milliseconds ) Dim result As PreTag = webDocument . FindSingle ( " .// div [ @id = ajax_response ]/ div / pre " , 1 )
List elements of a table and set css style

C#
GlobalRepository repo = GlobalRepository . Instance ; WebDocument webDocument = repo . WebPage . Self ; // List all elements of a table foreach ( TrTag row in repo . WebPage . DivTagContent . TableTagSimpletable . Find ( " ./ tbody / tr " ) ) { string rowInfo = " " ; TdTag rowNameCell = row . FindSingle ( " ./ td [2] " ) ; rowInfo += " Row index : " + rowNameCell . PreviousSibling . InnerText + " , " ; rowInfo += " Row name : " + rowNameCell . InnerText + " , " ; rowInfo += " Row value : " + rowNameCell . NextSibling . InnerText + " , " ; // Get all cells from the row rowInfo += " All Cells : " ; foreach ( TdTag cell in row . Find ( " ./ td " ) ) { rowInfo += cell . InnerText + " , " ; // Move the mouse to each cell element cell . MoveTo () ; // Set css style cell . SetStyle ( " background - color " ," #33 ff " ) ; } Report . Info ( rowInfo ) ; }
364
Web Testing
VB.NET
Dim repo As GlobalRepository = GlobalRepository . Instance Dim webDocument As WebDocument = repo . WebPage . Self List all elements of a table For Each row As TrTag In repo . WebPage . DivTagContent . TableTagSimpletable . Find ( " ./ tbody / tr " ) Dim rowInfo As String = " " Dim rowNameCell As TdTag = row . FindSingle ( " ./ td [2] " ) rowInfo += " Row index : " & rowNameCell . PreviousSibling . InnerText & " , " rowInfo += " Row name : " & rowNameCell . InnerText & " , " rowInfo += " Row value : " & rowNameCell . NextSibling . InnerText & " , " Get all cells from the row rowInfo += " All Cells : " For Each cell As TdTag In row . Find ( " ./ td " ) rowInfo += cell . InnerText & " , " Move the mouse to each cell element cell . MoveTo () Set css style cell . SetStyle ( " background - color " , " #33 ff " ) Next Report . Info ( rowInfo ) Next
Set inputs, tag attributes and perform a click without mouse

C#
// Use mouse and keyboard to set Name repo . WebPage . TestForm . InputTagTestname . Click () ; Keyboard . Press ( " Test Name " ) ; // Set email address directly via Value repo . WebPage . TestForm . InputTagTestemail . Value = " test@ranorex . com " ; // Open calendar form repo . WebPage . TestForm . ButtonTagCalendar . Click () ; // Select the 22 th of the current month repo . WebPage . TdTag_22nd . Click () ; // Select each item of list box foreach ( OptionTag option in repo . WebPage . TestForm . SelectTagTestmultiple . Find ( " .// option " ) ) { option [ " selected " ] = " selected " ; } // Perform a click without moving the mouse to the button repo . WebPage . TestForm . InputTagSubmit . PerformClick () ;
VB.NET
Use mouse and keyboard to set Name repo . WebPage . TestForm . InputTagTestname . Click () Keyboard . Press ( " Test Name " ) Set email address directly via Value repo . WebPage . TestForm . InputTagTestemail . Value = " test@ranorex . com " Open calendar form repo . WebPage . TestForm . ButtonTagCalendar . Click () Select the 22 th of the current month repo . WebPage . TdTag_22nd . Click () Select each item of list box For Each [ option ] As OptionTag In repo . WebPage . TestForm . SelectTagTestmultiple . Find ( " .// option " ) [ option ]( " selected " ) = " selected " Next Perform a click without moving the mouse to the button repo . WebPage . TestForm . InputTagSubmit . PerformClick ()
365
Web Testing
Execute javascript code

C#
webDocument . ExecuteScript ( " history . back () ; " ) ;
VB.NET
webDocument . ExecuteScript ( " history . back () ; " )
Handling of layer menus

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
366
Source Control
Source Control
Ranorex Studio comes with the integration of the two source control systems Subversion and Team Foundation Server. Have a look at the SVN Book to get more information about Subversion.
Note: Open the Ranorex Options (Tools->Options) to change Subversion settings. With Ranorex 4.0 the setting Automatically add new files is checked by default (which was unchecked by default before).
Figure 472: Subversion settings For further details about Team Foundation Server have a look at the related MSDN site.
Note: 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.
Note: To work with Team Foundation Server as source control system either a Microsoft Visual Studio or a Team Explorer for Microsoft Visual Studio installation is required.
In this chapter you will learn how to

Add a Solution to Source Control Check Out a Solution from Source Control Open an existing Ranorex TFS Solution with Visual Studio Open existing Visual Studio TFS Solution with Ranorex
367
Source Control
Add a Solution to Source Control

There are two ways to add a solution to source control.Either by checking the check box Add to source control in the New Project dialog.
Figure 473: Add a new project to source control Or by right-clicking an existing solution and choosing Source Control -> Add Solution to Source Control in context menu.
368
Source Control
Figure 474: Add an existing project to source control With adding the solution to source control, the Source Control Wizard will be started and you are prompted to choose a source control tool.
369
Source Control
Figure 475: Choose source control provider
Note: If the chosen tool is not installed on your machine, follow the link to download the installation package and install the tool.
Figure 476: SVN not installed
370
Source Control
Figure 477: TFS Provider not installed
SVN
Enter the URL of the repository.
Figure 478: Repository URL Authenticate yourself on the subversion server.
Figure 479: Authentication dialog Choose the folder you want to add your solution to.
371
Source Control
Figure 480: Choose folder Check the files you want to have under source control and uncheck the files you dont want to have under source control respectively.
372
Source Control
Figure 481: Add specific files to source control The chosen files will be added to source control.
Figure 482: Add finished Now, the changes have to be committed to the SVN server.
373
Source Control
Figure 483: Commit changes
Figure 484: Commit finished
374
Source Control
After performing these steps, your solution is under source control and your local copy is up to date.
Figure 485: Solution under source control Icon overlays Normal Conflicted Modified Added Not locally modified, no changes waiting for commit. Indicates a conflict. Modified, changes are waiting to be committed. Marked for addition, waiting to be committed.
TFS
Select your Team Foundation Server.
Figure 486: Connect to a TFS Choose the folder you want to add your solution to.
375
Source Control
Figure 487: Choose folder 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.
376
Source Control
Figure 488: Add specific files to source control After performing these steps, your solution is under source control.
Figure 489: Solution under source control
377
Source Control
Icon overlays Checked In Checked out Checked out Modified Added File under source control, not checked out for editing. File under source control, checked out, not dirty. File under source control, checked out, dirty. File added to project, not checked in.
Check Out a Solution from Source Control

To check out a solution which is under source control already open the Tools menu and click Source Control -> Checkout.
Figure 490: Check out existing solution The Source Control Wizard will be started and you are prompted to choose a source control tool.
Figure 491: Choose source control provider
SVN
Enter the URL of your repository and specify the checkout directory.
378
Source Control
Figure 492: Check out solution The chosen project will be checked out.
Figure 493: Checkout finished
TFS
Specify the local check out directory.
379
Source Control
Figure 494: Select local project path Select your Team Foundation Server.
Figure 495: Connect to a TFS Choose the folder you want to check out from server.
380
Source Control
Figure 496: Choose folder The chosen solution will be checked out.
Open an existing Ranorex TFS Solution with Visual Studio

When opening an existing Ranorex solution which is under TFS source control in Visual Studio, you have to follow the instructions below.
In File menu choose Source Control -> Advanced -> Change Source Control.
381
Source Control
Figure 497: Change source control

Bind the Solution to the server.
Figure 498: Change source control dialog
382
Source Control
Figure 499: Solution bound successfully

Check out to modify in Visual Studio.
Figure 500: Check-out in Visual Studio
Open existing Visual Studio TFS Solution with Ranorex

When opening an existing Visual Studio solution which is under TFS source control in Ranorex Studio, the binding will be done automatically. You only have to add the solution to source control and choose Microsoft Team Foundation Server from Source Control Wizard.
383
Source Control
Figure 501: Add solution to source control
Figure 502: Choose TFS
384
Ranorex Studio IDE
Ranorex Studio IDE

Ranorex Studio is an Integrated Development Environment for .Net framework applications written in C# and VB.Net. Ranorex Studio is based on SharpDevelop, an open source tool. The following paragraphs will explain individual functionality provided by Ranorex Studio:
Create Build Run Adding New Items Solution Explorer Debugging Code Completion Code Conversion Code Navigation Code Generation Refactoring
385
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.
Figure 503: New Project dialog
Ranorex Test Suite
A project holding a Ranorex Test Suite which may contain recordings and code modules. This might be your first choice when starting with Ranorex Studio A project holding recordings and code modules which can be shared and reused A project for creating classes which are used in other applications A project that creates a command line application A project that creates an application with a windows interface
Ranorex Test Suite Module Library Ranorex Class Library Ranorex Console Application Ranorex Windows Application
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.
386
Ranorex Studio IDE
Figure 504: Ranorex Studio
387
Ranorex Studio IDE
Build
After creating your application, it can be built using the Build menu.
Figure 505: 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.
Figure 506: Output window Build Errors and Warnings will be displayed in the Errors window.
Figure 507: Errors window Project specific settings can be defined in the Project Options dialog, which can be accessed from the Project menu.
388
Ranorex Studio IDE
Figure 508: Opening Project Options menu item To name some of these settings, you can set the name or the type of the generated assembly in the Application tab, for example.
Figure 509: Project Options Application tab You can also set the target CPU and framework or the output path in the Compiling tab.
389
Ranorex Studio IDE
Figure 510: Project Options Compiling tab
390
Ranorex Studio IDE
Run
After building the project successfully, it can be executed from the Debug menu either with or without debugger.
Figure 511: Debug menu
391
Ranorex Studio IDE
Adding New Items

Ranorex Studio provides several different templates which can be added to a project either via the Project menu, or within the Project Explorer context menu.
Figure 512: Add new item through Project menu
392
Ranorex Studio IDE
Figure 513: Adding new item through Project Explorer context menu
Figure 514: New File dialog
393
Ranorex Studio IDE
Additional to Ranorex specific files as

Code Module, Module Groups, Recording Module and Repository
programming language specific files like

Class, Interface, Struct and Form
can also be added just the same as

empty resource and 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.
394
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.
Figure 515: Add new folder to a project in solution browser 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.
395
Ranorex Studio IDE
Figure 516: Delete file from project Its also possible to redefine the Start Up Project of a solution.
396
Ranorex Studio IDE
Figure 517: Set project as StartUp project
397
Ranorex Studio IDE
Debugging
Ranorex provides the possibility to debug code directly in the development environment. 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
Figure 518: Add breakpoint

by putting the cursor to the line you want to add a breakpoint, open the Debug menu an choose Toggle Breakpoint.
Figure 519: Toggle breakpoint By setting a breakpoint, a red circle will be added at the margin and the line of code will be highlighted red. The breakpoint can be removed in the same way as it has been added. After setting a breakpoint the debugger can be started by executing your application as described in the chapter Run.
Note: To run an application with debugger, its necessary to not choose Run without Debugger from menu.
398
Ranorex Studio IDE
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: Continue Debugging Stop Process Step Over Step Into Step Out Continues execution Forces the process to stop Executes the statement on the current line but it will not step into Executes the statement on the current line and stops at the first line of code inside the method Finishes executing the current method and returns to its parent method
Figure 520: Debugging menu Items
399
Ranorex Studio IDE
Figure 521: Debugging toolbar items 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.
Figure 522: Context menu Set Current Statement 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.
400
Ranorex Studio IDE
Figure 523: Debug sub menu
Callstack Local Variables
Shows method calls currently on stack. 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 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.
Watch
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.
401
Ranorex Studio IDE
Figure 524: Tool tip
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.
402
Ranorex Studio IDE
Code Completion
Ranorex supports code completion as you type.
Figure 525: Code Completion in Ranorex Further details about how this works can be found in the article Code Completion posted at SharpDevelop Community Blog .
403
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.
Figure 526: Convert the whole project from C# to VB.NET
404
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 .
405
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 .
406
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 .
407
Visual Studio Integration

This example illustrates how to use Ranorex within a simple Visual Studio C# console application. It shows how to create a new Visual Studio C# console application and how to start and automate the Windows Calculator.
Note: The sample works with both Microsoft Visual Studio 2005 and 2008.
Create a new Visual Studio project

Start Microsoft Visual Studio. From the File menu click New Project to open the New Project Dialog. In this example we use C# as programming language. Choose another language if you would like to implement Ranorex code in VB.NET or Visual C++.
Figure 527: Create a new Console Application with Microsoft Visual Studio
Add Ranorex core assemblies as references

Right-click the References folder within the projects Solution Explorer and open the Add Reference dialog. Select the components System.Drawing, Ranorex Core and all Ranorex Plugin-References.
408
Figure 528: Add new references . . .
Figure 529: . . . select System.Drawing and Ranorex.Core
Write some Ranorex automation code

Open the file Program.cs and add following using statement to your existing using section:
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 )
409
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 = ; try { System . Diagnostics . Process . Start ( " calc . exe " ) ; Form form = Host . Local . FindChild < Ranorex . Form >( " Calculator " ) ; form . Activate () ; Button button = form . FindSingle < Ranorex . Button >( " .// button [ @controlid = 132 ] " ) ; button . Click () ; button = form . FindSingle < Ranorex . Button >( " .// button [ @controlid = 92 ] " ) ; button . Click () ; button = form . FindSingle < Ranorex . Button >( " .// button [ @controlid = 133 ] " ) ; button . Click () ; button = form . FindSingle < Ranorex . Button >( " .// button [ @controlid = 121 ] " ) ; button . Click () ; } } catch ( RanorexException e ) { Console . WriteLine ( e . ToString () ) ; error = -1; } return error ;
VB.NET
Dim returnError As Integer = Try System . Diagnostics . Process . Start ( " calc . exe " ) Dim form As Form = Host . Local . FindChild ( Of Ranorex . Form ) ( " Calculator " ) form . Activate () Dim button As Button = form . FindSingle ( Of Ranorex . Button ) ( " .// button [ @controlid = 132 ] " ) button . Click () button = form . FindSingle ( Of Ranorex . Button ) ( " .// button [ @controlid = 92 ] " ) button . Click () button = form . FindSingle ( Of Ranorex . Button ) ( " .// button [ @controlid = 133 ] " ) button . Click () button = form . FindSingle ( Of Ranorex . Button ) ( " .// button [ @controlid = 121 ] " ) button . Click () Catch e As RanorexException Console . WriteLine ( e . ToString () ) returnError = -1 End Try Return returnError
Build and start the application by pressing F5.
410
System Requirements
System Requirements
Supported Operating Systems
All versions (32 and 64 bit, except those for Itanium-based systems) of the following operating systems are supported by Ranorex:
Windows XP Windows Server 2003 (R2) Windows Vista Windows Server 2008 (R2) Windows 7 Windows 8 Windows Server 2012
Software Prerequisites
The following software prerequisites are required to run all Ranorex components (Runtime, Spy, Recorder, License Server). All needed prerequisites are usually automatically installed when running the Ranorex setup:
Microsoft Windows Installer 3.1 or higher Microsoft Visual C++ 9.0 x86 Microsoft Visual C++ 9.0 x64 (required for 64 bit Windows versions only) Microsoft Visual C++ 10.0 x86 Microsoft Visual C++ 10.0 x64 (required for 64 bit Windows versions only) Microsoft .NET Framework 2.0 SP2 or higher
Additionally, for running Ranorex Studio the following prerequisites are required:
Microsoft .NET Framework 3.5 SP1 or higher
Hardware Requirements
The hardware requirements depend on the version of the .NET Framework that needs to be installed for the respective Ranorex package. Ranorex (Runtime, Spy, Recorder, License Server) requires at least the .NET Framework 2.0 to be installed, Ranorex Studio requires the .NET Framework 3.5. 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 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
Ranorex License Server Firewall Configuration

On a system running Ranorex License Server the firewall must be configured to allow access to TCP and UDP port 7266. 411
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. 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.
Figure 530: Task manager showing 64 and 32 bit calculator application 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.
Figure 531: Ranorex Studio - advanced compiler settings
412
Remotely Working with Ranorex

This section will give information on how to successfully record and replay Ranorex Test Scripts on remotely connected machines.
Do not Automate via Remote Desktop Window Do not Close or Minimize the RDP Window Disable Mouse/Keyboard Activities Use same Color and Resolution Settings Increase Timeouts on Virtual Machines Disable Asynchronous Dispatching of Mouse and Keyboard Events
Do not Automate via Remote Desktop Window

The first important thing to know is that Ranorex, as every other automation software, is not able to automate via the Remote Desktop window. It is not possible to recognize any controls since the content of the remote desktop is only provided as one big image. The only way to automate using the Remote Desktop window to work coordinate based or with image comparison. This is not recommended by Ranorex because minimal variances in your system will make your tests fail. To guarantee successfully testing on remote machines, you have to install and start all Ranorex Tools you need on the remotely connected machine.
Do not Close or Minimize the RDP Window

Remote Desktop locks the screen when you minimize or close the Remote Desktop window. That causes screenshots to be blank/black and automation to fail. Consequently, if you use Remote Desktop, you need to have the RDP window open during automation and not closed or minimized. Also make sure that the screensaver is not activated on your remotely connected machine as the screensaver will also lock the Remote Desktops screen. As a workaround, you can set up one machine having all of your Remote Desktop windows opened. This machine does not do any automation. And while your tests are running on the different Remote Desktops with the client windows opened on the mentioned machine you can lock the desktop on this machine. While your client desktop is locked, the Remote Desktop sessions will remain opened and your test will continue. An alternative to RDP is using VNC or the VMWare Remote Console as these tools will not lock the screen when closing or minimizing the remote client window.
Disable Mouse/Keyboard Activities

As an alternative to locking the screen on your Remote Desktop, you can disable the physical mouse and keyboard on the remote machine. To do that just set the Ranorex Keyboard.Enabled and Mouse.Enabled properties to false. Be careful if you disable both keyboard and mouse because both devices will stay disabled until you set the Enabled property back to true or the automation process ends! If you want to disable the input for the whole test cycle, you should set
413
C#
Keyboard . Enabled = false ;
and
C#
Mouse . Enabled = false ;
in the Program.cs file. But again be careful when using these properties because when you set both to false you cannot abort the test without an AbortKey set. So also set
C#
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.
Use same Color and Resolution Settings

If you perform image based automation/validation on remote machines, you have to make sure that color and resolution settings are the same as on the machine you made the test/recording on. 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.
Increase Timeouts on Virtual Machines

Things might run a little slower on a virtual machine compared to real machine because multiple virtual machines may share the same physical host. Consequently it can take more time on a Virtual Machine to find some elements. You may need to increase repository timeouts for specific elements or alter your tests to check for ready states on your application under test. Its recommended to use the global timeout factor to adapt the timeouts for a specific test run.
Disable Asynchronous Dispatching of Mouse and Keyboard Events

Using Ranorex Tools on a remote machine connected with RDP might make the mouse pointer start wobbling sometimes. In that case try to disable the Use asynchronous dispatching of mouse and keyboard events option in the configurations advanced tab page.
414
Figure 532: Use asynchronous dispatching of mouse and keyboard events option This should fix the shaking mouse behavior.
415
Silent Installation of Ranorex

You can use standard MSI command line arguments (see below for examples) to customize the Ranorex installation, for example, to install the Ranorex Runtime silently on different (virtual) machines.
Installation Packages Installation Command Line Arguments Install Ranorex License
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.
Installation Command Line Arguments

To install Ranorex silently, pass the /quiet (no UI) or /passive (progress bar only) command line argument: msiexec /i Ranorex-x.x.x.x.msi /quiet or: setup.exe /passive or: Ranorex-x.x.x.exe /quiet 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: x.x.x.exe ADDLOCAL=ALL REMOVE=RanorexStudioFeature Possible feature names used as parameter to ADDLOCAL or REMOVE (separated by commas) are:
MainFeature (Core components) RanorexSamples RanorexStudioFeature RanorexFirefoxExtension RanorexIEAddon RanorexDocumentation
Ranorex-
416
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
Install Ranorex License

To finish your silent installation you have to install a valid license. If you would like to install afloating license you have to copy the file Ranorex3 Server.lic (for Ranorex3.x installations) or Ranorex2 Server.lic (for Ranorex 2.x installations) into the folder %ALLUSERSPROFILE% by using the XCOPY command in a batch file. The file will be created when you first install a License Server license on a Ranorex Client. Just search for that file on a client machine running a floating license. 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.
417
Licensing
Licensing
In general Ranorex provides two different types of licenses to install:
Installing a Node Locked License Installing a Floating License
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. Both license types are available for Ranorex Runtime, Professional, and Premium Edition. If you are going to transfer a license to another machine, have a look at the section Transfer Licenses. SAP support is not included in the Ranorex standard developer licenses. sales@ranorex.com for further details. Please contact our sales team at
License Registration
In order to register a Ranorex license, start the Ranorex Licensing tool, which is available in the Ranorex start menu folder.
Figure 533: License installation dialog The license installation tool is used to install both types of licenses.
Installing a Node Locked License

To install a machine-bound Ranorex license select the Use Machine License option. Though the license needs to be activated on the Ranorex server over the internet, it is not necessarily required to have an internet connection available on the target machine.
418
Licensing
Installing with Internet Connection

Simply type or paste in the Ranorex license key which has been delivered to you by email and press Install.
Figure 534: Installed license after activation
Installing license without Internet Connection

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.
419
Licensing
Figure 535: Error Dialog - No internet connection available 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.
Figure 536: License authentication using Ranorex web site
Installing a Floating License

Installing and configuring the Ranorex License Server
In order to use a Ranorex Floating License it is required to install and run the Ranorex license server application on a computer (server) within a network. The download link for the license server 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.
420
Licensing
Note: To prevent firewalls from blocking communication between license server and client, it is required to open port 7266 for TCP and UDP access on the server.
Note: By installing a Ranorex license server its required to use a Ranorex license server installation package which is at least as actual as your Ranorex client installation.
Figure 537: License server dialog - one premium licenses in use Open the Ranorex license server configuration tool. Add the floating license keys to the text box and press Install. These licenses are now ready to use. To get more information about the clients leasing a license you can select the specific license in license server configuration tool and open the Clients tab. Using the Save Server Log button allows you to export all actions processed by the license server 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.
421
Licensing
Figure 538: 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.
Configuring Developer and Runtime Clients

In order to use an installed floating license, open the Ranorex license tool on the client and select the option Use License Server.
Figure 539: Using license server for Ranorex Premium edition Press the button Detect to request a list of the currently available license servers within the local network. The license type specifies which license (Runtime, Professional, Premium) should be used on the client. By selecting Auto, the client automatically requests the appropriate license. In case of running Ranorex tests via the standalone test suite runner or from command line, only a Runtime floating license will be used. When starting Ranorex Spy tool a Professional floating license will be leased on the server. After pressing the Install button the client is assigned to
422
Licensing
the selected license type. To switch the currently installed license type, simply select another one from the list and click Install again. Every time a Ranorex test, a Ranorex tool, or Ranorex Studio is started the client sends a license request to the server. If the type of the required license is available, it will be assigned to the requesting client. By closing Ranorex Studio or finishing a test run the license will be automatically released and can then be used by other clients. 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.
Transfer Licenses
In order to transfer a license from one machine to another, you have to follow the instructions below. To transfer a node-locked license, open the Ranorex License Tool and press the Transfer License button.
Figure 540: Transfer a node locked license If you are going to transfer a floating license, open the Ranorex License Server Tool, right-click the license you are going to transfer and choose Transfer License(s) from the context menu.
423
Licensing
Figure 541: Transfer a floating license Confirm the license transfer for the specific license and the specific machine.
Figure 542: Confirm the license transfer A dialog will pop up, informing you about the success of your license transfer. If the license transfer was successful, the license has been uninstalled from the machine you transferred it from and can be installed on another machine as described in Installing a Node Locked License or Installing a Floating License.
424
Licensing
Figure 543: Succeeded license transfer If the license transfer has failed, you can manually transfer your license by sending a prepared mail to our support mail box.
Figure 544: Failed license transfer
Note: When performing a manual license transfer, the license cannot be used until the manual license transfer has been completed.
Uninstall License
In order to uninstall a license from a machine, please either use the uninstall button in the Ranorex License Tool for node-locked licenses, or right-click the license you are going to uninstall and choose Uninstall License(s) from the context menu in the Ranorex License Server Tool for floating licenses.
425
Licensing
Figure 545: Uninstall node-locked license
Figure 546: Uninstall floating license
426
Licensing
Figure 547: Confirm uninstall
427
FAQ
FAQ
How does Ranorex identify UI elements? Is it possible to run the same Ranorex test code on Vista and XP? Is it required to use RanoreXPath for test automation? Does Ranorex support data driven testing? What to do when items cant be found during Ranorex test execution? Is it possible to extend recordings with user specified code actions? What is the difference between Adapter and Element? Is it possible to trigger Ranorex tests from an existing test or build environment? Can I use Ranorex libraries within Visual Studio? What shall I do with unexpected dialogs and popup windows during test automation? Is it possible to test Silverlight applications with Ranorex? Is it possible to automate a webpage without moving the mouse pointer? What are the system requirements for developing and running Ranorex tests? Are there known incompatibilities with other software?
How does Ranorex identify UI elements?

Ranorex uses the RanoreXPath to identify applications and their UI elements required for test automation. The RanoreXPath provided by Ranorex Spy consists of many different, technology dependent attributes which can be modified and adapted by the user. To separate test code from identification information Ranorex provides a repository (see Lesson 6: UI Mapping with Ranorex Repository) to map logical names to RanoreXPath expressions.
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.
Is it required to use RanoreXPath for test automation?

No. Its also possible to search for GUI elements or forms using a number of different Find methods to search and/or filter for child elements. Have a look at the code example of the online documentation to see how it works. Code Examples
428
FAQ
Does Ranorex support data driven testing?

Yes. Ranorex supports four different data connectors to build data driven test cases:
Simple Data Table SQL Connector CSV File Excel File
A general description of how to create data driven test cases can be found here: Lesson 3: Data-Driven Testing
What to do when items cant be found during Ranorex test execution?

There are two primary reasons why some items cant be found during replay: 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.
Is it possible to extend recordings with user specified code actions?

You can easily extend standard recordings with user specific code actions by converting existing action items or by adding a new user code action item to a recording. Learn more about how to use user code actions in recordings here: User Code Actions
What is the difference between Adapter and Element?

Adapters provide an easy-to-use interface for accessing attributes and actions of elements. Each item generated by the Ranorex object repository automatically represents a Ranorex Adapter (Button, CheckBox, Text, ListItem, TreeItem, . . . ). You can only create a Button Adapter of an element if the element supports the Button role, i.e. if Ranorex Spy recognizes the element as a Button. If your controls are recognized as Unknown or Element, Ranorex cannot assign them a role. You cant use special attributes or actions with these elements, but you can usually still create a path that identifies the element to execute minimally mouse clicks.
Is it possible to trigger Ranorex tests from an existing test or build environment?

The result of a Ranorex test automation project is always an executable file. The generated *.exe can easily be started from other environments supporting command line execution. 429
FAQ
Can I use Ranorex libraries within Visual Studio?

Thats one of the big advantages of using Ranorex. Youre able to use your existing development environment to develop Ranorex based test automation code. Additionally the code generated by the Ranorex Recorder or Ranorex Repository can easily be integrated into your Visual Studio projects. Visual Studio Integration
What shall I do with unexpected dialogs and popup windows during test automation?
Ranorex recognizes and specifies whether an application still has the top level characteristic or not. In case of totally unexpected dialogs, the Ranorex.Report class provides a simple way to log screen shots of the current desktop status. Read more about how to handle popup dialogs within Ranorex test automation code in the section Handling unexpected Dialogs.
Is it possible to test Silverlight applications with Ranorex?

Yes it is. Simply ensure that your Silverlight application does not run in window-less-mode, i.e. set the Windowless property of the Silverlight HTML object to false. Find more information about window-less mode on the following site: msdn.microsoft.com/en-us/library/cc838156(VS.95).aspx
Is it possible to automate a webpage without moving the mouse pointer?

Yes it is. Simply use the PerformClick instead of the normal Click method when working with web adapters like DivTag, Input or Link.
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
Are there known incompatibilities with other software?

In general, there are no known incompatibilities. However, some antivirus or security software blocks certain Ranorex functionality. Consequently, if you experience problems with your automation and are running antivirus or security software, we recommend temporarily switching that software off for a test run.
430

Ranorex Tutorial

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Ranorex Tutorial

Enviado por

Direitos autorais:

Formatos disponíveis

Ranorex Tutorial Test Automation Guide

398 403 404 405 406 407

Ranorex Studio - The Layout

Ranorex Studio - The Layout

Figure 1: Ranorex Studio main views

Ranorex Studio - The Layout

Figure 2: Working with the projects test suite

Figure 3: Working with the projects module groups

Ranorex Studio - The Layout

Figure 4: Creating or adapting a recording module

Figure 5: Working with the repository

Ranorex Studio - The Layout

Figure 6: Writing code modules

Figure 7: Viewing a test report

Lesson 1: Getting Started

Lesson 1: Getting Started

Preparing to Record User Actions

System Under Test: KeePass Password Safe

Lesson 1: Getting Started

Note: The password to open this database file is rx.

Start Ranorex Studio and open the empty recording file.

Lesson 1: Getting Started

Figure 10: Specify programming language and project name

Lesson 1: Getting Started

Figure 12: Empty Recording

Start recording a test for the KeePass application.

Lesson 1: Getting Started

Lesson 1: Getting Started

Figure 15: Recording actions for the KeePass application

Enter the default Password.

Lesson 1: Getting Started

Figure 16: KeePass application

Open the Add new Entry Form.

Add a new entry to the KeePass application.

Choose any icon (e.g. the second one) Click on Close

Lesson 1: Getting Started

Choose 1 Year menu item

Figure 18: KeePass form for adding a password entry

Lesson 1: Getting Started

Figure 19: KeePass form for choosing an icon

Figure 20: KeePass expiration sub menu

Lesson 1: Getting Started

Validate the result.

Figure 22: Choose UI element to validate

Lesson 1: Getting Started

Figure 23: Choose attribute to validate

Delete added item and close application.

Lesson 1: Getting Started

Analyzing Recorded Steps

Executing the Test

Figure 26: Start the test by clicking the Run button

Lesson 1: Getting Started

Figure 27: Test run succeeded

Lesson 1: Getting Started

Lesson 2: Ranorex Modules - Test Actions

Lesson 2: Ranorex Modules - Test Actions

Refactoring: Why you should Separate Recordings

Figure 31: Move login actions to a new recording

Lesson 2: Ranorex Modules - Test Actions

Lesson 3: Data-Driven Testing

Lesson 3: Data-Driven Testing

Using Variables within Recordings

Lesson 3: Data-Driven Testing

Using Variables within the Repository