RDP Connection

Remote Desktop Protocol (RDP) is a proprietary protocol developed by Microsoft. RDP servers are built into Windows operating systems. This technology is in MS Windows also known as Terminal Services and the server is also called Terminal Server. There are RDP server implementations also for Unix and OS X. Testing over the RDP protocol was introduced by T-Plan Robot Enterprise v4.3:

  • The host running Robot must be MS Windows Vista or newer. Future releases will also deliver the support of OS X.
  • The server (the System Under Test, SUT) may be any OS running an RDP server

It is recommended to use Robot 6.1 which contains the most recent version of the RDP libraries.

RDP on Windows

MS Windows supports the RDP connection as follows:

  • Windows Professional and Ultimate editions support RDP out of the box. The server is off by default and must be enabled. The Network Level Authentication security (NLA) is supported since Robot 4.4.4. For older versions or in case of connection failures it must be disabled.
  • Windows Home editions do not support RDP officially. They do contain the functionality but it is hidden. It may be enabled there using 3rd party tools such as RDPWrap.
  • Windows Server systems must have the media codecs installed or the connection crashes Robot. To fix this you must install the Desktop Experience feature. The steps for Windows Server 2012 R2:
    • Go to Start -> Administrative Tools -> Server Manager.
    • Click on Add roles and features in the Dashboard screen. This will start the Add Roles and Features Wizard.
    • Select the Desktop Experience feature under the User Interfaces and Infrastructure category of the Features screen.
    • Click Install. Restart the server when done.

RDP on other systems

On other systems, you have to install and start an RDP server. Known implementations:

There are several 3rd party solutions supporting the RDP connection for non-Windows implementations. For non-Windows environments the RDP functionality that Robot support may vary from Windows-based systems.

For example, Oracle VirtualBox supports RDP connection to its virtual machines (VM). Robot can connect to such a VM and automate it, however, the clipboard transfer and drive redirection support is limited. Also, some systems running in VM don't set the correct screen size, and you may have to force the correct screen size through the connection parameters on the Robot side.

RDP features

Robot 4.4.4 introduced support of clipboard transfer between the local and the remote systems. It is based on synchronization of the local and remote clipboards. If you plan to have multiple RDP connections on a single Robot machine you have to implement some kind of lock to avoid parallel clipboard updates from two competing scripts.

  • The clipboard synchronization is on by default and it doesn't have to be activated. File transfer over the clipboard is not yet supported.
  • To get the clipboard content in a script retrieve the _SERVER_CLIPBOARD_CONTENT variable:

// Save the clip contents as text to the CLIP variable

  • To set the clipboard content populate the _SERVER_CLIPBOARD_CONTENT variable:

// Set the clipboard content to "Hello world"
"Hello world!"

  • To copy/paste objects from/to the remote desktop press the Ctrl+C/Ctrl+V keys using the Press command or use other system/application means (context/edit menu, etc.). All clipboard objects will be exposed to the script as text.

Robot 4.4.4 also accepts some of the FreeRDP CLI options which allow to modify the connection parameters and set on additional features. Examples:

  • Use the +auto-reconnect option to reconnect automatically when the connection crashes due to intermittent network issues.
  • To map (redirect) a local directory to the remote machine use the /drive:<sharename>,<path> option. This is useful to enable the transfer of files between the local and remote systems. For example, the option below will make the remote system see the local directory of "C:\MyData" as the "Z" drive:


Drive redirection is subject to the support from the remote system and it doesn't have to work on all environments. It is recommended to use a file path with maximum permissions.

The CLI options may be defined:

  • Through the user preferences in the RDP Server screen of the Edit→Preferences window. These options will be applied to all connections.
  • Test scripts may populate the _RDP_OPTIONS variable prior to establishing the RDP connection. The variable content will be appended to the option specified in the preferences without any efforts to eliminate the conflicting ones. For example, the following code will apply the redirected drive to the RDP connection:

Var _RDP_OPTIONS="/drive:Z,C:\MyData"
Connect rdp://myserver


To connect to the RDP from a test script use the Connect command (TPR scripts) or the connect() method (Java test scripts). The argument URL must be in form of  "rdp://<host_or_IP>". For example, the following command/method call will connect you to the local desktop using the Local Desktop connection:

TPR test scripts:     Connect rdp://<address>?user=<user>&password=<passwd>
Java test scripts:    connect("rdp://<address>?user=<user>&password=<passwd>");

The URL may be also used together with the c/-connect CLI option to establish the connection on the Robot startup.

IMPORTANT: The RDP system must use the US English keyboard layout. Other layouts are currently not supported and test scripts employing the Type and Press command will type wrong characters. This limitation will be addressed in a future Robot release.


Minimizing the RDP window

Using Remote Desktop ("RDP"), you can connect to another machine in order to run Robot natively on that remote computer. If however, you minimize the Remote Desktop window (the window that displays the remote computer’s desktop), Windows switches the remote session to the GUI-less mode and as a result, ceases to receive input controls. In this case, Robot will be unable to interact with the remote systems GUI, as it does not exist and your automated GUI test will Pause.

To work around this issue, on your local computer (the one from which you launch Remote Desktop), change the registry settings that affect that way Remote Desktop treats the GUI of the remote session when being minimized.

Change the local computer registry settings as follows:

  1. On your local computer, close all open Remote Desktop sessions

  2. Launch the Registry Editor (regedit.exe).

  3. Navigate to one of the following Registry keys, depending on whether you wish to modify the Remote Desktop settings only for the current user or for all users on the computer:

    HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client
    HKEY_LOCAL_MACHINE\Software\Microsoft\Terminal Server Client

  4. Create a DWORD value named RemoteDesktop_SuppressWhenMinimized and set its value to "2":

  5. Close the Registry Editor.

Now when you minimize the Remote Desktop Connection window on your computer, this will not affect the remote computer’s GUI but your automated tests should continue to execute on that remote machine.