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.
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 ⇢ Executing data-driven tests.
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.
Troubleshooting
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.
FAQ
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 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 will time 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):
- route add 192.168.2.0 mask 255.255.255.0 192.168.1.2 metric 2
(add whole network to the route table)
or - route add 192.168.2.2 mask 255.255.255.0 192.168.1.2 metric 2
(add single computer to the route table)
Once the command has been entered, the ping/communication would successfully go from 192.168.3.6 (VM C) to 192.168.2.2 (PC 2), but 192.168.2.2 (PC 2) would still not be 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 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 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
For our example, we chose the standard subnet 255.255.255.0
You’ll need to confirm the subnet on either side of the gateways, and adjust your route setup commands as needed.
The route metric (last number in command) 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. As the route in our example contains two hops, our router metric is 2.
A route command is only persistent (will stay 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’ve found the right route, you can make the commands persistent after reboot.
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.
Mouse click action on the Submit button of the Ranorex Studio Demo Application in an RDP window.
The resulting repository item doesn’t represent the button, but the entire image displayed in the RDP window.
Standby
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:
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 )
Save the batch file on the desktop of your remote machine and name it KeepSessionOpen.bat.
If you need to disconnect the RDP session, run the batch file with administrator privileges and your remote machine will remain unlocked.
Note
- This can make your remote machine vulnerable as an essential security feature is disabled. We recommend you do not store any sensitive information on the remote machine if you use this feature.
- If you end the RDP session while a test is running, the remote machine may change to a different screen resolution. This can cause a test failure.