Welcome to the new Ranorex Support Portal

Action 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


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


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


Description

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


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


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


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


Description

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

Components

Key

The action key to press.

Action-specific properties

Validation


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

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

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 to the report.

Download

Further reading


The concept of test validation is explained in Ranorex Studio fundamentals > Test validation > ⇢ Introduction.

Invoke action


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.

Download

Further reading


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

Get value


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

Set value


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
  1. The attribute that 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. Default is False.

Open browser


Description

Starts a browser, instruments it, and opens the specified website.

Components

Open browser action
  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

  • 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 is False. Can be bound to a variable.

Run application


Description

Directly runs an application from the specified directory.

Components

Run application action
  1. 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.

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

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


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.

Download

Further reading


Mobile testing is explained in detail starting with Web & mobile testing > Mobile testing > ⇢ Introduction.

Deploy Android app


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

Further reading


Mobile testing is explained in detail starting with Web & mobile testing > Mobile testing > ⇢ Introduction.

Deploy iOS app


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

Further reading


Mobile testing is explained in detail starting with Web & mobile testing > Mobile testing > ⇢ Introduction.

Set device orientation


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.

Download

Further reading


Mobile testing is explained in detail starting with Web & mobile testing > Mobile testing > ⇢ Introduction.

Close application


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

Wait for


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


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


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.

Download

Further reading


The separator action is also explained in Ranorex Studio fundamentals > Reporting > ⇢ Basic report characteristics & data.

Delay


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


Description

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

Download

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.

USERS LOVE US

SUBSCRIBE TO OUR NEWSLETTER

Get the latest test automation information right in your mailbox.

FOLLOW US

© 2024 Ranorex GmbH. All Rights Reserved