Runtime and Remote Execution Troubleshooting

This article addresses common issues encountered when running tests on remote machines or using the Ranorex Agent.

Before you start

Before troubleshooting specific remote execution issues, verify these settings:

• Hardware requirements: The machine you want to run a test on remotely must fulfill the system requirements.
• Software requirements: Ensure your target system has the required .NET Framework installed for the Ranorex Studio version you are using. For more information, see Software Requirements.
• Firewall: 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.

Note: If you’re deploying a data-driven test with an Excel data connector and don’t have or want to use an Excel license on the remote machine, refer to Data-driven Testing Introduction.

Ranorex Agent issues

Agent cannot be found/Execution not working correctly

If it is not possible to discover a remote Agent:

• Check the network: Make sure the machine Ranorex Studio is running on is in the same network (subnet) as the remote machine the Agent is running on. If this is not the case, the Agent may not automatically appear in your Agent list and you may not be able to manually add it using the IP address.
• Verify Agent status: Make sure the Ranorex Agent is running in an active user session on the remote machine. Do not log off the user.
• Check the firewall: Verify that the remote machine allows traffic through the TCP port 8081 and UDP ports 10000-10001.
• Check the Windows Event Log: Review the log on the machine the Agent is running on for entries related to the Agent.

Overcome NAT and subnet issues

If your local machine and the remote Agent need to reside on different subnets or behind NAT, automatic discovery fails.

To overcome this issue, you need to configure a network route either on the gateways between the networks, or on each machine.

The following image shows an example solution:

In the image, you can see that networks’ addresses start with 192.168.x.x. 

• One has the gateway 192.168.2.1 (right), the other 192.168.3.1 (left). Both gateways share the subnet 192.168.1.x (middle). This subnet has the gateway 192.168.1.1 (top middle), which is connected to the internet.
• The network of gateway 192.168.3.1 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 192.168.2.1 contains a router and two computers.
• They all have 192.168.2.x IP addresses.

Enable a route across gateways

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

• To add the whole network to the route table:

  route add 192.168.2.0 mask 255.255.255.0 192.168.1.2 metric 2

• To add a single computer to the route table:

  route add 192.168.2.2 mask 255.255.255.0 192.168.1.2 metric 2

The example uses the standard subnet 255.255.255.0. You need to confirm the subnet on either side of the gateways, and adjust your route setup commands as needed. The route metric (metric 2 in the example) is assigned to a route and is used to identify its priority – with 1 being of the highest priority. Usually network admins base the router metric on the amount of hops in a route, as the route with the least hops is usually the best. The route in the example contains two hops.

Once you enter the command, the ping/communication successfully goes from 192.168.3.6 (VM C) to 192.168.2.2 (PC 2), but 192.168.2.2 (PC 2) is still not able to ping 192.168.3.6 (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 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 192.168.2.2’

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.

Note: A route command is only persistent (stays after reboot) if you add the ‘-p’ argument to it. Thus, you can easily try route commands at no risk beforehand, and simply reboot if you want to undo them. Once you find the right route, you can make the commands persistent after reboot.

Yes. The system requirements listed on the Before you start section apply.

You may also need to increase the global timeout values in the Ranorex Recorder Settings, as virtual machines are often slower. The required increase depends mostly on your network.

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

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

For more information, see Create an Executable Build or contact our Sales team.

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

Using RDP for remote execution introduces specific challenges related to session management and display.

Running tests via RDP

You can run an executable build on a remote machine via RDP in the same way as without RDP. 

Recording tests via RDP

It is not possible to record tests via RDP with Ranorex Studio. The RDP window doesn’t allow Ranorex Studio, or other test automation tools, to identify UI elements as normal. Ranorex only identifies the RDP window.

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.

Standby mode

If the remote machine enters standby mode, it terminates the network connection and the RDP session.

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

Multiple users

If another user logs into the remote machine physically, your active session is interrupted and the current test fails.

• Solution: Dedicate specific machines for automation and ensure no one attempts to access the machine physically.

Session disconnects

When you connect to a remote machine via RDP, deploy and start your test, and then disconnect the remote session, your test fails because the current user session quits.

• Solution: Use a batch file to keep the user session active. 

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
)		

2. Save the batch file on the desktop of your remote machine and name it KeepSessionOpen.bat.

3. If you need to disconnect the RDP session, run the batch file with administrator privileges to ensure your remote machine remains unlocked.

   Important: Keeping a session open leaves the remote machine unlocked and potentially vulnerable; do not store sensitive data on the machine.

   Ending an RDP session during a test may change the screen resolution, leading to test failures.