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

To add a new action item, open the 'Add New Action' drop-down menu as shown below:

: 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.

: 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.

: 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'.

: 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'.

: 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.

: Use drag and drop to create a new action for a specific repository item

You are asked to specify the type of action after dropping the element into the actions table. For more information about the available actions, see below.

Types of Action Items

	Mouse	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
	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
	Deploy Android App	Instruments the given Android application and deploys it on the given mobile device
	Close Application	Closes an application or web site containing the given repository item
	Wait For Not Exists	Waits for given repository item to disappearance Note: This action can be used for any type of UI element
	Report	Adds a new report action item Note: In addition to the standard report levels, you can define custom report levels by changing the level from 'Info' to 'Custom'
	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: Next to the parameters as described in the next paragraphs there might be additional options for each action which can be accessed in the properties pane. You can open this pane by clicking the context menu item 'Properties' on any action item.

Mouse

This mouse action can be used for 'Up', 'Down', 'Click', 'Double-Click' and 'Move'-actions. This action is typically used for button clicks so a repository item assignment is required.

Mousewheel

This mousewheel action can be specified as 'Vertical' or 'Horizontal' direction. You are also able to specify a wheel-delta, which is 120 by default.

Touch Event

A touch event can be used to perform different kinds of touch events on mobile devices as well as on Windows 8 desktops.

Key Shortcut

This action can be used for executing key shortcut actions. Aside from the shortcut itself, it is possible to specify the events 'Press', 'Up' and 'Down'. For this action, a repository item assignment is not required.

Key Sequence

This action makes it possible to execute or to simulate a key sequence. This action is typically recorded in a form filling scenario (e.g. username field in login process). For this action a repository item assignment is not required.

Mobile Key Press

This action can be used for pressing mobile keys like {BACK} and {MENU}. For more detailed information please have a look at Android Testing - Record your Android Test.

Validation

The validation action is typically used for validating states, text or images of specific repository items. Every validation action leads to a specific entry in the report file and, depending on the type of validation and the validated element, there may be different validation results (success, failure). After assigning a repository item, you are able to choose one of the following validation-types:

Exists: The validation checks for the existence of the repository item and expects an existing item.

Example: A user can validate whether a button exists with a resulting success if the button actually exists.

NotExists: The validation checks for the existence of the repository item and expects the item not to exist.

Example: A user can validate whether an error dialog does not exist with a resulting success if the dialog does not exist.

AttributeEqual: This validation checks whether an attribute (column 'Match Name') is equal to a specific value (column 'Match Value'). The matching attributes depend on the assigned repository item and therefore an assignment of a repository item is assumed. For example a WinForms button may be validated on the 'Text', on the 'Valid' state, on the 'Pressed' state and also on 'AccessibleName', 'AccessibleValue' etc.. The matching value can either be a constant, a self-defined value or a module variable.

Example: A user can validate whether a button has the text 'OK' with a success result if the button text is 'OK'.

AttributeRegEx: This validation is for matching a 'match value' (self-defined match value or the content of a module variable) against a specific attribute (column 'Match Name') using a regular expression. Because the attribute itself (column 'Match Value') depends on the assigned repository item, assignment of a repository item is recommended prior to choosing a match value. If you plan to use a variable within this type of validation, you can easily implement your regular expression in the value of that variable.

Example: One can validate whether the title of the KeePass application ends with the text 'KeePass Password Safe' and could therefore use the 'Match Name' containing the regular expression '.+KeePass\ Password\ Safe$'. The validation would lead to success if the attribute (column 'Match Name') has any character (this is defined as a .+ in the regular expression) followed by the constant 'KeePass Password Safe'. For more information about Regular Expressions see RanoreXPath - RanoreXPath with Regular Expressions.

AttributeContains: This validation checks whether a specific attribute (column 'Match Name') of a specific repository item contains a 'match value'. The match value can either be a user-defined constant value or it can also be the content of a module variable. As above this validation assumes the assignment of a repository item.

Example: A user can validate whether the title of the KeePass application contains the constant value 'kdbx', which is the file extension of the database used by KeePass. The match name would thus be set to 'Title' and the match value would be set to 'kdbx'. As a result the validation would succeed if the title actually contains the constant 'kdbx'.

