Agent-based remote execution

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. Below, find information about the remote pad, and the command line interface.

The remote pad is the control center for managing Agents in your network, 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 an empty screen.

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 are using the remote pad on.

3. Click Manage Agents….
   

    

   
   

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

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

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

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

1. 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 is indicated by the green label.

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

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 Agents by their attributes (for example, tags, name, hostname, etc.), i.e. what’s displayed when you hover over them.

4. All Agents you’ve added to 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 the last viewing of the run history. The symbol’s color indicates the success status of the test run:

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

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

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, and deletes the selected history entry.

 

Note

 

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.

 

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.

Reference

---

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

 

Note

 

If you spell the Agent name incorrectly or if the Agent can’t be reached over the network, you’ll see a list of Agents available in the network. You can also bring this list up with the argument /agent:?.

 

If the Agent is found, the following happens 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. 1. Output folder being zipped.

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

 

Hint

 

When using the command line to run a remote test, you can use the /artifacts command to instruct the Agent to download files with other file endings to the local machine as well. This is explained in Command line execution under Ranorex Agent.

 

4. Everything completed.

 

Note

 

The test run will also appear in the run history of the Agent in the remote pad.