Action Properties

In this chapter, find a list of all actions with details on their components and properties.

All components that can be configured in the actions table are also available in the properties of the action. Here, you can find only the action-specific properties in this chapter. The standard properties are explained in Manage actions.

Description

Press a button on the mouse or move the mouse to a defined position.

Components

Subactions

• Up/Down: Down presses and holds the specified mouse button, up releases it.
• Click/Double-click
• Move: Move the mouse to the specified action spot.

Button

Specifies which button is pressed. XButtons refer to the side buttons on a mouse.

Action spot

Defines where on the screen the button press will be made or where the mouse will be moved. Can be a relative position, x;y pixel coordinates, or a variable.

Action-specific properties

• Disable bound warnings: Disables the out-of-bounds warning in the report. The default is False.
• Image-based: Configure parameters for image-based automation.
• Move time: How long a Mouse move action takes. Default is 300 ms. Can be bound to a variable.

 

Description

Performs a mouse wheel action in vertical or horizontal direction.

Components

Orientation

Horizontal, Vertical

Delta

How far the wheel is moved vertically or horizontally as a positive or negative integer. Can be bound to a variable.

 

Description

Performs different kinds of touch actions on a touchscreen device. Must be linked to a repository item.

Components

Touch type

• Touch
• DoubleTap
• LongTouch
• TouchStart/TouchMove/TouchEnd

Action spot

Defines where on the screen the touch action will be made or, for the TouchMove type, where to move. Can be a relative position, x;y pixel coordinates, or a variable.

Action-specific properties

• Disable bound warnings: Disables the out-of-bounds warning in the report. The default is False.
• Image-based: Configure parameters for image-based automation.
• Long touch duration: How long the long touch will be held. Default is 1s. Can be bound to a variable.
• Move time: How long a touch move action takes. The default is 100 ms. Can be bound to a variable.
• Touch Duration: How long the touch will be held. The default is 100 ms. Can be bound to a variable.

Description

Performs a swipe action on a specific repository item. You can configure the direction, distance, and duration of the swipe.

Components

Swipe direction

The direction of the swipe in degrees. Can be set to any value or bound to a variable.

Distance

Distance the swipe covers in pixels. Can be set to any value or bound to a variable.

Swipe duration

How long the swipe takes. Can be set to any value or bound to a variable.

Action-specific properties

• Disable bound warnings: Disables the out-of-bounds warning in the report. The default is False.
• Image-based: Configure parameters for image-based automation.
• Start location: Where the swipe starts. The default is Center. Various predefined values. Can also be an x;y pixel value. Can be bound to a variable.
• Steps: Number of times the swipe gesture is executed. Can be bound to a variable.

Description

Performs a keyboard shortcut using one or multiple keys.

Components

Key code

• Press: Press and release the keyboard shortcut.
• Up, Down: Down presses and holds, Up releases the keyboard shortcut.

Shortcut

The keyboard shortcut itself. Click … next to the field to open an assistant. You can also enter the shortcut directly. For example, to perform the copy shortcut, enter: ctrl+c and press Enter. You can also use the shortcut configurator in the action’s properties. Can also be a variable.

Action-specific properties

• Key data: The shortcut to perform. Contains a simple shortcut configurator with all possible combinations. Can be bound to a variable.
• Press time: How long the keyboard shortcut is held after being pressed. Can be bound to a variable.

Description

Enters a key sequence of any length. You can mask the entered sequence in the action’s properties.

Components

Sequence

The key sequence that will be entered. Click … next to the field to open an assistant.

Action-specific properties

• Mask sequence: Masks the entered sequence. The default is False.
• Press time: How long each key in the sequence is pressed. It can be bound to a variable.

Description

Presses a mobile action key, e.g., the Home or Back buttons.

Components

Key

The action key to press.

Action-specific properties

• Image-based: Configure parameters for image-based automation.
• Key: The action key to press. It can be bound to a variable.

Description

Performs a validation on a repository item, i.e. checks whether expected and actual states match. Depending on the result, this action will log a success or failure to the report. Several different types of validation are available, each with its own properties.

The validation action is complex. The different validation types share a set of action-specific properties, but most have their additional properties.

Shared validation properties

• Action: The type of validation. The rest of the properties change depending on this property.
• Message: The message that will be logged to the report for validation. Leave empty to use the default Ranorex message.
• Report level on failure: The report level the failure message will have.
• Report level on success: The report level the success message will have.
• Report screenshot: Whether a screenshot will be included in the report message.

Validation types and special properties

Exists

Checks whether a repository item exists. Logs a success if the item exists and a failure if it doesn’t.

NotExists

Checks whether a repository item does not exist. Logs a success if the item does not exist and a failure if it does.

AttributeEqual:

