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

    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

    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

    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.

    tipp icon

    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:

    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.

    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

    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

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

    Description

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

    Components

    Open browser action

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

    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

    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

    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.