User code actions

User code actions extend the functionality of basic and smart actions. Examples include custom validations, accessing test-case related data and parameters, and extended reporting.

In this chapter, you’ll learn how to manage user code actions in the actions table. Writing your own user code requires programming knowledge and is therefore outside the scope of this chapter. You can however make use of user code actions programmed by others through the user code library.

Further reading

The user code library is an expert topic explained in Ranorex Studio expert > User code library > ⇢ Introduction.

In this chapter

    tipp icon

    Screencast

    The screencast “User code actions” walks you through information found in this chapter.

    Watch the screencast now

    Locate the user code file

    Each recording module is made up of three files. You can find these files in the projects view in Ranorex Studio or directly on your hard drive in the project folder. Double-click to open them.

    Recording modules - code files

    Recording modules – code files

    Actions table with repository in the Recorder view.
    Code representation of the recording module.

    • Machine-generated code representation of the recording module.
    • Automatically updated by Ranorex. Any modifications you make are discarded.
    • Read-only.
    User code representation of the recording module.

    • The user code file for the recording module and user code actions.
    • Write all your user code to this file.
    • User code methods from the user code library will automatically be added to this file.

    View the underlying action code

    To view the underlying code of an action:

    Viewing action code

    Viewing action code

    Select an action.
    Right-click it and click View Code, or press CtrlEnter.
    The action’s code appears.
    Note icon

    Note

    The file is locked, so you can’t change it. It’s updated automatically by Ranorex.

    Convert a standard action to user code

    You can convert standard actions to User code actions.

    To do so:

    Converting to user code action

    Converting to user code action

    Right-click an action.
    Click Convert to user code.
    The action appears as a user code action with a default method name.

    Double-click the user code action to view its code in the code editor.

    Example user code action

    Example user code action

    User code actions and arguments

    You can configure arguments for user code actions in the argument editor or in code.

    User code action arguments & parameter

    User code action arguments and parameters

    Button to open the argument editor of the code method.
    The argument editor.
    The argument in the action’s code.

    Argument name:

    • Any name is possible.
    • It is a best practice to use naming conventions, especially when working in a team.

    Available argument type(s):

    • String (value), can be bound to a variable
    • Boolean (true, false), can be bound to a variable
    • DateTime (value “YYYY/DD/MM”), can be bound to a variable
    • Duration (value in ms), can be bound to a variable
    • Int32 (integer value), can be bound to a variable
    • Location (values center, middle, …), can be bound to a variable
    • Point (coordinate values), can be bound to a variable
    • Rectangle (dimension value), can be bound to a variable
    • TimeSpan (time format), can be bound to a variable
    • Double (double value), can be bound to a variable
    • Adapter (Ranorex adapter), linked to a repository item
    • RepoItemInfo (repository item), linked to a repository item

    Important to know:

    • Method parameters can be used within the method.
    • Use the argument types ‘Adapter’ or ‘RepoItemInfo’ to pass a reference to a repository item into an action method.
    • Using repository items as arguments for user code actions enables a variety of possibilities such as providing a framework of smart test actions, defining generic technology-independent get/set value actions, combining several related actions to one user code action, implementing complex validations, and many more.

    User code return values

    User code methods do not return a value by default. However, you can configure specify one of the available data types as method return value.

    To do so:

    Replace the default void return value with your desired data type.

    Implement your individual user code and add a line to return the specified value.

    This causes a Return value column to appear in the action table. It contains the return value of the user code method and allows you to make it variable.

    Alternatively, you can use the context menu to create a user code method with return value:

    Right-click an action.

    Click Convert to user code with return value.

    The new action appears in the action table, including a Return value column.

    Merge actions into a user code action

    Two or more actions can be merged into a single user code action, as shown below:

    Merging actions to user code

    Merging actions to user code

    Select the actions you want to merge.
    Right-click them to open the context menu.

    Click Merge items to user code item to create a default user code method without return value.

    Click Merge items to user code item with return value to create a user code method with a return value.

    Name the new user code action and press Enter.

    Result(s):

    The code of the actions appears in the code of the new user code action.

    Merged user code items

    Merged actions in user code

    Default merged user code method without return value
    Merged user code method with Boolean return value.