All actions and their properties
In this chapter, you’ll 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. We’ll explain only the action-specific properties in this chapter. The standard properties are explained in ⇢ Manage actions.
In this chapter
Mouse
| Summary: | Performs a mouse action. |
| Type: | Basic action |
| Variables possible: | Yes |
| Linkable to repository: | Yes |
Description
Presses a button on the mouse or moves 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: Moves 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. 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.
Mouse wheel
| Summary: | Performs a mouse wheel action |
| Type: | Basic action |
| Variables possible: | Yes |
| Linkable to repository: | No |
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.
Touch
| Summary: | Performs a touch screen action |
| Type: | Basic action |
| Variables allowed: | No |
| Linkable to repository: | Yes, required |
Description
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. 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. Default is 100 ms. Can be bound to a variable.
- Touch duration: How long the touch will be held. Default is 100 ms. Can be bound to a variable.
Swipe gesture
| Summary: | Performs a touch screen swipe gesture |
| Type: | Basic action |
| Variables allowed: | Yes |
| Linkable to repository: | Yes, required |
Description
Performs a swipe action on a specific repository item. You can configure the direction, distance, and duration of the swipe.
Components
Swipe direction
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. Default is False.
- Image based: Configure parameters for ⇢ image-based automation.
- Start location: Where the swipe starts. 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.
Key shortcut
| Summary: | Performs a keyboard shortcut |
| Type: | Basic action |
| Variables possible: | Yes |
| Linkable to repository: | Yes |
Description
Performs a keyboard shortcut using one or multiple keys.
Components
Key code
- Press: Presses and releases 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.
Key sequence
| Summary: | Enters a key sequence |
| Type: | Basic action |
| Variables possible: | Yes |
| Linkable to repository: | Yes |
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. Default is False.
- Press time: How long each key in the sequence is pressed. Can be bound to a variable.
Mobile key press
| Summary: | Performs a mobile key press. |
| Type: | Basic action |
| Variables possible: | Yes |
| Linkable to repository: | Yes, required |
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. Can be bound to a variable.
Validation
| Summary: | Performs a validation. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | Yes, required |
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 their own properties.
The validation action is complex. The different validation types share a set of action-specific properties, but most have their own 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 the 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) does not equal 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.
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.
Attention
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:
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 to 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:
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 to the report.
Further reading
The concept of test validation is explained in Ranorex Studio fundamentals > Test validation > ⇢ Introduction.
Invoke action
| Summary: | Invokes an action |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | Yes, required |
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 depending 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.
Further reading
For examples on using the Invoke action, see Ranorex Studio fundamentals > Actions > ⇢ Invoke actions.
Get value
| Summary: | Retrieves a value from a repository item attribute. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | Yes, required |
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
GetValue action example
The attribute whose value will be retrieved.
The variable the retrieved value will be passed to.
The regular expression according to which the value will be modified before it is passed to the variable.
The referenced repository item.
Set value
| Summary: | Sets an attribute of a repository item to a defined value. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | Yes, required |
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
SetValue action example
The attribute that will be set to a defined value.
The value the attribute will be set to. Can be bound to a variable.
The referenced repository item.
Action-specific properties
- Mask value: Masks the value. Default is False.
Open browser
| Summary: | Opens a browser and navigates to the specified URL. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to |
No |
Description
Starts a browser, instruments it, and opens the specified website.
Components
Open browser action
The URL the browser will navigate to once started. Optional. Can be bound to a variable.
The browser to start. Can be bound to a variable.
Whether the browser window will be maximized or not.
Action-specific properties
- Arguments: 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.
Default is False. Can be bound to a variable. - Clear cookies: Whether the browser’s cookies will be cleared upon starting.
Default is False. Can be bound to a variable. - Incognito mode: Whether the browser will be started in incognito mode.
Default is False. Can be bound to a variable. - Instrument: Automatically instruments the browser. Particularly useful when deploying tests in runtime environments via XCOPY or Ranorex Agent. Default is True.
- Kill existing: Whether previously opened instances of the browser will be closed upon starting.
Default
Run application
| Summary: | Runs an application from the given directory |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | No |
Description
Directly runs an application from the specified directory.
Components
Run application action
The path to the application. Can be relative if the application is located in the same folder as the test suite executable. Can be bound to a variable.
Command line arguments the application will be run with. Possible arguments depend on the application. Can be bound to a variable.
Working directory:
- Optional information for the working directory of the application
- Can be set as a constant value, or as 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. 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. Default is False.
Run mobile app
| Summary: | Runs an application on a mobile device. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | No |
Description
Runs an app on a mobile device.
Components
Endpoint
The endpoint (i.e. the mobile device) the app will be run on. Can be bound to a variable.
Startup arguments
Command line arguments the app will be run with. Possible arguments depend on the app. Can be bound to a variable.
Restart app
If the app is already running, restarts it. Can be bound to a variable.
Further reading
Mobile testing is explained in detail starting with Web & mobile testing > Mobile testing > ⇢ Introduction.
Deploy Android app
| Summary: | Instruments an Android app and deploys it to a mobile device. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | No |
Description
Instruments an Android app and deploys it to a specified mobile device.
Components
Endpoint
The endpoint (i.e. the mobile device) the app will be deployed to. Can be bound to a variable.
File name
The path to the app to instrument and deploy. Can be bound to a variable.
Action-specific properties
- Instrument APK: Whether the app will be instrumented before deployment. 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.
Further reading
Mobile testing is explained in detail starting with Web & mobile testing > Mobile testing > ⇢ Introduction.
Deploy iOS app
| Summary: | Instruments an iOS app and deploys it to a mobile device. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | No |
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 to. Can be bound to a variable.
App archive
The path to the app archive to instrument and deploy. Can be bound to a variable.
App ID
The app ID of the app to instrument and deploy. Can be bound to a variable.
Action-specific properties
- Instrumentation settings: Define various instrumentation settings.
Further reading
Mobile testing is explained in detail starting with Web & mobile testing > Mobile testing > ⇢ Introduction.
Set device orientation
| Summary: | Sets the orientation of a mobile device for a repository item. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | Yes, required |
Description
Sets the orientation of a mobile device for a specified repository item.
Components
Orientation
The orientation 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.
Further reading
Mobile testing is explained in detail starting with Web & mobile testing > Mobile testing > ⇢ Introduction.
Close application
| Summary: | Closes an application or website. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | Yes, required |
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 failed. If ‘Close Method’ is set to ‘KillProcess’ the application’s process is killed immediately and the grace period is ignored.
Components
Close application action
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.
If 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.
The referenced repository item whose parent application will be closed.
Wait for
| Summary: | Waits for a specified UI state to occur. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | Yes, required |
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.
Log message
| Summary: | Logs an item to the report. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | Yes |
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. Default is User.
Separator
| Summary: | Inserts a separation line at the current position in the actions table. |
| Type: | Smart action |
| Variables possible: | No |
| Linkable to repository: | No |
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 has no influence on test execution itself. It’s purely cosmetic.
Further reading
The separator action is also explained in Ranorex Studio fundamentals > Reporting > ⇢ Basic report characteristics & data.
Delay
| Summary: | Delays execution of the next action. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable to repository: | No |
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.
User code
| Summary: | Adds a user code action. |
| Type: | Smart action |
| Variables possible: | Yes |
| Linkable epository: | Yes |
Description
Adds a user code action. You can add an existing user code action from the user code library or code one yourself.
Further reading
User code actions are explained in Ranorex Studio fundamentals > Actions > ⇢ User code actions.
The user code library is explained in Ranorex Studio expert > User code libary > ⇢ Introduction.