Welcome to the Ranorex Support Portal

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.

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:

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

  2. Click Add Ranorex Agent.

  3. Click Download Ranorex Agent.

  1. The download archive opens in your default browser.

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

To install the Agent on a remote machine:

  1. Transfer the downloaded installation file to the desired remote machine.

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

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

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

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

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

  2. Starts the Agent with Windows.

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

  1. Keeps the Agent on top of all windows.

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

To add tags to an Agent:

  1. In the Agent, click Tags.

  2. Click Add tags to agent.

  3. Enter the tag and press Enter.

  4. The tag appears in the Agent.



Get the latest test automation information right in your mailbox.


© 2024 Ranorex GmbH. All Rights Reserved