Checks whether an attribute (column Match name) equals a defined value (column Match value) within a defined time (property Grace period). The available attributes change depending on the linked repository item. Similarly, the possible match values also change depending on the attribute. For example, the attribute Text only takes text strings, while the attribute Valid takes true/false values. Both match name and match value can be bound to variables.

Special properties

Match name and Match value: explained above.

• Grace period: Amount of time in seconds the action waits for an attribute value to be equal to the match value. The grace period starts after the action has found the referenced UI element. If the UI element stops existing during the grace period, the action starts looking for it again, but the grace period does not stop or restart.

AttributeNotEqual:

Checks whether an attribute (column Match name) matches a defined regular expression (column Match value) within a defined time (property Grace period). The available attributes change depending on the linked repository item. Both match name and match value can be bound to variables.

Special properties

Match name and Match value: explained above.

• Grace period: Amount of time in seconds the action waits for an attribute value to be equal to the match value. The grace period starts after the action has found the referenced UI element. If the UI element stops existing during the grace period, the action starts looking for it again, but the grace period does not stop or restart.

AttributeRegEx:

Checks whether an attribute (column Match name) matches a defined regular expression (column Match value) within a defined time (property Grace period). The available attributes change depending on the linked repository item. Both match name and match value can be bound to variables.

Special properties

Match name and Match value: explained above.

• Grace period: Amount of time in seconds the action waits for an attribute value to be equal to the match value. The grace period starts after the action has found the referenced UI element. If the UI element stops existing during the grace period, the action starts looking for it again, but the grace period does not stop or restart.

AttributeContains

Checks whether an attribute (column Match name) contains a defined value (column Match value) within a defined time (property Grace period). The available attributes change depending on the linked repository item. Both match name and match value can be bound to variables.

Special properties

Match name and Match value: explained above.

• Grace period: Amount of time in seconds the action waits for an attribute value to be equal to the match value. The grace period starts after the action has found the referenced UI element. If the UI element stops existing during the grace period, the action starts looking for it again, but the grace period does not stop or restart.

AttributeNotContains

Checks whether an attribute (column Match name) does not contain a defined value (column Match value) within a defined time (property Grace period). The available attributes change depending on the linked repository item. Both match name and match value can be bound to variables.

Special properties

Match name and Match value: explained above.

• Grace period: Amount of time in seconds the action waits for an attribute value to be equal to the match value. The grace period starts after the action has found the referenced UI element. If the UI element stops existing during the grace period, the action starts looking for it again, but the grace period does not stop or restart.

ContainsImage

This is an image-based automation validation.

When the validation executes, it creates a screenshot of the repository item’s current state. Then it checks whether this new execution screenshot contains a previously defined validation screenshot/the image-find region defined in the validation screenshot (column Screenshot name). This validation type is more flexible than CompareImage, but becomes exponentially slower with increasing image sizes.

The validation screenshot and execution screenshot don’t need to have the same dimensions, but the execution screenshot must be larger than the validation screenshot/the defined image-find region. Else, the validation will fail. Therefore, make sure the size of all relevant UI elements during test execution is the same or smaller than when you created the reference image.

Click the ellipsis … in the Screenshot name column to open an ⇢ image editor where you can define the image-find region and also image-ignore regions.

Image-ignore regions for ContainsImage should be outside the image-find region. The validation will then ignore image features that look similar to/are the same as the image-find region, avoiding false positives.

Warning: For ContainsImage, an overlap warning will appear if image-find and image-ignore regions overlap, as this will likely cause a test failure. Redefine the regions so the overlap is removed, unless the overlap is intentional and necessary for your test.

Special properties

• Image-based: Configure properties for image-based automation.
• Report difference images: Defines whether a difference mask showing the differing pixels as well as the differential image is logged to the report.
• Report expected and actual images: When the actual and expected images should be included in the report.
• Report similarity: Defines whether the similarity of the two images is logged in the report.

CompareImage

This is an image-based automation validation.

When the validation is executed, it creates a screenshot of the repository item’s current state. Then it checks whether this new screenshot is the same as a previously defined validation screenshot/image-find region (column Screenshot name). This validation type is faster than ContainsImage, but less flexible.

The validation screenshot and execution screenshot must have the same dimensions. Else, the validation will fail. Therefore, make sure that the size of all relevant UI elements during test execution is the same or smaller than when you created the validation screenshot. If you defined an image-find region that is smaller than the validation screenshot, the action will automatically crop the validation screenshot and the execution screenshot to these dimensions during test execution.

Click the ellipsis … in the Screenshot name column to open an ⇢ image editor where you can define the image-find region and also image-ignore regions.

Image-ignore regions for CompareImage must be inside the image-find region. The validation will then ignore differences in these regions.

