Ranorex is a Windows GUI test and automation Library for C, Python and for all.Net languages. Websites and applications can be automated using a Python script or a.NET program.
Ranorex Agent Download
Test Automation Guide
Ranorex Test Automation Guide Based on version 7.0 © Copyright 2017 Ranorex GmbH Created on: April 24, 2017 Ranorex Version: 7.0 Authors: Roland Enzinger, Martin Fahrenberger, Christoph Preschern, Christina Reisinger, Tobias Walter, and Mario Werkgarner Special Thanks to: Michael Gissing, Alexander Hoisl Contents Ranorex Studio - The Layout Studio Start Page . . . . Working environment . . #1 - Projects View . . . #2 - Module Browser . . #3 - File View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 4 5 5 6 Lesson 1: Getting Started Preparing to Record User Actions . . . . . System Under Test: KeePass Password Safe Recording a Test . . . . . . . . . . . . . . Analyzing Recorded Steps . . . . . . . . . . Executing the Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 12 12 13 25 25 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lesson 2: Ranorex Modules - Test Actions 29 Lesson 3: , ' Mouse Left Click item ’ FormAdd_Entry . TabPageList . InputFields . TextPassword ’ at 175;9. ' , repo . FormAdd_Entry . TabPageList . InputFields . T e x t P a s s wo r d I n f o ) ; repo . FormAdd_Entry . TabPageList . InputFields . TextPassword . Click ( ' 175;9 ' ) ; } } } VB.NET Namespace M y F i r s t T e s t P r o j e c t Public Partial Class AddEntry ’ ’’ < summary > ’ ’’ This method gets called right after the recording has been started . ’ ’’ It can be used to execute recording specific initiali zation code . ’ ’’ Private Sub Init () ’ Your recording specific init ializat ion code goes here . End Sub Public Sub C l i c k O n P a s s w o r d F i e l d () Report . Log ( ReportLevel . Info , ' Mouse ' , ' Mouse Left Click item ’ FormAdd_Entry . TabPageList . InputFields . TextPassword ’ at 175;9. ' , repo . FormAdd_Entry . TabPageList . InputFields . T e x t P a s s w o r d I n f o ) repo . FormAdd_Entry . TabPageList . InputFields . TextPassword . Click ( ' 175;9 ' ) End Sub End Class End Namespace 109 Lesson 5: Ranorex Recorder User Code Actions and Parameters With Ranorex it is possible to use parameters for user code actions. You can pass arguments with different types to your user code methods to gain more flexibility in your testing environment. Next to passing different types of values it is also possible to pass repository items to user code actions. This enables e.g. combining several actions on one UI object or building up a generic library of smart actions independent of the underlying technology to only name some of the potential applications. To use parameters for a new user code action, click the ’Args’ button next to the method’s cell to open the Argument Editor. Figure 158: Open the Argument Editor By pressing the ’Add’ button, you can choose the type of the argument you are going to pass to the user code action. Figure 159: Add argument After adding a new argument, you can edit its properties. To enhance flexibility, you can use variables instead of hardcoded values. 110 Lesson 5: Ranorex Recorder Figure 160: Edit properties of the argument After declaring the parameters with values or variables, you can switch to the user code method and use the passed parameters. C# public void A d d E n t r y W i t h P a r a m s ( string aTitle , string aUsername , string aPassword , string aURL ) { // Set text fields repo . PwEntryForm . Text . TextValue = aTitle ; repo . PwEntryForm . UserName . TextValue = aUsername ; repo . PwEntryForm . Password . TextValue = aPassword ; repo . PwEntryForm . Repeat . TextValue = aPassword ; repo . PwEntryForm . URL . TextValue = aURL ; } VB.NET Public Sub A d d E n t r y W i t h P a r a m s ( aTitle As String , aUsername As String , aPassword As String , aURL As String ) ’ Set text fields repo . PwEntryForm . Title . TextValue = aTitle repo . PwEntryForm . UserName . TextValue = aUsername repo . PwEntryForm . Password . TextValue = aPassword repo . PwEntryForm . Repeat . TextValue = aPassword repo . PwEntryForm . URL . TextValue = aURL End Sub You can bind the return value of a user code method by setting the option ’Return Value Variable’ in the properties pane. Additionally to creating method calls in Ranorex Recorder you are able to define your methods in code and just select the intended method in the Recorder Table. Here you are also able to choose overloaded methods. Figure 161: Choose one of the overloaded method calls 111 Lesson 5: Ranorex Recorder Figure 162: Ranorex Argument Editor with arguments and variable binding from overloaded method As mentioned above it also is possible to pass repository items to user code actions. This can be accomplished by either choosing the argument type ’Adapter’ or ’RepoItemInfo’, when adding arguments using the Argument Editor. After defining the repository item arguments, the can simply be bound to repository items the same way as any other action in the actions table by selecting them in the action table or dragging and dropping them from the repository. Figure 163: Repository item as argument for a user code action After declaring the parameters with repository items, values or variables, you can switch to the user code method and use the passed parameters. The following example simulates a keyboard input to the given repository item using the given string value. Followed by a validation whether the text value attribute of the given repository equals the given string value. After that a screenshot of the current state of the UI element represented by the repository item will be reported. C# public void S e t A n d V a l i d a t e T e x t V a l u e ( Ranorex . Adapter repoitem , string val ) { Keyboard . Press ( repoitem , val ) ; Validate . AreEqual ( repoitem . As < Ranorex . Text >() . TextValue , val ) ; Report . Screenshot ( repoitem , true ) ; } VB.NET Public Sub S e t A n d V a l i d a t e T e x t V a l u e ( repoitem As Ranorex . Adapter , val As String ) Keyboard . Press ( repoitem , val ) Validate . AreEqual ( repoitem .[ As ]( Of Ranorex . Text ) () . TextValue , val ) Report . Screenshot ( repoitem , True ) End Sub 112 Lesson 5: Ranorex Recorder Using repository items as arguments for user code actions enables a variety of possibilities such as providing a framework of smart test actions, defining generic technology independent get/set value actions, combining several related actions to one user code action, implementing complex validations and many more. Conditions in Code Another reason for writing user code is to read text values from UI elements like text boxes and to reuse them for conditional automation steps. Note: Only create small and easy to maintain user code actions for a recording. If an implemented method should also be available for other test cases, create a code module (see Lesson 7: Code Modules) instead. Within the ’DeleteEntry’ recording that was created in Lesson 3: , ' Mouse Right Click item ’ cellInfo ’ at Center . ' , cellInfo ) ; cellInfo . FindAdapter < cell >() . Click ( System . Windows . Forms . MouseButtons . Right , 100) ; Report . Log ( ReportLevel . Info , ' Mouse ' , ' Mouse Left Click item ’ menuitemInfo ’ at Center . ' , menuitemInfo ) ; menuitemInfo . FindAdapter < menuitem >() . Click (100) ; } } VB.NET 113 Lesson 5: Ranorex Recorder Public Sub D e l e t e I t e m I f F o c u s e d ( cellInfo As RepoItemInfo , menuitemInfo As RepoItemInfo ) If repo . MainForm . Entry . HasFocus Then Report . Log ( ReportLevel . Info , ' Mouse ' , ' Mouse Right Click item ’ cellInfo ’ at Center . ' , cellInfo ) cellInfo . FindAdapter ( Of Cell ) () . Click ( System . Windows . Forms . MouseButtons . Right , 100) Report . Log ( ReportLevel . Info , ' Mouse ' , ' Mouse Left Click item ’ menuitemInfo ’ at Center . ' , menuitemInfo ) menuitemInfo . FindAdapter ( Of MenuItem ) () . Click (100) End If End Sub 114 Lesson 5: Ranorex Recorder 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 you’ll 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 165: 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. 115 Lesson 5: Ranorex Recorder Figure 166: 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 recording’s repository. You can use the ’Search’ text box to filter the elements. You can read more about how to use repository search and how to add new UI elements in Lesson 6: UI Mapping with Ranorex Repository - Searching For Elements. Confirm your selection by clicking OK. Figure 167: 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’. 116 Lesson 5: Ranorex Recorder Figure 168: 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 169: 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. 117 Lesson 5: Ranorex Recorder Figure 170: 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 Actions used in the actions table can be divided into two groups: Basic and Smart Actions. Basic Actions are performed by the end user with the keyboard, mouse, on-screen keyboard or touchscreen utilizing the mouse, mouse wheel, touch, key shortcut, key sequence or mobile key-press. These actions are automatically recorded with the Ranorex Recorder. All other actions are so-called Smart Actions. Mouse Adds a new mouse action item at the current position Mouse Wheel Adds a new mouse wheel action item Touch Event Adds a new touch event action item at the current position Swipe Gesture Adds a new swipe gesture event action item at the current position Key Shortcut Adds a new key shortcut action item (e.g. ’CTRL+C’ or ’CTRL+V’) Key Sequence Adds a new key sequence action item (e.g. ’Hello’) Mobile Key Press Adds a new mobile key press action (e.g. {BACK}, {MENU}) Validation Adds a new validation action item Invoke Action Adds a new invoke action item (e.g. call method ’Select’ for a UI element of type list item) Get Value Adds a new get value action item (e.g. get ’Text’ for a UI element of type button) Set Value Adds a new set value action to set an attribute value (e.g. ’Text’ for a UI element of type text) Open Browser Opens a browser and navigates to the given URL Run Application Runs an application at the given directory and file path Run Mobile App Runs an application on a mobile device 118 Lesson 5: Ranorex Recorder Deploy Android/iOS App 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 Set Device Orientation Sets the orientation of the device either to ’Portrait’ or ’Landscape’ Close Application Closes an application or web site containing the given repository item Wait For Waits for a given repository item to appear or disappear Note: This action can be used for any type of UI element Log Message Adds a new report action item logging a user defined message Note: In addition to the standard report levels, you can define custom report levels by changing the level from ’Info’ to ’Custom’ Capture Screenshot Adds a new report action logging a screenshot of a specific repository item Create Snapshot Adds a new report action item adding a snapshot file of a specific repository item Separator Inserts a separation line on the currently selected position in the actions table Delay Adds a new delay action item User Code 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. The duration of the different kinds of touch events can be defined in the properties pane. You can open this pane by clicking the context menu item ’Properties’ on the ’Touch Event’ action item. 119 Lesson 5: Ranorex Recorder Swipe Gesture This action can be used to simulate a swipe gesture on a given repository item. You can specify the direction and the distance as well as the swipe duration. The distance can either be specified in pixels or as a percentage relative to the repository item connected to the action. The swipe gesture can only be added manually, it will not be recorded. Additionally you can set the start location as well as the amount of swipe steps in the properties pane. The properties pane can be accessed by right-clicking the swipe action and choosing ’Properties’ in the context menu. Key Shortcut This action can be used for executing key shortcut actions. Aside from the shortcut itself, it is possible to specify the events ’Press’, ’Up’ and ’Down’. For this action, a repository item assignment is not required. Key Sequence This action makes it possible to execute or to simulate a key sequence. This action is typically recorded in a form filling scenario (e.g. username field in login process). For this action a repository item assignment is not required. To protect proprietary data like passwords you can mask the key sequence by setting the option ’Mask Sequence’ in the properties pane. Mobile Key Press This action can be used for pressing mobile keys like {BACK} and {MENU}. For more detailed information please have a look at Android Testing - Record and Run an Android Test. Validation The validation action is typically used for validating states, text or images of specific repository items. Every validation action leads to a specific entry in the report file and, depending on the type of validation and the validated element, there may be different validation results (success, failure). After assigning a repository item, you are able to choose one of the following validation-types: EXISTS: The validation checks for the existence of the repository item and expects an existing item. Example: A user can validate whether a button exists with a resulting success if the button actually exists. NOTEXISTS: The validation checks for the existence of the repository item and expects the item not to exist. Example: A user can validate whether an error dialog does not exist with a resulting success if the dialog does not exist. ATTRIBUTEEQUAL: This validation checks whether an attribute (column ’Match Name’) is equal to a specific value (column ’Match Value’). The matching attributes depend on the assigned repository item and therefore an assignment of a repository item is assumed. For example a WinForms button may be validated on the ’Text’, on the ’Valid’ state, on the ’Pressed’ state and also on ’AccessibleName’, ’AccessibleValue’ etc. The matching value can either be a constant, a self-defined value or a module variable. Example: A user can validate whether a button has the text ’OK’ with a success result if the button text is ’OK’. ATTRIBUTEREGEX: This validation is for matching a ’match value’ (self-defined match value or the content of a module variable) against a specific attribute (column ’Match Name’) using a regular expression. Because the attribute itself (column ’Match Value’) depends on the assigned repository item, assignment of a repository item is recommended prior to choosing a match value. If you plan to use a variable within this type of validation, you can easily implement your regular expression in the value of that variable. Example: One can validate whether the title of the KeePass application ends with the text ’KeePass Password Safe’ and could therefore use the ’Match Name’ containing the regular expression ’.+KeePassPasswordSafe$’. The validation would lead to success if the attribute (column ’Match Name’) has any character (this is defined as a .+ in the regular expression) followed by the constant ’KeePass Password Safe’. For more information about Regular Expressions see RanoreXPath - RanoreXPath with Regular Expressions. 120 Lesson 5: Ranorex Recorder ATTRIBUTECONTAINS: This validation checks whether a specific attribute (column ’Match Name’) of a specific repository item contains a ’match value’. The match value can either be a user-defined constant value or it can also be the content of a module variable. As above this validation assumes the assignment of a repository item. Example: A user can validate whether the title of the KeePass application contains the constant value ’kdbx’, which is the file extension of the database used by KeePass. The match name would thus be set to ’Title’ and the match value would be set to ’kdbx’. As a result the validation would succeed if the title actually contains the constant ’kdbx’. 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. You can enable reporting the similarity in the properties pane. This can be useful for tweaking the similarity of the corresponding image validation action. For more information about image-based validation please have a look at the section entitled Image-Based Automation later in this chapter. Example: It’s possible to validate whether the user-defined list of icons (for a KeePass entry) contains a specific icon. This could be done using image-based validation. The repository item would therefore hold the list of icons and the screenshot would be a picture of the specified icon. The validation would lead to a result if the list contains the specified icon. COMPAREIMAGE: This validation checks whether a specified repository item is equal to a specific screenshot. This screenshot can be easily created within the ’Edit Image Validation’ which can be accessed via a button in the ’Screenshot’ column. For a better understanding of what is different between the two compared images you can enable ’Report Difference Images’ in the properties pane. This will report a difference mask showing the differing pixels as well as the differential image. Additional you can enable reporting the similarity in the properties pane. This can be useful for tweaking the similarity of the corresponding image validation action. For more information about image-based validation please see Image-Based Automation later in this chapter. Example: To validate whether the toolbar of the KeePass application contains the intended icons you can compare the repository item with a screenshot of the toolbar in its initial state. Invoke Action Used for invoking actions on the specified repository item. For example a WinForms button provides functionality for ’Ensuring Visibility’, ’Focusing’ and ’Pressing’. More important, this action can be used to easily select items in lists and drop-downs. No mouse movement and click is simulated but nevertheless the item itself is selected. This is a more powerful and smarter action than simulating the selection via mouse actions. Invoking a select action on a specific item also works if the item itself is not visible by default because there are too many elements in the list. You can bind the return value of an invoke action by setting the option ’Return Value Variable’ in the properties pane. Invoking user-defined (dynamic) actions: In addition to access actions delivered by default, you can also invoke user-defined actions (see Invoking User-Defined Actions) in your System Under Test. Get Value As the action name indicates, this method can be used for getting values from repository items. Depending on the assigned repository item, the available attributes can be different. The value obtained can be assigned to a module variable. Depending on the available adapters for the assigned repository item, the attributes are divided into several sections (see figure below). 121 Lesson 5: Ranorex Recorder Figure 171: 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 ’?’. 122 Lesson 5: Ranorex Recorder Example: If you have a string ’Rows: 23, Columns: 42’ and you want to return the number of columns you can use following regular expression: ’ˆRows: ([0-9]*), Columns: (?[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 172: Text value of a button stored in a variable To make the value stored in the module variable available to other modules, it’s necessary to bind the variable to a parameter. By doing so, it can then be bound to variables in other modules. Figure 173: Two variables are bound to one parameter for passing a variable value from one module to another Set Value As the action name indicates, this method can be used for setting the attribute values of repository items. Depending on the assigned repository item, the available attributes might be different. Depending on the available adapters for the assigned repository item, the attributes can be divided into several sections as shown below. 123 Lesson 5: Ranorex Recorder Figure 174: Submenu for Set Value Action To protect proprietary data like passwords you can mask the value by setting the option ’Mask Value’ in the properties pane. User-defined attributes: In addition, it is also possible to set user-defined attributes. If the application is running during the creation of the Set Value action then there is a submenu for ’Dynamic’ methods holding dynamic attributes. Note: To get access to the dynamic methods and attributes, the repository item has to be available. This can be verified by highlighting the specific element by right clicking the element in repository and choosing ’Highlight Element’ from the context menu. Open Browser This action can be used for opening a browser. For preparation you are able to use the parameter ’URL’ for directly opening a website. The parameter browser can be used for choosing a browser (e.g. ’IE’, ’Chrome’, ’Safari’ or ’Firefox’). Note: You can use a ’module variable’ inside the column ’Browser’ which can be used for cross-browser testing. For an extensive description including an example see Cross-Browser Test Automation with Ranorex. Additionally there is a parameter ’Maximized’. When this parameter is set to ’false’, the URL is opened in the default browser window size which can nevertheless be in maximized state. With the maximized-parameter set to true, the browser will be opened in maximized window state. Run Application This action can be used to run an application with the filename specified in the column ’File Name’. You can also pass arguments (column ’Arguments’) and define the working directory. Run Mobile App When using this action you can specify a ’Device’, an ’App’, and whether the specified app should be restarted or not. For more information see Android Testing - Record and Run an Android Test for Android testing or iOS Testing - Record and Run an iOS Test for iOS testing. Deploy Android/iOS App When using this action, you can specify a ’Device’ and an ’APK/IPA file’. The given application will be deployed to the given device. 124 Lesson 5: Ranorex Recorder Set Device Orientation When using this action, you can specify the orientation of the device. You can choose one of the following orientations: ’Portrait’, ’PortraitUpsideDown’, ’LandscapeLeft’, ’LandscapeRight’. Close Application This action can be used for closing applications and web sites. If the ’Close Method’ is set to ’CloseWindow’, the application is attempted to be closed. If the parameter ’Grace Period’ is set to a value greater than 0 ms, the process will be killed after the ’Grace Period’ if closing the application failed. If ’Close Method’ is set to ’KillProcess’ the application’s process is killed immediately and the grace period is ignored. Wait For You can use the ’Wait for’ action to wait until the assigned repository item appears (choosing the option ’Exists’) or does not exist anymore (choosing the option ’NotExists’). You can also specify a ’Timeout’. Report The Report action is typically used for providing information related to the test report. You are able to choose one of the following action types: Log: This action adds a line of text holding a given value to the test report. 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. The sample project including the source code can be downloaded here: sample-project. 125 Lesson 5: Ranorex Recorder Figure 175: Example (in initial state) with public functionality which will be invoked C# public void MyIn v ok ed Ac t io n ( string MyMessage ) { e dP ro te c te dT ex t . Text = MyMessage ; } private void bt S e t V a l u e _ C l i c k ( object sender , EventArgs e ) { e dP ro te c te dT ex t . Text = ' This text was set from GUI ' ; } The protected text can only be set by clicking the button. The application then sets the text field to a constant value. Figure 176: Example after clicking the button without using custom ’invoke’ functionality Ranorex provides the functionality for accessing methods that are declared as public directly within the actions table. The public method ’MyInvokedAction’ can easily be called using a custom argument value. When adding the new action it is recommended to keep the application (’InvokeExample’) open because accessible functionality is determined dynamically. 126 Lesson 5: Ranorex Recorder Figure 177: Submenus for available invoke actions Even parameters can be easily set in the Ranorex Recorder table. Figure 178: 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. 127 Lesson 5: Ranorex Recorder Figure 179: Browsing available arguments Invoking this method causes the text field’s content to be set to the desired value. Figure 180: 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 181: Disabled actions are grayed out while ’Continue-On-Fail’ is indicated by an italic font style Note: In case of an error the particular action logs a warning to the report. 128 Lesson 5: Ranorex Recorder Note: To make a validation action optional you additionally have to set the ’Report Level on Failure’ of the action to ’Warning’. You can set this option via the property grid. Splitting Recordings The more recorded actions you have after finishing a new recording, the less clear each single action becomes. As was already mentioned in Lesson 2: Ranorex Modules - Test Actions, identifying reusable steps within a newly created recording is recommended. Use the context menu item ’Move to New Recording Module’ to create a new recording module. Figure 182: 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. 129 Lesson 5: Ranorex Recorder Figure 183: 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. 130 Lesson 5: Ranorex Recorder Image-Based Automation In some situations, required information for automation is not available as text but only as pixel image. Ranorex provides image-based automation to bypass this lack of accessibility. Screencast: Information about image based automation can also be found in our screencast ”How and When to Use Imaging Capabilities”. Please follow the link to view this video: http://youtu.be/wwr5ddOe4h0. Sometimes you need to automate a click action based on image information. For this reason, Ranorex Recorder provides an optional way to capture image related mouse actions. To activate image-based recording, simply check the ’Image based’ checkbox in the Recorder’s toolbar during a recording session. Figure 184: ’Image based’ recording activated Now move the mouse pointer over a certain UI element. Ranorex highlights the UI element below the mouse and also highlights a recognized image region within the UI element. To turn off image-based recording, uncheck the checkbox or press the shortcut key ’I’. Note: Hotkey functionality has to be activated by first using the master hot key ’SCROLL’. Read more about hotkey usage in the current lesson in the section entitled Recorder Hotkeys. Introductive Example In KeePass, there is a way to include some user specific icons for password entries (e.g. someone could use the WordPress logo for his WordPress password entry). For automation of a click on a custom icon, it might be necessary to use image-based automation because the order and in addition the index of the icon can change because icons with a lower index can be deleted. 131 Lesson 5: Ranorex Recorder Figure 185: KeePass Icon Picker dialog containing two custom icons To prepare image-based automation for a click on a custom icon, activate image-based recording. Move the mouse pointer to the listview for custom icons in KeePass and wait until the whole listview frame is highlighted. Execute a mouse click on the listview (take care to not click on a custom icon). The click has to be done on the listview control in contrast to a click on an (icon) element itself because this click defines the region in which the prospective image has to searched. Thus the image is searched in the entire list control. After stopping the recording, the actions table contains an image-based mouse click action. At the time of recording the mouse click, a screenshot of the control was created and is now listed as a child element of the corresponding repository item. Figure 186: 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 132 Lesson 5: Ranorex Recorder the button in the location cell (see graphic above). In this dialog use the ’Select image find region’ toolbar button to define the user-defined icon which should be clicked. Additionally use the ’Select click location’ functionality to tell Ranorex at which position the mouse click should be executed. This features will be described in more detail later on in the Image Editor section. Figure 187: ’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 Advanced Options 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. Preprocessing Defines preprocessing steps that can be performed on an image before search (see table ”Image Preprocessing Filters” below). Screenshot Name Specifies the name of the screenshot used in the search. Selection Rectangle Defines the image selection region (= what to search for). Similarity Specifies the minimum similarity (0.0-1.0), that the image region to search for needs to have in common with the image in order to be considered a match. Image Preprocessing Filters 133 Lesson 5: Ranorex Recorder 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). 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). Image-Based Settings To set up the default values for image-based recording, open up the ’Settings’ dialog and continue with activating the ’Imaging’ tab. 134 Lesson 5: Ranorex Recorder Figure 188: 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 189: Click location dialog to change the settings of image-based mouse actions 135 Lesson 5: Ranorex Recorder Image Editor Functionality Image Based Specifies whether the click is based on image information or not Select Image Find Region Specifies the region to search within the image Select Click Location Defines the click position in relation to the searched region Autoselect Image Find Region Helps to specify the search region within the image Zoom Out Zooms out Zoom 100% Switches to 1:1 view Zoom In Zooms in Capture New Screenshot 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’. It’s 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 190: 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 it’s available for other image-based validation (checkpoint) or automation actions. 136 Lesson 5: Ranorex Recorder Figure 191: Add a new image or select an existing image to specify the location/graphic to search 137 Lesson 6: UI Mapping with Ranorex Repository Lesson 6: UI Mapping with Ranorex Repository The Ranorex Element Repository is used to separate identification information (RanoreXPath) from Ranorex test automation modules. For test maintenance, it is recommended that you also use Ranorex repositories within code modules to reduce the effort in adaptation necessary when the UI under test changes. In the following lesson you’ll learn about: Adapting an Existing Repository Adding Repository Items Waiting for UI Elements - Repository Timeouts Editing RanoreXPath Repository Separation Repository Settings Dialog Repository Item Properties 138 Lesson 6: UI Mapping with Ranorex Repository 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 192: File view of a repository Figure 193: Integrated repository view within the Recorder Screencast: Watch the screencast (http://youtu.be/uYqruaEUcCU) on organizing and optimizing a Ranorex Repository to find out how to best use simple and rooted folders. 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. 139 Lesson 6: UI Mapping with Ranorex Repository 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 to edit the names. Figure 194: 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 195: Adding a ’Simple Folder’ to the repository 140 Lesson 6: UI Mapping with Ranorex Repository Figure 196: 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: Figure 197: Ranorex repository structure Application Folder #1 Represents a top level application, a dialog or a context menu Rooted Folder #2 Contains GUI elements having the same parent (i.e. RanoreXPath prefix) Simple Folder #3 Used to group items Adapter Item #4 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. 141 Lesson 6: UI Mapping with Ranorex Repository Figure 198: Specify whether to search in ’Names’, ’Paths’ or to ’Search All’ elements Figure 199: Search result for text ’button’ used in names and paths Repository Cleanup The repository’s ’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 200: 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. 142 Lesson 6: UI Mapping with Ranorex Repository Figure 201: After clicking the ’Cleanup’ button a dialog is shown with the repository elements currently not in use by any of recording or code modules within the project 143 Lesson 6: UI Mapping with Ranorex Repository Note: The cleanup functionality only searches for used items in the solution the repository is located in. There is no check if items are used in other solutions referencing the repository. 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 item’s name or the item’s 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 202: Search for references of repository item KeePass Figure 203: Search result - simply double-click a result item to open the code file Next to finding repository items in code you can also search all test modules. 144 Lesson 6: UI Mapping with Ranorex Repository Figure 204: Search for references of a repository item in all test modules Figure 205: Search result - simply click a result to open the test module 145 Lesson 6: UI Mapping with Ranorex Repository Adding Repository Items Screencast: In addition to going through the explanations on the following pages, you can get a good overview of ”Adding Repository Items” by watching our screencasts on this topic. How to add items manually is explained here: http://youtu.be/C1AVdFbUlIo. Several ways to use the Ranorex Spy tool are pointed out in this video: http://youtu.be/p25kFcjcuBs. In this section you will find several ways to add items to your repository without using the recording functionality. In addition, you’ll learn about how you can manually add actions (clicking, typing, etc.) to the recorder and connect these actions to repository items to specify 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: , ModuleType . UserCode , 1) ] public class O p t i o n s C o d e M o d u l e : ITestModule { // Repository object to access UI elements of KeePass Application M y F i r s t T e s t P r o j e c t R e p o s i t o r y repo = M y F i r s t T e s t P r o j e c t R e p o s i t o r y . Instance ; // Repository object to access UI elements of KeePass Options Dialog K e e P a s s O p t i o n s R e p o s i t o r y OptionsRepo = K e e P a s s O p t i o n s R e p o s i t o r y . Instance ; // / < summary > // / Constructs a new instance . // / public O p t i o ns C o d e M o d u l e () { // Do not delete - a parameterless constructor is required ! } // / < summary > // / Performs the playback of actions in this module . // / // / < remarks > You should not call this method directly , instead pass the module // / instance to the < see cref =' T e s t M o d u l e R u n n e r . Run ( ITestModule ) ' > method // / that will in turn invoke this method . void ITestModule . Run () { Mouse . D ef a ul tM ov e Ti me = 300; Keyboard . D e f a u l t K e y P r e s s T i m e = 100; Delay . SpeedFactor = 1.0; // Click the Save - Button in KeePass MainForm repo . KeePass . ButtonSave . Click () ; // Check the option to AutoClear the Clipboard OptionsRepo . FormOptions . TabSecurity . C h e c k B o x C l i p b o a r d _ a u t o _ c l e a r . Checked = true ; } } VB.NET < testmodule ( ' baa60b6c -5 dd1 -4 eb5 - bc39 - fdfd65775742 ' , moduletype . usercode ,= ' ' 1) = ' ' > _ Public Class Us e rC od eM o du le 1 Implements ITestModule ’ ’’ Repository object to access UI elements of KeePass Application Private repo As M y F i r s t T e s t P r o j e c t R e p o s i t o r y = M y F i r s t T e s t P r o j e c t R e p o s i t o r y . Instance ’ ’ Repository object to access UI elements of KeePass Options Dialog Private OptionsRepo AS K e e P a s s O p t i o n s R e p o s i t o r y = K e e P a s s O p t i o n s R e p o s i t o r y . Instance ’ ’’ < summary > ’ ’’ Constructs a new instance . ’ ’’ Public Sub New () ’ Do not delete - a parameterless constructor is required ! End Sub Test Reposito ry repo = TestRep ository . Instance ; ’ ’’ < summary > ’ ’’ Performs the playback of actions in this module . ’ ’’ ’ ’’ < remarks > You should not call this method directly , instead pass the module ’ ’’ instance to the < see cref =' T e s t M o d u l e R u n n e r . Run ( Of ITestModule ) ' > method ’ ’’ that will in turn invoke this method . Sub Run () Implements ITestModule . Run Mouse . D ef a ul tM ov e Ti me = 300 Keyboard . D e f a u l t K e y P r e s s T i m e = 100 Delay . SpeedFactor = 1.0 ’ ’’ Click the Save - Button in KeePass MainForm repo . KeePass . ButtonSave . Click ’ ’’ Check the option to AutoClear the Clipboard OptionsRepo . FormOptions . TabSecurity . C h e c k B o x C l i p b o a r d _ a u t o _ c l e a r . Checked = true End Sub End Class 160 Lesson 6: UI Mapping with Ranorex Repository 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 227: Open ’Settings’ from Recorder Figure 228: 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 229: Current settings of a repository 161 Lesson 6: UI Mapping with Ranorex Repository Figure 230: Default repository configuration Repository Troubleshooting - Folder Caching In some situations, repository items cannot be found because the caching information of the item’s parent folder is incorrect. In such cases, replaying the steps involving these items may only work part of the time or only with long delays. This is caused by a fallback mechanism which is used to search for an item without using the cache if the first attempt fails. If this occurs, it is recommended to disable the folder cache for the item’s ancestor folders by setting the ’Use Cache’ property to ’False’. 162 Lesson 6: UI Mapping with Ranorex Repository 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 231: Opening the repository item’s properties 163 Lesson 6: UI Mapping with Ranorex Repository Figure 232: Repository item properties Within the properties tab the following properties are available: Absolute Path The ’Absolute Path’ represents the path to the repository item including the paths of all parent folders. This property is read-only. Adapter Type With the ’Adapter Type’ property the adapter type of the repository item can be changed. The best fitting adapter will be chosen by setting this property to default. Effective Timeout The ’Effective Timeout’ property represents the sum of the search timeouts for the specific repository item and all its parent folders. This property is read-only. Comment Using the comment property, the repository item can be described textual. Live Element The ’Live Element’ represents the element specified by the repository item found in the live system as it is shown in Ranorex Spy. Name The ’Name’ property defines the name of the repository item. Search Timeout The ’Search Timeout’ property defines the amount of time an element will be searched for before an exception is thrown. Use Ensure Visible The ’Use Ensure Visible’ property specifies whether the repository item should be forced to become visible before automation or not. Additionally to the properties mentioned in the table above, a rooted folder or an app folder has the following property: 164 Lesson 6: UI Mapping with Ranorex Repository Use Cache The ’Use Cache’ property will either enable or disable caching for the specific folder. The chapter Repository Troubleshooting - Folder Caching will give more information about folder caching. 165 Lesson 7: Code Modules 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 Screencast: In addition to going through the explanations below, you can have a look at the screencast ”Code Modules - Benefits and Use Cases” which provides a good overview of reasons for switching to the code level and how do this well. The screencast can be found here: http://youtu.be/4k-lcNxQd2U Creating Code Modules Create a new code module by clicking the ’Add Code Module’ button at the toolbar. Figure 233: Adding a new code module with the toolbar button Alternatively you are able to add a new code module by using the context menu in the Test Suite. 166 Lesson 7: Code Modules Figure 234: Adding a new code module using the context menu Figure 235: Specifying the name used for the code module After clicking the ’Create’ button a new file is added to the project and automatically opened in the file view. Ranorex Studio creates a new test module class which contains a ’Run’ method that is ready to be extended with test automation code. C# namespace KeePass { // / < summary > // / Description of A d d C r e d e n t i a l E n t r y . // / [ TestModule ( ' 03 F5603B -0 DDC -49 AA -8 C26 -4 D8088260C66 ' , ModuleType . UserCode , 1) ] public class A d d C r e d e n t i a l E n t r y : ITestModule { // / < summary > // / Constructs a new instance . // / public A d d C r e d e n t i a l E n t r y () { // Do not delete - a parameterless constructor is required ! } // / < summary > 167 Lesson 7: Code Modules // / Performs the playback of actions in this module . // / // / < remarks > You should not call this method directly , instead pass the module // / instance to the < see cref =' T e s t M o d u l e R u n n e r . Run ( ITestModule ) ' > method // / that will in turn invoke this method . void ITestModule . Run () { Mouse . D e fa ul tM o ve Ti me = 300; Keyboard . D e f a u l t K e y P r e s s T i m e = 100; Delay . SpeedFactor = 1.0; } } } VB.NET Namespace KeePass ’ ’’ < summary > ’ ’’ Description of A d d C r e d e n t i a l E n t r y . ’ ’’ < testmodule ( ' 03 f5603b -0 ddc -49 aa -8 c26 -4 d8088260c66 ' , moduletype . usercode ,= ' ' 1) = ' ' > _ Public Class A d d C r e d e n t i a l E n t r y Implements ITestModule ’ ’’ < summary > ’ ’’ Constructs a new instance . ’ ’’ ’ Do not delete - a parameterless constructor is required ! Public Sub New () End Sub ’ ’’ < summary > ’ ’’ Performs the playback of actions in this module . ’ ’’ ’ ’’ < remarks > You should not call this method directly , instead pass the module ’ ’’ instance to the < see cref =' T e s t M o d u l e R u n n e r . Run ( ITestModule ) ' > method ’ ’’ that will in turn invoke this method . Private Sub IT e st Mo du l e_ Ru n () Implements ITestModule . Run Mouse . D e fa ul tM o ve Ti me = 300 Keyboard . D e f a u l t K e y P r e s s T i m e = 100 Delay . SpeedFactor = 1.0 End Sub End Class End Namespace 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 A d d C r e d e n t i a l E n t r y : ITestModule { // Repository object to access UI Elements M y F i r s t T e s t P r o j e c t R e p o s i t o r y MyRepo = M y F i r s t T e s t P r o j e c t R e p o s i t o r y . Instance ; // / Constructs a new instance . public A d d C r e d e n t i a l E n t r y () { // Do not delete - a parameterless constructor is required ! } void ITestModule . Run () { Mouse . D e fa ul tM o ve Ti me = 300; 168 Lesson 7: Code Modules Keyboard . D e f a u l t K e y P r e s s T i m e = 100; Delay . SpeedFactor = 1.0; // Click ’ Add Entry ’ Button MainMenu MyRepo . MainForm . Edit . Click () ; MyRepo . KeePass . AddEntry . Click () ; // Set text fields MyRepo . AddEntry . T a b S h e e t A d d E n t r y . Title . TextValue = ' WordPressDemo ' ; MyRepo . AddEntry . T a b S h e e t A d d E n t r y . UserName . TextValue = ' admin ' ; MyRepo . AddEntry . T a b S h e e t A d d E n t r y . Password . TextValue = ' demo123 ' ; MyRepo . AddEntry . T a b S h e e t A d d E n t r y . Repeat . TextValue = ' demo123 ' ; MyRepo . AddEntry . T a b S h e e t A d d E n t r y . URL . TextValue = ' bitly . com / wp_demo ' ; // Choose an icon MyRepo . AddEntry . T a b S h e e t A d d E n t r y . MBtnIcon . Click () ; MyRepo . IconPicker . LI_Icon . Click ( Location . CenterLeft ) ; MyRepo . IconPicker . ButtonClose . Click () ; // Set Expires MyRepo . AddEntry . T a b S h e e t A d d E n t r y . M B t n S t a n d a r d E x p i r e s . Click () ; MyRepo . KeePass . MI_Expires . Click () ; // Save Credential Entry MyRepo . AddEntry . ButtonOK . Click () ; } } VB.NET Public Class A d d C r e d e n t i a l E n t r y Implements ITestModule ’ Repository object to access UI Elements Private MyRepo As M y F i r s t T e s t P r o j e c t R e p o s i t o r y = M y F i r s t T e s t P r o j e c t R e p o s i t o r y . Instance ’ ’’ Constructs a new instance . ’ Do not delete - a parameterless constructor is required ! Public Sub New () End Sub Private Sub IT e st Mo du l e_ Ru n () Implements ITestModule . Run Mouse . D ef a ul tM ov e Ti me = 300 Keyboard . D e f a u l t K e y P r e s s T i m e = 100 Delay . SpeedFactor = 1.0 ’ Click ’ Add Entry ’ Button MainMenu MyRepo . MainForm . Edit . Click () MyRepo . KeePass . AddEntry . Click () ’ Set text fields MyRepo . AddEntry . T a b S h e e t A d d E n t r y . Title . TextValue = ' WordPressDemo ' MyRepo . AddEntry . T a b S h e e t A d d E n t r y . UserName . TextValue = ' admin ' MyRepo . AddEntry . T a b S h e e t A d d E n t r y . Password . TextValue = ' demo123 ' MyRepo . AddEntry . T a b S h e e t A d d E n t r y . Repeat . TextValue = ' demo123 ' MyRepo . AddEntry . T a b S h e e t A d d E n t r y . URL . TextValue = ' bitly . com / wp_demo ' ’ Choose an icon MyRepo . AddEntry . T a b S h e e t A d d E n t r y . MBtnIcon . Click () MyRepo . IconPicker . LI_Icon . Click ( Location . CenterLeft ) MyRepo . IconPicker . ButtonClose . Click () ’ Set Expires MyRepo . AddEntry . T a b S h e e t A d d E n t r y . M B t n S t a n d a r d E x p i r e s . Click () MyRepo . KeePass . MI_Expires . Click () ’ Save Credential Entry MyRepo . AddEntry . ButtonOK . Click () End Sub End Class Note: By default the class name of a repository is the same as the repository file name (*.rxrep) shown in the project’s view. Now the class uses a private member to refer to the repository in order to reuse some of the objects (’Title’, ’Username’, ’Password’, ’PasswordRepeat’ and ’URL’) within the ’Run’ method. 169 Lesson 7: Code Modules Figure 236: 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. 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 Starting with Ranorex 3.3 it’s 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. Note: Screenshots will be captured automatically if you chose to record image based. Get more information here: Image-Based Automation. 170 Lesson 7: Code Modules Figure 237: Screen shot captured in repository C# // get the screenshot from the repository Bitmap MyScreenshot = MyRepo . IconPicker . LI_IconInfo . G e t S c r e e n s h o t _ I c o n () ; // create FindOptions with similarity set to 95% Imaging . FindOptions MyFindOptions = new Imaging . FindOptions (0.95) ; // compare the captured screenshot with the actual list item Validate . CompareImage ( MyRepo . IconPicker . LI_Icon , MyScreenshot , MyFindOptions ) ; VB.NET ’ get the screenshot from the repository Dim MyScreenshot As Bitmap = MyRepo . IconPicker . LI_IconInfo . G e t S c r e e n s h o t _ I c o n () ’ create FindOptions with similarity set to 95% Dim MyFindOptions As New Imaging . FindOptions (0.95) ’ compare the captured screenshot with the actual list item Validate . CompareImage ( MyRepo . IconPicker . LI_Icon , MyScreenshot , MyFindOptions ) Note: Using the FindOptions, you can set custom values like ’similarity’. This option allows you to define the minimum similarity that the image region to search for needs to have in common with the screenshot in order to be considered a match. For further details have a look at Lesson 5: Ranorex Recorder - Image-Based Automation. 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’. 171 Lesson 7: Code Modules Figure 238: Add a new variable to your code module Figure 239: 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 ’’ and a private member ’ ’. _ Public Property varTitle () As String Get Return _varTitle End Get Set _varTitle = value End Set End Property 172 Lesson 7: Code Modules Now create additional variables for the ’Username’, ’Password’ and ’URL’. All the module variables will appear immediately in the module browser. Figure 240: 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 KeePass’s ’Add Entry Dialog’) are easily accessible via the repository, even from code. In order to bind these variables to external data (e.g. one row in our Excel file) in a code module you have to create a new module variable to act as a bridge between external data and repository variables. Following such an approach, it is obviously best to use the setter methods for public variables. A public variable’s setter method is called every time the value of this variable is set; i.e. assigning the value to the private variable holding the information for the public property. This method can easily be extended in order to set the repository variable as well. First two new module variables, ’varExpires’ and ’varIconIndex’, have to be created the same way as was shown for ’varTitle’, ’varPassword’. After that, a simple code line has to be inserted into the setter method for each variable. This code line is used for assigning the passed value to the repository variable and facilitates binding to external data. C# string _ v a r R e po I c o n I n d e x = ' 1 ' ; [ TestVariable ( ' EF09BC93 -3447 -4 AC2 -9 DEB - FE3D78ED5538 ' ) ] public string va r R e p o I c o n I n d e x { get { return _ v a r R e p o I c o n I n d e x ; } set { _ v a r R e p o I c o n I n d e x = value ; // Additionally set the Repository Variable in Setter - Method MyRepo . varIconIndex = _ v a r R e p o I c o n I n d e x ; } } string _ va r Re po Ex p ir es = ' 1 Year ' ; 173 Lesson 7: Code Modules [ TestVariable ( ' D0A54427 -68 FF -4 B9D - B861 -4882 BCEC846B ' ) ] public string varRepo Expires { get { return _v ar Re p oE xp ir e s ; } set { _ va rR ep o Ex pi re s = value ; // Additionally set the Repository Variable in Setter - Method MyRepo . varExpires = _ v ar Re po E xp ir es ; } } VB.NET Private _ v a r R e p o I c o n I n d e x As String = ' 1 ' < testvariable ( ' ef09bc93 -3447 -4 ac2 -9 deb - fe3d78ed5538 ' ) > _ Public Property v a r R e p o I c o n I nd e x () As String Get Return _ v a r R e p o I c o n I n d e x End Get Set _ v a r R e p o I c o n I n d e x = value ’ Additionally set the Repository Variable in Setter - Method MyRepo . varIconIndex = _ v a r R e p o I c o n I n d e x End Set End Property Private _v ar R ep oE xp i re s As String = ' 1 Year ' < testvariable ( ' d0a54427 -68 ff -4 b9d - b861 -4882 bcec846b ' ) > _ Public Property varR epoExpi res () As String Get Return _ va r Re po Ex p ir es End Get Set _ va rR ep o Ex pi re s = value ’ Additionally set the Repository Variable in Setter - Method MyRepo . varExpires = _ v ar Re po E xp ir es End Set End Property 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. Figure 241: Drag and drop the code module into a test case and combine it with recordings 174 Lesson 7: Code Modules Now you can reuse the existing data connector created during Lesson 3: Ranorex . Report . Debug ( ' This is a Debug Information ' ) ; Ranorex . Report . Info ( ' This is a Information ' ) ; // Setting Parameter Category to specific value and report a warning and an error Ranorex . Report . Warn ( ' Specific Category ' ,' This is a Warning Information ' ) ; Ranorex . Report . Error ( ' Specific Category ' , ' This is an Error Information ' ) ; // Setting the Default Category Ranorex . Report . De f au lt Ca t eg or y = ' My new default category ' ; // Reporting information ( success , failure ) using the new default category Ranorex . Report . Success ( ' This is a success information ' ) ; Ranorex . Report . Failure ( ' This is a failure Information ' ) ; VB.NET ’ Reporting information ( debug , info ) using default Category ' User ' Ranorex . Report . Debug ( ' This is a Debug Information ' ) Ranorex . Report . Info ( ' This is a Information ' ) ’ Setting Parameter Category to specific value and report a warning and an error Ranorex . Report . Warn ( ' Specific Category ' , ' This is a Warning Information ' ) Ranorex . Report . Error ( ' Specific Category ' , ' This is an Error Information ' ) ’ Setting the Default Category Ranorex . Report . De f au lt Ca t eg or y = ' My new default category ' ’ Reporting information ( success , failure ) using the new default category Ranorex . Report . Success ( ' This is a success information ' ) Ranorex . Report . Failure ( ' This is a failure Information ' ) 186 Lesson 8: Reporting Figure 254: 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 M y N ew R e p o r t L e v e l = new ReportLevel ( ' My low Report Level ' , 25 , null ) ; Ranorex . Report . Log ( MyNewReportLevel , ' This is unimportant information ' ) ; VB.NET Dim M y N e w R e p o rt L e v e l 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: 187 Lesson 8: Reporting Figure 255: Report with information for a user-defined level Current Report Level Report information will only appear in the report if its report level is higher than or equal to the current report information level from the parent’s test container. The current report level can also be set using code: C# Ranorex . Report . C u r r e n t R e p o r t L e v e l = Ranorex . ReportLevel . Parse ( ' Only Highest Importance ;90 ' ) ; VB.NET Ranorex . Report . C u r r e n t R e p o r t L e v e l = Ranorex . ReportLevel . Parse ( ' Only Highest Importance ;90 ' ) This assignment causes the inclusion of reporting information only at a level greater than 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. 188 Lesson 8: Reporting Figure 256: 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 ' ) ; 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 ) 189 Lesson 8: Reporting Figure 257: 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). 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 258: System summary provided by Report.SystemSummary() 190 Lesson 8: Reporting 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 ’LogMessage’ Action. Figure 259: Add a new log message action to your recording Predefined Report Level Just like a call from code, you can specify one of the predefined report levels directly within the recorder’s actions table. 191 Lesson 8: Reporting Figure 260: Define the report level Custom Report Level Report messages with a custom report level can also be submitted. Simply type the custom report level into column ’Level’ in the action table following this format: name for the custom report level, a semicolon, and the priority as a number. To use a custom report level named ’Custom’ with priority 50 type: Custom;50 Figure 261: 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 recorder’s 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 262: Usage of the report action using the screenshot and the snapshot action type Updating the Custom Report Format Ranorex 4.0.0 Starting 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. 192 Lesson 8: Reporting Figure 263: 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 264: Choose resolve option Ranorex 7.0 Please refer to the online guide on upgrading custom report templates created in versions before Ranorex 7.0. Create a Custom Report Template To create a custom report template, open the test suite’s properties dialog, navigate to tab page ’Report’ and click the ’Create Custom Template’ button in the ’Report Template’ area. 193 Lesson 8: Reporting Figure 265: Create a custom report template A new report template folder has automatically been created at ’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 266: Show all files in project view Open the file ’RanorexReport5.css’ to edit the style of the report according to your wishes. 194 Lesson 8: Reporting Note: It’s recommended to make customizations at the end of the file. Open the file ’RanorexReport5.xsl’ to edit the structure of the report according to your wishes. Open the file ’View.rxlog’ to get a preview of your customizations using some sample data. Figure 267: Preview of customizations 195 Lesson 9: Ranorex Spy 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 268: 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 computer’s desktop with all currently opened applications. The name of the root node is set to the machine’s host name. By selecting one of the elements from the browser tree, the Spy provides more detailed information about the selected item in the tabs ’Overview’, ’Detail’ and ’Screenshot’ shown on the right. Ranorex recognizes over 30 of the most commonly known types of UI elements. In Ranorex vocabulary they are called ’adapters’. Every element shown within the element tree of Ranorex Spy is represented by 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’ 196 Lesson 9: Ranorex Spy Figure 269: 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 197 Lesson 9: Ranorex Spy 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 270: 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 box’s RanoreXPath Edit Mode. Note: You are able to access common text functionality like ’Select All’ (+A), ’Copy’ (+C), ’Cut’ (+X), ’Paste’ (+V), ’Undo’ (+Z) or ’Delete’ ( 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. 198 Lesson 9: Ranorex Spy Figure 271: 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. 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 >, >=, ’: 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 ’). Figure 296: Matches all entries that start with ’adm’ Figure 297: Result from the comparison above Example for Numerical Comparisons The following examples demonstrates how numerical operators (>, >=, File, or Add > New Item in the context menu. 3. In the opened Dialog, choose ’User Code Collection’ and enter a suitable file name. Figure 364 4. The code file is added to the project and opened. An empty class with the attribute ’[UserCodeCollection]’ is automatically generated. Only classes with this attribute will be listed in the library. 302 User Code Library Figure 365 Follow these steps to add a user code method to a user code collection: 1. Place the mouse cursor between the brackets of the class. 2. Open the context menu and click ’Insert New User Code Method’. Figure 366 3. Fill in a suitable method name for the new user code method and press OK. 303 User Code Library Figure 367 4. The stub for the new method is created. All user code methods have to be attributed with ’[UserCodeMethod]’ to be available in the user code library. Figure 368 5. Write the code for the new method. 6. Update the summary to provide a suitable description. This description will be available in the library and helps your colleagues in finding the method they are looking for. 304 User Code Library Using the User Code Library Where to find the user code library You can directly access the user code library from the action table. Simply click ’Add New Action’ in the menu to select a method from the library. Figure 369 How does the user code library look like? All collections and their methods within a test automation solution are available in the user code library and displayed in aphabetical order. 305 User Code Library Figure 370 When you select a collection or method, its description is automatically displayed. You are looking for a specific collection or method? Then you can use the search and filter functionality above the list. The keyword you enter will be used to filter the library content for method names, namespaces and descriptions. Add a user code method from user code library 1. Choose a user code method from the list. 306 User Code Library Figure 371 2. Confirm your selection by pressing the button ”Confirm Selection”. The selected user code method will be added as action to the recording. 307 User Code Library Figure 372 308 Endpoints Endpoints Endpoints are the gateways through which a locally executed test exchanges data with an external AUT. In simpler words, they allow you to test an external application or system as if it were on your machine. The endpoint pad allows you to view and add endpoints. Open the pad by clicking on ”View Endpoints” in the toolbar. Figure 373 Adding your first endpoint If you havent added any endpoints yet, the welcome screen will be shown. 309 Endpoints Figure 374 310 Endpoints Click on ”Add endpoint” to continue and follow the instructions for adding an Android, iOS, or WebDriver endpoint. Adding additional endpoints If youve added an endpoint before, the Endpoint list will appear and the pad will look like this: Figure 375 Click on the ”+” sign to continue and follow the instructions for adding an Adding Android endpoint, Adding iOS endpoint, or Adding WebDriver endpointendpoint. Shortcuts and command line execution When building a solution, shortcut files for each endpoint are created in the output folder where the test executable is saved as well. These shortcuts allow you to execute the test directly on a specific endpoint. 311 Endpoints Figure 376 You can also do this by using the Running Tests via Command Line ”endpoint”. 312 Endpoints Endpoint list The endpoint list shows the desktop computer you are running Ranorex Studio on and all endpoints added. The endpoints are categorized according to their type (Android, iOS, WebDriver) and displayed with their name, address, and connection status (Connected, Offline, Error). You can search the listed endpoints by name using the search bar at the top. Figure 377 Set as automation root Click the icon to the left of an endpoint to activate it as automation root. The run buttons in the Ranorex Studio toolbar and the test suite toolbar will change accordingly. Once an endpoint has been activated, tests can only interact with this endpoint and will receive and send all data for test execution through this endpoint. 313 Endpoints Figure 378 The endpoint is not the automation root. Click it to set the endpoint as automation root. Figure 379 The endpoint is the automation root. Figure 380 Run button in the Ranorex Studio toolbar when a mobile device or WebDriver endpoint is set as automation root. 314 Endpoints Figure 381 Run button in the test suite toolbar when a mobile device or WebDriver endpoint is set as automation root. Endpoint options Click the icon to the right of an endpoint to display a set of options for it. The available options change depending on the endpoint type. Set as automation root: Does the same as clicking the icon to the left of an endpoint (see above). View Details: Displays a detailed view of the endpoints properties. For Android or iOS endpoints, you will also see a list of the instrumented apps on the device. Click on the icon to the right of an app to start the instrumented app on the device. Click on the rocket button at the bottom to instrument and deploy an app on the device. For further information, please refer to the Android and iOS instrumentation chapters of the user guide. Instrument and deploy app*: Allows you to instrument and deploy an app on the device. For further information, please refer to the Android and iOS instrumentation chapters of the user guide. Save ADB log**: Allows you to save the log file of the ADB (Android debug bridge). Refresh*: Refreshes the connection to the endpoint. Delete: Deletes the endpoint form the endpoint list. * only available for Android and iOS endpoints ** only available for Android endpoints 315 Endpoints Figure 382: Endpoint options for desktop 316 Endpoints Figure 383: Endpoint options for Android endpoints 317 Endpoints Figure 384: Endpoint options for iOS endpoints 318 Endpoints Figure 385: Endpoint options for WebDriver endpoints 319 Endpoints Adding Android endpoint 1. Open the endpoint pad. 2. If you haven’t added an endpoint yet, click on ”Add endpoint” to continue. If you have added an endpoint before, click on the ”+” sign to continue. 3. Select Android from the list in step 1. 4. You will now need to prepare your device so it can be added as an endpoint. First, install the RxService App on the device. You can do so by scanning the QR code or by downloading the required files from ranorex.com/RxApp. Then connect your device to the same network as the computer you are running Ranorex Studio on. Alternatively, you can also connect it directly to the computer via USB. Finally, start the RxService App on your device. 5. Your device should now appear in the list at the bottom. Select it. If you want to change the name of the device as it will appear in the Endpoint list, click on ”Other Device” and enter a new name in the ”Endpoint name” field. Do not change the IP address or device serial (USB). 6. Finally, click on ”Add endpoint”. 320 Endpoints 321 Endpoints Note: If your device is missing from the list, try clicking the refresh button. You can also add a device manually by clicking on ”Other Device”. Choose an endpoint name and enter the devices IP address or USB serial. Click on ”Add endpoint”. You have successfully added the device. It will now appear in the endpoint list. Click on ”Add endpoint” to add another device or on ”Complete setup” to return to the endpoint list. 322 Endpoints Adding iOS endpoint 1. Open the endpoint pad. 2. If you haven’t added an endpoint yet, click on ”Add endpoint” to continue. If you have added an endpoint before, click on the ”+” sign to continue. 3. Select iOS from the list in step 1. 4. You will now need to prepare your device so it can be added as an endpoint. First, install the RxService App on the device. You can do so by scanning the QR code or by downloading the required files from ranorex.com/RxApp. Then connect your device to the same network as the computer you are running Ranorex Studio on. Alternatively, you can also connect it directly to the computer via USB. Finally, start the RxService App on your device. 5. Your device should now appear in the list at the bottom. Select it. If you want to change the name of the device as it will appear in the Endpoint list, click on ”Other Device” and enter a new name in the ”Endpoint name” field. Do not change the IP address or device serial (USB). 6. Finally, click on ”Add endpoint”. 323 Endpoints 324 Endpoints Note: If your device is missing from the list, try clicking the refresh button. You can also add a device manually by clicking on ”Other Device”. Choose an endpoint name and enter the devices IP address or USB serial. Click on ”Add endpoint”. You have successfully added the device. It will now appear in the endpoint list. Click on ”Add endpoint” to add another device or on ”Complete setup” to return to the endpoint list. 325 Endpoints Adding WebDriver endpoint 1. Open the endpoint pad. 2. If you haven’t added an endpoint yet, click on ”Add endpoint” to continue. If you have added an endpoint before, click on the ”+” sign to continue. 3. Select WebDriver from the list in step 1. 4. Choose a name for the Selenium Server you want to add and enter its URL or IP address. 5. Click on ”Test connection” to check whether the Selenium Server can be connected to. If this fails, make sure youve entered the endpoint address correctly and that the endpoint is connected to an accessible network or the Internet. 6. Finally, click on ”Add endpoint”. 326 Endpoints Figure 388 327 Endpoints You have successfully added the WebDriver endpoint. It will now appear in the endpoint list. Click on ”Add endpoint” to add another device or on ”Complete setup” to return to the endpoint list. 328 Selenium WebDriver integration Selenium WebDriver integration With the Selenium WebDriver integration, you can run web tests created with Ranorex on different browsers, operating systems, and machines without any plug-ins or add-ons. Ranorex uses the existing Selenium WebDriver infrastructure torun web tests on: Microsoft Edge, Google Chrome, Mozilla Firefox, and Chromium on Microsoft Windows Apple Safari, Google Chrome, and Mozilla Firefox on Apple macOS Google Chrome and Mozilla Firefox on Linux Note: Web tests still have to be recorded locally. You will need Ranorex Studio, a locally installed web browser with activated Ranorex automation add-on, and your local computer has to be set as automation root in the Endpoint list. Ranorex Studio supports the following OS + browser combinations for web-test recording: Microsoft Windows + Microsoft Internet Explorer, Google Chrome, Mozilla Firefox, and Chromium. Quick-start guide for Selenium WebDriver integration in Ranorex 1. Setting up a Selenium WebDriver infrastructurea Selenium WebDriver infrastructure. 2. Running Selenium ServerSelenium Standalone Server. 3. Adding WebDriver endpoint to Ranorex Studio. 4. Record your web test on your local machine or use an existing one. 5. Review the web test following these Web test guidelines. 6. Set the WebDriver endpoint as Endpoint list. 7. Run the test Suite. Setting up a Selenium WebDriver infrastructure This chapter only provides a basic introduction. For complete documentation of the Selenium WebDriver infrastructure, please visit the official Selenium web site. For a basic setup, you will need: The Java Runtime Environment A Selenium Server Download the latest version of Selenium Standalone Server and place it into a folder. Drivers for the web browser you want Selenium Server to automate All related links and setup steps can be found here. Download the correct driver for your platform, unpack if needed, and place into the same folder as Selenium Standalone Server. 329 Selenium WebDriver integration Running Selenium Server Before adding an endpoint or running a test you need to start the server. Open a command line console and switch to the folder containing Selenium Standalone Server. Execute the following command: java -jar selenium-server-standalone-.jar Replace ”” with the version number of the downloaded Selenium Standalone Server file. The window has to remain open. Web test guidelines Selenium WebDriver differs from the web testing capabilities that Ranorex offers for desktop-based web tests. After recording a web test on your local web browser, follow these steps to make it compatible for execution with Selenium WebDriver: Remove all actions and repository items which interact with the web browser application itself. Use the Close Application action for closing the web browser. Please also refer to the Ranorex 7.0 release notes. They contain important information about the Selenium WebDriver integration. 330 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 Using the Validate Class Forcing a Test Case to Fail using Exceptions 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 Advanced Validation - Clipboard Advanced Validation - Whole Table Advanced Validation - Whole Table in Web Advanced Validation - File (text-based) Advanced Validation - File (non text-based, binary) Advanced Validation - Database (Single Field) Advanced Validation - Database (Whole Table) Advanced Validation - XML code Using Repository in Code C# [ TestModule ( ' D451F1D1 - C347 -4 B58 -939 F - F6187642EB56 ' , ModuleType . UserCode , 1) ] public class Us i ng Re po s it or y : ITestModule { // Repository object to access UI elements M y F i r s t T e s t P r o j e c t R e p o s i t o r y repo = M y F i r s t T e s t P r o j e c t R e p o s i t o r y . Instance ; // / < summary > // / Constructs a new instance . // / public U si n gRep os i to ry () { // Do not delete - a parameterless constructor is required ! } void ITestModule . Run () 331 Code Examples { Mouse . D ef a ul tM ov e Ti me = 300; Keyboard . D e f a u l t K e y P r e s s T i m e = 100; Delay . SpeedFactor = 1.0; // Using Ranorex . Form adapter represented by ’ MyApp ’ // ’ MyApp ’ is used as a folder within the repository ; // the ’ Self ’ property returns an object of type Ranorex . Form // Activates application repo . MyApp . Self . Activate () ; // Log ’ Active ’ state Report . Info ( repo . MyApp . Self . Active . ToString () ) ; // Maximize , Minimize and Restore repo . MyApp . Self . Maximize () ; repo . MyApp . Self . Minimize () ; repo . MyApp . Self . Restore () ; // Closes application repo . MyApp . Self . Close () ; // Using Ranorex . Button adapter represented by ’ ButtonAdd ’ // Read and log value of ’ Text ’ attribute Report . Info ( repo . MyApp . Buttons . ButtonAdd . Text ) ; // Press button repo . MyApp . Buttons . ButtonAdd . Press () ; // Read and log value of ’ Enabled ’ attribute Report . Info ( repo . MyApp . Buttons . ButtonAdd . Enabled . ToString () ) ; // Using Ranorex . RadioButton adapter // represented by ’ GenderOption ’ // Select radio button repo . MyApp . GenderOption . Select () ; // Accessing listitems of Ranorex . List adapter // represented by ’ CategoryList ’ IList < ranorex . listitem > listItems = repo . MyApp . CategoryList . Items ; foreach ( Ranorex . ListItem item in listItems ) { Report . Info ( item . Text + ' is member of CategoryList ' ) ; } // Using Ranorex . MenuItem to open ’ File ’ menu repo . MyApp . MenuItemFile . Select () ; // Selecting sub menu item ’ Connect ’ repo . FileMenu . Connect . Select () ; // Read and log ’ Enabled ’ state of menu item ’ Connect ’ Report . Info ( repo . FileMenu . Connect . Enabled . ToString () ) ; } } VB.NET Public Class Us i ng Re po s it or y Implements ITestModule ’ Repository object to access UI elements Private repo As M y F i r s t T e s t P r o j e c t R e p o s i t o r y = M y F i r s t T e s t P r o j e c t R e p o s i t o r y . Instance ’ ’’ < summary > ’ ’’ Constructs a new instance . ’ ’’ ’ Do not delete - a parameterless constructor is required ! Public Sub New () End Sub ’ ’’ < summary > ’ ’’ Performs the playback of actions in this module . ’ ’’ ’ ’’ < remarks > You should not call this method directly , instead pass the module ’ ’’ instance to the < see cref =' T e s t M o d u l e R u n n e r . Run ( ITestModule ) ' > method ’ ’’ that will in turn invoke this method . Private Sub IT e st Mo du l e_ Ru n () Implements ITestModule . Run Mouse . D ef a ul tM ov e Ti me = 300 Keyboard . D e f a u l t K e y P r e s s T i m e = 100 Delay . SpeedFactor = 1.0 ’ Using Ranorex . Form adapter represented by ’ MyApp ’ ’ ’ MyApp ’ is used as a folder within the repository ; ’ the ’ Self ’ property returns a Ranorex . Form object 332 Code Examples ’ Activates application repo . MyApp . Self . Activate () ’ Log ’ Active ’ state Report . Info ( repo . MyApp . Self . Active . ToString () ) ’ Maximize , Minimize and Restore repo . MyApp . Self . Maximize () repo . MyApp . Self . Minimize () repo . MyApp . Self . Restore () ’ Closes application repo . MyApp . Self . Close () ’ Using Ranorex . Button adapter represented by ButtonAdd ’ ’ Read and log value of ’ Text ’ attribute Report . Info ( repo . MyApp . Buttons . ButtonAdd . Text ) ’ Press button repo . MyApp . Buttons . ButtonAdd . Press () ’ Read and log value of ’ Enabled ’ attribute Report . Info ( repo . MyApp . Buttons . ButtonAdd . Enabled . ToString () ) ’ Using Ranorex . RadioButton adapter ’ represented by ’ GenderOption ’ ’ Select radio button repo . MyApp . GenderOption .[ Select ]() ’ Accessing listitems of Ranorex . List adapter ’ represented by ’ CategoryList ’ Dim listItems As IList ( Of Ranorex . ListItem ) = repo . MyApp . CategoryList . Items For Each item As Ranorex . ListItem In listItems Report . Info ( item . Text & ' is member of CategoryList ' ) Next ’ Using Ranorex . MenuItem to open ’ File ’ menu repo . MyApp . MenuItemFile .[ Select ]() ’ Selecting sub menu item ’ Connect ’ repo . FileMenu . Connect .[ Select ]() ’ Read and log ’ Enabled ’ state of menu item ’ Connect ’ Report . Info ( repo . FileMenu . Connect . Enabled . ToString () ) End Sub End Class Wait for UI Elements Using Repository Each item and each folder type provides an additional object item declared with ’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 [ @ ac ce ss i bl en am e = ’ Online ’] // This way you can wait with the timeout specified for // the item within the repository for the text ’ Online ’ bool s t a t u s T e x t C o n n e c t e d = repo . MyApp . Te xtOnline Info . Exists () ; // Using ’ Info ’ objects for validation // Throws a Ranorex . V a l i d a t i o n E x c e p t i o n if validation // fails . Automatically reports success or failed message // to log file Validate . Exists ( repo . SaveDialog . ButtonOKInfo ) ; // Validates the existence of the repository item , // but does not throw any exception Validate . Exists ( repo . SaveDialog . ButtonOKInfo , ' Check Object ’{0} ’ ' , false ) ; 333 Code Examples VB.NET ’ Use the ’ Info ’ object to check existence of the ’ ’ SaveDialog ’ item ; Method ’ Exists ’ uses the timeout ’ specified for the ’ SaveDialog ’ in the repository Report . Info ( ' Exists = ' & repo . SaveDialog . SelfInfo . Exists () . ToString () ) ’ Use the ’ Info ’ object to check existence of the ’ ’ TextOnline ’ item which uses the following RXPath : ’ statusbar / text [ @a c ce ss ib l en am e = ’ Online ’] ’ This way you can wait with the timeout specified for ’ the item within the repository for the text ’ Online ’ Dim s t a t u s T e x t C o n n e c t e d As Boolean = repo . MyApp . Te xtOnline Info . Exists () ’ Using ’ Info ’ objects for validation ’ Throws a Ranorex . V a l i d a t i o n E x c e p t i o n if validation ’ fails . Automatically reports success or failed message ’ to log file Validate . Exists ( repo . SaveDialog . ButtonOKInfo ) ’ Validates the existence of the repository item , ’ but does not throw any exception Validate . Exists ( repo . SaveDialog . ButtonOKInfo , ' Check Object ’{0} ’ ' , False ) 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 repository’s 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 '.. Info ' object Ranorex . NativeWindow nativeWnd = repo . MyApp . SelfInfo . CreateAdapter < Ranorex . NativeWindow >( false ); // .. and read value of attribute ’ ProcessName ’ Report . Info ( ' Process name of VIP Database : ' + nativeWnd . ProcessName ) ; // Using Control Adapter to access properties and methods of // . NET WinForms control Ranorex . Control w i nF or ms C on tr ol = repo . MyApp . SelfInfo . CreateAdapter < Ranorex . Control >( false ) ; // Set background color of VIP application to Color . Black using the // exposed property ’ BackColor ’ w in Fo rm s Co nt ro l . S e t P r o p e rt y V a l u e ( ' BackColor ' , Color . Black ) ; // Report screenshot after changing the background color Report . Screenshot ( repo . MyApp . Self ) ; // Closes VIP Database by invoking the ’ Close ’ method // exposed by the System . Windows . Forms . Form class w in Fo rm s Co nt ro l . InvokeMethod ( ' Close ' ) ; VB.NET ’ Creating adapter of type ’ NativeWindow ’ using the '.. Info ' object Dim nativeWnd As Ranorex . NativeWindow = repo . MyApp . SelfInfo . CreateAdapter ( Of Ranorex . NativeWindow ) ( False ) ’ .. and read value of attribute ’ ProcessName ’ Report . Info ( ' Process name of VIP Database : ' & nativeWnd . ProcessName ) ’ Using Control Adapter to access properties and methods of ’ . NET WinForms control Dim w in Fo r ms Co nt r ol As Ranorex . Control = repo . MyApp . SelfInfo . CreateAdapter ( Of Ranorex . Control ) ( False ) ’ Set background color of VIP application to Color . Black using the ’ exposed property ’ BackColor ’ 334 Code Examples w in Fo rm s Co nt ro l . S e t P r o p e rt y V a l u e ( ' BackColor ' , Color . Black ) ’ Report screenshot after changing the background color Report . Screenshot ( repo . MyApp . Self ) ’ Closes VIP Database by invoking the ’ Close ’ method ’ exposed by the System . Windows . Forms . Form class w in Fo rm s Co nt ro l . InvokeMethod ( ' Close ' ) Note: In order to access properties or methods exposed by a WinForms control you need to know their names. If you’re not familiar with the control’s API ask the developer of your application for assistance. 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 . E n a b l e d B u t t o n s I n f o . CreateAdapters < ranorex . button >() ; // Move the mouse pointer to each button of the list // and add a screenshot for each to the report foreach ( Ranorex . Button button in buttonList ) { button . MoveTo () ; Report . Screenshot ( button ) ; } VB.NET ’ Create a list of adapters using the ' Info ' object Dim buttonList As IList ( Of Ranorex . Button ) = repo . MyApp . E n a b l e d B u t t o n s I n f o . CreateAd apters ( Of Ranorex . Button ) () ’ Move the mouse pointer to each button of the list ’ and add a screenshot for each to the report For Each button As Ranorex . Button In buttonList button . MoveTo () Report . Screenshot ( button ) Next Learn more about how to create repository items delivering multiple elements here: Repository Items Representing Multiple Elements 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# 335 Code Examples // Validate for Existence // Using ’ Info ’ objects for validation // Throws a Ranorex . V a l i d a t i o n E x c e p t i o n if validation // fails . Automatically reports success or failed message // to log file Validate . Exists ( repo . SaveDialog . ButtonOKInfo ) ; // Validates the existence of the repository item , // but does not throw any exception bool exists = Validate . Exists ( repo . SaveDialog . ButtonOKInfo , ' Check Object ’{0} ’ ' , false ) ; // Check whether an application form exists using a RanoreXPath Validate . Exists ( ' / form [ @controlname = ’ formVipApplication ’] ' ) ; // Check whether an application does not exists // for the time specified as timeout for the given repository item Validate . NotExists ( repo . MyApp . SelfInfo ) ; // Validate ’ Enabled ’ attribute of button ’ Delete ’ Validate . Attribute ( repo . MyApp . Buttons . ButtonDeleteInfo , ' Enabled ' , false ) ; VB.NET ’ Validate for Existence ’ Using ’ Info ’ objects for validation ’ Throws a Ranorex . V a l i d a t i o n E x c e p t i o n if validation ’ fails . Automatically reports success or failed message ’ to log file Validate . Exists ( repo . SaveDialog . ButtonOKInfo ) ’ Validates the existence of the repository item , ’ but does not throw any exception Dim exists As Boolean = Validate . Exists ( repo . SaveDialog . ButtonOKInfo , ' Check Object ’{0} ’ ' , false ) ’ Check whether an application form exists using a RanoreXPath Validate . Exists ( ' / form [ @controlname = ’ formVipApplication ’] ' ) ’ Check whether an application does not exists ’ for the time specified as timeout for the given repository item Validate . NotExists ( repo . MyApp . SelfInfo ) ’ Validate ’ Enabled ’ attribute of button ’ Delete ’ Validate . Attribute ( repo . MyApp . Buttons . ButtonDeleteInfo , ' Enabled ' , false ) Note: Each method provided by the Validate class allows to suppress exceptions thrown in case of a failed validation. The code snippet above uses only a few validation methods. For further and more detailed explanation of the Ranorex.Validate class see the API documentation. Forcing a Test Case to Fail Using the Validate Class As described above you can use the Validate class to compare values from UI and non UI related objects bringing a test to fail or success. Additional to this, you can force a test case to fail without comparing using the Validate class. C# Ranorex . Cell cellObject = null ; // Try to find a cell object bool found = false ; found = Host . Local . TryFindSingle < Ranorex . Cell >( ' / form // table / row / cell [3] ' , 2000 , out cellObject ) ; // If the expressions does not return an object // call Validate . Fail and the test case fails if (! found ) Validate . Fail ( ' RanoreXPath with no return ' ) ; 336 Code Examples VB.NET Dim cellObject As Ranorex . Cell = Nothing ’ Try to find a cell object Dim found As Boolean = False found = Host . Local . TryFindSingle ( Of Ranorex . Cell ) ( ' / form // table / row / cell [3] ' , 2000 , cellObject ) ’ If the expressions does not return an object ’ call Validate . Fail and the test case fails If Not found Then Validate . Fail ( ' RanoreXPath with no return ' ) End If Forcing a Test Case to Fail using Exceptions 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] ' , 2000 , out cellObject ) ; found = found textpipe textpipe Host . Local . TryFindSingle < Ranorex . cell >( ' / form // table / row / cell [4] ' , 2000 , out cellObject ) ; // If none of the expressions returns an object // throw new ’ ElementNotFoundException ’ and test case fails if (! found ) { throw new Ranorex . E l e m e n t N o t F o u n d E x c e p t i o n ( ' Both RanoreXPath with no return ' , null ) ; } else { // If the value of attribute ’ Text ’ does not equal to the expected value // throw new ’ ValidationException ’ to break the test case if ( cellObject . Text ' M y E x p e c t e d T e x t V a l u e ' ) { Report . Success ( ' User Specific Validation ' ,' Text validation of cell object succeeded ' ) ; } else { throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( ' Text validation of cell object succeeded failed ' ) ; } } VB.NET Dim cellObject As Ranorex . Cell = Nothing ’ Try to find a cell object using two ’ different RanoreXPath expressions Dim found As Boolean = Host . Local . TryFindSingle ( Of Ranorex . Cell ) ( ' / form // table / row / cell [3] ' , 2000 , cellObject ) found = found OrElse Host . Local . TryFindSingle ( Of Ranorex . Cell ) ( ' / form // table / row / cell [4] ' , 2000 , cellObject ) 337 Code Examples ’ If none of the expressions returns an object ’ throw new ’ ElementNotFoundException ’ and test case fails If Not found Then Throw New Ranorex . E l e m e n t N o t F o u n d E x c e p t i o n ( ' Both RanoreXPath with no return ' , 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 = ' M y E x p e c t e d T e x t V a l u e ' Then Report . Success ( ' User Specific Validation ' , ' Text validation of cell object succeeded ' ) Else Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( ' Text validation of cell object succeeded failed ' ) 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 . D efa ul tM o ve Ti me = 300; Keyboard . D e f a u l t K e y P r e s s T i m e = 100; Delay . SpeedFactor = 1.0; } VB.NET Private Sub IT e st Mo du l e_ Ru n () Implements ITestModule . Run Mouse . D efa ul tM o ve Ti me = 300 Keyboard . D e f a u l t K e y P r e s s T i m e = 100 Delay . SpeedFactor = 1.0 End Sub Accessing Test Case & Test Suite Context Sometimes it’s 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 case’s data binding dialog to transfer data within a test case. C# // - - - - - - - - - - - - - - - - - Code Block used by Code Module A - - - - - - - - - - - - - - - - // Click ’ Save ’ button to open ’ SaveDialog ’ repo . MyApp . Buttons . ButtonSave . Click () ; // Read text message shown with ’ SaveDialog ’ // and assign it to the variable ’ varDialogTextA ’ bound to a test case parameter varD ialogTex tA = repo . SaveDialog . TextMessage . TextValue ; // - - - - - - - - Code Block used by User Code Action of recording B - - - - - - - - 338 Code Examples // Read value of module variable ’ varDialogTextB ’ in other code module // or recording module using a user code action Report . Info ( varDial ogTextB ) ; // Get the current data context and log // the current row index of a data driven run Report . Info ( TestCase . Current . DataContext . C ur r en tR ow I nd ex . ToString () ) ; VB.NET ’ - - - - - - - - - - - - - - - - - Code Block used by Code Module A - - - - - - - - - - - - - - - - ’ Click ’ Save ’ button to open ’ SaveDialog ’ repo . MyApp . Buttons . ButtonSave . Click () ’ Read text message shown with ’ SaveDialog ’ ’ and assign it to the variable ’ varDialogTextA ’ bound to a test case parameter varD ialogTex tA = repo . SaveDialog . TextMessage . TextValue ’ - - - - - - - - Code Block used by User Code Action of recording B - - - - - - - ’ Read value of module variable ’ varDialogTextB ’ in other code module ’ or recording module using a user code action Report . Info ( varDial ogTextB ) ’ Get the current data context and log ’ the current row index of a data driven run Report . Info ( TestCase . Current . DataContext . C ur r en tR ow I nd ex . ToString () ) 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 : E l em en tN o tF ou nd exception is thrown if item is not found within // the specified timeout of 2000 ms . Ranorex . Button addButtonVar1 = Host . Local . FindSingle < Ranorex . Button >( ' / form [ @controlname = ’ formVipApplication ’]/ button [ @controlname = ’ btAdd ’] ' ,2000) ; addButtonVar1 . MoveTo () ; // Alternatively you can use the ’ TryFindSingle ’ method to prevent // a test case from failing because of an exception thrown if // the element is not found within the specified timeout of 2000 ms Ranorex . Button addButtonVar2 = null ; bool found = Host . Local . TryFindSingle < Ranorex . Button >( ' / form [ @controlname = ’ formVipApplication ’]/ button [ @controlname = ’ btAdd ’] ' , 2000 , out addButtonVar2 ) ; // Move mouse pointer to button addButtonVar2 . MoveTo () ; // Request a list of buttons shown from the VIP Database application // and create a screenshot for each button in the report file IList < Ranorex . Button > buttonList = Host . Local . Find < Ranorex . Button >( ' / form [ @controlname = ’ formVipApplication ’]/ button ' ,500) ; foreach ( Ranorex . Button bt in buttonList ) { Report . Screenshot ( bt ) ; } // Using find methods in combination with existing Ranorex repository items Ranorex . Button btAdd = repo . MyApp . Self . FindSingle < Ranorex . Button >( ' button [ @controlname = ’ btAdd ’] ' ,2000) ; VB.NET 339 Code Examples ’ Create Ranorex . Button adapter using ’ FindSingle ’ method ’ from Host . Local ( starting at root node ) with absolute RanoreXPath ’ Note : E le me n tN ot Fo u nd exception is thrown if item is not found within ’ the specified timeout of 2000 ms . Dim addButtonVar1 As Ranorex . Button = Host . Local . FindSingle ( Of Ranorex . Button ) ( ' / form [ @controlname = ’ formVipApplication ’]/ button [ @controlname = ’ btAdd ’] ' , 2000) addButtonVar1 . MoveTo () ’ Alternatively you can use ’ TryFindSingle ’ method to prevent ’ a test case from failing because of an exception thrown if ’ the element is not found within the specified timeout of 2000 ms Dim addButtonVar2 As Ranorex . Button = Nothing Dim found As Boolean = Host . Local . TryFindSingle ( Of Ranorex . Button ) ( ' / form [ @controlname = ’ formVipApplication ’]/ button [ @controlname = ’ btAdd ’] ' , 2000 , addButtonVar2 ) ’ Move mouse pointer to button addButtonVar2 . MoveTo () ’ Request a list of buttons from the VIP Database application ’ and create a screenshot for each button in the report file Dim buttonList As IList ( Of Ranorex . Button ) = Host . Local . Find ( Of Ranorex . Button ) ( ' / form [ @controlname = ’ formVipApplication ’]/ button ' , 500) For Each bt As Ranorex . Button In buttonList Report . Screenshot ( bt ) Next ’ Using find methods in combination with existing Ranorex repository items Dim btAdd As Ranorex . Button = repo . MyApp . Self . FindSingle ( Of Ranorex . Button ) ( ' button [ @controlname = ’ btAdd ’] ' , 2000) 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% = 0.95) . myRepo . WinFormsApp . Self . Click ( new Location ( bmp , new Imaging . FindOptions (0.95) ) ) ; // OR Set the default Similarity value for all following image operations Imaging . FindOptions . Default . Similarity = 0.95; myRepo . WinFormsApp . Self . Click ( bmp ) ; Report . Success ( ' Image found and clicked successfully ' ) ; VB.NET ’ Create bitmap to search for ’ within application form and ’ click it Dim bmp As Bitmap = Ranorex . Imaging . Load ( ' .. Green Sea Turtle Small . bmp ' ) ’ Performs a right click on the image found ’ within the application window based ’ on the image location myRepo . WinFormsApp . Self . Click ( MouseButtons . Right , bmp ) ’ You can also search for images that are slightly different to the ’ loaded image by specifying the minimum Similarity for a match (95% = 0.95) . 340 Code Examples myRepo . WinFormsApp . Self . Click ( new Location ( bmp , new Imaging . FindOptions (0.95) ) ) ’ OR Set the default Similarity value for all following image operations Imaging . FindOptions . Default . Similarity = 0.95 myRepo . WinFormsApp . Self . Click ( bmp ) Report . Success ( ' Image displayed successfully ' ) 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. 341 Code Examples Figure 389: 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 myP opupWatc her = new PopupWatcher () ; // Add a Watch using a RanoreXPath and triggering the Method C l o s e U p d a t e C h e c k D i a l o g myPo pupWatch er . Watch ( ' / form [ @controlname = ’ UpdateCheckForm ’]/ button [ @controlname = ’ m_btnClose ’] ', CloseUpdateCheckDialog ); // Add a Watch using the info object of a button and triggering the Method CloseUpdateCheckDialog // myP opupWat cher . Watch ( repo . U p d a t e C h e c k D i a l o g . btCloseInfo , C l o s e U p d a t e C h e c k D i a l o g ) ; // Add a Watch using the info object of the dialog and the info object of the button to click // myP opupWat cher . WatchAndClick ( repo . U p d a t e C h e c k D i a l o g . SelfInfo , repo . U p d a t e C h e c k D i a l o g . btCloseInfo ) ; // Add a Watch using a repository folder object and the info object of the button to click // myP opupWat cher . WatchAndClick ( repo . UpdateCheckDialog , repo . U p d a t e C h e c k D i a l o g . btCloseInfo ) ; // Start PopupWatcher myPo pupWatch er . Start () ; } public static void C l o s e U p d a t e C h e c k D i a l o g ( Ranorex . Core . Repository . RepoItemInfo myInfo , Ranorex . Core . Element myElement ) { myElement . As < Ranorex . Button >() . Click () ; } public static void C l o s e U p d a t e C h e c k D i a l o g ( Ranorex . Core . RxPath myPath , Ranorex . Core . Element myElement ) { myElement . As < Ranorex . Button >() . Click () ; } VB.NET 342 Code Examples Private Sub IT e st Mo du l e_ Ru n () Implements ITestModule . Run ’ Create PopupWatcher Dim myPopupW atcher As New PopupWatcher () ’ Add a Watch using a RanoreXPath and triggering the Method C l o s e U p d a t e C h e c k D i a l o g myPop upWatch er . Watch ( ' / form [ @controlname = ’ UpdateCheckForm ’]/ button [ @controlname = ’ m_btnClose ’] ' , AddressOf C l o s e U p d a t e C h e c k D i a l o g ) ’ Add a Watch using the info object of a button and triggering the Method CloseUpdateCheckDialog ’ myPo pupWatc her . Watch ( repo . U p d a t e C h e c k D i a l o g . btCloseInfo , C l o s e U p d a t e C h e c k D i a l o g ) ; ’ Add a Watch using the info object of the dialog and the info object of the button to click ’ myPo pupWatc her . WatchAndClick ( repo . U p d a t e C h e c k D i a l o g . SelfInfo , repo . U p d a t e C h e c k D i a l o g . btCloseInfo ) ; ’ Add a Watch using a repository folder object and the info object of the button to click ’ myPo pupWatc her . WatchAndClick ( repo . UpdateCheckDialog , repo . U p d a t e C h e c k D i a l o g . btCloseInfo ) ; ’ Start PopupWatcher myPo pupWatch er . Start () End Sub Public Shared Sub C l o s e U p d a t e C h e c k D i a l o g ( myInfo As Ranorex . Core . Repository . RepoItemInfo , myElement As Ranorex . Core . Element ) myElement .[ As ]( Of Ranorex . Button ) () . Click () End Sub Public Shared Sub C l o s e U p d a t e C h e c k D i a l o g ( myPath As Ranorex . Core . RxPath , myElement As Ranorex . Core . Element ) myElement .[ As ]( Of Ranorex . Button ) () . Click () End Sub Advanced Validation - Clipboard This sample shows how the current content of the clipboard can be validated against a given reference value. C# public void V a l i d a t e _ C l i p b o a r d C o n t e n t E q u a l ( string compareText , string c u s t o m L o g M e s s a g e ) { // check if content of clipboard is text if ( System . Windows . Forms . Clipboard . ContainsText () ) { // Get text from clipboard string clipboardtext = System . Windows . Forms . Clipboard . GetText () ; // prepare log message if the log - parameter is empty if ( string . IsNullOrEmpty ( clipboardtext ) ) { c u s t o m L o g M e s s a g e = ' Comparing content of clipboard with given text : ({0} vs . {1}) ' ; ; } // Validate if given text ( compareText ) is equal to current text in clipboard Ranorex . Validate . AreEqual ( clipboardtext , compareText , c u s t o m L o g M e s s a g e ) ; } else { throw new Ranorex . R a n o r e x E x c ep t i o n ( ' There is not text on the clipboard that can be compared ' ) ; } } VB.NET Public Sub V a l i d a t e _ C l i p b o a r d C o n t e n t E q u a l ( compareText As String , c u s t o m L o g M e s s a g e As String ) ’ check if content of clipboard is text 343 Code Examples If System . Windows . Forms . Clipboard . ContainsText () Then ’ Get text from clipboard Dim clipboardtext As String = System . Windows . Forms . Clipboard . GetText () ’ prepare log message if the log - parameter is empty If String . IsNullOrEmpty ( clipboardtext ) Then c u s t o m L o g M e s s a g e = ' Comparing content of clipboard with given text : ({0} vs . {1}) ' End If ’ Validate if given text ( compareText ) is equal to current text in clipboard Ranorex . Validate . AreEqual ( clipboardtext , compareText , c u s t o m L o g M e s s a g e ) Else Throw New Ranorex . R a n o r e x E x c ep t i o n ( ' There is not text on the clipboard that can be compared ' ) End If End Sub Advanced Validation - Whole Table This sample shows how the content of a whole table (UI control) can be validated at once. Therefore the table has to be passed as a parameter. Additionally the filename of a Ranorex Snapshot needs to be provided which will act as a reference and defines the expected content of the table. Note: The referencing snapshot has to be created before calling this advanced validation function. Simply select the table in the tree view in Ranorex Spy, right-click and choose ”Save as Snapshot” in the context menu. More information on creating snapshots can be found here: Creating Ranorex Snapshot Files. C# public void V a l i d a t e _ T a b l e C o n t e n t E q u a l ( Ranorex . Adapter repoItem , string f i le n a me _ R ef e r e nc e T ab l e S na p s ho t , string customLogMessageOverall , string customLogMessageDetail ) { // check if snapshot file exists const string fileNotExists = ' The given file does not exist : {0} ' ; if (! System . IO . File . Exists ( f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) ) { throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( string . Format ( fileNotExists , filename_ReferenceTableSnapshot )); } E le me nt S na ps h ot snap = null ; try { snap = Ranorex . Core . El em en t Sn ap sh o t . CreateFr omFile ( f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) ; // E le me n tS na ps h ot . Cre ateFromF ile is available starting with Ranorex 5.4.2 } catch { throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( ' Snapshot could not be loaded from file ' ); } // restore table from snapshot Ranorex . Table refTable ; try { refTable = snap . Element ; } catch { throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( ' Table could not be created from snapshot ' ) ; } var tableAdapter = repoItem . As < Ranorex . Table >() ; if ( tableAdapter null ) { 344 Code Examples throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( ' Repo - item could not be accessed ' ) ; } // check if rowcount is identical if ( tableAdapter . Rows . Count != refTable . Rows . Count ) { throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( String . Format ( ' Tables do not have same number of rows ({0} vs . {1}) ' , tableAdapter . Rows . Count , refTable . Rows . Count ) ) ; } // run through table - rows for ( int iRow = 0; iRow () . Text ; string v a l i d a t i o n M e s s a g e = string . Empty ; if ( string . IsNullOrEmpty ( c u s t o m L o g M e s s a g e D e t a i l ) ) { v a l i d a t i o n M e s s a g e = String . Format ( ' Comparing content of cell ({2}/{3}) ( found : ’{0} ’ , expected : ’{1} ’) ' , aCurText , aRefText , iRow , iCol ) ; } else { validationMessage = customLogMessageDetail ; } // validate whether current text and expected text are identical Ranorex . Validate . AreEqual ( aCurText , aRefText , v a l i d a t i o n M e s s a g e ) ; } } // Log overall success if ( string . IsNullOrEmpty ( c u s t o m L o g M e s s a g e O v e r a l l ) ) c u s t o m L o g M e s s a g e O v e r a l l = ' Successfully completed content - validation of table with provided snapshot of table ( reference ) ' ; Ranorex . Report . Log ( ReportLevel . Success , c u s t o m L o g M e s s a g e O v e r a l l ) ; } VB.NET public Sub V a l i d a t e _ T a b l e C o n t e n t E q u a l ( repoItem As Ranorex . Adapter , f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t As String , c u s t o m L o g M e s s a g e O v e r a l l As String , c u s t o m L o g M e s s a g e D e t a i l As String ) ’ check if snapshot file exists Const fileNotExists As String = ' The given file does not exist : {0} ' If Not System . IO . File . Exists ( f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) Then Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( String . Format ( fileNotExists , filename_ReferenceTableSnapshot )) End If Dim snap As E le m en tS n ap sh ot = Nothing Try snap = Ranorex . Core . El em en t Sn ap sh o t . CreateFr omFile ( f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) ’ E le m en tS na p sh ot . Cre ateFrom File is available starting with Ranorex 5.4.2 Catch Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( ' Snapshot could not be loaded from file ' ) 345 Code Examples End Try ’ restore table from snapshot Dim refTable As Ranorex . Table Try refTable = snap . Element Catch Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( ' Table could not be created from snapshot ' ) End Try Dim tableAdapter = repoItem .[ As ]( Of Ranorex . Table ) () If tableAdapter Is Nothing Then Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ( ' Repo - item could not be accessed ' ) End If ’ check if rowcount is identical If tableAdapter . Rows . Count refTable . Rows . Count Then Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ([ String ]. Format ( ' Tables do not have same number of rows ({0} vs . {1}) ' , tableAdapter . Rows . Count , refTable . Rows . Count ) ) End If ’ run through table - rows For iRow As Integer = 0 To tableAdapter . Rows . Count - 1 Dim cellCountCur As Integer = tableAdapter . Rows ( iRow ) . Cells . Count Dim cellCountRef As Integer = refTable . Rows ( iRow ) . Cells . Count ’ check if number of cells is identical in current row If cellCountCur cellCountRef Then Throw New Ranorex . V a l i d a t i o n E x c e p t i o n ([ String ]. Format ( ' Table - Rows do not have same number of cells ({0} vs . {1}) ' , cellCountCur , cellCountRef ) ) End If ’ run through cells in current row For iCol As Integer = 0 To cellCountCur - 1 Dim aCurText As String = tableAdapter . Rows ( iRow ) . Cells ( iCol ) .[ As ]( Of Ranorex . Cell ) () . Text Dim aRefText As String = refTable . Rows ( iRow ) . Cells ( iCol ) .[ As ]( Of Ranorex . Cell ) () . Text Dim v a l i d a t i o n M e s s a g e As String = String . Empty If String . IsNullOrEmpty ( c u s t o m L o g M e s s a g e D e t a i l ) Then v a l i d a t i o n M e s s a g e = [ String ]. Format ( ' Comparing content of cell ({2}/{3}) ( found : ’{0} ’ , expected : ’{1} ’) ' , aCurText , aRefText , iRow , iCol ) Else validationMessage = customLogMessageDetail End If ’ validate whether current text and expected text are identical Ranorex . Validate . AreEqual ( aCurText , aRefText , v a l i d a t i o n M e s s a g e ) Next Next ’ Log overall success If String . IsNullOrEmpty ( c u s t o m L o g M e s s a g e O v e r a l l ) Then c u s t o m L o g M e s s a g e O v e r a l l = ' Successfully completed content - validation of table with provided snapshot of table ( reference ) ' End If Ranorex . Report . Log ( ReportLevel . Success , c u s t o m L o g M e s s a g e O v e r a l l ) End Sub Advanced Validation - Whole Table in Web This sample shows how the content of a whole web table (HTML tag table) can be validated at once. Therefore the table has to be passed as a parameter. Additionally the filename of a Ranorex Snapshot needs to be provided which will act as a reference and defines the expected content of the web table. Note: The referencing snapshot has to be created before calling this advanced validation function. Simply select the table in the tree view in Ranorex Spy, right-click and choose ”Save as Snapshot” in the context menu. More information on creating snapshots can be found here: Creating Ranorex Snapshot Files. 346 Code Examples C# public void V a l i d a t e _ W e b T a b l e C o n t e n t E q u a l ( Ranorex . Adapter repoItem , string f i le n a me _ R ef e r e nc e T ab l e S na p s ho t , string customLogMessageOverall , string customLogMessageDetail ) { // check if snapshot file exists Ranorex . Validate . IsTrue ( System . IO . File . Exists ( f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) , string . Format ( ' Checking existence of snapshot file : {0} ' , filename_ReferenceTableSnapshot )); E le me nt S na ps h ot snap ; try { snap = Ranorex . Core . El em en t Sn ap sh o t . CreateFr omFile ( f i l e n a m e _ R e f e r e n c e T a b l e S n a p s h o t ) ; // E le me n tS na ps h ot . Cre ateFromF ile is available starting with Ranorex 5.4.2 } catch { throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( ' Snapshot could not be loaded from file '); } // restore table from snapshot Ranorex . TableTag refTable ; try { refTable = snap . Element ; } catch ( Exception e ) { throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( ' Table could not be created from snapshot . ' , e ) ; } Ranorex . TableTag tableAdapter = repoItem . As < Ranorex . TableTag >() ; if ( tableAdapter null ) { throw new Ranorex . V a l i d a t i o n E x c e p t i o n ( ' Repo - item could not be accessed . ' ) ; } IList < TrTag > actTableRows = tableAdapter . FindDescendants < TrTag >() ; int rowCntAct = actTableRows . Count ; IList < TrTag > refTableRows = refTable . FindDescendants < TrTag >() ; int rowCntRef = refTableRows . Count ; // check if rowcount is identical Ranorex . Validate . AreEqual ( rowCntAct , rowCntRef , ' Comparing number of rows ({0} vs . {1}) ' ) ; // run through table - rows for ( int iRow = 0; iRow cellsInActRow = actTableRows [ iRow ]. FindChildren < Ranorex . WebElement >() ; IList < Ranorex . WebElement > cellsInRefRow = refTableRows [ iRow ]. FindChildren < Ranorex . WebElement >() ; // check if number of cells is identical in current row Ranorex . Validate . AreEqual ( cellsInActRow . Count , cellsInRefRow . Count , ' Comparing number of cells in current row ({0} vs . {1}) ' ) ; // run through cells in current row for ( int iCol = 0; iCol 0) 352 Code Examples { // retrieve single result from SQL database var actualValue = SQLReader . GetString (0) ; // prepare log message if ( c u s t o m L o g M e s s a g e . Trim () . Equals ( string . Empty ) ) { c u s t o m L o g M e s s a g e = ' Actual value = ’{0} ’ , expected value = ’{1} ’ ( database query = ' + SQLQuery + ' ) ' ; } // compare retrieved value with expected value Ranorex . Validate . AreEqual ( actualValue , expectedValue , c u s t o m L o g M e s s a ge ) ; } else { throw new Ranorex . R a n o r e x E x c e p t io n ( string . Format ( ' SQL statement did not return any results : {0} ' , SQLQuery ) ) ; } } finally { command . Dispose () ; SQLReader . Dispose () ; } } } VB.NET Public Sub V a l i d a t e _ D a t a b a s e F i e l d W i t h Q u e r y ( O L E C o n n e c t i o n S t r i n g As String , SQLQuery As String , expectedValue As String , c us t o m L o g M e s s a g e As String ) ’ check is connection string is empty If String . IsNullOrEmpty ( O L E C o n n e c t i o n S t r i n g ) Then Throw New Ranorex . R a n o r e x E x c ep t i o n ( ' C o n n e c t io n S t r i n g is empty ' ) End If ’ check if SQL statement is empty If SQLQuery . Trim () . Equals ( String . Empty ) Then Throw New Ranorex . R a n o r e x E x c e pt i o n ( ' SQLQuery is empty ' ) End If ’ establish connection to database Using connection As New System . Data . OleDb . O le D bC on ne c ti on ( O L E C o n n e c t i o n S t r i n g ) connection . Open () Dim command As System . Data . OleDb . OleDbCommand = Nothing Dim SQLReader As System . Data . OleDb . O le D bD at aR e ad er = Nothing Try ’ set SQL statement and execute search command = New System . Data . OleDb . OleDbCommand ( SQLQuery , connection ) SQLReader = command . ExecuteReader () SQLReader . Read () ’ check if there is a result If SQLReader . FieldCount > 0 Then ’ retrieve single result from SQL database Dim actualValue = SQLReader . GetString (0) ’ prepare log message If c u s t o m L o g M e s s a g e . Trim () . Equals ( String . Empty ) Then c u s t o m L o g M e s s a g e = ' Actual value = ’{0} ’ , expected value = ’{1} ’ ( database query = ' & SQLQuery & ' ) ' End If ’ compare retrieved value with expected value Ranorex . Validate . AreEqual ( actualValue , expectedValue , customLogMessage ) Else Throw New Ranorex . R a n o r e x E x c ep t i o n ( String . Format ( ' SQL statement did not return any results : {0} ' , SQLQuery ) ) End If Finally command . Dispose () SQLReader . Dispose () 353 Code Examples End Try End Using End Sub Advanced Validation - Database (Whole Table) This sample shows how the content of a database can be validated. Using it you can check against an entire table, a database view or against every result of an SQL statement. Thus a valid SQL statement as well as a valid connection string has to be provided to allow access to the database. Please see the MSDN for more information on establishing an OLE database connection. Additionally, the filename of a csv-file needs to be passed in as a parameter. This file is acts as a reference and should contain the expected values. If the values in the file are separated differently than using the semicolon (”;”), please use the parameter ”csvSeparator” to pass it in. Note: The reference file (csv-file) needs to be created in forefront of calling this method. Every text editor can be used for creating this reference-file. C# public void V a l i d a t e _ D a t a b a s e T a b l e W i t h Q u e r y ( string OLEConnectionString , string SQLQuery , string referenceCSVTable , string csvSeparator , string customLogMessageOverall , string customLogMessageDetail ) { // check if reference file exists if (! System . IO . File . Exists ( r e f e r e n c e C S V T a b l e ) ) { throw new Ranorex . R a n o r e x E x c ep t i o n ( string . Format ( ' File does not exist : {0} ' , referenceCSVTable )); } // check if connection string is empty if ( O L E C o n n e c t i o n S t r i n g . Trim () . Equals ( string . Empty ) ) { throw new Ranorex . R a n o r e x E x c e pt i o n ( ' C o n n e c t io n S t r i n g is empty ' ) ; } // check if SQL statement is empty if ( SQLQuery . Trim () . Equals ( string . Empty ) ) { throw new Ranorex . R a n o r e x E x c e pt i o n ( ' SQLQuery is empty ' ) ; } // prepare separator for csv file ( if not passed in ) char separator ; if ( string . IsNullOrEmpty ( csvSeparator ) ) { separator = ’; ’; } else { separator = csvSeparator [0]; } // establish database connection using ( System . Data . OleDb . Ol eD b Co nn ec t io n connection = new System . Data . OleDb . O le Db Co n ne ct io n ( @ O L E C o n n e c t i o n S t r i n g ) ) { connection . Open () ; System . Data . OleDb . OleDbCommand command = null ; System . Data . OleDb . O l eD bD at a Re ad er SQLReader = null ; System . IO . StreamReader CSVReader = null ; try { // set SQL statement and execute search command = new System . Data . OleDb . OleDbCommand ( SQLQuery , connection ) ; SQLReader = command . ExecuteReader () ; // open csv file ( reference file ) 354 Code Examples CSVReader = new System . IO . StreamReader ( System . IO . File . OpenRead ( @referenceCSVTable )); // run through every line in file int iRow = 0; while (( SQLReader . Read () ) && (! CSVReader . EndOfStream ) ) { // read line from csv file var line = CSVReader . ReadLine () ; // split line into array of values var values = line . Split ( separator ) ; // check if number of values equals ( in current row of csv file and in SQL result ) if ( values . Length != SQLReader . FieldCount ) { throw new Ranorex . R a n o r e x E x c e p ti o n ( string . Format ( ' Number of fields in SQL query and reference - file does not match ({0} vs . {1}) ' , values . Length + 1 , SQLReader . FieldCount ) ) ; } // run through every field in SQL result for ( int iFields = 0; iFields < book title = ' Ranorex Test Automation Guide ' author = ' Ranorex ' year = ' 2014 ' > 359 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 390: Open ’Manage Data Sources’ dialog from test suite view 360 Data Connectors Figure 391: ’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. 361 Data Connectors Figure 392: Set up data sources for a test case Figure 393: Test case properties dialog shows the currently used data source In this new opened dialog you can create a new data connector by selecting one of the data connector types described in the next chapters from the combo box marked in green. You can also choose an existing data connector by selecting one of the data sources from the combo box marked in red. By pressing the blue marked button, labeled ’Manage Data Sources’ the data source management dialog, explained before, will be opened. By pressing the yellow marked button labeled ’Refresh’, the data of the actual selected data source will be updated from its source file or database. You can limit the data of your data source by selecting a data range in the area marked orange. To open a dialog showing you the effective data set limited by a range (area marked in orange, e.g. ’1-5, 8, 11-13’), press the purple marked button, labeled ’Preview effective data set..’. 362 Data Connectors Figure 394: 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 363 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 395: New created simple data table 364 Data Connectors Figure 396: Add new test data directly to a table of type ’Simple Data Connector’ To protect proprietary data like passwords you can mask specific columns of your data source. To do so, open the Manage Data Sources dialog, choose the connector and select the column you want to mask. 365 Data Connectors Figure 397: Choose the column you want to mask 366 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 398: Set up CSV file as external data source To protect proprietary data like passwords you can mask specific columns of your data source. CSV data connectors are, like simple data connectors, not read-only. You can add rows and columns in the same way as described in chapter Simple Data Table. The changes to your table will be applied to the CSV file. If you have chosen the option ’Include File in Test Suite’ in the data source management dialog, the changes will be applied to the local copy of your CSV file. 367 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 399: Set up SQL connector - main dialog After setting up the connector you can mask specific columns of your data source to protect proprietary data like passwords. Create Connection String By pressing the red marked ’Create’ button in the data source management dialog the connection properties dialog will be opened. 368 Data Connectors Figure 400: 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. 369 Data Connectors Figure 401: 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. 370 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 402: Create new Excel file connector To protect proprietary data like passwords you can mask specific columns of your data source. Note: Instead of using the default Excel file format xlsx for your test data you can also use the native binary file format xlsb. This file format is supported since Microsoft Office 2007 and is much faster than the non-binary version. 371 Instrumentation Wizard Instrumentation Wizard Note: Ranorex supports the testing of many different UI technologies, however some technologies need to be instrumented correctly to guarantee the best possible automation results. The Ranorex Instrumentation Wizard is a tool which helps you instrumenting these technologies to ensure optimal object recognition and consequently robust test automation projects. The Ranorex Instrumentation Wizard can be started either from ’Tools’ menu in Ranorex Studio, from the pop-up dialog triggered by a technology limitation, from the start menu, or directly from the binary folder of your Ranorex installation (binRanorex.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 403: Start Instrumentation Wizard from Ranorex Tools Menu Figure 404: Start Instrumentation Wizard from Technology Limitation 372 Instrumentation Wizard Figure 405: 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. 373 Instrumentation Wizard Figure 406: 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 / 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: The name of the device to that the APK file shall be deployed. This parameter is not required if deploymode is set to ’NoDeploy’. a|apkfile: Required. The path where the APK file resides. s|skip: Default is False. Set this switch to skip APK file instrumentation prior to deploying. 374 Instrumentation Wizard dm|deploymode: Possible Values: WiFi, Usb, NoDeploy, Auto. Default is Auto. Specifies how the apk file shall be deployed. Set to nodeploy if the file shall not be deployed to the device. Auto means the connection mechanism used to configure the device will be used. o|outfile: Sets a custom output location for the instrumented file. This can be a directory or a file path. Read/Write permission is required for this path. If a directory was specified, (to specify a directory add a trailing ’’) the process will place the APP file in it with the -instrumented suffix added to the source file name. If the file already exists it will be overwritten. This option only has an effect if an APP is instrumented (no skip). android Advanced options: APK Signing JdkBinPath: Full Path to your JDK installation bin folder. KeyAlias: Alias of the keystore entity used for jarsigner. KeyPass: Password of the key used for jarsigner. Warning: Please note that password is stored in plain text. Do not use production certificates. KeyStore: Location (full path) of the keystore used for jarsigner. KeyStorePass: Password of the keystore used for jarsigner. Warning: Please note that password is stored in plain text. Do not use production certificates. Note: For custom signing, Keystore, Keystore alias, Keystore password, Key password and JDK bin path have to be set. android Advanced Options: Instrumentation Options RIdClass: Provide a custom class name for locating resource ids (e.g. com.ranorex.demo.R). By default Ranorex will search id in .R. EnableWebTesting: When set to true Ranorex shows DOM content of Web Views in UI-Hierarchy. Note that this feature has a huge performance impact on your app. Default is true. FullImageComparison: When enabled, more robust image comparison is used to determine resource id’s for images. This option decreases startup performance. TreeSimplification: When set to false, no post processing of the UI-Tree takes place. This results in a larger UI-Tree which could be useful for automating 3rd party Android controls. android d|device: The name of the device to that the APK file shall be deployed. This parameter is not required if deploymode is set to ’NoDeploy’. a|apkfile: Required. The path where the APK file resides. s|skip: Default is False. Set this switch to skip APK file instrumentation prior to deploying. dm|deploymode: Possible Values: WiFi, Usb, NoDeploy, Auto. Default is Auto. Specifies how the apk file shall be deployed. Set to nodeploy if the file shall not be deployed to the device. Auto means the connection mechanism used to configure the device will be used. o|outfile: Sets a custom output location for the instrumented file. This can be a directory or a file path. Read/Write permission is required for this path. If a directory was specified, (to specify a directory add a trailing ’’) the process will place the APP file in it with the -instrumented suffix added to the source file name. If the file already exists it will be overwritten. This option only has an effect if an APP is instrumented (no skip). 375 Instrumentation Wizard chrome e|enable: Required. Enable this switch to activate Chrome browser addon. If the switch is disabled the addon will be deactivated. firefox e|enable: Required. Enable this switch to activate FireFox browser addon. If the switch is disabled the addon will be deactivated. flex pl|preloader: Required. Enable this switch to enable the Ranorex preloader. If the switch is disabled the preloader will get deactivated. ie: Enable this switch to enable Internet Explorer Flex debug player. If the switch is disabled Internet Explorer Flex debug player will get deactivated. ff|firefox: Enable this switch to enable the Firefox/Safari NPAPI Flex debug player. If the switch is disabled Firefox/Safari Flex debug player will get deactivated. cr|chrome: Enable this switch to enable the Chrome PPAPI Flex debug player. If the switch is disabled the Chrome PPAPI Flex debug player will get deactivated. o|other: Enable this switch to enable the Chrome *and* Firefox Flex debug player. If the switch is disabled the Chrome and Firefox Flex debug player will get deactivated. [Obsolete option use /cr and/or /ff instead.] ft|flextrace: Default is False. Enable this switch to enable Flash tracelog. If the switch is disabled flash trace log will get deactivated. java jp|javapath: Required. System path to the JRE. d|disable: Default is True. Tells Ranorex that the instrumentation should be removed. safari e|enable: Required. Enable this switch to activate Safari browser addon. If the switch is disabled the addon will be deactivated. ios u|udid: The unique device identifier for the device on that the application shall be installed (Note: instead of UDID the new option ’devicename’ can be used). To get the UDID start Ranorex Studio open the manage devices dialog and select your device (that was added as a USB device) and click edit. In the meta data field you will find the UDID of the device. dn|devicename: The name of the device. You can specify the name instead of the UDID. The name needs to exactly match the name, you set for your device in the settings app of that device. ip|inputpath: The path to the application archive (*.ipa). o|outfile: Sets a custom output location for the instrumented file. This can be a directory or a file path. Read/Write permission is required for this path. If a directory was specified, (to specify a directory add a trailing ’’) the process will place the APP file in it with the -instrumented suffix added to the source file name. If the file already exists it will be overwritten. This option only has an effect if an APP is instrumented (no skip). si|skipinstrumentation: Default is False. Set this switch to skip IPA file instrumentation. 376 Instrumentation Wizard sd|skipdeployment: Default is False. Set this switch to skip IPA file deployment. k|keypath: The path to the p12 key file (*.p12). pw|password: The password for the p12 key file. pp|provisionpath: The path to the embedded mobile provision file (*.mobileprovision). ai|appid: Default is . The application Id (bundle identifier of the app). This is required so that an application can be uninstalled prior to installing the new archive. Can be set to ’[auto]’ to resolve it automatically during instrumentation. db|deploybrowser: Default is False. Set this switch to deploy Ranorex browser app. ds|deployservice: Default is False. Set this switch to deploy Ranorex service app. ub|uninstallbrowser: Default is False. Set this switch to uninstall Ranorex browser before deploy us|uninstallservice: Default is False. Set this switch to uninstall Ranorex service before deploy uf|uninstallfail: Default is False. Set this switch to throw exception when uninstalling an app fails. 377 Instrumentation Wizard Java AWT/Swing The Ranorex Java Plug-In allows testing of Java Swing and Java AWT applications. With Ranorex 5.0.0 and higher, the instrumentation will be enabled automatically. If you have instrumented your Java Runtime Environment using the Ranorex Instrumentation Wizard of a previous Ranorex version, it’s recommended to deactivate the obsolete instrumentation. To do so, start the Ranorex Instrumentation Wizard from command line with argument ’/p:java’: Bin>Ranorex.InstrumentationWizard.exe /p:java The Instrumentation Wizard tries to remove the obsolete Plug-In specific files from the Java Runtime Environment (JRE) of your choice. 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 under test. This is the preferred method, as you can determine exactly which Java runtime is being used by your application under test. Select a JRE from a list of installed Java runtimes: Here you can choose the Java Runtime Environment from a list of all installed Java runtimes on your machine. Specify a custom Java runtime directory: Here you can specify the folder holding the Java runtime. Figure 407: Java Instrumentation Wizard After deactivating the obsolete Java AWT/Swing instrumentation, restart your application under test and your Ranorex tools to ensure that the automatically added instrumentation works correctly. 378 Instrumentation Wizard Figure 408: Finished Java Instrumentation 379 Instrumentation Wizard Adobe Flash/Flex The Flash/Flex technology limitation will pop up if your Flash/Flex application is not instrumented correctly. Figure 409: 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 the Flash Debug Player for Internet Explorer and the Flash Debug Player for Mozilla Firefox and Safari and the Flash Debug Player for Google Chrome if you like. Moreover, you can enable the Ranorex Preloader Instrumentation. This allows you in combination with the Flash Debug Player to instrument your application under test without the need to alter your application. Additionally, you can enable logging for the Flash Debug Player. This might be helpful if you have any problems with this kind of instrumentation. In such case you can then simply provide this logging information to our support team. 380 Instrumentation Wizard Figure 410: 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 411: 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. 381 Instrumentation Wizard Google Chrome To use the preloader method with Google Chrome, you have to disable the internal Flash Player. This can be done by performing following steps: Open Chrome’s plugins overview (chrome://plugins/): Figure 412: Open plug-ins overview Display the Plug-Ins details: Figure 413: Plug-In in detail Disable the internal Flash Player (framed red) and keep the Flash Debug Player (framed green) enabled: 382 Instrumentation Wizard Figure 414: Disable the internal Flash Player 383 Instrumentation Wizard Mozilla Firefox The Mozilla technology limitation will pop up if the Ranorex Add-On for you Mozilla Browser is not installed or enabled. This technology limitation should only occur if you install Firefox after successfully installing Ranorex. If Mozilla Firefox has been installed before installing Ranorex, the Mozilla Browser Add-On will be installed and activated automatically. Figure 415: 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 416: 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. 384 Instrumentation Wizard Figure 417: 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 418: 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. 385 Instrumentation Wizard Figure 419: Confirm Ranorex Automation Add-On installation 386 Instrumentation Wizard Google Chrome The Chrome technology limitation will pop up if the Ranorex Extension for the Chrome Browser is not installed or enabled. Figure 420: Google Chrome Technology Limitation The Instrumentation Wizard opens the Chrome web store page when pressing the ’Next’ button. You can install the Extension by clicking the + sign in the store page. Figure 421: 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. 387 Instrumentation Wizard Figure 422: Finished Google Chrome Instrumentation When not using the default Chrome user profile, you have to add the Ranorex Chrome Add-On manually. To do so, open the Chrome Extensions settings (chrome://extensions), enable ’Developer mode’ and press the ’Load unpacked extension’ button. After choosing the ’Ranorex Chrome Extension’ folder (Ranorex Chrome Extension) and confirming the new Extension, the Ranorex Add-On will be listed on the Extensions page. 388 Instrumentation Wizard Figure 423: Load Ranorex Chrome Extension Figure 424: Confirm Extension 389 Instrumentation Wizard Figure 425: Installed Ranorex Automation Extension Note: If you want to test cross domain iframe scripting with Google Chrome, you have to start Chrome with the command line argument ’--disable-web-security --user-data-dir=”” ’. Note: Verify that the extension ID (see screenshot above) is listed in the ”allowed origins” section of binRanorex.Plugin.ChromeMsgHost.manifest file. Note: If you want to test file URLs, you have to enable ’Allow access to file URLs’ for the Ranorex Automation Extension. Figure 426: Allow access to file URLs 390 Instrumentation Wizard Note: If the NotScript Chrome Extension is installed, it has to be disabled to allow from point tracking with Ranorex. 391 Instrumentation Wizard Apple Safari The Safari technology limitation will pop up if the Ranorex Extension for the Safari Browser is not installed or enabled. Figure 427: 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 428: Apple Safari Instrumentation Wizard After activating the Extension, you have to confirm the installation in Safari. 392 Instrumentation Wizard Figure 429: 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 430: 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. 393 Instrumentation Wizard Figure 431: 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 432: 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. 394 Instrumentation Wizard 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. Note: Note: It’s recommended to fresh instrument your app for every new Ranorex release. For further information have a look at the section ’Versioning’. Figure 433: Android instrumentation wizard Next to instrumenting and deploying your Android app, the Instrumentation Wizard allows you to update the Ranorex Service on your device as well as deploy the RXBrowser app, which enables Testing of Mobile Websites on Android. Choose the APK file of the app and the device, the instrumented APK file will be deployed to. More information about setting up a mobile device can be found in section Manage Devices. If the APK is already instrumented and only needs to be deployed on a mobile device, the checkbox ’Instrument the App under test’ can be unchecked. After processing the instrumentation and deploying the instrumented APK file to the selected device, the installation has to be confirmed on the device. 395 Instrumentation Wizard Figure 434: Finished Android instrumentation The instrumented APK file can be found at location referenced by the link ’Open instrumentation File location’. After instrumenting and deploying the APK file, the app is available in the ’Record a Mobile Test’ section of Record Setting dialog. Figure 435: Choose mobile as technology 396 Instrumentation Wizard Figure 436: Instrumented APK in Record Settings The Ranorex Service App installed on the mobile device shows an overview of instrumented apps installed on the device. Figure 437: 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. 397 Instrumentation Wizard iOS To make an iOS app automatable by Ranorex, it is necessary to instrument this application and deploy it to a device. The Instrumentation wizard can be used to deploy the instrumented app to the device. Note: Deployment only works for USB connected iOS devices.Have a look at Instrumentation and Preparation to learn how to instrument iOS applications. Note: Note: It’s recommended to fresh instrument your app for every new Ranorex release. For further information have a look at the section ’Versioning’. Figure 438 398 Instrumentation Wizard Figure 439 Next to instrumenting and deploying your iOS app, the Instrumentation Wizard allows you to update the Ranorex Service on your device as well as deploy the RXBrowser app, which enables web testing for iOS. Choose the IPA file of the app and the device, the app will be deployed to. To instrument the IPA file of the app, a p12 key file, the corresponding password and the mobileprovision file are necessary. Note: The iOS signing needs to be configured only once. The settings will be saved for future IPA files instrumentation. More information about setting up a mobile device and deploying from windows machines can be found in the section iOS Testing. To delete the existing version of the app on your device before deploying a new one, check the corresponding check box. 399 Instrumentation Wizard Figure 440: Finished iOS instrumentation The instrumented IPA file can be found at location referenced by the link ’Open Instrumentation File location’. After instrumenting and deploying the IPA file, the app is available in the ’Record a Mobile Test’ section of Record Setting dialog. Figure 441: Instrumented APK in Record Settings Note: iOS application packages (IPA files) that have been downloaded from the App Store will not be instrumented correctly, because they have the DRM (Digital Rights Management) restriction. 400 Instrumentation Wizard Note: Because the Ranorex automation lib uses non-public APIs, make sure that you do not submit a Ranorex instrumented app to the app store as your app might be rejected and you might be banned from submitting apps to the app store for a period of time. 401 Technology Instrumentation Technology Instrumentation Ranorex supports testing of many different UI technologies. Although some of them need to be instrumented correctly to ensure optimal object recognition and furthermore to built robust test automation projects. If an application under test requires additional manual instrumentation, a pop-up dialog is shown when using a Ranorex tool. Figure 442: 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 Testing of CEF applications General Troubleshooting 402 Technology Instrumentation Flash/Flex Testing The Flash/Flex Test Automation Plugin provides a smooth integration with the Ranorex Automation Framework and its tools. You can easily filter, access and validate Flex controls easily using RanoreXPath. You have full access to all the properties and attributes of Flash and Flex elements. Prerequisites The automation of Flash/Flex applications requires inclusion of the Ranorex Flex Automation Lib. 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 403 Technology Instrumentation 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 CS4 Flex CS5 3.X 4.X AIR* 2.X 3.X 4.X PreLoader Automation Lib Module * Support for Adobe AIR 2 Release in combination with Flex 3.5 and Flex 4 Release Figure 443 = supported Figure 444 = 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. 404 Technology Instrumentation Figure 445: 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: // Set the checked state with the property ' Checked ' repo . Fl ex T es tPag eDo m . C h e c k B o x _ C o n t r o l _ E x a m p l e . CheckBoxEggs . Checked = true ; To access custom attributes and styles, you first have to load your Flex item as a FlexElement in order to read your attributes. Here’s an example: // Load the slider as a Flex element to access flex attributes FlexElement sliderFlex = repo . Flex Tes tPag eD o m . C o n t a i n e r H S l i d e r _ C o n t r o l . SliderHSlider . As < flexelement >() ; sliderFlex [ ' value ' ] = ' 100 ' ; FlexElement containerFlex = repo . Fle xTe st Pa g eD om . Self . FindSingle ( ' .// container [ @caption = ’ Tree Control ’] ' ) ; containerFlex . SetStyle ( ' borderColor ' ,' # ee0000 ' ) ; Using the Ranorex PreLoader The Adobe Flash/Flexautomatically activates Flash/Flex automation for your machine as Adobe Flash/Flex. If the automatic instrumentation did not work, you can follow these steps to achieve what the Instrumentation Wizard would have done: 1. Install the Adobe Debug Flash Player on the machine on which you would like to record and execute Ranorex test scripts and for all browsers you would like to test with. The installers are available on Adobe’s download page; the following are the links to the Debug Player for Internet Explorer (Windows 8: x86 / x64 and Windows 8.1: x86 / x64) Firefox / Safari Chrome 2. Open your user profile directory %UserProfile%, e.g. by opening Windows Explorer and copying the string %UserProfile% into the address bar. 405 Technology Instrumentation 3. Create a new file called ’mm.cfg’ in your user profile directory and insert the following line of code: PreloadSwf = C : Program Files Ranorex X . X Bin R a n o r e x A u t o m a t i o n . swf where ’C:Program FilesRanorex X.XBinRanorexAutomation.swf’ needs to be replaced by the preloader location of your Ranorex installation. If the ’mm.cfg’ file already exists, check if the location is correctly set to your current preloader location (Ranorex X.X might change after upgrading to a new version!). In addition to this configuration entry you can enable the logging mechanisms of the Adobe Debug Flash Player, which might be helpful if you have any problems with this kind of instrumentation. In such a case you can then simply provide the logging information to our support team. To enable logging you have to add (or modify) the following line of code to your ’mm.cfg’ file: T r a c e O u t p u t F i l e E n a b l e =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 where needs to be replaced by the username that is logged on. 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 Flash Builder and open your workspace 2. Right-click on your project and choose Properties 3. Under Flex Compiler add the RanorexAutomation.swc file (located in the Bin directory of your Ranorex installation) to the the compiler argument as follows: - include - libraries ' C :/ Program Files / Ranorex X . X / Bin / R a n o r e x A u t o m a t i o n . swc ' 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 406 Technology Instrumentation 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: 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 407 Technology Instrumentation How to load the Ranorex Module into your Flex/AIR application 1. Start Adobe 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 408 Technology Instrumentation Testing of Java Applications The Ranorex Java Plug-In allows testing of Java Swing and Java AWT applications. With Ranorex 5.0.0 and higher, the instrumentation will be enabled automatically. If you have instrumented your Java Runtime Environment using the Ranorex Instrumentation Wizard of a previous Ranorex version, it’s recommended to deactivate the obsolete instrumentation. To do so, either use the Java AWT/Swing or manually delete the Plug-In specific files as shown below. Figure 446: Java Instrumentation Wizard Manual Disable obsolete 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 delete each of the following files from its corresponding directory based on the root folder of your java runtime installation (e.g. ’C:Program Files (x86)Javajre6’). ’accessibility.properties’ from lib ’RanorexAutomation.jar’ from libext ’JavaHelper32/64.dll’ from bin 409 Technology Instrumentation Qt Testing The Ranorex Automation Framework fully supports out-of-the-box test automation of Qt based applications. Qt versions: Qt Widgets: Qt version 4.5.3 or higher Qt Quick: Qt version 5.0.2 or higher Qt WebKit: Qt version 4.6.4 or higher There is no need for a manual instrumentation, it will be done automatically. Only dynamically linked Qt applications are supported. To go back to MSAA (Microsoft Active Accessibility) and Qt Accessibility recognition, the ’Qt legacy automation mode’ can be enabled in the ’Plugin Specific Settings’. When ’Qt legacy automation mode’ has been enabled, MSAA support for your Qt application must be enabled to ensure that Ranorex can access UI elements and properties in the Qt application. This provides additional information on Qt UI elements to automation software like Ranorex and can be accomplished by shipping and loading the ’Accessible Plug-in’ included in the Qt SDK (Software Development Kit) with the Qt application under test (see below). Loading Accessible Plug-in for your Qt application: 1. Copy the ’accessible’directory(and all its contents)from the Qt SDK (used to build the application under test) installation folder to the folder of the automated application (e.g. ’Program Files/Your-Application/plugins’). If you do not have access to the Qt SDK which the Qt application is developed with, please contact the developer of the application and request the ’accessible’ directory from him. 2. 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 410 Technology Instrumentation Figure 447: Without Accessible Plug-in Figure 448: With Accessible Plug-in 411 Technology Instrumentation 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 449: 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. 412 Technology Instrumentation Figure 450: Before .. Figure 451: .. 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. 413 Technology Instrumentation Figure 452: 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. 414 Technology Instrumentation 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 453: SAP GUI options dialog Note: The administrator has to enable the support by setting the profile parameter sapgui/user scripting to ”TRUE” on the application server. 415 Technology Instrumentation Testing of CEF applications Starting with Ranorex 6.2, you can test web content in desktop applications that are based on these chromium-based frameworks: Chromium Embedded Framework (CEF) CefSharp Electron NW.Js Qt WebEngine Preparing the application under test To start testing CEF applications with Ranorex, you have to enable the remote debugging port in the application under test (AUT). You can do so by using the command line argument ’remote-debugging-port’ when starting the AUT. For example: MyApplicationUnderTest.exe --remote-debugging-port=8081 The port number you are using in this command must not be used by another application or service on the windows machine you are testing the AUT. In a Ranorex recording you can add this command line argument to the ’Run Application’ action. CefSharp applications If your AUT is based on CefSharp, the command line argument does not work. Please enable the remote debugging port in the source code of the AUT. To set the remote debugging port in CefSharp, you have to specify it with help of the CefSettings class before initializing the control like this: var settings = new CefSettings(); settings.RemoteDebuggingPort = 8081; Cef.Initialize(settings); Technology Limitations When testing CEF applications, you may come across a technology warning. Here are potential causes for these technology warnings: Another application is already listening on the remote debugging port If another application on the machine is already listening on the remote debugging port of the application under test, Ranorex cannot connect to the AUT. By Default, Ranorex tries to close these applications. In some cases, like the Chrome Developer Tools, this is not successful. That is why a manual action from the user is needed. Please try to: Close all other applications, like the Chrome Development Tools, that may have a connection to the application under test at the remote debugging port. Choose a different port number as remote debugging port for the application under test. 416 Technology Instrumentation CEF UI element invisible The UI element containing the CEF control is not visible. In order to test the web content inside the CEF control, the containing UI element has to be visible. Please try to: Include an action in your recording to make sure the UI element is visible. Remote debugging not available The remote debugging interface of the application under test is not available. However, this is a prerequisite for testing CEF applications with Ranorex. Please try to: Make sure the application under test is correctly Preparing the application under test. The port number used as remote debugging port must not be used by any other application on the machine. Make sure no other application on the machine listens to the remote debugging port the application under test provides. 417 Technology Instrumentation General Troubleshooting This section provides an overview of possible reasons for a limited object recognition with Ranorex tools and recommends ways to correct a malfunction. .NET WinForms .NET WPF .NET Silverlight Flash/Flex Applications Win32 Based Applications Browser (Mozilla Firefox, Google Chrome, Apple Safari, Microsoft Internet Explorer) Image Related Automation or Validation Geometry Related Issues Windows Apps (aka Windows 8 UI Apps) Other Software Different Display DPI Scaling Values .NET WinForms Ranorex failed to load the assemblies containing the definition of this control. UI element identification capabilities for this control are limited. There might be several reasons for limited support of .NET WinForms based applications or controls: Reason #1: The automating process (Ranorex executable) and the automated application (AUT) are not started with the same security rights, i.e. not as the same Windows user. Solution: Try starting both applications as the same user. Reason #2: Either the automating executable or the AUT are started from a network drive or encrypted folder and consequently do not have the required security rights. Solution: Try copying both applications to a folder on your hard disk. Reason #3: The .NET Framework 4 (or higher) got installed after Ranorex was already installed and the AUT uses .NET 4.0. Consequently, as the .NET Framework 4 was not present when Ranorex was installed, the Ranorex setup could not install the DLLs required to recognize and automate .NET 4.0 applications. Solution: Uninstall Ranorex completely and then re-install Ranorex. 418 Technology Instrumentation Reason #4: The controls that cannot be identified are implemented in a mixed-mode EXE file (not DLL). This can be the case with some obfuscating applications or assembly merging utilities that create mixed-mode EXE files. The .NET Framework does not support loading such mixed-mode executables in other processes and that’s why Ranorex cannot recognize controls implemented within them. Solution: As a workaround, you can try to automate the non-obfuscated version of your application. Reason #5: The controls that cannot be identified are implemented in an assembly that targets a particular platform/processor and the automating executable targets a different platform/processor. This can cause problems on 64 bit operating systems, since such assemblies cannot be loaded by the automating process. Solution: Try changing the ’Target CPU’ (Ranorex Studio) or ’Platform Target’ (Visual Studio) option in the automation project settings to match the target of the automated application as described in 64-bit Platforms. If you don’t know the target CPU/platform of the automated application, first try to change the option to ’Any processor’ or ’Any CPU’, respectively, then try the remaining options. Reason #6: The .NET Framework 4.0 Extended package is needed but not installed. An indication for this problem typically is that controls can correctly be identified by the standalone Ranorex Spy application, but not by the integrated Ranorex Spy or Recorder in Ranorex Studio.The application under test uses the .NET Framework 4.0 and you may get Technology Limitation pop-ups saying that specific assemblies cannot be loaded. Solution: Either install the .NET Framework 4.0 Extended or if that is not possible always use the standalone Ranorex Spy and Recorder tools instead of the integrated ones in Ranorex Studio. Reason #7: If the application under test is built with the .NET Framework 4.0, a .exe.config file (where 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 .exe.config file in the same folder as the Ranorex executable with following content: < configuration >< startup >< s u p p o r t e dR u n t i m e version = ' v4 .0 ' / > .NET WPF For compatibility with existing tests, Ranorex 5.3+ shows WPF windows twice in its tree; once using the WPF-specific plug-in, another time using UIAutomation. When selecting a specific element, the UIAutomation tree was chosen, although the native WPF plug-in is available and active. 419 Technology Instrumentation Reason #1: While selecting an element of a WPF application in the element-tree of Spy, you selected the UIAutomation tree of that application. Solution: The preceding sibling of the selected window will identify the same window, but provide the ”WpfElement” capability instead of ”UiAutomation”. When browsing elements in Spy, select elements below the ”WpfElement” window. Reason #2: Instrumentation of the WPF application has failed, because the application runs on a .NET 3.0 runtime, and .NET 3.5 is not installed. Solution: Upgrade the .NET installation to version 3.5. No changes are required for the application under test. .NET Silverlight Reason #1: 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. 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: 420 Technology Instrumentation Reason #1: The automating process is not being run with the required security permissions to access the process under test. UI element identification capabilities for controls in that process are limited. Solution: The automating process (Ranorex executable) and the automated application (AUT) are not started with the same security rights, i.e. not as the same Windows user. Ensure that both processes are started with the same rights. Reason #2: The automating and the automated process do not have the same bit width and Ranorex was unable to start the 32/64 Bit Bridge. UI element identification capabilities for controls in that process are limited. Solution: 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 Settings overview. Browser (Mozilla Firefox, Google Chrome, Apple Safari, Microsoft Internet Explorer) 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 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 Google 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. 421 Technology Instrumentation Microsoft Internet Explorer: UI element identification capabilities for Microsoft Internet Explorer are slow. Solution: Please make sure that you have enabled the Ranorex Extension in your Internet Explorer (Manage Add-ons). Note: The ”Enhanced Protected Mode” needs to be disabled. Note: The ”Internet Explorer Enhanced Security Configuration” has to be disabled for the add-on to work on Windows Server machines. Image Related Automation or Validation Reason #1: Ranorex’s 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 Advanced Settings. Geometry Related Issues Reason #1: Controls being displaced, staying empty, or being scrolled out of view during automation. Solution: Set the ’Use Ensure Visible’ property of the corresponding repository items (and their parent folders) to ’False’ as described in the chapter Repository Item Properties. 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. 422 Technology Instrumentation Solution: Install Ranorex to ’Program Files’ or ’Program Files (x86)’. Reason #3: The test executable is not started by a Ranorex Tool. Solution #1: Start the test suite using the TestSuiteRunner. Solution #2: Use the Ranorex UiaLauncher (binRanorex.UiaLauncher32.exe) to start the test executable by passing the executable name as the first argument. E.g. Ranorex.UiaLauncher32.exe bindebug.exe . Solution #3: Add the following lines of code to the Program.cs/Program.vb of the main (executable) project: C# if ( Ranorex . Core . Util . I s R e s t a r t R e q u i r e d F o r W i n A p p A c c e s s ) return Ranorex . Core . Util . R e s t a r t W i t h U i A c c e s s () ; VB.NET If Ranorex . Core . Util . I s R e s t a r t R e q u i r e d F o r W i n A p p A c c e s s Then Return Ranorex . Core . Util . R e s t a r t W i t h U i A c c e s s () End If Reason #4: You checked the ”Run this program as an administrator” in the Compatibility settings of a Ranorex Tool EXE file, e.g. for the RanorexStudio.exe file. Setting this option disables access to Windows 8 UI apps. Solution: Do not check the mentioned setting for any of the Ranorex EXE files. Alternatively, if you want to always run the tool using administrator rights, you can create a shortcut to the EXE file and check the ”Run as administrator” option in the ”Shortcut” -> ”Advanced..” settings of the shortcut properties. Other Software Running some antivirus or security software might lead to a limited object recognition with Ranorex tools. Reason #1: 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. 423 Technology Instrumentation Different Display DPI Scaling Values By default, Microsoft Windows is automatically adapting the DPI scaling value for each of your physical displays connected to your machine. This ensures a uniform experience over all displays, even if the displays have a different physical size. When using Ranorex, all physical displays have to be set to the same DPI scaling value. Solution for Windows 8.1 1. On your Windows 8.1 machine, open the Control Panel and switch to section ’Display’. Do not use the application ’PC settings’. Make sure the option ’Let me choose one scaling level for all my Displays’ is checked. Figure 454 2. After checking this option, choose the size category you prefer. 424 Technology Instrumentation Figure 455 Press ’Apply’, sign-out and sign-in again to your machine to activate the new settings. The technology limitation warning should not appear again. Solution for Windows 10 1. On your Windows 10 machine, open the Windows start menu and choose ’Settings’. 2. Click on ’System’. 425 Technology Instrumentation Figure 456 3. The section ’Display’ should be shown automatically if not, open it manually. Make sure that all your physically connected displays have the same setting at ’Change the size of text, apps, and other items’. Move through the list of displays (labelled with numbers) one by one, and check the setting. When changing a display value, press ’Apply’ before moving on to the next display. 426 Technology Instrumentation Figure 457 4. Once all changes have been applied, you can close the ’Settings’ window. The technology limitation warning should not appear again. 427 RanoreXPath RanoreXPath A RanoreXPath expression is primarily used to uniquely identify UI elements within a desktop, web or mobile application. Generally, a RanoreXPath expression consists of: Adapters Attributes and Values Figure 458: Main components of a RanoreXPath expression Screencast: A detailed explanation of RanoreXPath expressions, the elements and the way they work can be found in our screencast named ”RanoreXPath”. You can watch it here: http://youtu.be/UqiCtDlk0hM The adapter type specifies the type or classification of a UI element to search for (button, form, text field, listbox, etc.). Looking at the first part of the RanoreXPath expression ’/form[@title=’Form 1’]’ the ’/form’ string specifies a search for a UI element of adapter type form. A Ranorex.Form adapter represents top-level windows such as dialogs or messageboxes on the Windows desktop system. The attribute value comparison ’[@title=’Form 1’]’ specifies the UI element in detail. As an example the first part of the RanoreXPath expression shown in the pictures will look for a UI element which is of type form and has an attribute called ’title’ with the value ’Form 1’. This form holds a container witch caption ’Container 1’, which holds a button with text ’Button 1’. 428 RanoreXPath Figure 459: 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. Note: Use the key in combination with the arrow keys to navigate to the previous or the next token in RanoreXPath. Use the key and the key in combination with the arrow keys for selecting specific parts of the RanoreXPath. Use the key in combination with the 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 Result Set Selector 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 absolute path identifying all buttons that are children of a form ./button relative path identifying all buttons that are children of the current element /form//button absolute path identifying all buttons that are descendants of a form, i.e. all buttons in all levels of a form subtree 429 RanoreXPath .//button relative path identifying all buttons that are descendants of the current element (or the element itself), i.e. all buttons in the subtree of the current element (including the element itself) ./button relative path identifying all buttons that are descendants of the parent of the current element /form/container?/button optional location step fitting a container adapter between form and button; identifies both, ’/form/container/button’ and ’/form/button’ /form/?/button optional location step fitting every adapter between form and button Attributes /form identifies a top level application /form[@title=’Calculator’] identifies a top level application with the title ’Calculator’ /form[@title=’Calculator’ and @instance=’2’] identifies a top level application with the title ’Calculator’ and an attribute of instance with value two /form[@title=’Calculator’ or @class=’SciCalc’] identifies a top level application with the title ’Calculator’ or by its class /form/button identifies a button in the application /form/button[2] identifies the second button in the application /form/button[-2] identifies the second-to-last button in the application /form/button[@text=’7’] identifies a button with a text attribute value of ’7’ /form/button[@text!=’7’] identifies a button with a text attribute value that is not ’7’ /form/button[@text>’sample’] identifies a button with a text attribute starting with ’sample’ /form/button[@text=13.5] identifies a progress bar with value greater than or equal 13.5 (following comparison operators are also available: >, 100] identifies a top level application with screen coordinates greater than 100 /form/button[cx()>10 and cy()>10] identifies a button with client coordinates (coordinates of an element relative to its parent) greater than 10 /form[width()>100 and height()>100] identifies a top level application with width and height greater than 100 /dom/body/form/button[text()=’Clear’] If the innertext-attribute is available (web testing), test() brings back the value of the innertext attribute /dom/body/form[@id=null()] identifies a form with the id-attribute not being set (=null) Result Set Selector Every step in a RanoreXPath expression produces a list containing zero or more elements. These elements can be in various relationships to each other, for example siblings, parent-child or any other relationship imaginable. Example: form//button[@enabled=’True’] The expression above selects all enabled buttons on all available levels below a Form element. For picking one element from the entire result set, a Result Set Selector can be specified by using an additional set of brackets. 431 RanoreXPath Example: form//button[@enabled=’True’][2] From the complete list of enabled buttons (on various levels), the Result Set Selector selects the second element. Note that the Result Set Selector is only applied after the step where it was specified has been completely evaluated. The result will be fundamentally different from the result list of the following statement: form//button[@enabled=’True’ and index()=2] (This would select all enabled buttons with index equal to 2) 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 460: Advanced RanoreXPath example RanoreXPath with Regular Expressions 432 RanoreXPath button[@text~’sample[0-9]’] matches the following button elements: ’sample0’, ’sample1’, .. ’sample9’, ’My sample26’ listitem[@text~’^sample’] matches all elements starting with text value sample listitem[@text~’sample$’] matches all elements ending with text value sample listitem[@text~’gr(a|e)y’] matches text value gray or grey listitem[@text~’^sample 123$’] matches ’sample 123’ (use backslash to escape special characters like space) listitem[@text~’^(?i:MyTeXt)$’] matches the regular expression case-insensitive, e.g. ’mytext’, ’MYTEXT’, ’mYTeXT’, .. 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.’. 433 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. [^0-9] 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. For additional information on regular expressions please consult the corresponding MSDN web site: http://msdn. microsoft.com/en-us/library/az24scfc.aspx 434 RanoreXPath Weight Rule Library RanoreXPath Weight Rule Library Why RanoreXPath Weight Rules How to Add Your Own RanoreXPath Weight Rule How to Add Shared RanoreXPath Weight Rules Rule Library Why RanoreXPath Weight Rules If software is based on dynamic content it is typically based on dynamic identifiers. This might lead to problems in object recognition as these identifiers will be newly generated every time an element will be displayed. One way to overcome this challenge is to manually adapt the repository after recording a test scenario which of course is very time-consuming. The recommended way of handling dynamic content is to use RanoreXPath Weight Rules to optimize the object recognition for specific dynamic frameworks. A path weight rule sets the weight of a specific attribute for a specific capability meeting a set of defined conditions. The weight will be used when building up the RanoreXPath. The attribute with the highest weight and a value other than empty will be taken for the identification of the UI element. The RanoreXPath Weight Rules can be accessed via the ’RanoreXPath Weight Rules’ editor (’Settings -> Advanced -> Edit Path Weights’ or ’Ranorex Spy -> Edit Path Weights’). Figure 461: Edit RanoreXPath Weight Rules via settings dialog 435 RanoreXPath Weight Rule Library Figure 462: Edit RanoreXPath Weight Rules via Ranorex Spy Using the RanoreXPath Weight Rules can assist you in automatically creating a robust repository which is the base of a robust test automation framework. How to Add Your Own RanoreXPath Weight Rule You can find a detailed description of how to add your own RanoreXPath Weight Rule in the blog post Automated Testing and Dynamic IDs. If you want to share your RanoreXPath Weight Rules with the Ranorex community, please send your XML rule to [email protected] and provide us with a short description. How to Add Shared RanoreXPath Weight Rules Open ’RanoreXPath Weight Rules’ editor from settings dialog (Settings -> Advanced -> Edit Path Weights). Copy the specific XML rule from below ( + , + ) and paste it to ’RanoreXPath Weight Rules’ Dialog by pressing + or use the context menu. 436 RanoreXPath Weight Rule Library Figure 463: Add shared rule Rule Library RxWinForms ControlNet11 Classnames XML < rule name = ' RxWinForms ControlNet11 Classnames ' enabled = ' True ' capability = ' nativewindow ' attribute = ' class ' setweight = ' 0 ' c o n d i t i o n s o p e r a t o r = ' and ' >< condition source = ' self ' attribute = ' class ' match = ' ^ Wi ndowsFo rms10 . Window ' negate = ' False ' / > RxWeb YUI (Yahoo User Interface Library) XML < rule name = ' RxWeb YUI ( Yahoo User Interface Library ) ' enabled = ' True ' capability = ' webelement ' attribute = ' id ' setweight = ' 0 ' c o n d i t i o n s o p e r a t o r = ' or ' >< condition source = ' self ' attribute = ' id ' match = ' ^ yui ( _ d +) ' negate = ' False ' / >< condition source = ' self ' attribute = ' id ' match = ' ^ yui - gen .* ' negate = ' False ' / > 437 RanoreXPath Weight Rule Library RxWeb JS Frameworks (ExtJS, Sencha, Ozone Widget ,..) XML < rule name = ' RxWeb JS Frameworks ( ExtJS , Sencha , Ozone Widget ,..) ' enabled = ' True ' capability = ' webelement ' attribute = ' id ' setweight = ' 0 ' c o n d i t i o n s o p e r a t o r = ' or ' >< condition source = ' self ' attribute = ' id ' match = ' ^ ext -.* d +.* ' negate = ' False ' / >< condition source = ' self ' attribute = ' id ' match = ' ^[ a - z ]+ - d {4}( -[ a - z ]*( - d *) ?) ? ' negate = ' False ' / > RxWeb jQuery XML < rule name = ' RxWeb jQuery ' enabled = ' True ' capability = ' webelement ' attribute = ' id ' setweight = ' 0 ' c o n d i t i o n s o p e r a t o r = ' or ' >< condition source = ' self ' attribute = ' id ' match = ' ^ ui - id - d + ' negate = ' False ' / > RxWeb ASP.net XML < rule name = ' RxWeb ASP . net ' enabled = ' False ' capability = ' webelement ' attribute = ' id ' setweight = ' 0 ' c o n d i t i o n s o p e r a t o r = ' or ' >< condition source = ' self ' attribute = ' id ' match = ' ^ ctl00 ($ textpipe _ ) (.*($ textpipe _ ) ) ' negate = ' False ' / > 438 RanoreXPath Weight Rule Library RxWeb GWT XML < rule name = ' RxWeb GWT ' enabled = ' True ' capability = ' webelement ' attribute = ' id ' setweight = ' 0 ' c o n d i t i o n s o p e r a t o r = ' or ' >< condition source = ' self ' attribute = ' id ' match = ' ^ gwt - uid - d +.* ' negate = ' False ' / >< condition source = ' self ' attribute = ' id ' match = ' ^ isc_ .+ ' negate = ' False ' / > RxWeb MS Dynamics CRM XML < rule name = ' RxWeb MS Dynamics CRM ' enabled = ' True ' capability = ' webelement ' attribute = ' id ' setweight = ' 0 ' c o n d i t i o n s o p e r a t o r = ' or ' >< condition source = ' self ' attribute = ' id ' match = ' [a - zA - Z_ ]+ _ {([0 -9 A - F ]+( -) ?) +} _ d + ' negate = ' False ' / > RxWin32 Random ControlIds XML < rule name = ' RxWin32 Random ControlIds ' enabled = ' False ' capability = ' nativewindow ' attribute = ' controlid ' setweight = ' 0 ' c o n d i t i o n s o p e r a t o r = ' or ' / > 439 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 464: Properties of a Ranorex ’Text’ Adapter 440 Ranorex UI Adapter Figure 465: 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# 441 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: 442 Ranorex UI Adapter Figure 466: Button of calculator application which provides a Ranorex Button and a Ranorex NativeWindow Adapter 443 Ranorex UI Adapter Figure 467: Button of a .NET WinForms application which provides an additional Ranorex Control adapter 444 Ranorex UI Adapter The Control adapter, which is available for .NET WinForms applications, allows Ranorex to access more properties in the application under test, like the background color or font size of the displayed text. Simply convert a standard Button adapter to a WinForms Control adapter as follows: C# // Create Button adapter with RanoreXPath Ranorex . Button button = ' / form [ @controlname = ’ TestedApp ’] / button [ @controlname = ’ button1 ’] ' ; // Convert Button adapter to Control adapter Ranorex . Control winFo rmsButto n = new Ranorex . Control ( button ) ; // Call ’ GetPropertyValue ’ method provided by the Control adapter Color color = w inForms Button . GetPropertyValue < color >( ' BackColor ' ) ; VB.NET ’ Create Button adapter with RanoreXPath Dim button As Ranorex . Button = ' / form [ @controlname = ’ TestedApp ’] / button [ @controlname = ’ button1 ’] ' ’ Convert Button adapter to Control adapter Dim winForm sButton As New Ranorex . Control ( button ) ’ Call ’ GetPropertyValue ’ method provided by the Control adapter Dim color As Color = w inForms Button . G et P r o p e r t y V a l u e ( Of Color ) ( ' BackColor ' ) It is not required to work with Ranorex adapters. It’s also possible to write automation code using Ranorex Element instances (which are used internally by Ranorex adapters) - it’s just more difficult. Note: UI objects managed within Ranorex repositories always use Ranorex adapters. 445 Mobile Testing Mobile Testing Learn how to automate Android or iOS app testing for different devices and languages. The following sections will explain how to set up an environment for mobile testing, how to generate and execute a test and what to do if any problems occur. The mobile apps KeePassDroid for Android and MiniKeePass for iOS are taken as examples on how to automate mobile applications using Ranorex. Introduction To automate apps on mobile devices (both iOS and Android), these devices need to be connected to a computer with Ranorex installed. The connection can be accomplished either with a USB cable or over Wi-Fi Getting Started To get started with mobile application test automation choose your platform below: Figure 468 Figure 469 Versioning Versioning ensures that only versions of the automation library and device service compatible with the currently installed Ranorex Studio version are used. When using an incorrect version of an automation library/device service, a warning or error message will be shown. If you are using an automation library/device service that is still compatible but is not the latest version, you will get a warning. It is always recommended to use the latest version because it includes the most recent bug fixes, meaning that you will most probably have the best possible automation experience. If for some reason you have to use an older library/service version, you can disable the technology limitation warning. If you are using an incompatible version you will get an error. In this case it is recommended to use the latest version or at least a compatible one. A version becomes incompatible when completely new features are integrated or the communication protocol is changed. Here you’ll find the Mobile Download Archive to download the correct automation libraries matching your Ranorex version. For further platform dependent information, have a look at the Android Testing and iOS Testing chapters. 446 Mobile Testing Mobile Download Archive Please follow the link to the mobile download archive on the Ranorex Website: https://bitly.com/mArchive. 447 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 and Run an Android Test Extended Information After doing your first steps in mobile testing on Android devices please find the following chapters providing detailed information on more advanced topics and testing scenarios. Manage Devices Non-UI Testing on Android Automation of System Apps Run Your Test on Any Android Device Testing of Mobile Websites on Android Troubleshooting Instrumentation with Source Code Add Device with Source Code Testing of Android Wear Apps Infrastructure Before getting started with Android test automation, it’s necessary to choose the connection type that suits your needs. The following overview helps you to find out which connection type will work best for you. Record Replay Start/Stop App Install APK Deploy (unattended) Automate System Apps USB Wi-Fi Even if automating via Wi-Fi it is recommended to have your system under test plugged into a power supply during test recording and execution. Note: To automate on a device connected via USB instead of Wi-Fi, have a look at ’Add a device connected via USB’. 448 Android Testing Getting Started This quick start guide will show you how easy it is to record your Android test and execute the test on different devices and Android languages. Prepare your Android device In order to ensure that the device connection is as stable as possible, it is recommended to enable the ’Developer Mode’ on your Android device. This mode grants access to some advanced settings which are responsible for a stable connection. On Android 4.2 and higher, ’Developer Mode’ is hidden by default. You can unhide it by navigating to ’Settings’ -> ’About Phone’ and tapping ’Build Number’ for seven times. Now return to the previous screen and find ’Developer options’ in the main menu: Figure 470: Enter ’Developer options’ Inside the ’Developer options’ menu, please enable the following settings: ’Stay awake’ which prevents your device from going to Standby during test automation. Note: Although you might be automating via Wi-Fi, your devices should always be connected to a power supply to ensure both letting this setting work as well as ensuring to not run out of battery during your tests. Furthermore it disables any energy saving mechanisms for your Wi-Fi interface and makes the Wi-Fi connection more stable. ’USB debugging’ (only when automating via USB) 449 Android Testing Figure 471: Enable ’Stay awake’ and ’USB debugging’ Start your first recording by pressing the record button in Ranorex Recorder. Next to starting a desktop, web or instant recording it is also possible to start a mobile recording. Figure 472: Choose technology to record 450 Android Testing Figure 473: Record a mobile test Add Device Open the ’Manage Device’ dialog by pressing the Devices button from the Record Settings dialog. As we there is no Android device listed open the ’Add new Device’ dialog by pressing the ’Add’ button. Choose ’Android’ and follow the instructions to install the Ranorex service on your Android device. Figure 474: Choose target technology 451 Android Testing Figure 475: Choose connection type Figure 476: 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. 452 Android Testing Figure 477: Installation of the Ranorex Service app Note: If you have more than one user account activated on your Android device, make sure that the Ranorex Service app is only installed and running on the owner’s 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 (binRxEnvAndroidtools). First of all, type ”adb devices”. If you installed the device’s USB driver correctly, adb devices should list the connected device properly. Secondly, type ”adb install /.apk” to install the service app. After performing these steps, start the installed service app on your device. After downloading and installing, the Ranorex Service app will be started on the device which can now be added to the list of devices by selecting your discovered device and clicking on the ’Finish’ button. 453 Android Testing Figure 478: 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. Figure 479: 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. 454 Android Testing Note: Note: It’s recommended to fresh instrument your app for every new Ranorex release. For further information have a look at the section ’Versioning’. Note: The Instrumentation Wizard can be started from command line. For further details have a look at the section ’Running Instrumentation Wizard from the Command Line’. Note: You can also instrument and deploy your APK in a recording or from code. For further details have a look the chapter ’Types of Action Items’ and the API documentation of the ’InstrumentAndDeployAndroidApp’ method. As mentioned before, the Android app KeePassDroid is taken as an example how to automate mobile applications using Ranorex. The APK file can be downloaded at https://storage.googleapis.com/google-code-archivedownloads/v2/code.google.com/keepassdroid/KeePassDroid-1.99.10.apk. Next to instrumenting and deploying your Android app, the Instrumentation Wizard allows you to update the Ranorex Service on your device as well as deploy the RXBrowser app, which enables web testing for Android. After choosing a device to deploy and an APK file to instrument, the process will be started by pressing the ’Next’ button. Figure 480: Android Instrumentation Wizard Note: Open the Advanced Instrumentation Settings dialog by clicking the Advanced button. Here you can change the APK signing as well as some instrumentation options. When enabling ”Full image comparison”, a more robust image comparison mechanism will be used. Enabling this option decreases the apps startup performance but might be useful when having problems with determining resource id’s for images. When disabling ”Tree simplification”, UI-trees will remain unchanged. This means no post processing will take place, resulting in larger UI-trees. Disabling this option decreases the apps startup performance but might be useful when automating 3rd party controls. 455 Android Testing After the instrumentation of the APK file, it will be automatically deployed to the selected device. Figure 481: Successfully finished instrumenting and deploying APK To finish the instrumentation and deployment process, the installation has to be confirmed on the mobile device. Figure 482: Confirm installation of instrumented APK Note: Because the Ranorex automation lib uses non-public API and adds additional permissions to your APK, make sure you do not release automated APKs to an app store to avoid biased user experience. 456 Android Testing Note: If you have problems with instrumenting your APK using the instrumentation wizard or if you want to integrate the instrumentation into your build process, please have a look at the ”Instrumentation with Source Code” section. Record and Run an 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 483: Mobile Recording with chosen device and app By pressing the ’Record’ button, the instrumented app will be automatically started on the mobile device and a notification on the desktop will inform the user, that actions will be recorded directly on the mobile device. Figure 484: Record notification During the recording process, the action table of the Ranorex Recorder will give a good overview over the performed 457 Android Testing steps, as the table is updated live. Figure 485: 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: It’s recommended to wait a short period of time before operating on list elements after scrolling the list. Note: It’s recommended to touch the text of a list element and not the empty space next to the text when operating a list element. During recording it’s possible to add validations using the ’Validation’ button. By pressing the button, a dialog will open where the element which should be validated can be chosen. 458 Android Testing Figure 486: 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. 459 Android Testing Figure 487: Choose attribute to validate Additionally to recording actions, it’s also possible to add actions to the action table after the recording process. This can be done by dragging a repository item to the action table and choosing the action which should be performed from the menu. Figure 488: Adding actions manually After recording and adding actions manually, the action table might look something like the following. 460 Android Testing Figure 489: Action table Action #1 is a ’Run Mobile App’ action which starts the instrumented APK file on the selected device. Note: You can add a launcher activity to your ”Run Mobile App” action by simply adding the activity name to the ”Startup Arguments” using the following syntax: / 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. Note: The duration for both, ’Touch’ and ’Long Touch’ can be defined int the properties pane. You can open this pane by clicking the context menu item ’Properties’ on the ’Touch Event’ action item. Action # 4 is a ’Set Value’ action, which is typically used for keyboard input. Action # 6 is a ’Wait For Not Exists’ action, which is useful when having for example an item indicating a loading process and the automation should go ahead when the item has disappeared. Action # 7 is a ’Validate’ action as described before. Action # 8 is a ’Get Value’ action, which can be used to write back an attribute value of a control to a variable for further processing. Action # 9 is a ’Report’ action, which is used to add information to the test report. Action # 10 is a ’Invoke Action’ which performs a scroll action on a list control to its index ’0’. ’Invoke Actions’ directly call the corresponding method of the selected control. You can use the invoke action to call user defined methods or get and set user defined members. To call such a user defined method 1. type ’CallMethod’ to the action name field of the invoke action 2. add the method name to the first argument field 3. add a value or a variable you want to pass to the method to the argument field or fields 461 Android Testing To get or set a member use ’GetMember’ or ’SetMember’ instead of ’CallMethod’ as action name. For further details about invoke action have a look at ”Invoking User-Defined Actions”. User defined methods can also be invoked from code the same way. Here is a short example: C# string text = ( string ) repo . App . Text . Element . InvokeAction ( ' CallMethod ' , ' m y C u s t o m G e t T e x t M e t h o d '); VB.NET Dim text As String = DirectCast ( repo . App . Text . Element . InvokeAction ( ' CallMethod ' , ' m y C u s t o m G e t T e x t M e t h o d ' ) , String ) Action # 11 is a ’Mobile Key Press’ action. ’Mobile Key Press’ actions simulate the physical buttons ’Back’ and ’Menu’ of the mobile device. Action # 12 is a ’Close Application’ action. ’Close Application’ actions stop the selected application on the mobile device. Note: Make sure to add a ’Close Application’ action, when running your test on different devices, because if the app will not be closed on the devices, the app on the first identified device will be automated. Stop Recording After performing the test on the mobile device, the recording process can be stopped by pressing the ’Stop’ button. Figure 490: 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. 462 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’ as target technology and ’Network’ as connection type and follow the instructions to install the Ranorex service on your Android device. Figure 491: Choose target technology 463 Android Testing Figure 492: Choose connection technology Figure 493: 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. 464 Android Testing Figure 494: Installation of the Ranorex service app After downloading and installing, the Ranorex Service app will be started on the device which can now be added to the list of devices by selecting your discovered device and clicking on the ’Finish’ button. 465 Android Testing Figure 495: Add Android device 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 isn’t listed’ button. The IP address can be found within the service app on the device by opening the settings. 466 Android Testing Figure 496: Ranorex Service app details view Figure 497: Add mobile device manually 467 Android Testing After adding a device, it is available within the ’Manage Devices’ dialog. Figure 498: 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. 468 Android Testing Figure 499: Choose ’Emulator’ Figure 500: Select the emulator 469 Android Testing Figure 501: 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 502: Choose USB 470 Android Testing Figure 503: Select the USB connected device Figure 504: 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. 471 Android Testing Figure 505: Failed to connect to mobile device 472 Android Testing Non-UI Testing on Android Next to automate testing of the user interface of mobile applications it’s also possible to perform non-UI tests invoking technology dependent actions (see Types of Action Items). This feature allows you to get information about the devices hardware, the operating system etc.You are able to get the device info of your Android device directly by right-clicking the mobile device in Ranorex Spy. Figure 506: Get device info of Android test device You can access the non-UI testing methods in the action table by adding an invoke action on the mobile app. 473 Android Testing Figure 507: Invoke non-UI testing methods You can also access the non-UI testing methods within User Code Actions as well as Code Modules. The code should look something like the following: C# var app = repo . AndroidApp . Self . As < AndroidApp >() ; // get an A n d r o i d D e v i c e I n f o object holding all available device info var info = app . GetDeviceInfo () ; // get a list of SMS from the device var sms = app . GetSms () ; // get a list of calls from the device var calls = app . GetCalls () ; // report the manufacturer of the device Report . Info ( ' Manufacturer : ' + info . Manufacturer ) ; // report the manufacturer of the device Report . Info ( ' SMS : ' + sms . ToString () ) ; // report the manufacturer of the device Report . Info ( ' Calls : ' + calls . ToString () ) ; VB.NET Dim app = repo . AndroidApp . Self .[ As ]( Of AndroidApp ) () ’ get an A n d r oi d D e v i c e I n f o object holding all available device info Dim info = app . GetDeviceInfo () ’ get a list of SMS from the device Dim sms = app . GetSms () ’ get a list of calls from the device Dim calls = app . GetCalls () ’ report the manufacturer of the device Report . Info ( ' Manufacturer : ' & info . Manufacturer ) ’ report the manufacturer of the device Report . Info ( ' SMS : ' & sms . ToString () ) ’ report the manufacturer of the device Report . Info ( ' Calls : ' & calls . ToString () ) 474 Android Testing For further information about code modules and user code actions please have a look at the sections ”Lesson 7: Code Modules” and ”User Code Actions”. 475 Android Testing Automation of System Apps When automating an Android App it might sometimes be necessary to leave the application under test. For example you want to: check if an issued notification has been received share something on a social network change the system settings As only the application under test is instrumented for Ranorex Automation you can only record within this application. To automate outside of the application you have to manually create the needed steps using the Ranorex Spy. Note: To automate system apps the setting ’Android OS Automation’ has to be enabled. The setting can be found in the mobile section of the plugin specific settings in Plugin Specific Settings. Note: To speed up the test execution of system app automation you can disable the generation of screenshots for android. The setting can be found in the mobile section of the plugin specific settings in Plugin Specific Settings. 476 Android Testing Figure 508: Enable Android OS automation Restrictions To automate system apps a USB connection has to be established. Highlighting on the device does not work for system apps Recording is not possible for system apps Validate an Issued Notification The following example will show how to validate a text in a received notification. Create a new recording and open the Ranorex Spy. You will notice a node labeled ’MobileApp AndroidOS’ at the application level in the object tree. 477 Android Testing Figure 509: System app in Spy To navigate through the element tree you can either use the tree view. Another way to navigate is to use the image navigator which can be found at the bottom of the Overview/Advanced tab. Clicking a UI element selects it, double-clicking outside the selected element selects the parent. To open the notification bar, a swipe action from the top of the screen has to be performed. Navigate to a tree element including the navigation bar in the representing screenshot and add this element to the repository using the context menu. 478 Android Testing Figure 510: Add a system app container to the repository Add a swipe action by dragging/dropping the newly created repository item to the actions table and choosing ’Swipe Action’ as action type from the context menu. 479 Android Testing Figure 511: Add a swipe gesture action In the properties pane set the swipe direction to ’90’ and the start location to ’0.5;0.0’ which is the top center of the element. Figure 512: Set properties of the swipe action Manually open the notification bar on your device and switch back to Ranorex Spy. Navigate through the element tree until you’ll find the element you want to validate. 480 Android Testing Figure 513: Identify the element to validate Add the specific element to the repository and add a validation action on the repository item as described before. Additionally add a key press on the back button to return to the initial situation. 481 Android Testing Figure 514: Added validation action After adding these three actions, the recording is ready to be executed. 482 Android Testing 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 515: Add a ’Close Application’ action to ensure that the recording will be executed on the right device After doing so, make the ’Device Display Name’ of the ’Run Mobile App’ action in your recording variable. Figure 516: 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. 483 Android Testing Figure 517: Open data source dialog.. Figure 518: Add a simple data table.. 484 Android Testing Figure 519: And add the device names to the simple data table After doing so, switch to the ’Data Binding’ tab and bind the data source to the variable in your recording. 485 Android Testing Figure 520: Bind the data source to the variable Have a look at Lesson 3: / >< uses - permission android:name = ' android . permission . INJECT_EVENTS ' / > 4. In your AndroidManifest.xml under the application node add: XML < meta - data android:name = ' RxVersion ' android:value = ' 5.0.0 ' / >< meta - data android:name = ' RxLibVersion ' android:value = ' 1.5.0 ' / > with the corresponding Ranorex and automation library version. 498 Android Testing Add Device with Source Code Add a using directive to Ranorex.Core.Remoting C# using Ranorex . Core . Remoting ; VB.NET Imports Ranorex . Core . Remoting Add the following code to add a device connected via Wi-Fi and start the first Ranorex instrumented app found on the device: C# var device = R e m o t e S e r v i c e L o c a t o r . Service . AddDevice ( ' DeviceName ' , Remo tePlatfo rm . Android , R e m o t e C o n n e c t i o n T y p e . WLAN , ' IPAddress ' ) ; device . WaitFor ( ChannelState . De vi ce C on ne ct e d ) ; var firstApp = device . R a n o r e x C o m p a t i b l e A p p s [0]; device . S t a r t A p p l i c a t i o n ( firstApp ) ; device . WaitFor ( ChannelState . AppConnected ) ; VB.NET Dim device = R e m o t e S e r v i c e L o c a t o r . Service . AddDevice ( ' DeviceName ' , Remo tePlatfo rm . Android , R e m o t e C o n n e c t i o n T y p e . WLAN , ' IPAddress ' ) Choose a proper device name and set the IP address of your device when using a network connection. When using a USB connection set the remote connection type to RemoteConnectionType.USB instead of RemoteConnectionType.WLAN and the serial of the device instead of the IP address. 499 Android Testing Testing of Android Wear Apps Following the instructions below you can easily create automated tests on compatible Android Wear apps directly on real or emulated devices. Prerequisites Install adb: The Android Debug Bridge (adb) is a versatile command line tool that lets you communicate with an emulator instance or connected Android device. You can find it at BinRxEnvAndroidtools. Connect with the phone: Download the Android Wear app on your phone and pair the watch with your phone. You can find detailed information on how to do so here: https://support.google.com/androidwear#topic=6056405 Enable the debug mode: On the smartphone go to ”Developer Options” and enable ”USB Debugging”. On the watch got to ”Developer Options” and enable ”ADB Debugging” as well as ”Debug over Bluetooth”. Finally, open the Android Wear app on your smartphone, press the Settings button on the top right and check the ”Debugging over Bluetooth”. The target should be shown as connected. Note: If the target is still disconnected, try to restart both the smartphone and the watch. Getting Started Connect the device via USB to your computer and call adb via command line by typing ”adb devices”. It should print something like this: List of devices attached 08937p69d0518aac device This means you have successfully connected your phone to your computer. Now we need to connect the watch too. Type the following commands: adb forward tcp:6666 localabstract:/adb-hub adb connect localhost:6666 Note: You need to accept the connection on your watch. Type once again ”adb devices”. You should now see a new device called localhost:6666: 08937p69d0518aac device localhost:6666 device In your Android Wear App, Host and Target should now show up as connected. Note: Connecting host and target does not always work at first go. Try restarting both devices in different order and be patient. Now you can Add Device, Instrument and Deploy your Android App and Record and Run an Android Test. Automate on an Emulated Device The following instructions explain how to connect a Genymotion emulated smartphone with a Google emulated watch. 500 Android Testing First, download Genymotion setup and start any Genymotion emulator with Android 4.3 or later. For Google’s emulated watch you need the AVD Manager. Start the Android Studio, go to Tools -> Android -> AVD Manager. Create a new Virtual Wear device and start it. Next, install Google Apps or Gapps on the Genymotion smartphone. With Gapps, also the Play Store will be installed, which is needed for downloading the Wear App. Go to http://wiki.cyanogenmod.org/w/Google Apps and download the correct Gapps for your emulator. To install Gapps on Genymotion, please follow these instructions. Note: Gapps may sometimes be unstable when running on Genymotion emulators. Follow the steps explained in Prerequisites and list your devices via adb as described in Getting Started. It should print something like this:List of devices attached 192.168.154.102:5555 device This means you have successfully connected your emulated phone to your computer. Now you need to connect the watch too. Type the following command into the command line:adb -s {genimotion ip}:{genimotion port} -d forward tcp:5601 tcp:5601 Type once again the ”adb devices” command. You should see a new device called emulator-5600. You can now Add Device, Instrument and Deploy your Android App and Record and Run an Android Test. 501 iOS Testing iOS Testing Learn how to automate your iOS app testing for different iPhone/iPad devices and languages. The following sections will explain how to set up an environment for iOS testing, how to generate and execute a test and what to do if any problems occur. The iPhone/iPad app MiniKeePass is taken as an example of mobile application automation using Ranorex. Infrastructure Getting Started Record and Run an iOS Test Extended Information After doing your first steps in mobile testing on iOS devices please find the following chapters providing detailed information on more advanced topics and testing scenarios. Instrumentation and Preparation iOS Service App Non-UI Testing on iOS Run a Test on Any iOS Device Testing of Mobile Websites on iOS Instrumentation with Source Code on iOS Infrastructure Before getting started with iOS test automation, it’s necessary to choose the connection type that suites your needs. The following overview helps you to find out which connection type will work best for you. Record Replay Start/Stop App Install IPA Deploy (unattended) USB Wi-Fi Note: To make an iOS app testable with Ranorex, it is necessary to instrument the app. However, for a quick start you can take your first steps with the pre-instrumented KeePass app (see Getting Started) that is provided for download. USB Requirements iTunes is necessary to establish a USB connection (debug mode and non-debug mode) because iTunes installs the USB driver on the Windows machine to connect to iOS devices. 502 iOS Testing Network Requirements When choosing ”Wi-Fi” as connection type, it is recommended that you have your system under test plugged into a power supply during test recording and execution. Additionally make sure that the system under test (the mobile devices) and the machine running the tests (where Ranorex is installed) are on the same network. Getting Started Although at the end of the day you might want to test your own mobile application, you can also take your first steps with the pre-instrumented MiniKeePass app. Please scan the QR code with your device and follow the link to the mobile download archive. From there the app can easily be installed. Figure 532: QR code for the mobile download archive Note: In order to automate your own mobile app it needs to be instrumented guided by the instructions in the section Instrumentation and Preparation. The following steps are needed to get started with the sample application: 1. Connect your iOS device (Wi-Fi or USB). See Infrastructure for pros and cons. 2. Go to the mobile download archive on your device using the QR Code above or the url bitly.com/mArchive. 3. Download and install the iOS service app and make sure it is started on your device. 4. Download and install the sample app and initially start it to let the service app recognize it. 5. Add the device in Ranorex using the Device Wizard. You’ll find more details in the section Adding Your iOS Device 6. Start your mobile recording Note: There is a small sample delivered with Ranorex Studio (can be found on the start page) that shows how the iOS MiniKeePass app can easily be tested with Ranorex. 503 iOS Testing Record and Run an 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 to be tested. Figure 533: Mobile recording with chosen target technology.. Figure 534: ..device and app By pressing the ’Record’ button, a notification on the desktop will inform you, that actions will be recorded directly on the mobile device. 504 iOS Testing Figure 535: Record notification During the recording process, the action table of the Ranorex Recorder will give a good overview of the steps performed as the table is updated live. 505 iOS Testing Figure 536: 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 is to be validated can be selected. 506 iOS Testing Figure 537: Select element to validate After choosing an element, the ’Validate Element’ dialog will pop up. In this dialog, the attributes to be validated can be selected. 507 iOS Testing Figure 538: Choose attribute to validate 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. 508 iOS Testing Figure 539: Adding actions manually If your device is connected via USB you can also add a ’Deploy iOS App’ action to automatically deploy the current version of your application under test for each test run. Choose the device, the file location of the app archive and the app id to enable automated deployment. Figure 540: Add ’Deploy iOS App’ action After recording and adding actions manually, the action table might look something like the following. 509 iOS Testing Figure 541: 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 two 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 can be compared to a right click. Note: The duration for both ’Touch’ and ’Long Touch’ can be defined in the properties pane. You can open this pane by clicking the context menu item ’Properties’ on the ’Touch Event’ action item. Action #4 is a ’Set Value’ action, which is typically used for keyboard input. Action #5 is a ’Mobile Key Press’ action. With a ’Mobile Key Press’ action you can simulate the ’Enter’ button on your devices keyboard. Action #6 is a ’Wait For Not Exists’ action, which is useful for cases where an item indicates a loading process and the automation should continue after the item has disappeared. Action #7 is a ’Validate’ action as was previously described. 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. You can use the invoke action to call user-defined methods or get and set user-defined members. To call such a user-defined method 1. Type ’CallMethod’ into the action name field of the invoke action 2. Add the method name to the first argument field 3. In the following argument field enter a value or choose a variable you want to pass to the method 4. Repeat the previous step for all additional arguments 510 iOS Testing To get or set a member, use ’GetMember’ or ’SetMember’ instead of ’CallMethod’ as the action name. For further details about invoke action, have a look at Invoking User-Defined Actions. User-defined methods can also be invoked from code in the same way. Here is a short example: C# string text = ( string ) repo . App . Text . Element . InvokeAction ( ' CallMethod ' , ' m y C u s t o m G e t T e x t M e t h o d '); VB.NET Dim text As String = DirectCast ( repo . App . Text . Element . InvokeAction ( ' CallMethod ' , ' m y C u s t o m G e t T e x t M e t h o d ' ) , String ) Action #11 is a ’Close Application’ action. ’Close Application’ actions stop the selected application on the mobile device. Stop Recording After performing the test on the mobile device, the recording process can be stopped by pressing the ’Stop’ button. Figure 542: 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. 511 iOS Testing Instrumentation and Preparation This quick starting guide will show you, how to prepare your iOS project before creating the application package (IPA file) and how to Instrument and Deploy iOS applications using Ranorex Studio. Prepare your iOS device It’s recommended to disable the ’Auto-Lock’ functionality during your test executions. To do this, open the Settings app, tap the ’General’ settings, choose ’Auto-Lock’ settings and set ’Auto-Lock’ to ’Never’. Figure 543: Disable Auto-Lock Prepare Your iOS Project Before Creating the IPA File In order to ensure that the instrumentation and deploying will work correctly, it is recommended to do the steps described below. Make sure that no Ranorex libs are linked to the project. Note: Ranorex studio cannot instrument iOS applications, which have been already instrumented with Xcode using the Ranorex libs. The iOS Deployment target should be correctly set. 512 iOS Testing Note: If the Deployment target doesn’t match, between the iOS device and the iOS application, Ranorex Studio will show you an error message that will tell you why the application could not be deployed. Figure 544: Correctly set the deployment target Make sure that the Architecture (armv7 or arm64) match with the iOS device, which will be used for testing. Obtaining the P12 Certificate and the Mobile Provisioning Profile All iOS applications must be correctly signed with P12 certificate and matching provisioning profile. Because the instrumentation will make some changes to the application package (IPA file), the application must be signed again. Note: For more information about signing and distribution, refer to the official Apple documentation. To obtain the P12 certificate, perform the following steps: Open the Keychain Access tool on your Mac machine. Under the Category section, select My Certificates. 513 iOS Testing Figure 545: Export the certificate Make a right mouse click on your certificate and choose Export. Type a password and save the certificate. Figure 546: Enter password Note: Make sure that you have chosen a valid Developer certificate. The mobile provisioning profile can be obtained with Xcode or on the iOS Dev Center website. If you are using Xcode, perform the following steps: In Xcode menu choose Xcode and select the Preferences option. Select your Apple ID and choose View Details 514 iOS Testing Figure 547: Select your Apple ID In Signing Identities choose iOS Development With the right mouse click select your Provisioning Profile and choose Show in Finder 515 iOS Testing Figure 548: Show profile file in finder Copy the Provisioning Profile to your windows machine If you are using the iOS dev center website, please make the following steps: Navigate to https://developer.apple.com/devcenter/ios/index.action Log with your developer account Go to Member Center Go to Certificates, Identifiers & Profiles Choose Provisioning Profiles Download your Provisioning Profile 516 iOS Testing Figure 549: Download provisioning profile Note: The development provisioning profile should be used for testing your app and not the distribution provisioning profile. Adding Your iOS Device Note: When using Wi-Fi as the connection type, make sure that your iOS device or simulator is reachable over Wi-Fi. Start your first recording by pressing the Record button in Ranorex Recorder. Next to starting a desktop, web or instant recording it is also possible to start a mobile recording. Open the ’Manage Device’ dialog by pressing the ’Add device’ button in the Record Settings dialog. Figure 550: Choose technology to record 517 iOS Testing Figure 551: Record a mobile test Choose ’iOS (iPhone, iPad)’ and follow the instructions to install the service app on your device shown in the following dialog. Figure 552: Choose ’iOS’ 518 iOS Testing Figure 553: Install service app Make sure that the service app is running on your device. Choose the preferred connection type. Figure 554: Choose connection type When choosing USB as the connection type, the connected device should be discovered automatically. Choose the device from the list to finish the process. 519 iOS Testing Figure 555: Add new device If the device cannot be found automatically click the ”The device isn’t listed” button. Enter the name of the device and choose the corresponding device serial. Figure 556: Add device manually When choosing Wi-Fi as the connection type the device should be visible in the list of devices. Choose the device to add it to your list of devices. If the device cannot be found automatically, click the ”The device isn’t listed” button. Enter a name and IP address of the device and click ”Finish” to add the device manually. 520 iOS Testing Figure 557: Manually adding device Figure 558: Added iOS device Instrument and Deploy Your iOS Application Package Apart from Instrumentation with Source Code on iOS the recommended way is to instrument iOS application packages (IPA files) with Ranorex Studio on a Windows machine. Note: Note: It’s recommended to fresh instrument your app for every new Ranorex release. For further information have a look at the section ’Versioning’. After setting up the iOS device, the app which should be automated has to be instrumented and deployed to the 521 iOS Testing device. The Instrumentation wizard for instrumenting and deploying an IPA file can be started from ’Manage Devices’ dialog or directly by starting the instrumentation wizard as described in the section iOS. Figure 559: iOS instrumentation wizard Before instrumenting any IPA file, the iOS signing must be configured first. To do so, press Settings button in the Instrumentation wizard for iOS. In the iOS instrumentation Settings dialog choose your P12 certificate, type the correct password and choose the mobile provisioning profile. To get the P12 certificate and mobile provisioning profile, please read the chapter Obtaining the P12 Certificate and the Mobile Provisioning Profile. 522 iOS Testing Figure 560: Instrumentation settings After choosing an iOS USB connected device to deploy and an IPA file to instrument, the process will be started by pressing the ’Next’ button. 523 iOS Testing Non-UI Testing on iOS In addition to automating testing of the user interface of mobile applications, it’s also possible to perform non-UI tests invoking technology-dependent actions (see Types of Action Items). This feature allows you to get information about the devices hardware, the operating system etc. To enable this feature you have to additionally link the library Mobile Download Archive as well as the following libraries: AVFoundation.framework CoreTelephony.framework SystemConfiguration.framework ExternalAccessory.framework Now you are able to get the info on your iOS device directly by right-clicking the mobile device in Ranorex Spy. Figure 561: Get device info on an iOS test device You can access the device information during your test automation within User Code Actions as well as Code Modules. The code should look something like the following: C# var app = repo . iOSApp . Self . As < IosApp >() ; // get an iOSDeviceInfo object holding all available device info 524 iOS Testing var info = app . GetDeviceInfo () ; // Report e . g . the IP address of the device Report . Info ( ' IP address : ' + info . IpAddress ) ; VB.NET Dim app = repo . iOSApp . Self .[ As ]( Of IosApp ) () ’ get an iOSDeviceInfo object holding all available device info Dim info = app . GetDeviceInfo () ’ Report e . g . the IP address of the device Report . Info ( ' IP address : ' & Convert . ToString ( info . IpAddress ) ) For further information about code modules and user code actions please have a look at the sections ”Lesson 7: Code Modules” and ”User Code Actions”. 525 iOS Testing iOS Service App This quick starting guide will show you, how to properly use the new iOS RxServiceApp to create automated tests and how to prepare your iOS project so that start/stop app functionality can be used. Prepare Your iOS Project to Enable Start/Stop Functionality Note: The following step by step instructions are based on Xcode 6. If the app will be instrumented manually, please do the following steps to register the custom URL scheme so that the starting and stopping will work correctly: Open your project in Xcode 6.x Follow the instructions in the section Instrumentation with Source Code on iOS In Xcode choose the ”Info” tab Under Custome iOS Target Properties add URL types key Expand URL types key with Item0 Expand Item0 with URL schemes Expand URL schemes with Item0 and write the app activity name as value Figure 562: Enable start/stop functionality Note: If no URL scheme is set, the app under test cannot be launched and you will get an error message when you try to start the app with Ranorex. In the app list of the iOS RxServiceApp there will be also a warning message ”Can’t launch”. After Instrumenting and deploying the app for the first time, start the app manually once. 526 iOS Testing Note: The newly instrumented and deployed app, needs to be started manually for the first time, so that it gets registered at the RxServiceApp. Note: If the app is instrumented with Ranorex Studio on the Windows machine, the correct URL scheme will be set automatically. Proper use of the iOS Service App To use the new start/stop functionality via USB or WiFi, make sure that the RxServiceApp is running and is active on the device. You can either use the instrumentation wizard to deploy the service app as described in ”iOS”, or download and install the service app on your device from our mobile download archive by scanning the following QR Code or the using the following short URL: Figure 563: Use the QR Code above or the url bitly.com/mArchive to directly access the download archive on your mobile device. Note: Start/Stop functionality can not be used from the home screen of the device, even if the RxServiceApp is running in the background. You can still create automated tests without the iOS RxServiceApp. Please note that without the RxServiceApp the start/stop functionality won’t work. To add a device without the service app, make sure that an instrumented app is running and active on the device. Note: When using the start functionality, the app under test will be launched multiple times, because it needs to be reseted into initial state. 527 iOS Testing Note: If you want to create automated test on an instrumented app that has no URL Scheme, please make sure, that the RxServiceApp is not installed on the device and that the testing app is active on the device. 528 iOS Testing Run a 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 convert the ’Device Display Name’ value of the ’Run Mobile App’ action in a recording variable. Figure 564: Make the device name value variable After making the device name value variable, open the ’Data Source’ dialog of the test case with your recording and add a new simple data table containing the names of the devices on which you want to run the test on. 529 iOS Testing Figure 565: Add a simple data table Figure 566: Add the device names to the simple data table 530 iOS Testing After doing so, switch to the ’Data Binding’ tab and bind the data source to the variable in your recording. Figure 567: Bind the data source to the variable See Lesson 3: ; // Open a website webDocument . Navigate ( ' http :// www . ranorex . com ' ) ; // Wait until the document is loaded webDocument . W a i t F o r D o c u m e n t L o a d e d () ; // Execute a javascript code webDocument . ExecuteScript ( ' history . back () ; ' ) ; VB.NET ’ Identify a web document by its title Dim webDocument As WebDocument = ' / dom [ @caption = ’ Ranorex Test Page ’] ' ’ Open a website webDocument . Navigate ( ' http :// www . ranorex . com ' ) ’ Wait until the document is loaded webDocument . W a i t F o r D o c u m e n t L o a d e d () ’ Execute a javascript code webDocument . ExecuteScript ( ' history . back () ; ' ) 545 Web Testing Find or filter Web Elements The Ranorex Framework offers a wide range of adapters for each HTML tag elements (e.g.: ATag adapter for tags). Each adapter has specific methods and attributes; the link tag () 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 () 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 ’] ' ; 546 Web Testing okIE . Click () ; } // If the current browser is Mozilla Firefox else if ( webDocument . BrowserName ' Mozilla ' ) { Button okFF = ' / form [ @processname = ’ firefox ’]// button [ @text = ’ OK ’] ' ; okFF . Click () ; } // If the current browser is Google Chrome else if ( webDocument . BrowserName ' Chrome ' ) { Button okChrome = ' / form [ @processname = ’ chrome ’]// button [ @text = ’ OK ’] ' ; okChrome . Click () ; } // If the current browser is Apple Safari else if ( webDocument . BrowserName ' Safari ' ) { Button okSafari = ' / form [ @processname = ’ Safari ’]// button [ @text = ’ OK ’] ' ; okSafari . Click () ; } VB.NET ’ Click the OK button in popping up dialog of one of the supported browser ’ If the current browser is Internet Explorer If webDocument . BrowserName = ' IE ' Then Dim okIE As Button = ' / form [ @processname ~ ’( iexplore | IEXPLORE ) ’]// button [ @text = ’ OK ’] ' okIE . Click () ’ If the current browser is Mozilla Firefox ElseIf webDocument . BrowserName = ' Mozilla ' Then Dim okFF As Button = ' / form [ @processname = ’ firefox ’]// button [ @text = ’ OK ’] ' okFF . Click () End If ’ If the current browser is Google Chrome ElseIf webDocument . BrowserName = ' Chrome ' Then Dim okChrome As Button = ' / form [ @processname = ’ chrome ’]// button [ @text = ’ OK ’] ' okChrome . Click () End If ’ If the current browser is Apple Safari ElseIf webDocument . BrowserName = ' Safari ' Then Dim okSafari As Button = ' / form [ @processname = ’ Safari ’]// button [ @text = ’ OK ’] ' okSafari . Click () End If 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 Recorder’s actions table. The corresponding repositorycontains all required UI web element objects used within the actions table. 547 Web Testing Figure 586: Web based recording Repositories and the WebDocument The following example shows how to access the methods of the WebDocument using a repository: C# // Load repository P r o j e c t R e p o s i t o r y repo = P r o j e c t R e p o s i t o r y . Instance ; // Open a website repo . WebPage . Self . Navigate ( ' http :// www . ranorex . com ' ) ; // Wait until the document is loaded repo . WebPage . Self . W a i t F o r D o c u m e n t L o a d e d () ; VB.NET ’ Load repository Dim repo As P r o j e c t R e p o s i t o r y = P r o j e c t R e p o s i t o r y . Instance ’ Open a website repo . WebPage . Self . Navigate ( ' http :// www . ranorex . com ' ) ’ Wait until the document is loaded repo . WebPage . Self . W a i t F o r D o c u m e n t L o a d e d () 548 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: https://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 (.SamplesWebTestSample) Figure 587: Ranorex Web Testing reference page Handling of AJAX C# G l o b a l R e p o s i t o ry repo = G l o b a l R e p o s i t o r y . Instance ; WebDocument webDocument = repo . WebPage . Self ; // Fill out the AJAX form InputTag input1 = webDocument . FindSingle ( ' .// form [ @id = ’ ajax - form ’]/ fieldset // input [ @name = ’ value1 ’] ' ) ; input1 . EnsureVisible () ; input1 . Value = ' Size ' ; 549 Web Testing InputTag input2 = webDocument . FindSingle ( ' .// form [ @id = ’ ajax - form ’]/ fieldset // input [ @name = ’ value2 ’] ' ) ; input2 . Value = ' Weight ' ; InputTag checkbox = webDocument . FindSingle ( ' .// form [ @id = ’ ajax - form ’]/ fieldset // input [ @name = ’ checkbox2 ’] ' ) ; checkbox . Checked = ' true ' ; SelectTag selectColor = webDocument . FindSingle ( ' .// form [ @id = ’ ajax - form ’]/ fieldset // select [ @name = ’ color2 ’] ' ) ; selectColor . TagValue = ' blue ' ; // Submit data InputTag submit = webDocument . FindSingle ( ' .// form [ @id = ’ ajax - form ’]// input [ @id = ’ submit - ajax ’] ' ) ; submit . Click () ; // Wait for the ajax request for max 10 seconds (10000 milliseconds ) PreTag result = webDocument . FindSingle ( ' .// div [ @id = ’ ajax_response ’]/ div / pre ' , 10000) ; VB.NET Dim repo As G l o b a l R e po s i t o r y = G l o b a l R e p o s i t o r y . Instance Dim webDocument As WebDocument = repo . WebPage . Self ’ Fill out the AJAX form Dim input1 As InputTag = webDocument . FindSingle ( ' .// form [ @id = ’ ajax - form ’]/ fieldset // input [ @name = ’ value1 ’] ' ) input1 . EnsureVisible () input1 . Value = ' Size ' Dim input2 As InputTag = webDocument . FindSingle ( ' .// form [ @id = ’ ajax - form ’]/ fieldset // input [ @name = ’ value2 ’] ' ) input2 . Value = ' Weight ' Dim checkbox As InputTag = webDocument . FindSingle ( ' .// form [ @id = ’ ajax - form ’]/ fieldset // input [ @name = ’ checkbox2 ’] ' ) checkbox . Checked = ' true ' Dim selectColor As SelectTag = webDocument . FindSingle ( ' .// form [ @id = ’ ajax - form ’]/ fieldset // select [ @name = ’ color2 ’] ' ) selectColor . TagValue = ' blue ' ’ Submit data Dim submit As InputTag = webDocument . FindSingle ( ' .// form [ @id = ’ ajax - form ’]// input [ @id = ’ submit ajax ’] ' ) submit . Click () ’ Wait for the ajax request for max 10 seconds (10000 milliseconds ) Dim result As PreTag = webDocument . FindSingle ( ' .// div [ @id = ’ ajax_response ’]/ div / pre ' , 10000) List elements of a table and set css style C# G l o b a l R e p o s i t o ry repo = G l o b a l R e p o s i t o r y . Instance ; WebDocument webDocument = repo . WebPage . Self ; // List all elements of a table foreach ( TrTag row in repo . WebPage . DivTagContent . T a b l e T a g S i m p l e t a b l e . Find ( ' ./ tbody / tr ' ) ) { string rowInfo = ' ' ; TdTag rowNameCell = row . FindSingle ( ' ./ td [2] ' ) ; rowInfo += ' Row index : ' + rowNameCell . Pr e vi ou sS i bl in g . InnerText + ' , ' ; rowInfo += ' Row name : ' + rowNameCell . InnerText + ' , ' ; rowInfo += ' Row value : ' + rowNameCell . NextSibling . InnerText + ' , ' ; // 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 ff00 ' ) ; } Report . Info ( rowInfo ) ; } 550 Web Testing VB.NET Dim repo As G l o b a l R e po s i t o r y = G l o b a l R e p o s i t o r y . Instance Dim webDocument As WebDocument = repo . WebPage . Self ’ List all elements of a table For Each row As TrTag In repo . WebPage . DivTagContent . T a b l e T a g S i m p l e t a b l e . Find ( ' ./ tbody / tr ' ) Dim rowInfo As String = ' ' Dim rowNameCell As TdTag = row . FindSingle ( ' ./ td [2] ' ) rowInfo += ' Row index : ' & rowNameCell . Pr e vi ou sS i bl in g . InnerText & ' , ' rowInfo += ' Row name : ' & rowNameCell . InnerText & ' , ' rowInfo += ' Row value : ' & rowNameCell . NextSibling . InnerText & ' , ' ’ Get all cells from the row rowInfo += ' All Cells : ' For Each cell As TdTag In row . Find ( ' ./ td ' ) rowInfo += cell . InnerText & ' , ' ’ Move the mouse to each cell element cell . MoveTo () ’ Set css style cell . SetStyle ( ' background - color ' , ' #33 ff00 ' ) Next Report . Info ( rowInfo ) Next Set inputs, tag attributes and perform a click without mouse C# // Use mouse and keyboard to set Name repo . WebPage . TestForm . I n p u t T a gT e s t n a m e . Click () ; Keyboard . Press ( ' Test Name ' ) ; // Set email address directly via ’ Value ’ repo . WebPage . TestForm . I n p u t T a g T e s t e m a i l . Value = ' VB.NET ’ Use mouse and keyboard to set Name repo . WebPage . TestForm . I n p u t T a gT e s t n a m e . Click () Keyboard . Press ( ' Test Name ' ) ’ Set email address directly via ’ Value ’ repo . WebPage . TestForm . I n p u t T a g T e s t e m a i l . Value = ' 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 551 Web Testing 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 552 Source Control Source Control Introduction to Source Control A source control system, also called revision control or version control system (VCS), keeps track of changes to a file or set of files. One can thus see who made changes and when. It allows reverting single files, or an entire project, to a previous state and comparing changes over time. It provides an easy way to recover previous versions of a file or project. There are two types of version control systems: centralized version control systems, such as Subversion and Team Foundation Version Control, and distributed version control systems like Git. Important notice This User Guide section provides information on the software prerequisites for each of the supported version control systems and how they can be used within Ranorex Studio. As a precondition we assume you have knowledge about version control in general, as well as your specific version control system. Setting up and configuring the version control system of your choice is not in the scope of this documentation. Source Control in Ranorex Studio Ranorex Studio supports three version control systems. You can find more details on how to connect Ranorex Studio with these version control systems in the corresponding chapters: Git Subversion Microsoft Team Foundation Server (TFVC) 553 Source Control Git Using Git for Source Control About Git and Ranorex Studio Add a Ranorex Solution to Git Check out a Ranorex Solution from Git Icon overlays in Projects View About Git and Ranorex Studio Git is a distributed version control system which is free and open source. In order to use Git as a source control provider in Ranorex Studio, the following preconditions have to be fulfilled in the given order: Git needs to be installed Download Git for Windows here: https://git-scm.com/download/win Please make sure you choose to ’Use Git from the Windows Command Prompt’ during Git installation! Figure 588 554 Source Control TortoiseGit needs to be installed Download TortoiseGit here: https://tortoisegit.org/download TortoiseGit is a Windows shell interface to Git and is needed, for example, to overlay icons which show the file status. Ranorex Studio will assist you with this dialog in case the required prerequisite is not present on the machine: Figure 589 Add a Ranorex Solution to Git Please make sure your Git infrastructure is set up and working. To add an existing Ranorex Solution to Git, open the context menu of the solution. Go to ’Source Control’ and select ’Add Solution to Source Control’. 555 Source Control Figure 590 To add a new Ranorex Solution to Git, check the option ’Add to Source Control’ in the ’New Project’ dialog. 556 Source Control Figure 591 The ’Source Control Wizard’ will be opened. Please follow these instructions: 1. Choose ’Git’ as Source Control provider. 557 Source Control Figure 592 2. The Ranorex Solution is automatically configured as a new local Git repository. All files are indicated with a plus sign in Projects View. 558 Source Control Figure 593 3. To commit the current state to the local repository click on ’Commit..’ in the context menu of the solution. 559 Source Control Figure 594 560 Source Control 4. After the commit a check symbol is shown in Projects View. Figure 595 All further Git related steps should be defined in your workflow. Check out a Ranorex Solution from Git Please make sure your Git infrastructure is set up and working. 1. Open the ’Tools’ menu, move to ’Source Control’ and click on ’Checkout’. 561 Source Control Figure 596 2. Choose ’Git’ as Source Control provider in Source Control Wizard. 562 Source Control Figure 597 3. TortoiseGit will ask you for the path to the repository and where you would like to store the files on your local machine. Fill in the URL to the Git repository as well as the path to the local directory and press ’OK’. 563 Source Control Figure 598 4. The whole repository will be cloned to the local folder. After a successful clone this dialog will be shown. 564 Source Control Figure 599 5. In case your repository includes a Ranorex Solution in its root, this solution will be opened automatically. If this is not the case, you have to open the Ranorex Solution manually from the file System. After opening the Ranorex Solution from the local folder you see the icon overlays in Projects View. 565 Source Control Figure 600 All further Git related steps should be defined in your workflow. Icon overlays in Projects View Overlay icons are added to the items in the Projects View in Ranorex Studio, as the solution is under source control. Icon overlays Normal Not locally modified, no changes waiting for commit. Conflicted Indicates a conflict. Modified Modified, changes are waiting to be committed. Added Marked for addition, waiting to be committed. 566 Source Control Subversion Using Subversion for Source Control About Subversion and Ranorex Studio Add a Ranorex Solution to Subversion Check out a Ranorex Solution from Subversion Icon overlays in Projects View Options Using another version of SharpSvn and TortoiseSVN About Subversion and Ranorex Studio Subversion is a centralized version control system by Apache (https://subversion.apache.org/ ). To get more information about Subversion, please have a look at the official Subversion online documentation: http://svnbook.org Ranorex Studio uses two applications for working with subversion, which are installed with Ranorex Studio by default: SharpSvn Is a set of libraries for working with Subversion. TortoiseSVN It is a Windows shell extension for Subversion and provides the icon overlays showing the file status in Ranorex Studio. Ranorex Studio will assist you with this dialog in case the required prerequisite is not present on the machine: Figure 601 Add a Ranorex Solution to Subversion Please make sure your Subversion infrastructure is set up and working. To add anexisting Ranorex Solution to Subversion, open the context menu of the solution. Go to ’Source Control’ and click on ’Add Solution to Source Control’. 567 Source Control Figure 602 To add a new Ranorex Solution to Subversion, check the option ’Add to Source Control’ in the ’New Project’ dialog. 568 Source Control Figure 603 The ’Source Control Wizard’ will be opened. Please follow these instructions: 1. Choose ’Subversion’ as Source Control provider. 569 Source Control Figure 604 2. TortoiseSVN will ask for the URL of the repository. Figure 605 3. Authenticate yourself on the subversion server. 570 Source Control Figure 606 4. Choose the folder in the repository you want to add your solution to. 571 Source Control Figure 607 5. Check the files you want to have under source control and uncheck the files you don’t want to have under source control respectively. 572 Source Control Figure 608 6. The chosen files will be added to source control. 573 Source Control Figure 609 7. Now, commit the changes to the Subversion server. 574 Source Control Figure 610 8. The commit is done. 575 Source Control Figure 611 After performing these steps, your solution is under source control and your local copy is up to date. Figure 612 Check out a Ranorex Solution from Subversion Please make sure your Subversion infrastructure is set up and working. 1. Open ’Tools’ menu, move to ’Source Control’ and click on ’Checkout’. 576 Source Control Figure 613 2. Choose ’Subversion’ as Source Control provider in Source Control Wizard. 577 Source Control Figure 614 3. Enter the URL of your repository and specify the checkout directory. 578 Source Control Figure 615 4. The chosen project will be checked out. 579 Source Control Figure 616 Icon overlays in Projects View Overlay icons are added to the items in the Projects View in Ranorex Studio, as the solution is under source control. Icon overlays Normal Not locally modified, no changes waiting for commit. Conflicted Indicates a conflict. Modified Modified, changes are waiting to be committed. Added Marked for addition, waiting to be committed. Options In Ranorex Studio Options you can find options related to Subversion. Open main menu item ’Tools’ and choose ’Options’. In the following dialog select folder ’Tools’ and sub-item ’Subversion Options’. By default, all checkboxes are checked. The currently used SharpSvn version can be found here. 580 Source Control Figure 617 Using another version of SharpSvn and TortoiseSVN In order to use another version of TortoiseSVN and SharpSvn than the preinstalled ones, you have to download and install the version you want to use: Download and install TortoiseSVN first from http://tortoisesvn.tigris.org/. After that download, the corresponding package for SharpSvn from https://sharpsvn.open.collab.net. Please make sure you choose the right version of SharpSvn, which matches the TortoiseSVN version. Extract the downloaded Version. Copy the extracted folder to ’RanorexStudioAddInsSourceControlSubversionAddin’. Once you restart Ranorex Studio, the correct version of SharpSVN will be automatically chosen. 581 Source Control Team Foundation Version Control (TFVC) Using Team Foundation Version Control (TFVC) for Source Control About Team Foundation Version Control (TFVC) and Ranorex Studio Add a Ranorex Solution to TFVC Check out a Ranorex Solution from TFVC Icon overlays in Projects View Options About Team Foundation Version Control (TFVC) and Ranorex Studio Team Foundation Version Control (TFVC) is a centralized version control system by Microsoft included in Team Foundation Server. In order to work with TFVC in Ranorex Studio either Microsoft Visual Studio or Team Explorer for Microsoft Visual Studio have to be installed on the same machine. These programs come with the required ’Team Foundation Server MSSCCI Provider’. Ranorex Studio will assist you with this dialog in case the required prerequisite is not present on the machine: Figure 618 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. Add a Ranorex Solution to TFVC Please make sure your Team Foundation Server infrastructure is set up and working. 582 Source Control For adding anexisting Ranorex Solution to TFVC open the context menu of the solution. Go to ’Source Control’ and click on ’Add Solution to Source Control’. Figure 619 To add a new Ranorex Solution right from the beginning to TFVC check the option ’Add to Source Control’ in the ’New Project’ dialog. 583 Source Control Figure 620 The ’Source Control Wizard’ will be opened. Please follow these instructions: 1. Choose ’Microsoft Team Foundation Server’ as Source Control provider. 584 Source Control Figure 621 2. Select your Team Foundation Server. 585 Source Control Figure 622 3. Choose the folder you want to add your solution to. 586 Source Control Figure 623 587 Source Control 4. Select the files you want to have under source control and deselect the files you don’t want to have under source control respectively and perform a check in. Figure 624 After performing these steps, your solution is under source control and your local copy is up to date. 588 Source Control Figure 625 Check out a Ranorex Solution from TFVC Please make sure your Team Foundation Server infrastructure is set up and working. 1. Open ’Tools’ menu, move to ’Source Control’ and click on ’Checkout’. Figure 626 2. Choose ’Microsoft Team Foundation Server’ as Source Control provider in Source Control Wizard. 589 Source Control Figure 627 3. Specify the local check out Directory 590 Source Control Figure 628 4. Select your Team Foundation Server. Figure 629 5. Choose the folder in the repository you want to check out from server. 591 Source Control Figure 630 592 Source Control 6. The chosen solution will be checked out. Icon overlays in Projects View Overlay icons are added to the items in the Projects view in Ranorex Studio as the solution is under source control. Icon overlays Checked In File under source control, not checked out for editing. Checked out File under source control, checked out, not dirty. Checked out Modified File under source control, checked out, dirty. Added File added to project, not checked in. Options In Ranorex Studio Options you can find options related to TFVC. Open main menu item ’Tools’ and choose ’Options’. In the following dialog select folder ’Tools’ and sub-item ’TFS Options’. By default, all checkboxes are checked. If you are working with TFVC and running into performance problems with big solutions, uncheck ’Enable file state ’Modified’ check’. 593 Source Control Figure 631 594 Integration Integration Introduction Ranorex can perfectly be used as a standalone tool in order to launch automated tests manually on local and/or remote machines. However it might be more powerful and comprehensive to integrate Ranorex with other tools. These tools could be Continuous Integration (CI) tools, Test Management (TM) tools or simply with Task Scheduling tools. This comes with the main benefit that automated tests get launched automatically. This launch could be triggered by a specific action (e.g. source code commit from a developer), a periodical build (e.g. ”nightly build”), a test case with underlying test automation or simply triggered by a scheduled task for a specific (e.g. every midnight). Figure 632 Continuous Integration There are a lot of brilliant and useful Continuous Integration tools around. See how to integrate Ranorex into a typical Continuous Integration process which is explained in detail in our general blog post: Integrate Ranorex into Any Continuous Integration Process For several widely spread Continuous Integration tools please find the a specific blog post here: Jenkins: Integrating Ranorex Automation in Jenkins CI Process Bamboo: Bamboo CI with Ranorex Test Automation TeamCity: Integrating Ranorex Automation in TeamCity CI Process For a deeper integration of your Ranorex Report into a common CI tool (e.g. Jenkins) using xUnit/jUnit please see the blog post: Fully integrate your Ranorex Report with CI tools like Jenkins using xUnit 595 Integration This blog post also contains explanations and downloadable samples for the XSL transformation of the Ranorex report to xUnit/jUnit format. Test Management and Application Lifecycle tools Nowadays Test Management (TM) tools and Application Lifecycle Management tools (ALM) are more and more important. They store the information how testing is organized, implemented, and executed as well as a clearly arranged history of executed tests from the past. There is a lot of excellent tool support. For the integration of Ranorex into two widely spread test management tools and ALM tools respectively please read the blog posts: Running Ranorex Automated Tests with HP Quality Center Running Ranorex Automated Tests with Microsoft Test Manager Although Coded UI Tests as well as VAPI-XP tests might be specific for the particular tool, the common idea of integrating Ranorex with TM/ALM tools might be pretty much the same for all other tools around. It all breaks down to the usage of command line arguments for tailored automated test runs with Ranorex. Team Foundation Server There is a comprehensive article about the Microsoft Team Foundation Server, Visual Studio and Microsoft Testmanager and the Integration with Ranorex. Please find the documentation here: TFS 2012 and Ranorex Atlassian Jira There is a very informative blog post on how to integrate Ranorex Test Cases into the issue and defect management tool Jira. Please find it here: Integrating Ranorex Test Cases into Jira Source Control / Revision Control Integration can also be accomplished with Ranorex Studio - namely integrating Source Control tools. First and foremost it should be mentioned that any common Source Control tool can be used to control relevant files of a Ranorex Studio Solution - which are text-based files only. There is a specific integration of two of these tools, namely for SVN (Subversion) and TFS (Team Foundation Server). Please find detailed information on the source control integration and support here: Source Control. 596 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 597 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 633: ’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 Ranorex Test Suite Module Library A project holding recordings and code modules which can be shared and reused Ranorex Class Library A project for creating classes which are used in other applications Ranorex Console Application A project that creates a command line application Ranorex Windows Application A project that creates an application with a windows interface After choosing a project type and a name for the project, a project will be created in the solution and Ranorex Studio is ready for you to start developing. 598 Ranorex Studio IDE Figure 634: Ranorex Studio 599 Ranorex Studio IDE Build After creating your application, it can be built using the ’Build’ menu. Figure 635: ’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 636: ’Output’ window Build Errors and Warnings will be displayed in the ’Errors’ window. Figure 637: ’Errors’ window Project specific settings can be defined in the ’Project Options’ dialog, which can be accessed from the ’Project’ menu. 600 Ranorex Studio IDE Figure 638: 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 639: ’Project Options’ ’Application’ tab You can also set the target CPU and framework or the output path in the ’Compiling’ tab. 601 Ranorex Studio IDE Figure 640: ’Project Options’ ’Compiling’ tab 602 Ranorex Studio IDE Run After building the project successfully, it can be executed from the ’Debug’ menu either with or without debugger. Figure 641: ’Debug’ menu 603 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 642: Add new item through ’Project’ menu 604 Ranorex Studio IDE Figure 643: Adding new item through ’Project Explorer’ context menu Figure 644: ’New File’ dialog 605 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 it’s possible to use a forms designer which allows to visually design the UI as described explicitly in the article ’Visually Designing Forms’ posted at SharpDevelop Community Blog. 606 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 645: 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. 607 Ranorex Studio IDE Figure 646: Delete file from project It’s also possible to redefine the ’Start Up Project’ of a solution. 608 Ranorex Studio IDE Figure 647: Set project as StartUp project 609 Ranorex Studio IDE Debugging Ranorex provides the possibility to debug code directly in the development environment. To enable the debugger press the ’Enable Debugging’ button in the toolbar. Figure 648: Enable Debugging 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 649: Add breakpoint by putting the cursor to the line you want to add a breakpoint, open the ’Debug’ menu an choose ’Toggle Breakpoint’. 610 Ranorex Studio IDE Figure 650: Toggle breakpoint By setting a breakpoint, a red circle will be added at the margin and the line of code will be highlighted red. The breakpoint can be removed in the same way as it has been added. After setting a breakpoint the debugger can be started by executing your application as described in the chapter Run. Note: To run an application with debugger, it’s necessary to not choose ’Run without Debugger’ from menu. The application will start and Ranorex Studio will switch to the ’Debug Layout’ which causes the following menu items to be available from ’Debugger’ menu and toolbar: Continue Debugging Continues execution Stop Process Forces the process to stop Step Over Executes the statement on the current line but it will not step into Step Into Executes the statement on the current line and stops at the first line of code inside the method Step Out Finishes executing the current method and returns to its parent method 611 Ranorex Studio IDE Figure 651: Debugging menu Items Figure 652: 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. 612 Ranorex Studio IDE Figure 653: 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. 613 Ranorex Studio IDE Figure 654: Debug sub menu Callstack Shows method calls currently on stack. Local Variables Shows variables defined in the function currently being executed, arguments passed into the current function and fields and properties of the class where the function is defined. Watch 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. Additionally to the different views it’s also possible to diagnose individual objects directly in code using the tool tips popping up when moving the mouse over them. 614 Ranorex Studio IDE Figure 655: 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. 615 Ranorex Studio IDE Code Completion Ranorex supports code completion as you type. Figure 656: Code Completion in Ranorex Further details about how this works can be found in the article Code Completion posted at SharpDevelop Community Blog. 616 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 657: Convert the whole project from C# to VB.NET 617 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. 618 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. 619 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. 620 Visual Studio Integration 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 658: 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. 621 Visual Studio Integration Figure 659: Add new references .. Figure 660: .. 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 ) 622 Visual Studio Integration VB.NET < stathread > _ Public Shared Function Main ( args As String () ) As Integer Add the following code lines to the ’Main’ routine of the class ’Program’: C# int error = 0; try { System . Diagnostics . Process pr = System . Diagnostics . Process . Start ( ' calc . exe ' ) ; Form form = Host . Local . FindSingle < ranorex . form >( ' form [ @processname = ’ ' + pr . ProcessName + ' ’] ' ); form . Activate () ; Button button = form . FindSingle < ranorex . button >( ' .// button [ @controlid = ’132 ’] ' ) ; button . Click () ; button = form . FindSingle < ranorex . button >( ' .// button [ @controlid = ’92 ’] ' ) ; button . Click () ; button = form . FindSingle < ranorex . button >( ' .// button [ @controlid = ’133 ’] ' ) ; button . Click () ; button = form . FindSingle < ranorex . button >( ' .// button [ @controlid = ’121 ’] ' ) ; button . Click () ; } catch ( R a n o r e xE x c e p t i o n e ) { Console . WriteLine ( e . ToString () ) ; error = -1; } return error ; VB.NET Dim returnError As Integer = 0 Try Dim pr As System . Diagnostics . Process = System . Diagnostics . Process . Start ( ' calc . exe ' ) Dim form As Form = Host . Local . FindSingle ( Of Ranorex . Form ) ( ' form [ @processname = ’ ' & pr . ProcessName & ' ’] ' ) form . Activate () Dim button As Button = form . FindSingle ( Of Ranorex . Button ) ( ' .// button [ @controlid = ’132 ’] ' ) button . Click () button = form . FindSingle ( Of Ranorex . Button ) ( ' .// button [ @controlid = ’92 ’] ' ) button . Click () button = form . FindSingle ( Of Ranorex . Button ) ( ' .// button [ @controlid = ’133 ’] ' ) button . Click () button = form . FindSingle ( Of Ranorex . Button ) ( ' .// button [ @controlid = ’121 ’] ' ) button . Click () Catch e As R a no re x E x c e p t i o n Console . WriteLine ( e . ToString () ) returnError = -1 End Try Return returnError Build and start the application by pressing F5. 623 System Requirements System Requirements The following system requirements are valid for all Ranorex components including Studio, Runtime, Spy, Recorder, License Manager and Agent. Supported Operating Systems Software Requirements Hardware Requirements Required Disk Space Firewall Configuration Ranorex License Manager Firewall Configuration Ranorex Agent Firewall Configuration Former Ranorex Versions (up to 6.0) System Requirements for Ranorex Versions up to 6.0 Supported Operating Systems Ranorex supports the following operating systems (32- and 64-bit editions, except for Itanium-based systems): Windows XP Windows Vista Windows 7 Windows 8 Windows 8.1 Windows 10 Windows Server 2003 Windows Server 2003 R2 Windows Server 2008 Windows Server 2008 R2 Windows Server 2012 Windows Server 2012 R2 624 System Requirements Software Requirements The following software requirements are needed to run all Ranorex components (Runtime, Spy, Recorder, License Manager and Agent). They are usually automatically installed when running the Ranorex setup: Microsoft Windows Installer 3.1 or higher Microsoft Visual C++ 2008 x86 Microsoft Visual C++ 2008 x64 (required for 64 bit Windows versions only) Microsoft Visual C++ 2010 x86 Microsoft Visual C++ 2010 x64 (required for 64 bit Windows versions only) Microsoft Visual C++ 2015 x86 Microsoft Visual C++ 2015 x64 Microsoft .NET Framework 4.0 or higher Internet Explorer 8 or higher (with the latest patches and updates) Hardware Requirements The hardware requirements depend on the .NET Framework version that needs to be installed for the respective Ranorex package. Ranorex (Runtime, Spy, Recorder, License Manager, Studio and Remote Agent) requires the installation of the .NET Framework 4.0 or higher. The minimum system requirements for running Ranorex (Runtime, Spy, Recorder, License Manager, Studio and Agent) are the same as those for the .NET Framework 4.0: https://www.microsoft.com/en-US/download/details.aspx?id=17718 The recommended minimum system requirements for running Ranorex (Runtime, Spy, Recorder, License Manager, Studio and Remote Agent) are: Processor: 2 GHz Memory: 512 MB Required Disk Space Full installation: Approximately 200 megabytes (MB) free disk space are required to install the full Ranorex package (includes Ranorex Studio, main components, documentation, etc.). Minimum installation: Approximately 80 megabytes (MB) free disk space are needed to install the Ranorex runtime environment. Ranorex Agent: A Ranorex Agent requires approximately 25 megabytes (MB) free disk space. Please keep in mind that a Ranorex Runtime License is needed per Ranorex Agent. Ranorex License Manager Firewall Configuration On a system running Ranorex License Manager, the firewall must be configured to allow access to TCP and UDP port 7266. 625 System Requirements Ranorex Agent Firewall Configuration On a system running a Ranorex Agent, the firewall must be configured to allow access to TCP ports 8081 and 29189, and UDP ports 10000-10001. System Requirements for Ranorex Versions up to 6.0 Software Requirements The following software requirements are needed to run all Ranorex components (Runtime, Spy, Recorder, License Manager). They are usually automatically installed when running the Ranorex setup: Microsoft Windows Installer 3.1 or higher Microsoft Visual C++ 2008 x86 Microsoft Visual C++ 2008 x64 (required for 64 bit Windows versions only) Microsoft Visual C++ 2010 x86 Microsoft Visual C++ 2010 x64 (required for 64 bit Windows versions only) Microsoft .NET Framework 2.0 SP2 or higher Internet Explorer 7 or higher (with the latest patches and updates) Additionally, for automating WPF applications (since Ranorex 5.3) and running Ranorex Studio the following prerequisites are required: Microsoft .NET Framework 3.5 SP1 or higher Hardware Requirements The hardware requirements depend on the .NET Framework version that needs to be installed for the respective Ranorex package. Ranorex (Runtime, Spy, Recorder, License Server) requires the installation of the .NET Framework 2.0 or higher. Ranorex Studio requires the .NET Framework 3.5. Consequently: The minimum system requirements for running Ranorex (Runtime, Spy, Recorder, License Server) are the same as those for the .NET Framework 2.0: http://msdn.microsoft.com/en-us/library/ms229070.aspx The recommended minimum system requirements for running Ranorex (Runtime, Spy, Recorder, License Server): Processor: 2 GHz Memory: 512 MB The minimum system requirements for running Ranorex Studio are the same as those for .NET Framework 3.5: http: //msdn.microsoft.com/en-us/library/bb882520.aspx The recommended minimum system requirements for running Ranorex Studio: Processor: 2 GHz Dual Core Memory: 1 GB Required Disk Space Full installation: Approximately 200 megabytes (MB) free disk space are required to install the full Ranorex package (includes Ranorex Studio, main components, documentation, etc.) 626 System Requirements Minimum installation: Approximately 80 megabytes (MB) free disk space are needed to install the Ranorex runtime environment. 627 64-bit Platforms 64-bit Platforms Ranorex handles testing of 32/64 bit based applications on 64 bit operating systems automatically. It is possible, but recommended only for advanced users, to turn off the bit bridge feature within the Ranorex Settings dialog. Note: If you disable the bit bridge feature (not recommended!) or your Ranorex version does not support the bit bridge (versions prior to V2.3), follow these guidelines to make 32/64 bit automation interoperable: On 64 bit versions of Windows, processes may run using 64 bit or 32 bit (also called ’x86’) architecture. Applications that are started as 32 bit processes are marked with ’*32’ or ’(32 bit)’ in the Windows Task Manager, all others use the 64 bit architecture. Figure 661: 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 662: Ranorex Studio - advanced compiler settings 628 Remotely Working with Ranorex 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 Keeping remote session unlocked even if closing it 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 Desktop’s screen. As a workaround, you can set up one machine having all of your Remote Desktop windows opened. This machine does not do any automation. And while your tests are running on the different Remote Desktops with the client windows opened on the mentioned machine you can lock the desktop on this machine. While your client desktop is locked, the Remote Desktop sessions will remain opened and your test will continue. An alternative to RDP is using VNC or the VMWare Remote 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 629 Remotely Working with Ranorex 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, don’t 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. It’s recommended to use the global timeout factor to adapt the timeouts for a specific test run. Keeping remote session unlocked even if closing it There is a way to keep the remote session unlocked even if you’ve disconnected the RDP session. Find out more here: How do I make sure that my user session keeps unlocked if I close my remote session? 630 Silent Installation of Ranorex 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” Ranorex- Possible feature names used as parameter to ADDLOCAL or REMOVE (separated by commas) are: ’MainFeature’ (Core components) ’RanorexSamples’ ’RanorexStudioFeature’ ’RanorexFirefoxExtension’ ’RanorexIEAddon’ ’RanorexDocumentation’ 631 Silent Installation of Ranorex For more installation options see the help for the MsiExec program by typing (’/v’ is needed for the ’*.exe’ files): msiexec /help or: setup /v /help or: Ranorex-x.x.x.exe /v /help 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 machine’s host name into the respective fields. After clicking the ’Authenticate’ button you will be able to download the license file. Rename the downloaded file to Ranorex3.lic (for 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. 632 XCOPY Deployment XCOPY Deployment Running tests without Ranorex Installation Opening Note: The way of deploying tests without Ranorex Installation described below is possible but not recommended. Still this approach is documented since it allows to overcome internal policies and/or restrictions inhibiting installations on runtime environments, e.g. due to group policies within domains. Deploy Ranorex Libraries and Assemblies The required files for executing Ranorex tests on runtime machines are located in the ”bin” folder of the Ranorex installation path. These files can be found easily on machines having a valid Ranorex Installation using the environment variable %RANOREXPATH%. Please copy the whole content of the ”bin” folder (including all subdirectories) to a target folder () on the runtime machine. xcopy ”%RANOREXPATH%bin*.*” xcopy Note: It is crucial to deploy the Ranorex Assemblies with exactly the same version that was used to compile the test executable Deploy Ranorex License Information In the runtime environment a valid license information needs to be available. Most likely the runtime machine will use a floating license, so the only information necessary can be provided by the license file (Ranorex3 Server.lic). This file can be copied easily from any machine having a floating license installed to the target machine and is located in the path of the environment variable %ALLUSERSPROFILE%. For more information please refer to chapter ”Install Ranorex License” in the section ”Silent Installation of Ranorex”. Deploy Your Ranorex Test Ranorex generates the files needed to run automated tests in the ”Output Folder” (by default binDebug) of a test suite project. 633 XCOPY Deployment Figure 663: Open output folder from Ranorex Studio 634 XCOPY Deployment Note: You can directly access this folder by right-clicking the current project and choosing ”Open Output Folder” in the context menu. Next to files needed for test execution, additional files are created in the output folder during test execution (e.g. Reports, Screenshots etc.). Those files do not have to be copied. It’s recommended to clear your output folder before and then trigger a new build (Build -> ”Build Solution” or hot key F8). Required files for executing Ranorex test automation: Executable file (*.exe) Test Suite File (*.rxtst) Additionally required on the base of your project needs: Ranorex Module Group (*.rxtmg), only necessary if modules groups are in use Test Data (*.xlsx, *.xlsb, *.xls, *.csv, *), only necessary for data driven tests and if data source files were added to project Module Libraries (*.dll), only necessary if module libraries are linked and embedded functionality is referenced in the Test Suite Sub folder ”RepositoryImages” including all files, if exists Finally copy the files needed to the target machine and place them in the folder where all Ranorex Libraries and Assemblies are already located (). Of course, by copying the whole output folder (”bindebug” by default), you will ensure you have everything possibly required for running your test. xcopy ”bindebug*.*” xcopy Note: For executables being explicitly compiled against 64bit CPUs, place these files in the sub folder ”x64” of the target folder. 635 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 machine’s host name. After registration each license can be used perpetually on the registered machine. A floating user license can be shared between different machines, but can only be used by one machine (and user) at a time. If you are going to transfer a license to another machine, have a look at the section Transfer Licenses. License Registration In order to register a Ranorex license, start the Ranorex Licensing tool, which is available in the Ranorex start menu folder. Figure 664: 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 ’Node-Locked’ 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. Installing with Internet Connection Simply type or paste in the Ranorex license key which has been delivered to you by email and press ’Install’. 636 Licensing Figure 665: 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. Figure 666: 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 machine’s host name. After clicking the ’Authenticate’ button you’ll be able to download the license file. Load the downloaded file within the Ranorex licensing tool in order to finish the license installation process on the target machine. 637 Licensing Figure 667: License authentication using Ranorex web site Installing a Floating License Installing and configuring the Ranorex License Manager In order to use a Ranorex Floating License it is required to install and run the Ranorex license manager application on a computer within a network. The download link for the license manager setup package is part of the license delivery email. Simply install the package on a system which is reachable from computers which intend to use a Ranorex floating license. Note: To prevent firewalls from blocking communication between license manager and client, it is required to open port 7266 for TCP and UDP access on the machine running the license manager. Note: By installing a Ranorex license manager it’s required to use a Ranorex license manager installation package at least as current as your Ranorex client installation. Note: The Ranorex license manager can be used in IPv4, IPv6 and mixed networks. 638 Licensing Figure 668: License manager dialog - one premium licenses in use Open the Ranorex license manager configuration tool. Add the floating license keys to the text box and press ’Install’. These licenses are now ready to use. To get more information about the clients leasing a license you can select the specific license in license manager configuration tool and open the ’Clients’ tab. Using the ’Save Log’ button allows you to export all actions processed by the license manager as CSV- or XML-file for further processing. Note: It is recommended to have an internet connection available in order to install a new license. Figure 669: 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 machine’s host name. After clicking the ’Authenticate’ button you’ll be able to download the license file. Load the downloaded file within the Ranorex licensing tool in order to finish the license installation process on the target machine. 639 Licensing 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 ’Floating’. Figure 670: Using license manager for automatically requesting an appropriate license Press the button ’Detect’ to request a list of the currently available license managers within the local network. The license type specifies which license (Runtime, Premium) should be used on the client. By selecting ’Auto’, the client automatically requests the appropriate license. In case of running Ranorex tests via the standalone test suite runner or from command line, only a Runtime floating license will be used. When starting Ranorex Spy tool a Premium floating license will be leased on the manager. After pressing the ’Install’ button the client is assigned to the selected license type. To switch the currently installed license type, simply select another one from the list and click ’Install’ again. Every time a Ranorex test, a Ranorex tool, or Ranorex Studio is started the client sends a license request to the manager. If the type of the required license is available, it will be assigned to the requesting client. By being idle, closing Ranorex Studio or finishing a test run the license will be automatically released and can then be used by other clients. For this reason a reliable network environment is required when working with floating licenses. Note: If a floating license has not been released correctly (based on a network problem for example), it will be locked for a time-out of 5 minutes. Uninstall License In order to uninstall a floating license right-click the license you are going to uninstall and choose ”Uninstall License(s)” from the context menu in the Ranorex license manager tool. 640 Licensing Figure 671: Uninstall floating license Figure 672: Confirm uninstall In order to uninstall a node-locked license from a machine, please use the uninstall button in the Ranorex License Tool. 641 Licensing Figure 673: Uninstall node-locked license Figure 674: Confirm uninstall Transfer Licenses In order to transfer a license, you have to uninstall the license from the machine you want to transfer it from as described in the section above. After that, the license will be available for installation on a different machine. 642 How to instructions How to instructions This library includes instructions for often needed tasks in a short and practical format: How to create a Ranorex Snapshot How to create a compressed Ranorex solution How to create a compressed Ranorex Report How to add a solution settings file to a solution 643 How to instructions How to add a solution settings file to a solution What is a solution settings file? A solution can have one solution settings file, named ’Ranorex.rxsettings’. It stores the value of so called solution settings in it. Find out more about solution settings here: Solution settings Add a solution settings file to a solution 1. Start Ranorex Studio. 2. Load the solution. 3. Click on ”Create solution settings” in the toolbar of the ’Projects’ view. Figure 675 4. A folder named ’Solution Items’, including the solution settings file ’Ranorex.rxsettings’ is automatically created. Figure 676 644 How to instructions How to create a Ranorex Snapshot What is a Ranorex Snapshot? A Ranorex Snapshot is a representation of the the user Interface (UI) structure of a system under test (SUT) at a particular Point in time. A Ranorex Snapshot captures all interface elements, their hierarchy, values, etc. It can be saved as a single file. A Ranorex Snapshot file can be created and viewed with Ranorex Spy. The file extension is ’.rxsnp’. Typically, Ranorex Snapshots are used to share detailed information about the UI of a SUT with the Ranorex Support and Technical Sales Team. Create a Ranorex Snapshot 1. Start your system under test (SUT). 2. Start Ranorex Spy. 3. Get to the part of your SUT you want to create a snapshot of. 4. In Ranorex Spy, press the TRACK-Button. Figure 677 If you move the mouse cursor over a UI element, a red border will appear around this element in tracking mode. 5. Place the mouse cursor over the UI element of the SUT you want to track. Wait until the red border appears and left click your mouse button. 6. The tracked element automatically appears in Ranorex Spy. 7. Click on ’Save as Snapshot..’ in Ranorex Spy toolbar, select the desired location, enter a filename and click ’Save’. 645 How to instructions Figure 678 8. A progress dialog is shown during snapshot creation. 646 How to instructions Figure 679 Wait until the snapshot is created and successfully saved to the file. 647 How to instructions Figure 680 Snapshots of special UI elements Particular UI elements of the SUT, such as drop-down menus, pop-up windows, combo boxes, etc., only become visible after a mouse click, or disappear if the SUT loses focus. These elements are often not automatically included in a Ranorex Snapshot , as they appear as separate items in Ranorex Spy at the top level of the element tree. There are two ways to create Ranorex Snapshots of these elements: Temporarily deactivate tracking with F12 key 1. Start your SUT. 2. Start Ranorex Spy. 3. Get to the part of your SUT you want to create a snapshot of. 4. In Ranorex Spy, press the TRACK-Button. Figure 681 Now you are in tracking mode, which is indicated by a red border around the UI elements as you move the mouse cursor over them. 648 How to instructions 5. Press and hold F12 key while navigating to the desired element in the SUT. While you press the F12 key, the tracking mode is paused. 6. Move the mouse over the UI element of the SUT you want to track and release the F12 key. 7. Wait until the red border appears and press the Scroll key. A temporary Ranorex Snapshot is created in Ranorex Spy. This may take a few seconds. 8. Save the Ranorex Snapshot as described above. Instant capturing with key shortcut Ctrl + Win 1. Start your SUT. 2. Start Ranorex Spy. 3. Get to the part of your SUT you want to create a snapshot of. 4. Place the mouse cursor above the part of the SUT you want to create a Ranorex Snapshot of and press key shortcut Ctrl + Win. This instantly tracks the element in Ranorex Spy. 5. Save the Ranorex Snapshot as described above. 649 How to instructions How to create a compressed Ranorex solution What is a compressed Ranorex solution? A compressed Ranorex solution is a file archive including all relevant files of a solution. Create a compressed Ranorex solution 1. Start Ranorex Studio. 2. Load your solution. 3. In the Ranorex Studio menu click on Tools > Zip Solution. The zip-file will be created in the folder of the solution. Figure 682 4. A Windows Explorer opens, showing you the final zip-file. Figure 683 650 How to instructions How to create a compressed Ranorex Report What is a compressed Ranorex Report? A compressed Ranorex Report is one single file including all files that belong to a single report. These are the report file itself (*.rxlog), all images and further relevant files. The file extension is ’.rxzlog’. Create a compressed Ranorex Report 1. Open a Ranorex Report in Ranorex Studio or with Ranorex Report Viewer. 2. Open the context menu with a right mouse click on the report and choose ’Save As..’. Figure 684 3. Select the desired location, enter a filename and make sure ’Ranorex Compressed Report (*.rxzlog) is selected as file type. Figure 685 651 How to instructions 4. Click ’Save’ 652 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? How can I speed up my Excel-based data connector? What to do when items can’t 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 run my tests on machines where I am not allowed to install Ranorex? 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&n’’t Save’] The RanoreXPath searches for a button, whether it contains the text ’&No’ or ’Do&n’’t Save’. Is it required to use RanoreXPath for test automation? No. It’s 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 653 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 How can I speed up my Excel-based data connector? Especially with big files, the performance of Microsoft’s default file format for excel spreadsheets is getting poor. This weakness might also affect your data driven test execution. For performance improvements you could use the binary file format (xlsb) instead of the default one (xlsx). Simply save your Excel spreadsheet with the extension ”xlsb” and assign it to your Excel File. What to do when items can’t be found during Ranorex test execution? There are two primary reasons why some items can’t be found during replay: 1. Search timeout: Each element and each folder stored within the objects repository defines is it’s own timeout used for search. In many cases it is required to wait for a dialog before continuing automation. Use the 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 object’s RanoreXPath within the repository browser using the ’Highlight Element’ context menu item to see if Ranorex can find the element. Open Ranorex Spy to track the specified GUI object again. Compare the absolute path, shown within the object repository’s property grid, with the given RanoreXPath provided by Ranorex Spy. If the given path by Ranorex Spy differs from the path represented by the repository use the path from Spy to the repository. 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 can’t 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. 654 FAQ 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. Can I run my tests on machines where I am not allowed to install Ranorex? Yes, it is possible to run automated tests on runtime machines without Ranorex Installation. Please refer to the chapter XCOPY Deployment (Running tests without Ranorex Installation) in the User Guide. Can I use Ranorex libraries within Visual Studio? That’s one of the big advantages of using Ranorex. You’re 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 provides the dedicated class ”PopupWatcher” to watch for and to handle popup windows. By using this class, not only simply click actions to close popup dialogs can be called. Even more complex scenarios can be handled in custom callback routines being called at the time the popup appears. Read more about how to handle popup dialogs with Ranorex in the section Handling unexpected Dialogs. 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 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 655 FAQ 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. 656 Free Mp3 Download ArchiveDownload Archive Gamershell Patch
DOS-on-USB lets you install MS-DOS 7.1 on your USB memory key. The best thing about having a DOS-bootable memory key is you can boot into it on any computer, just like a CD.You'll find this utility great for times you need to do system maintenance, because you wont constantly have to burn a new CD, just copy the program to the USB Drive. After formatting your flash drive, you can install a full working version of MS-DOS to let you run games or system utilities. Old dos games. With the DOS prompt, you can even install Windows 95 or 98. Recommended USB drive size: 16MB - 2GB.
Comments are closed.
|
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |