On this page, you’ll learn what Ranorex Agents are, how to install them, and how to configure them.
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.
- 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 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, click View > Remote. in the menu bar of Ranorex Studio. The remote pad opens.
Click Add Ranorex Agent.
Click Download Ranorex Agent.
Click your Ranorex Studio version and download the file under Ranorex Remote Agent.
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.
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.
To configure Agents, click the button in the top-right of the Agent window:
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.
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.
Starts the Agent with Windows.
Keeps the Windows user session active even when a remote desktop connection is ended or interrupted.
- 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.
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.
- You have 5 Agents. 3 of them you tag with “midnight-job”, the other two are untagged.
- Now you want to run a midnight job. You run it from the command line with this tag.
- Ranorex Studio now searches for all Agents that have this tag and runs the test on the one with the least jobs.
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.
- You can add any number of tags to an Agent.
- Tags are case-insensitive.