Special properties

• Image-based: Configure parameters for ⇢ image-based automation.
• Report difference image: Defines whether a difference mask showing the differing pixels as well as the differential image is logged to the report.
• Report expected and actual images: When the actual and expected images should be included in the report.
• Report similarity: Defines whether the similarity of the two images is logged in the report.

 

Description

Directly invokes a particular action on the referenced repository item without any simulated UI interaction through mouse clicks, key presses, etc. Especially useful for accessing UI elements that are not immediately visible, such as items in lists; or drop-down menus or buttons in windows that are not in focus.

Components

Action name

The action that is invoked. Changes depend on the referenced repository item.

Various arguments

Most actions don’t require any arguments. Some do, however. Arguments appear in parentheses after the action name, e.g. InvokeMethod(Name). Define them in the actions table or the properties. They can be bound to variables.

For examples of using the Invoke action, see Ranorex Studio fundamentals > Actions > ⇢ Invoke actions.

 

Description

Retrieves a value from a repository item attribute and passes it to a variable. Depending on the assigned repository item, the available attributes change. The retrieved value can also be modified using RegEx before being passed to the variable.

A common scenario for using this action is retrieving a value that is the result of a particular interaction. You then pass this value to a variable that’s used in a validation that checks whether the result of the interaction is correct.

Components

1. The attribute whose value will be retrieved
2. The variable the retrieved value will be passed to
3. The regular expression according to which the value will be modified before it is passed to the variable
4. The referenced repository item

 

Description

Sets a repository item attribute to a defined value. Depending on the assigned repository item, the available attributes change. The value can also be masked.

Components

1. The attribute will be set to a defined value
2. The value the attribute will be set to. Can be bound to a variable
3. The referenced repository item

Action-specific properties

• Mask value: Masks the value. The default is False.

 

Description

Starts a browser, attempts to instrument it (if required), and opens the specified website.

When Instrument is enabled, Ranorex Studio tries to install and enable the Ranorex browser extension for the selected browser. In some environments, automatic instrumentation is blocked (for example, by security settings or group policies). In these cases, make sure the Ranorex browser extension is already installed on the machine before you run your test, for example, by using the Ranorex Instrumentation Wizard.

Components

1. The URL the browser will navigate to once started. Optional. Can be bound to a variable.
2. The browser to start. Can be bound to a variable.
3. Whether the browser window will be maximized or not.

Action-specific properties

• Argument: Define command line arguments to use when starting the browser, such as -ProfileManager to start Firefox with the profile manager opened. Can be bound to a variable.
• Clear cache:  Whether the browser’s cache will be cleared upon starting. The default is False. Can be bound to a variable.
• Clear cookies: Whether the browser’s cookies will be cleared upon starting. The default is False. Can be bound to a variable.
• Incognito mode: Whether the browser will be started in incognito/private mode. The default is False. Can be bound to a variable.
• Instrument: Automatically attempts to instrument the browser by installing or enabling the Ranorex browser extension when the action runs. Particularly useful when deploying tests in runtime environments via XCOPY or Ranorex Agent. The default is True.
  In environments where automatic extension installation is restricted (for example, due to group policies), instrumentation may not be possible at runtime. In such cases, pre-install the Ranorex browser extension using the Ranorex Instrumentation Wizard and, if desired, set Instrument to False to avoid repeated instrumentation attempts.
• Kill existing: Whether previously opened instances of the browser will be closed before starting a new one. The default is False. Can be bound to a variable.

 

Description

Directly runs an application from the specified directory.

Components

1. The path to the application. It can be relative if the application is located in the same folder as the test suite executable. Can be bound to a variable.
2. Command line arguments the application will be run. Possible arguments depend on the application. Can be bound to a variable.
3. Working directory:

• Optional information for the working directory of the application
• It can be set as a constant value or as a variable
• If not changed, similar to a directory of the application executable

Action-specific properties

• Return value type/variable: These two fields are for working with the return value of the Run application action. The return value is always the process ID of the executed application. The type is therefore always System.Int32, i.e., an integer. The return value variable lets you select the variable to which you want to pass the process ID.
• Run flags: Allows you to set the NoElevation flag. This flag runs the application without Windows administrator privileges, e.g., as a normal user. Can be bound to a variable.
• Run maximized: Whether the application will be run maximized. The default is False.

 

Description

Runs an app on a mobile device.

Components

Endpoint

The endpoint (i.e. the mobile device) the app will be run. Can be bound to a variable.

Startup arguments

Command line arguments the app will be run. Possible arguments depend on the app. Can be bound to a variable.

Restart app

If the app is already running, restart it. Can be bound to a variable.

Mobile testing is explained in detail, starting with the mobile testing requirements.

 

