Runtime and Remote Execution Troubleshooting – Ranorex

Use this article to troubleshoot common issues when running Ranorex tests on runtime machines, through Remote Desktop Protocol (RDP), or with a Ranorex Agent.

Before you start

Before troubleshooting a specific issue, verify the following:

System requirements: Make sure the runtime or remote machine meets the Ranorex hardware and software requirements. See Software Requirements.
Active user session: Make sure the Ranorex Agent is running in an active Windows user session. Do not log off the user while tests are running.
Firewall configuration: If you use a Ranorex Agent, allow communication through TCP port 8081 and UDP ports 10000–10001.
Network connectivity: Verify that the Ranorex Studio machine and the remote machine can communicate with each other.
Power settings: Prevent the remote machine from entering sleep or standby mode while tests are running.

Attention: Ranorex Agent uses TCP port 8081 by default. This port may also be used for remote debugging of CEF applications. If you use both features, configure CEF remote debugging to use a different available port to avoid a port conflict.

Note: Virtual machines can respond more slowly than physical machines. If tests fail because UI elements are not found within the expected time, consider increasing the applicable timeout values in the Ranorex settings.

If you run a data-driven test that uses an Excel data connector on a runtime machine without Microsoft Excel installed, see the documentation for executing data-driven tests without Excel.

Ranorex Agent cannot be found

If Ranorex Studio cannot discover or connect to a Ranorex Agent, check the following.

Verify the Agent status

Make sure:

Ranorex Agent is running on the remote machine.
The Agent is running in an active user session.
The user has not logged off the remote machine.
Only one Ranorex Agent is installed on the Windows system.

Check the network

Ranorex Studio and the Agent should normally be able to communicate across the network.

If the Agent does not appear automatically:

Verify that both machines can communicate.
Check whether they are located in the same subnet.
Try connecting to the Agent by hostname or IP address, where applicable.
Check the Windows Event Log on the Agent machine for Agent-related errors.

Check the firewall

Verify that the following ports are available on the remote machine:

TCP 8081
UDP 10000–10001

Also verify that corporate firewall, endpoint security, or network policies do not block communication between Ranorex Studio and the Agent.

Agent is on another subnet or behind NAT

If the Ranorex Studio machine and the Agent are located on different networks, automatic Agent discovery may not work because the networks may not contain routes to each other.

In this case, configure routing between the networks.

Important: Network routing can affect other systems and security policies. If you are working in a managed network, contact your network administrator before changing routes, gateway settings, or port-forwarding rules.

Configure a route

Depending on your network configuration, you can configure a route:

On the gateways between the networks.
On the individual machines that need to communicate.

For example, to add a network to the Windows routing table:

route add 192.168.2.0 mask 255.255.255.0 192.168.1.2 metric 2

To add a route to a single machine:

route add 192.168.2.2 mask 255.255.255.0 192.168.1.2 metric 2

Adjust the IP addresses, subnet mask, gateway, and metric for your network environment.

To inspect the path between two machines, you can use:

tracert <IP_address>

If the route does not reach the target system, check the gateway configuration and firewall rules.

Note: Windows routes created with route add are normally removed after a restart. Use the -p option only after confirming that the route is correct and should remain persistent.

Tests fail when using Remote Desktop

You can execute a Ranorex test on a remote machine through an RDP connection, but RDP introduces limitations related to the Windows user session and display environment.

Recording does not work through RDP

Ranorex Studio cannot record UI elements inside another machine's RDP window as though they were local UI elements.

If you run Ranorex Studio on one machine and attempt to record controls displayed inside an RDP session, Ranorex identifies the RDP window rather than the individual controls inside the remote application.

To create or maintain recordings, work directly in the environment where the application under test is running.

Test fails when the remote machine enters standby

If the remote machine enters standby or sleep mode, its network connection and active RDP session can be interrupted.

Resolution: Disable sleep or standby while the machine is being used for automated test execution.

Test fails when another user accesses the machine

A test can fail if another user takes over or interrupts the active Windows session on the remote machine.

Resolution: Use dedicated automation machines where possible and prevent other users from interacting with the active test session while a test is running.

Test fails after disconnecting the RDP session

Closing an RDP session can terminate or change the interactive Windows session required for UI automation.

To keep the console session active after disconnecting RDP, you can use a batch file that transfers the session to the console.

Create a batch file with the following content:

for /f "skip=1 tokens=3 usebackq" %%s in (
    `query user %username%`
) do (
    %windir%\System32\tscon.exe %%s /dest:console
)

Save the file, for example, as:

KeepSessionOpen.bat

Run the batch file with administrator privileges before disconnecting the RDP session.

Important: Transferring the session to the console can leave the remote machine unlocked. Consider the security implications before using this approach and do not leave sensitive information accessible on the machine.

Disconnecting from RDP may also change the display resolution of the remote machine. Tests that depend on screen coordinates, image recognition, or a specific display configuration can fail if the resolution changes.

Tests run slowly on a virtual machine

Virtual machines can perform differently from physical systems depending on available CPU, memory, graphics resources, and network performance.

If tests frequently fail because elements are not available within the expected time:

Verify that the virtual machine meets the Ranorex system requirements.
Check CPU and memory usage while the test is running.
Verify network performance if the test accesses remote resources.
Increase the applicable Ranorex timeout settings when necessary.

Avoid increasing timeouts excessively without first determining whether the environment itself is causing the delay.

Remote execution fails because of licensing

Remote test execution requires an appropriate Ranorex license.

When an executable build runs through a Ranorex Agent, the Agent uses a Runtime Floating License during test execution. The license is released when the Agent is idle.