Welcome to the new Ranorex Support Portal

Ranorex
Try DesignWise with Ranorex
Help Center › User Guide › Ranorex Studio expert › Runtime and remote execution
User Forum

Ranorex Agents

On this page, you’ll learn what Ranorex Agents are, how to install them, and how to configure them.

In this chapter

    What are Ranorex Agents?

    A Ranorex Agent is a standalone tool that simplifies and streamlines test execution on remote machines. The Agent is installed on the remote machine and communicates with a Ranorex Studio installation on the source machine, from which it receives tests and to which it reports results. This way, you can start tests on a remote machine directly from within Ranorex Studio.

    Quick facts:

    • You can install an Agent on virtual or physical machines.
    • You can install one Agent per machine.
    • Agents queue tests and execute them one after another.
    Note icon

    Note

    You need a Runtime Floating License to execute tests via an Agent. When idling, Agents don’t require a license. They only lease it when executing tests. You need to ⇢ include the license information with the executable build of the test that you deploy to the Agent. The Agent must also have access to the network with the server where the Ranorex License Manager is installed, so it can lease the license.
    You can deploy and execute tests on Agents in two ways:

    • through the remote pad from within Ranorex Studio, from where you can manage all Agents and execute tests on them.
    • through a command line interface.

    Both possibilities are explained in ⇢ Agent-based test execution.

    Download and install Agents

    The Ranorex Agent comes as a standalone tool with a separate installer. It isn’t included in the Ranorex Studio installation. You need to download it and install it separately on each remote machine you want to run tests on.

    Download the Agent on a machine with Ranorex Studio:

    On a machine with Ranorex Studio,  from the Ranorex Studio menu bar click View > Remote. The remote pad opens.

    Click Add Ranorex Agent.

    Click Download Ranorex Agent.

    The download archive opens in your default browser.

    Click your Ranorex Studio version and download the file under Ranorex Remote Agent.

    To install the Agent on a remote machine:

    Transfer the downloaded installation file to the desired remote machine.

    Run the installation file, accept the license agreement, and click Install.

    Wait for the Agent to install. The Agent will start automatically once installation has finished.

    Note icon

    Note

    The machine you’re installing the Agent on doesn’t need to have any sort of Ranorex Studio license preinstalled. However, you need to include license information in the executable build of the test you deploy to it. The Agent then leases the correct license automatically from the Ranorex License Manager in your network.
    Follow the instructions of the first-time setup.

    Start Agents

    By default, Agents start with Windows. You can also start Agents manually from the Start menu.

    Agents normally run minimized to the system tray. You can open them from there.

    Configure Agents

    To configure Agents, click the button in the top-right corner of the Agent window:

    Lets you change the Agent’s name.
    The default name is MyAgent. The display name is shown in the title bar of the Agent window and in the remote pad in Ranorex Studio. In the above image, we’ve named it Ranorex Agent.
    tipp icon

    Attention

    If you change the display name, you need to remove and re-add the Agent in the remote pad in Ranorex Studio.

    We recommend you give each Agent a unique name. Otherwise, it will become more difficult to find the correct one in the remote pad and to address them through a command line interface.

    Opens the folder RanorexAgentData in the installation directory of the Agent. This is where Agent logs and configuration files are stored.

    Starts the Agent with Windows.

    Keeps the Windows user session active even when a remote desktop connection is ended or interrupted.

    Note icon

    Note

    • This can make your remote machine vulnerable as an essential security feature is disabled. We recommend you do not store any sensitive information on the remote machine if you use this feature.
    • If you end the RDP session while a test is running, the remote machine may change to a different screen resolution. This can cause a test failure.
    • For more information on running a test via RDP, refer to ⇢ Tips and troubleshooting.
    Keeps the Agent on top of all windows.

    Quits the Agent.

    Add tags to Agents

    Tags allow you to categorize Agents, so you can trigger runs not on a specific Agent, but on an Agent with one or more specific tags.  This is particularly helpful when tests are triggered on Agents in a CI pipeline because it allows you to balance the workload better and ensure a particular test is run on a machine with certain properties.

    For example:

    1. You have 5 Agents. 3 of them you tag with “midnight-job”, the other two are untagged.
    2. Now you want to run a midnight job. You run it from the command line with this tag.
    3. Ranorex Studio now searches for all Agents that have this tag and runs the test on the one with the fewest jobs.
    Note icon

    Note

    To run tests on Agents via tags, you need to use command line arguments. The relevant arguments are explained ⇢ here.

    To add tags to an Agent:

    In the Agent, click Tags.

    Click Add tags to agent.

    Enter the tag and press Enter.

    The tag appears in the Agent.

    tipp icon

    Hint

    • You can add any number of tags to an Agent.
    • Tags are case-insensitive.