Welcome to the Ranorex Support Portal

Agent-based remote execution

On this page, you’ll find out how to run executable builds on remote machines via a Ranorex Agent. You can do so either from the remote pad in Ranorex Studio or manually through a command line interface. We’ll first explain the remote pad, and then the command line interface.

In this chapter

The remote pad

The remote pad is the control center for managing Agents in your network, and for deploying and running executable builds on them.

You can open the remote pad in Ranorex Studio in two ways:

  1. In the toolbar, click the remote pad symbol

  2. In the menu bar, click View > Remote.

If you haven’t added any Agents yet, the remote pad will display its empty screen.

Add Agents to the remote pad

Before you can work with Agents from the remote pad, you need to add them to it.

To add an Agent:

  1. In the remote pad, click Add Ranorex Agent.

  2. If you haven’t done so yet, ⇢ download the Agent and install it on the remote machine. The remote machine must be in the same network as the machine you’re using the remote pad on.

  3. Click Manage Agents….


The Agent list appears. Add your Agent in one of two ways:


Under Available Agents in your network, identify the Agent you want to add and click Add Agent.


Under Search manually, enter the IP address or the host name of the remote machine the Agent is installed on and click Add Agent.

  1. When you’re done, click Back to return to the control panel of the remote pad.

  1. The added Agent appears in the Agent list. Remove deletes the Agent from the list. It does not uninstall the Agent on the remote machine.

  2. An added Agent indicated by the green label.

In the control panel of the remote pad, you’ll see the added Agent in its idle state, ready to be used for running tests.

Remote pad control panel

Use the control panel to deploy and run tests on Agents. To do so, you first need to have a solution with a test suite project opened.

The control panel consists of the following elements:

  1. Button to open the Manage Agents… screen.

  2. Lets you select the test suite/test sequence and specify the run configuration you want to run.
    If you select a test sequence, you can’t specify a run configuration. Instead, the individual test suites of the test sequence will execute in the run configuration that is active when you click the Run button next to an Agent.

  3. Lets you search added Agents by their attributes (e.g. tags, name, host name, etc.), i.e. what’s displayed when you hover over them (see item 5).

  4. All Agents you’ve added to the remote pad.

  5. Hovering over an Agent will display a tooltip showing the Agent’s attributes.

Run a test on an Agent through the remote pad

Deploying and executing a test on an Agent is easy with the remote pad.

To deploy and execute a test:

  1. Select the desired test suite or test sequence.

  2. Select a run configuration if possible (test sequences use the configurations active in the contained test suites at the time of clicking the Run button in the remote pad).

  3. Click the Run button to deploy and run the test on the Agent.

You can continue working on the machine you started the test from. The test will execute on the remote machine the respective Agent is installed on. Once the test has started, you can see how the test is progressing in the remote pad:

  1. Ranorex Studio is creating an executable build of the test and deploying it to the Agent machine. The green status bar shows the progress.

  2. Test execution has started on the Agent machine. The status message shows which test container is currently being executed and the clock symbol on the Run button indicates a test in progress. You can abort the test with the Stop button at any time.

  3. Test execution has finished.

  4. The Agent returns to the idle state. Click the button with the page and the numbered symbol to display the run history for this Agent.

The numbered symbol indicates how many test runs were completed since last viewing the run history. The symbol’s color indicates the success status of the test run:

  1. Green = successful test run.

  2. Red = test run with at least one error.

If more than one test run is queued on the Agent, a blue number over the Run button shows which test in the queue is currently being executed:

Run history

The run history provides detailed information about the test runs executed on an Agent.

Top open it:

  1. Click the button View run history.

  1. Filter categories for test runs. You can filter by success/error, test run initiator, and time.

  2. List of executed tests in chronological order.

  3. Clicking a run above displays details about it in this area.

  4. From left to right: Opens the report, downloads the report from the Agent machine to the local machine, deletes the selected history entry.

Note Icon


The run history of an Agent shows all tests executed on this Agent: for example, even those that were not started from the remote pad, but from a command line interface.

Run a test on an Agent through the command line

Aside from starting tests from the remote pad as explained above, you can also use a command line interface to deploy tests to Agents, where they will then be run. This is especially useful for incorporating Agent-based test execution into your continuous integration process.



All command line arguments are listed in
Ranorex Studio Expert > Runtime and remote execution > ⇢ Command line execution

To run a test on an Agent via command line:

  1. In Ranorex Studio, ⇢ create an executable build of your test.

  2. On your source machine, start a command line interface and navigate to the executable build’s output folder.

  3. Run the .exe file in the output folder with the argument /agent:<agent-name>.

If the Agent is found, the following will happen automatically:

  • The output folder is added to a ZIP file.
  • The ZIP file is deployed to the Agent.
  • The test is executed on the Agent.
  • Progress of the test run is displayed in the command line interface.
  1. Output folder being zipped.

  2. Test run started on the Agent machine.

  3. Report files being downloaded to the local machine. By default, files with the endings .rxzlog (default Ranorex Studio report) and .junit.xml (Ranorex Studio report in JUnit format) are downloaded.

  1. Everything completed.



Get the latest test automation information right in your mailbox.


© 2024 Ranorex GmbH. All Rights Reserved