Ranorex Agents

A Ranorex Agent is a standalone tool that simplifies and streamlines test execution on remote machines. It receives test packages from Ranorex Studio, runs them, and sends the results back to the source machine. This setup allows you to start tests on a remote machine directly from within Ranorex Studio.

Quick facts:

• You can install the 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. You need to include the license information with the executable build of the test that you deploy to the Agent.
• The Agent must have access to the network with the server where the Ranorex License Manager is installed, so it can lease the license.

Note: When idling, Agents don’t require a license. They only lease it when executing tests.

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.

For more information, see Agent-Based Test Execution.

The Ranorex Agent is a standalone tool that uses a separate installer from Ranorex Studio. You need to download it and run it separately on each remote machine you want to run tests on.

1. On the source machine, open Ranorex Studio.
2. Navigate to View > Remote to open the remote pad.
3. Click Add Ranorex Agent and then click Download Ranorex Agent.
   
4. Select your Ranorex Studio version from the download archive and download the file under Ranorex Remote Agent.
5. Transfer the installer file to your remote machine.
6. Run the installation file, accept the license agreement, and click Install.
7. Wait for the installation to end.
8. Follow the first-time setup instructions after the Agent starts automatically.

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.

You manage Agent settings by clicking the icon in the top-right corner of the Agent window.

1. Change display name: Allows you to change the Agent's name. The default name is MyAgent. The display name is shown in the title bar of the Agent window and the remote pad in Ranorex Studio. If you change this name, you must remove the agent and then re-add it to your Remote pad list.
2. Show files…: Opens the folder RanorexAgentData in the installation directory of the Agent. This folder contains Agent logs and configuration files.
3. Autostart at logon: This toggle ensures the Agent launches automatically when the machine boots.
4. Keep session active: Keeps the Windows user session active even when you end or interrupt a remote desktop connection

Note: This can make your remote machine vulnerable as an essential security feature is disabled. 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 Ranorex Solutions and Best Practices.

5. Always on top: Keeps the Agent on top of all windows.
6. Exit: Quits the Agent.

Tags allow you to categorize Agents. You can trigger runs 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: To run tests on Agents via tags, you need to use command-line arguments. For more information, see User Code Actions.

To add tags to an Agent:

1. Click Tags in the Agent window.
2. Click Add tags to agent.
3. Enter the tag and press Enter.
4. The tag appears in the Agent.

Hint: Tags are case-insensitive.

The tag appears in the Agent. You can add any number of tags to an Agent.