AttributeNotContains: This validation can be thought of as the opposite of 'AttributeContains'. It checks whether an attribute (column 'Match Value') does not contain a 'match value'.

Example: One can validate whether the content of a specific cell (URL) in KeePass does not contain the constant value 'http://'. 'Match Name' would therefore be set to 'Text' and 'Match Value' would be set to 'http://'. This validation would lead to a positive result if the URL does not contain the constant value 'http://'.

ContainsImage: This validation checks whether the assigned repository item contains a specified screenshot. This screenshot can be easily created within the 'Edit Image Validation' dialog which can be accessed via a button in the 'Screenshot' column. For more information about image-based validation please have a look at the section entitled Image-Based Automation later in this chapter.

Example: It's possible to validate whether the user-defined list of icons (for a KeePass entry) contains a specific icon. This could be done using image-based validation. The repository item would therefore hold the list of icons and the screenshot would be a picture of the specified icon. The validation would lead to a result if the list contains the specified icon.

CompareImage: This validation checks whether a specified repository item is equal to a specific screenshot. This screenshot can be easily created within the 'Edit Image Validation' which can be accessed via a button in the 'Screenshot' column. For more information about image-based validation please see Image-Based Automation later in this chapter.

Example: To validate whether the toolbar of the KeePass application contains the intended icons you can compare the repository item with a screenshot of the toolbar in its initial state.

Invoke Action

Used for invoking actions on the specified repository item. For example a WinForms button provides functionality for 'Ensuring Visibility', 'Focusing' and 'Pressing'. More important, this action can be used to easily select items in lists and drop-downs. No mouse movement and click is simulated but nevertheless the item itself is selected. This is a more powerful and smarter action than simulating the selection via mouse actions. Invoking a select action on a specific item also works if the item itself is not visible by default because there are too many elements in the list.

Invoking user-defined (dynamic) actions: In addition to access actions delivered by default, you can also invoke user-defined actions (see Invoking User-Defined Actions) in your System Under Test.

Get Value

As the action name indicates, this method can be used for getting values from repository items. Depending on the assigned repository item, the available attributes can be different. The value obtained can be assigned to a module variable. Depending on the available adapters for the assigned repository item, the attributes are divided into several sections (see figure below).

: Submenu for Get-Value action

Parse strings with regular expressions: In the 'Capture Regex' column of the GetValue action you can specify a regular expression.

For additional information on regular expressions please consult the corresponding MSDN web site: http://msdn.microsoft.com/en-us/library/az24scfc.aspx

With this regular expression it is possible to easily parse a string out of the specified field. The matched string will be saved to the chosen module variable for further use. So far there is no need to write a single line of code. If the regular expression delivers more than one match, the first match will be stored in the module variable.

Example: If you have a string 'Count: 42' and you want to return the digits only (42) you can use the following regular expression: '^Count: ([0-9]*)$'

The first non-trivial group matched by the regular expression is returned. If there are no groups captured the full match will be returned. In case that there are more grouping constructs in the regular expression, you can mark the requested group using the following construct '?<1>'.

Example: If you have a string 'Rows: 23, Columns: 42' and you want to return the number of columns you can use following regular expression: '^Rows: ([0-9]*), Columns: (?<1>[0-9]*)$'

User-defined methods and attributes: In addition, it is also possible to call user-defined methods defined in your system under test. As is described in the next section (see Invoking-User Defined Actions), a simple application could have a public function that returns a string value holding the text of a protected text field. If the application is running during the creation of the GetValue-Action, there is a submenu for 'Dynamic' methods. Public attributes can also be accessed and returned through the 'Dynamic' submenu.

Note: To get access to the dynamic methods and attributes, the repository item has to be available. This can be verified by highlighting the specific element by right clicking the element in repository and choosing 'Highlight Element' from the context menu.

Reuse values from the GUI in other modules: Using a Get Value action allows one to store an attribute value of a UI element to a module variable. Doing so makes the value available within this module.

: 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.

: 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.

: Submenu for Set Value Action

User-defined attributes: In addition, it is also possible to set user-defined attributes. If the application is running during the creation of the Set Value action then there is a submenu for 'Dynamic' methods holding dynamic attributes.

