Welcome to the Ranorex Support Portal

Troubleshooting and FAQ

This page collects helpful tips and troubleshooting advice for remote testing.

In this chapter

System requirements for remote testing

The machine you want to run a test on remotely must fulfill the ⇢ system requirements of the respective Ranorex Studio version you’re using.

However, in terms of software requirements, you only need to make sure your target system has the required .NET Framework installed.

Ranorex Agent firewall settings

On a remote machine running a Ranorex Agent, the firewall must be configured to allow access to TCP port 8081 and UDP ports 10000-10001.


Agent can’t be found/execution not working correctly

  • Make sure the machine Ranorex Studio is running on is in the same network (subnet) as the remote machine the Agent is running on.
  • Make sure the Agent is running in an active user session. Do not log off the user from the machine the Agent is running on.
  • Ensure TCP port 8081 and UDP ports 10000-10001 are open on the remote machine.
  • Check the Windows Event Log on the machine the Agent is running on for entries related to the Agent.


Can I install a Ranorex Agent on a virtual machine?

Yes. The system requirements described above on this page apply.

You will likely also need to increase the global timeout values in the > ⇢ Recorder settings, as virtual machines are often slower. We can’t recommend an exact value, as the required increase depends mostly on your network.

Can I install more than one Ranorex Agent per Windows installation?

No. You can install only one Agent per Windows installation.

Which type of license do I need to run an executable build remotely?

You will need at least one Runtime Floating License. You have to ⇢ include the license information in the executable build, so the Agent can lease the Runtime Floating License from the Ranorex License Manager when starting a test run.

If you don’t have a license, you can also install a free trial of Ranorex Studio on the remote machine. However, you have to manually confirm the license each time you run a test.

Contact our Sales team for more information about licenses.

How many licenses do I need for remote test execution on a Ranorex Agent?

An Agent uses one Runtime Floating License while executing tests. When not executing tests (idling), no license is used.

How to overcome NAT issues

If the machine with the Ranorex Studio installation and the Agent machine aren’t in the same network, the Agent may not automatically appear in your Agent list and you may not be able to manually add it using the IP address. This is because by default, machines do not have the routing information to connect to a machine outside their own network.

To overcome this issue, a network route has to be configured either on the gateways between the networks, or on each machine.

Below is an example solution.

In the image, our networks’ addresses start with 192.168.x.x. One has the gateway (right), the other (left). Both gateways share the subnet 192.168.1.x (middle). This subnet has the gateway (top middle), which is connected to the internet.

The network of gateway contains two computers. One of them has three virtual machines (VMs) running on it. All of the VMs have 192.168.3.x IP addresses.

The network of gateway contains a router and two computers.
They all have 192.168.2.x IP addresses.

Enable a route across gateways

If you ping ‘’ (PC 2) from computer ‘’ (VM C), then the request will time out, unless you enable a proper route across the gateways. Assuming the (VM C) is running Windows 7, type one of the following commands on (VM C):

  • route add mask metric 2
    (add whole network to the route table)
  • route add mask metric 2
    (add single computer to the route table)

Once the command has been entered, the ping/communication would successfully go from (VM C) to (PC 2), but (PC 2) would still not be able to ping (VM C). There are two workarounds to enable communication between these two networks:

  • Set up a route on the gateways
  • Set up the route on the machines that need to communicate across networks

Consider gateway firewalls when setting up the routes, as they may block cross-traffic from the machines. If this is the case, you will need a network admin to either set up the route on the gateway instead or to set up port forwarding to allow traffic through the firewall.

As most gateways behind corporate internet firewalls function as bridges, not much internal traffic is firewalled on the local network. To check if your connection is firewalled, try ‘tracert’. If stars ‘*’ appear in the ‘trace route’ instead of IP addresses, then either the connection went through the firewall, or it has been misdirected into the internet.

Guidelines for testing via remote desktop protocol (RDP)

You can test remotely via RDP connections. There are some limitations, however.

Running tests via RDP

You can run an executable build on a remote machine via RDP in the same way as without RDP. The procedure is the same as explained on the previous pages

Recording tests via RDP

It is not possible to record tests via RDP with Ranorex Studio.

This is because the RDP window doesn’t allow Ranorex Studio, or other test automation tools, to identify UI elements as normal. Instead, only the RDP window is identified.

  1. Mouse click action on the Submit button of the Ranorex Studio Demo Application in an RDP window.

  2. The resulting repository item doesn’t represent the button, but the entire image displayed in the RDP window.


When the remote machine switches to standby mode, it disconnects from the network. This also interrupts the RDP connection and therefore causes a currently running test to fail.

Disable standby mode on remote machines you want to run tests on via RDP, even if they’re connected to a power source.

Other people accessing the remote machine

When you connect to a remote machine via RDP, it’s locked to other users and they cannot connect to it remotely without your agreeing to hand over the session first. However, someone can still log in physically on the actual remote machine. This automatically interrupts the RDP connection and causes a currently running test to fail.

Keep user session alive after closing remote desktop connection

When you connect to a remote machine via RDP, deploy and start your test, and then disconnect the remote session, your test will fail. This is because the current user session will be quit.

To keep the current user session active even if you’ve disconnected the RDP session:

  1. On the remote machine, create a batch file and insert the following code:

for /f "skip=1 tokens=3 usebackq" %%s in (
`query user %username%`
) do (
%windir%\\System32\\tscon.exe %%s /dest:console
  1. Save the batch file on the desktop of your remote machine and name it KeepSessionOpen.bat.

  2. If you need to disconnect the RDP session, run the batch file with administrator privileges and your remote machine will remain unlocked.



Get the latest test automation information right in your mailbox.


© 2024 Ranorex GmbH. All Rights Reserved