Description

Instruments an Android app and deploys it to a specified mobile device.

Components

Endpoint

The endpoint (for example, the mobile device) the app will be deployed to. It can be bound to a variable.

File name

The path to the app to instrument and deploy. It can be bound to a variable.

Action-specific properties

• Instrument APK: Whether the app will be instrumented before deployment. The default is True. Can be bound to a variable.
• Instrumentation options: Define various instrumentation options.
• Timeout: Maximum amount of time the instrumentation and deployment may take before the action fails. Can be bound to a variable.

 

Description

Instruments an iOS app and deploys it to a specified mobile device.

Components

Endpoint

The endpoint (i.e., the mobile device) the app will be deployed. It can be bound to a variable.

App archive

The path to the app archive to instrument and deploy. It can be bound to a variable.

App ID

The app ID of the app to instrument and deploy. It can be bound to a variable.

Action-specific properties

• Instrumentation settings: Define various instrumentation settings.

 

Description

Sets the orientation of a mobile device for a specified repository item.

Components

Orientation

The orientation of the device will be set to. Portrait and landscape orientations are available. Landscape left means the top of the device is rotated left. Vice versa for Landscape right. Can be bound to a variable.

 

Description

Closes an application or website.

This action can be used for closing applications and websites. If the ‘Close Method’ is set to ‘CloseWindow’ or “CloseWindowByProcessID’, an attempt is made to close the application. 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 fails. If ‘Close Method’ is set to ‘KillProcess’, the application’s process is killed immediately, and the grace period is ignored.

Components

1. The close method. CloseWindow and CloseWindowByProcessID attempt to close the window. If this fails, it will kill the process after the grace period. KillProcess ignores the grace period and immediately kills the process. CloseWindowByProcessID works with the ReturnValue property of the Run application action.
2. If the normal closing of the application failed, the grace period is the time Ranorex will wait before killing the process. Can be bound to a variable.
3. The referenced repository item whose parent application will be closed.

 

Description

Waits until a defined state is reached within a specific time. Several different Wait-for types are available.

Exists

Waits for the referenced repository item to exist within a specified timeout (column Timeout). The timeout can be bound to a variable.

NotExists

Waits for the referenced repository item to stop existing within a specified timeout (column Timeout). The timeout can be bound to a variable.

AttributeEqual

Waits for an attribute (column Match name) of the referenced repository item to equal a specified value (column Match value) within the specified timeout. Match name and match value can be bound to variables. Available attributes changed depending on the repository item. If the values don’t match within the timeout, the action fails.

Configure the timeout in the action’s properties (Wait timeout). It can be bound to a variable.

AttributeNotEqual

Waits for an attribute (column Match name) of the referenced repository item to stop being equal to a specified value (column Match value) within the specified timeout. Match name and match value can be bound to variables. Available attributes changed depending on the repository item. If the values don’t stop matching within the timeout, the action fails.

Configure the timeout in the action’s properties (Wait timeout). It can be bound to a variable.

AttributeContains

Waits for an attribute (column Match name) of the referenced repository item to contain a specified value (column Match value) within the specified timeout. Match name and match value can be bound to variables. Available attributes changed depending on the repository item. If the attribute doesn’t contain the match value within the timeout, the action fails.

Configure the timeout in the action’s properties (Wait timeout). It can be bound to a variable.

AttributeNotContains

Waits for an attribute (column Match name) of the referenced repository item to stop containing a specified value (column Match value) within the specified timeout. Match name and match value can be bound to variables. Available attributes changed depending on the repository item. If the attribute doesn’t stop containing the match value within the timeout, the action fails.

Configure the timeout in the action’s properties (Wait timeout). It can be bound to a variable.

 

Description

Logs a message to the report, or captures a screenshot or Ranorex snapshot.

Components

Subaction

• Log: Logs a message to the report.
• Screenshot: Captures a screenshot and adds it to the report.
• Snapshot: Captures a Ranorex snapshot and adds it to the report.

Message

The message that will appear in the report. Also, applies to screenshot/snapshot captures. Can be bound to a variable.

Level

The report level at which the item will be logged.

Action-specific properties

• Category: Define under which category the item will appear in the report. The default is User.

 

Description

Inserts a separator line at the current position in the actions table. Use it to visually separate or group related actions. You can add a header text to describe the separator. The separator and its header text will also appear in the report. This action does not influence the test execution itself. It’s purely cosmetic.

 

Description

Delays execution of the next action for a specified amount of time. In essence, this action pauses test execution for a specified time (the AUT will still run normally, however). The time value can be bound to a variable. The delay is not affected by turbo mode.

 

Description

Adds a user code action. You can add an existing user code action from the user code library or code one yourself.