Note: To get access to the dynamic methods and attributes, the repository item has to be available. This can be verified by highlighting the specific element by right clicking the element in repository and choosing 'Highlight Element' from the context menu.

Open Browser

This action can be used for opening a browser. For preparation you are able to use the parameter 'URL' for directly opening a website. The parameter browser can be used for choosing a browser (e.g. 'IE', 'Chrome', 'Safari' or 'Firefox').

Note: You can use a 'module variable' inside the column 'Browser' which can be used for cross-browser testing. For an extensive description including an example see Cross-Browser Test Automation with Ranorex.

Additionally there is a parameter 'Maximized'. When this parameter is set to 'false', the URL is opened in the default browser window size which can nevertheless be in maximized state. With the maximized-parameter set to true, the browser will be opened in maximized window state.

Run Application

This action can be used to run an application with the filename specified in the column 'File Name'. You can also pass some arguments (column 'Arguments') and define whether the application should be started in maximized window state (column 'Maximized', see explanation for open browser action to find out more about this parameter).

Run Mobile App

When using this action you can specify a 'Device' and an 'App'. For more information see Android Testing - Record your Android Test.

Deploy Android App

When using this action, you can specify a 'Device' and an 'APK file'. The given Android application will be instrumented and deployed to the given Android device.

Close Application

This action can be used for closing applications and web sites. If the 'Close Method' is set to 'CloseWindow', the application is attempted to be closed. If the parameter 'Grace Period' is set to a value greater than 0 ms, the process will be killed after the 'Grace Period' if closing the application failed. If 'Close Method' is set to 'KillProcess' the application's process is killed immediately and the grace period is ignored.

Wait For Not Exists

You can use the 'Wait for not exists' action to wait until the assigned repository item does not exist anymore. You can also specify a 'Timeout'.

Report

The Report action is typically used for providing information related to the test report.

You are able to choose one of the following action types:

Log: This action adds a line of text holding a given value to the test report.

Example: One could report the current value of a variable or UI element.

Screenshot: This action adds a screenshot of a specific repository item and some user-defined text to the test report. If no repository item is assigned, a screenshot of the whole desktop is created and will be passed to the report.

Example: One could report a screenshot to make the report file clarify the current state of the system under test in the report file.

Snapshot: This action adds a snapshot file of a specific repository item and some user-defined text to the test report. The snapshot file can be opened directly from the report file. Please mind that the assignment of a repository item is obligatory for this type.

Example: One could report a snapshot file of the application under test if an automation problem occurs in order to analyze this automation problem.

In addition to the specification of the action type you are also able to deliver a 'Message' and to specify a 'Report Level'. For more information about the 'Report Level' see Lesson 8: Reporting.

Separator

A separator can be used to visually separate recordings into smaller sections to get a clearer view of "thematically" related actions. You can specify a 'Header Text' to name or describe the following group of actions.

Delay

A delay action can be used to pause test automation execution for a specific time (column 'Duration').

Note: This time delay is not scaled with the speed factor and is also present in 'Turbo Mode'

User Code

User code actions can be used to execute custom class methods defined in the recording user code file. User code actions are described extensively in User Code Actions.

Invoking User-Defined Actions

Sometimes it might be useful to access internal, user-defined functionality from your system under test. You could use the recorder action 'Invoke Action' which also allows parameters. For example a simple WinForms application 'Invoke-Example' written in Visual Studio (C#) provides a button which automatically sets a constant text to a protected text field.

: Example (in initial state) with public functionality which will be invoked

C#

public void MyInvokedAction(string MyMessage)
{ 
	edProtectedText.Text = MyMessage;
} 

private void btSetValue_Click(object sender, EventArgs e)
{
	edProtectedText.Text = "This text was set from GUI";
}

The protected text can only be set by clicking the button. The application then sets the text field to a constant value.

: 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.

: Submenus for available invoke actions

Even parameters can be easily set in the Ranorex Recorder table.

: 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.

: Browsing available arguments

Invoking this method causes the text field's content to be set to the desired value.

: 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.

: 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.

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.

: 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.

: 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.

Online User Guide

Download Test Automation Guide
(PDF file, 20MB)

Online API Documentation