T-Plan Home
T-Plan Robot Enterprise 2.3.5 Doc Collection
11/07/12

T-Plan Robot Enterprise 2.3.5 Release Notes

Build No.  2.3.5-20120711.1


Contents

1. Client System Requirements
1.1 Java Requirements
1.2 JDK Installation & Configuration
2. Server System Requirements
2.1 VNC Server
2.2 Static Image Testing
3. Installation
4. License Key
5. Upgrade And Migration
6. Uninstallation
7. Startup
8. Integration With T-Plan Professional
9. Optimizing Performance
10. Troubleshooting

1. Client System Requirements

T-Plan Robot Enterprise runs in a client-server scenario where the client system executes T-Plan Robot Enterprise and automates the server system (System Under Test, SUT) through one of the supported remote desktop technologies (such as RFB/VNC). As the client and server systems may be two fundamentally different platforms, we list the client system (discussed in this chapter) and server system requirements (the following chapter) separately. These are the T-Plan requirements for the client system running T-Plan Robot Enterprise:

Item
Minimum
Recommended
Processor (CPU)
Not set1
2GHz+
Memory (RAM)
128MB (required by Java)2
512MB+
Free Disk Space
50MB for Robot alone. Add approx. 50/100MB for the Java JRE/JDK installation.
200MB+
Operating System
Any system supported by Oracle's Java 1.6+ (Java 6 or higher) or compatible.
64-bit OS preferred for memory intensive2 deployments.
Web Browser
Internet Explorer 6 and higher
Mozilla Firefox 3 and higher
Google Chrome 1 and higher
Opera 9 and higher
Apple Safari 3 and higher (limited support due to missing XPath support)
Any other web browser supporting XML, XSLT and XPath

Installed Software
  1. Windows Installer 3.1 (WindowsInstaller-KB893803-v2-x86.exe) - only for users installing the Robot's .exe distribution (see Installation)
  2. Java (JRE or JDK) version 6 or higher (see the Java Requirements and JDK Installation & Configuration chapters below)
Latest Java SE (JDK) from Oracle Inc.
1 Slower processors will result in slow performance of graphical operations, such as image comparison or OCR.
2 The overall memory requirements depend on the SUT desktop size, the nature of graphical operations performed by the script and the number of parallel automated processes where the test suite is designed as a multithreaded one. If you experience errors with java.lang.OutOfMemoryError visible in the stack trace, raise the heap size allocated to the Java Virtual Machine (JVM) through the -Xmx option. The instructions are available in the Memory Adjustments chapter.

1.1 Java Requirements


T-Plan Robot Enterprise is a Java application and it will run on any system with Java 1.6 (Java 6) or higher installed. Though there are more Java producers, T-Plan Robot Enterprise is being developed on Java 6 from Sun Microsystems Inc. and we recommend you to use it as long as your platform (OS) is supported (see the list of supported systems) .

To verify whether Java is installed on your machine open a terminal window (Unix/Linux) or a command line prompt (Windows) and run the following command:

java -version

If Java is present on your machine and its binaries are on the system path, it displays its version. Make sure it is at least the required one (1.6). If Java is not present, you may download it for free from the following location:
Java is being shipped in two distributions, the Java Runtime Environment (JRE) and Java Development Kit (JDK). JRE is a subset of JDK and doesn't contain the Java source code compiler and libraries needed for development. T-Plan Robot Enterprise runs with both but certain functionality requires JDK, such as development and on-the-fly execution of Java test scripts and Java code blocks. If you plan on using this functionality, get a JDK. If you are used to Java development with NetBeans IDE, you may consider getting it from Oracle Inc. together with the JDK in one software bundle. Both components are open source and free.


1.2 JDK Installation & Configuration


If you plan on developing Java test scripts or using the Java code blocks you will need to install JDK and configure T-Plan Robot Enterprise in one of the following two ways:

Alternative 1: Configure the JDK path through T-Plan Robot Enterprise preferences (v2.3.3 and newer):
  1. Create a new Java test script through the File->New Test Script->Java Test Script in the T-Plan Robot Enterprise GUI.
  2. Right click the editor and select Compile.
  3. T-Plan Robot Enterprise will search known paths for the installed JDK packages. If it finds a JDK the compilation succeeds and no error is reported. Otherwise it will display a message leading to the Preferences window where you may set the JDK installation path or location of the javac compiler manually.
  4. Should you need to cancel the auto setting or to switch to another JDK you may reconfigure the path in Edit->Preferences->Java Test Script Interpret panel.
Alternative 2: Make T-Plan Robot Enterprise start using the java or javaw binary (all product versions). This method overrides the first alternative if both are set up.
  1. Option 1: Put the <JDK_dir>\bin path to the system path. This will make your OS use the JDK as a default interpret for all Java applications.
MS Windows instructions:
    1. Start Windows Explorer, right click the Computer node and select Properties in the context menu.
    2. Navigate to the Advanced tab or item (depends on Windows version) and select Environment Variables.
    3. Edit the Path system variable and put path to your JDK's bin/ directory followed by a semicolon to the beginning of the path (typically "C:\Program Files\Java\jdk1.6.0_<version>\bin;").
    4. Save the variable and close all windows with OK. 
    5. Open a command prompt and type javac. The command must be found and print out the supported parameters.
Other systems: Installation of JDK on other systems may or may not configure the system to use the JDK binaries by default. Refer to your OS documentation for information on how to adjust the system path list and/or associate Java applications with a particular Java distribution.
  1. Option 2: Replace "java" in the T-Plan Robot Enterprise start command with absolute path to the JDK's "java" binary. For example, on MS Windows edit the robot.bat file, replace "java" with "C:\Program Files\Java\jdk1.6.0_<version>\bin\java" and use the batch file to start T-Plan Robot Enterprise. For information on how to modify other start up methods (Windows menu, starting from T-Plan Proffesional) see the Startup and Integration with T-Plan Professional chapters. 
To verify that Robot runs on top of the JDK restart Robot's GUI, select Help->About in the menu, switch to the System Information tab and make sure that the java.home property value points to the JDK install folder.


2. Server System Requirements

Server system requirements depend on the protocol selected for automation. T-Plan Robot Enterprise 2.3.5 by default supports RFB protocol (better known as VNC) versions 3.3, 3.7 and 3.8. The Enterprise version also supports static images. As the product is open to client plugins, there are likely to be more protocols supported in the future such as RDP or OS specific local display clients.

For system requirements on the SUT see the documentation of the particular server layer (such as the selected VNC Server product).

2.1 VNC Server

Automation through the RFB protocol requires the SUT to run a VNC server. A good overview of existing VNC products is on Wikipedia, both in the VNC and Comparison Of Remote Desktop Software topics. T-Plan Robot Enterprise should work fine with any VNC server which is RFB 3.x compatible.

Summary of servers by the target platform:

Desktop PC Platforms
Portable Devices

For mappings of the phone keyboard onto standard PC keyboard events see documentation of the particular server you are using.

Be aware that many mobile VNC servers do not fully comply with the RFB 3.x specification and may crash on the standard VNC session settings. When a connection failure is experienced, it is recommended to reconfigure the RFB client on Robot's side (at Edit->Preferences->RFB (VNC) 3.x Client) to the minimal configuration (disable all encodings except the Raw one and disable the custom pixel format). It is also a good idea to set on the Console debug logging preference to get debug messages printed out into the console window (command prompt). If the connection succeeds this time, try adding the encodings and/or setting the pixel format one by one to identify the one which causes the crash. Most problems are due to enabled Cursor or Zlib encodings or when the pixel format is forced to a one which the server can not handle.

Summary of servers for mobile devices:
The following matrix describes the servers in details. Should you want to contribute to the list with a new unlisted server, contact us through the T-Plan Robot Enterprise Contacts web page.

VNC Server
Platforms
Status/Notes
Tight VNC
all supported by server
Tested by us on Linux & Windows. Be aware that Windows specific keys (Win, Properties) do not work on TightVNC server. The issue has been reported and it is likely to get fixed in TightVNC 1.3.11 or 2.0.
Real VNC
all supported by server
Servers for portable devices (such as mobile phones) distributed by RealVNC in form of OEM software are not compatible and will not work with T-Plan Robot Enterprise.

RealVNC Free Edition relies on the standard RFB v3.x protocol and works out of the box.

RealVNC Personal Edition and RealVNC Enterprise Edition work on a proprietary enhancement of the RFB protocol coded as v4.x. T-Plan Robot Enterprise can work with these servers only in the 3.3 protocol compatibility mode which must be configured on the server side as follows:

1. On the Connections tab of the VNC server window change the settings:
  Authentication - None
  Encryption - None
  Prompt VNC Server user to approve connections - Untick

2. On the Expert settings tab:
  Protocol 3.3 - True
UltraVNC
all supported by server Tested by us; reported to work by users.
Apple Remote Desktop (ARD; Mac OS feature)
10.4 PPC Mac
10.5 and higher (Intel Mac)
Tested by us on 10.6 Snow Leopard; the legacy platforms were reported to work by users.

To make ARD work with T-Plan Robot Enterprise perform these steps on the Mac OS X desktop:
  1. Start System Preferences from the system main menu (Apple icon)
  2. Open Sharing in the Internet & Wireless section
  3. Tick the Screen Sharing check box in the list 
  4. Click the Computer Settings button, set off "Anyone may request permission", set on the "VNC viewers may control screen with password" and enter a password
  5. Confirm with OK (authorization may be required) 
  6. The window displays description containing an URL like "vnc://192.168.100.10/". As the desktop server runs on the default VNC port of 5900, to connect trom Robot use either the IP alone (such as "192.168.100.10") or the IP with the port number ("192.168.100.10:5900").
Pocket VNC
Windows CE and Windows Mobile devices
Tested by us. Older versions such as PocketVNC v1.4.3 contain a bug which breaks the desktop image transfer. There's a workaround:
  1. Go to Edit->Preferences in T-Plan Robot Enterprise GUI and locate the "RFB (VNC) Client" panel.
  2. Move the Hextile and Raw encodings to be first and second in the list.
  3. Select "Use custom pixel format" and choose the "16 bit (65k colors)" item in the drop down.
See the Mobile Devices And TCP/IP tutorial on the PocketVNC site to find out how to get your mobile connectible from T-Plan Robot Enterprise. If your mobile phone can't have an IP address but is connected to the network, use the RFB listen mode for reverse connection from PocketVNC to T-Plan Robot Enterprise.

As some devices disconnect regularly from the network to save battery, Robot may fail to connect with a message like "No route to server" or "Server not found". Pinging the device IP from the PC seems to wake it up in some cases. If it doesn't help, reconnect the device to the network (WiFi) and restart the VNC server to make sure that the connection is active and the device is visible in the local network.
 
NOTE: Pocket VNC in combination with T-Plan Robot Enterprise is one of the very few real black box GUI automation solutions for Windows mobile OS and application testing.
EfonVNC
Windows CE and Windows Mobile devices Version 4.3 has been reported to work by users. As the server by default uses an unusual 15-bit pixel format, the screen may appear bluish. This can be fixed by making Robot to request one of the standard pixel formats as follows:
  1. Go to Edit->Preferences in T-Plan Robot Enterprise GUI and locate the "RFB (VNC) Client" panel.
  2. Set on the "Use custom pixel format" check box and choose any standard pixel format in the drop down (32-bit is OK).
mVNC
Symbian OS mobile devices
Reported to work by users.

As most keys on the device keyboard are mapped onto the PC numpad, commands automating typing on the device must use the "location=numpad" parameter. For example, to automate typing of a phone number of 123456789 use "Type 123456789 location=numpad".
Veency (download through the Apple Market)
iOS (iPod, iPhone)
Tested by us for basic functionality; reported to work by users. Veency requires a jailbroken (rooted) device. There's no alternative because the iOS API does not contain interfaces providing access to the necessary features.

Should you experience freezing display image or other connection problems perform the following steps:
  • On Veency side set off the Enable Cursor preference.
  • On Robot side navigate to Edit->Preferences, select the "RFB (VNC) v3.x Client" panel and move the Raw encoding to the top of the list. On newer Robot versions also disable the Cursor encoding (move it to the disable list on the right).
Droid VNC Server
Android
The Droid VNC Server is the most advanced VNC server for the Android platform. It however requires a rooted phone.

The server is available through the Android Market. Alternatively search the web for the latest Droid's .apk distribution and install it onto the Android device either tfrom the PC hrough Android SDK's "adb install xxx.apk" or through the Astro File Manager on the Android device itself. For more information on the Android SDK see the Android VNC Server below.
Android VNC Server
Android
Tested by us for basic functionality. It may run both on unrooted and rooted phones.

The server binary requires to have the Android SDK installed because it relies on the "adb" tool (short for Android Debug Bridge). ADB is used for interaction of the Android device and PC over USB cable. The following steps are intended to give you a quick overview of the installation procedure; for eventual troubleshooting refer to the project home page.
  1. Download Android SDK to your PC. It's just a zip package which you extract somewhere.
  2. Windows users only: Install the USB driver as is described in the Android SDK documentation. If you are running Windows 7, use these instructions or install PDANet.
  3. Download the server binary onto your PC and place it to the <AndroidSDK>/tools folder.
  4. Connect your Android device to the PC using the USB cable. Make sure the device has the "USB debugging" mode enabled; this is usually located in Settings->Applications->Development  It is also recommended to set on the "Stay awake" option to keep the device awake as long as it is connected to USB.
  5. On your PC switch to the <AndroidSDK>/tools folder and execute the following commands to start the adb server and connect to the Android device. Note that on Linux/Unix you willhave to run it with root privileges or sudo (sudo ./adb <cmd>):
adb kill-server
adb start-server
adb devices


The last command should display a list containing your connected device. If it lists the device as "????????  no permissions" you have to re-run the commands above with admin privileges (sudo).
  1. Copy the androidvncserver binary to your Android, change it to executable and start it:
    1. Installation on a rooted device:
adb push androidvncserver /data/
adb shell chmod 755 /data/androidvncserver
adb shell
/data/androidvncserver
    1. Installation on a standard device (not rooted) is only possible if your Android file system contains at least one folder with sufficient rwx permissions. To find out list the root directory of your Android:
adb shell
$ ls -l

Search the output for a folder which has the permissions of "drwxrwxrwt", for example:

drwxrwxrwt root     root              2010-11-22 12:53 sqlite_stmt_journals

The above folder usually exists on devices with Android 2.1 and older. An alternative one for Android 2.x is the /data/local/tmp one. Note that as most such folders are temporary, you may have to reinstall the server after every restart of the Android device.

Once you have identified such a folder, copy the server binary in there, change its permissions and execute it as follows:
adb push androidvncserver /data/local/tmp
adb shell chmod 755 /data/local/tmp/androidvncserver
adb shell
/data/local/tmp/androidvncserver
  1. The server is up and running and you may connect to it from Robot. If your Android is connected to the network over WiFi, check Settings->Wireless & networks->WiFi settings->[your network] to get your device IP and connect from Robot to "<IP>:5901". Alternatively follow the Android SDK docs to redirect the port over the USB to the PC and connect to it through the PC.
TROUBLESHOOTING:

As some devices disconnect regularly from the network to save battery, Robot may fail to connect with a message like "No route to server" or "Server not found". Pinging the device IP from the PC seems to wake it up in some cases. If it doesn't help, reconnect the device to the network (WiFi) and restart the VNC server to make sure that the connection is active and the device is visible in the local network.

PC keyboard doesn't work on touch phones save for a few control buttons listed below. This is expected because the phone has no keyboard and doesn't accept classic typed events. The following keys  should work because they emulate buttons available on most touch phones. The keys may or may not work; this seems to be subject to the device model and Android version.

Home – Home or Mouse Right Button
Menu – Pg Up
Back – Esc
Search – Ctrl

The server fails to connect to the right event queues on some devices and must be tweaked from CLI. For example, on HTC Wildfire it connects to the /dev/input/event2 for the touch screen and /dev/input/event3 for the keyboard while the right queues are /dev/input/event1 and /dev/input/event4  (Android 2.1) or even /dev/input/event2  (Android 2.2.1) . If you experience a failing touch screen or keyboard input, you have to search the project forum for information or experiment with the event queue numbers to find out the right ones. For example, on HTC Wildfire with Android 2.1 the server must be started as follows:

adb shell <dir>/androidvncserver -t /dev/input/event1 -k /dev/input/event4

On the other hand the same HTC Wildfire with Android 2.2.1 must be started as:

adb shell <dir>/androidvncserver -t /dev/input/event1 -k /dev/input/event2

There's also a server called Fastdroid (see below) which was apparently forked from the same source code.

Fastdroid
Android Tested by us for basic functionality. The server is great if it works out of the box right after installation. As it doesn't support any CLI or configuration options, it is impossible to tweak it to address eventual issues. Since the server shares part of the code with Android VNC Server, most tips described above apply to Fastdroid as well.

As Fastdroid seems to have problems with the RFB v3.7 and 3.8 protocols, it is necessary to force T-Plan Robot Enterprise v2.3 and higher to communicate in RFB v3.3. To do so go to Preferences in T-Plan Robot Enterprise GUI, locate the "RFB (VNC) Client" panel and set the RFB Protocol Version to 3.3.

The "vncconfig" utility has to run on your server to make the clipboard transfer working. As some VNC servers do not distribute it (for example, TightVNC), the feature may be switched off in T-Plan Robot Enterprise. If you plan on using clipboard changes to transfer text from server to client, get a VNC server which has it, such as UltraVNC or RealVNC.

VNC Servers On Linux/Unix

On Unix or Linux you may run a VNC server on the same machine as T-Plan Robot Enterprise. Most Linux distributions already contain a VNC server in the package repository and allow to install it through the package manager. To find out whether the software is installed on your machine try to run vncserver in a terminal.

The autocutsel utility can be used on Linux/Unix to make the clipboard transfer work instead of vncconfig. It must be executing on the server as "autocutsel -s PRIMARY". If you are running Debian or Ubuntu, you may find the tool in the package repository. Other resources also mention xcutsel but we haven't tested it. Be aware the RFB client can transfer only characters from the Latin-1 (ISO8859-1) character set. This is limitation set by the RFB protocol and we can't do anything about it.

VNC Servers On Windows

Windows systems are generally not capable of running multiple window servers (desktops) save for their RDP support. The impact is that you can't run the server and client (meaning T-Plan Robot Enterprise) on the same system. To automate on a Windows system you need at least two machines (physical or virtual), one with a VNC server (Windows) and another one which will run T-Plan Robot Enterprise (any system). It should be theoretically possible to run the tool in CLI mode on a Windows VNC server; this configuration has however never been tested. If you need to run everything on one Windows machine, set up one or more virtual Windows machine using VirtualBox or VMware (see below).

It is recommended that you run VNC server on Windows as a service. This will allow you to restart Windows from T-Plan Robot Enterprise and access the login screen after the system restarts. To send system reserved key combinations like Ctrl+Alt+Delete use the Keys tab situated in the top left corner of the T-Plan Robot Enterprise GUI.

There is no direct RDP (Windows Terminal Services) support at the moment. A few users reported that they had succeeded to make the tool work with Citrix/ICA using the RDP2VNC proxy. We are considering to provide an RDP client in one of the future versions. The client API is otherwise open to plugins for those who wish to implement their own protocol support or plug in functionality of other open source projects.

If you connect T-Plan Robot Enterprise to a Windows server running TightVNC, you may experience a refresh problem. Application windows sometimes display on the remote desktop without content and pieces of the window image appear as user moves the mouse pointer over the window. To prevent this behavior open the TightVNC settings window and select the 'Poll full screen' check box.

Windows specific keys like 'Windows' and 'Properties' may be reproduced in scripts through the Press command as long as the VNC server supports them. The keys work fine on RealVNC and UltraVNC. Should you experience any issues make sure to switch on the scroll lock (this is a workaround described in UltraVNC forums). TightVNC 1.3.10 doesn't support the Windows specific keys but planned to support them in the 2.0 release.

VNC Servers In Virtual Environments

VNC servers can execute on a guest system running on a virtual machine, for example in VirtualBox or VMware. The steps for VirtualBox are:
  1. Download and install VirtualBox
  2. Create a virtual machine and install the guest OS in there
  3. Download and install one of the VNC servers on the target machine
  4. Modify network configuration of the guest OS to make port of the VNC server accessible from outside (NAT, ...). See the Control Guest Through VNC VirtualBox forum topic.
VNC servers running on VMware have been reported to have problems with key mapping where the client and server have different keyboard layout (see example[1], example[2]). This typically results in some characters being typed incorrectly on the VNC desktop. This is not T-Plan Robot Enterprise failure.

Another issue you may experience is that the Type/TypeLine commands type lower case characters instead of upper case ones. This problem shoud go away when you open the Preferences window, locate the Press Command panel and make sure that the flag called Fake Shift for upper case characters is on.

2.2 Static Image Testing

Version 2.2 introduces Static Image Client which allows to load image from a file in the local file system and test it the same way as live computer desktops (except key events). The client supports all Java-compliant lossless image formats such as PNG, BMP, WBMP and GIF. This scenario doesn't require any server or additional configuration.

3. Installation

T-Plan Robot Enterprise 2.3.5 is delivered in three forms:
  1. T-Plan Robot Enterprise with Windows installer (an .exe or a ZIP file containing an .exe file). This package can be installed just on MS Windows and it will allow you to manage the software as a standard Windows program. It also associates Robot with the .tpr test script file extension. The installer installs the tool into the C:\Program Files\T-Plan\Robot directory by default.
  2. T-Plan Robot Enterprise packaged as Mac OS X application (a .dmg or a ZIP file containing a .dmg file). This package can be installed on Apple Mac OS X only. To install the product on Mac OS drag the TPlanRobot application to Applications after the system opens the downloaded file.
  3. T-Plan Robot Enterprise ZIP file which is a self contained platform independent ZIP archive containing all necessary files. There's no installer. It can be used for all platforms including Windows and Mac OS. All you have to do is to unzip the file into a folder on your hard drive. The archive should contain at least the following files:
File Name
Description
robot.jar Java archive with compiled T-Plan Robot Enterprise classes.
jh.jar JavaHelp(TM) v1.1.3 library, distributed by Sun Microsystems Inc. under Binary Code License (BCL).
activation.jar
JavaBeans(TM) Activation Framework (JAF) v1.1.1 library, distributed by Sun Microsystems Inc. under BCL.
mail.jar
JavaMail(TM) v1.4.1 library, distributed by Sun Microsystems Inc. under BCL.
poi-3.6-20091214.jar Repackaged Apache POI 3.7 libraries distributed under Apache License v2.0. The archive contains
contents of the poi-ooxml, poi-ooxml-schemas, xmlbeans and dom4j libraries.
The old library name of poi-3.6-20091214.jar is preserved for compatibility with v2.1 and 2.2.
For information on the POI and its subcomponent licenses see the LICENSE file.
robot.sh T-Plan Robot Enterprise start script for Unix/Linux. See the 6. Startup chapter for more information.
robot.bat T-Plan Robot Enterprise start script for Windows. See the 6. Startup chapter for more information.
imgcompare.sh
Script for offline CLI image comparisons for Unix/Linux. See the 6. Startup chapter for more information.
imgcompare.bat Script for offline CLI image comparisons for Windows. See the 6. Startup chapter for more information.
install.html A copy of this T-Plan Robot Enterprise 2.3.5 Release Notes document.
LICENSE.txt License text. Please read carefully before you start using T-Plan Robot Enterprise.
crc32.properties
CRC32 check sums of all installed files for the Update & Upgrade feature.
help/
Directory with help topics and Java API documentation.
plugins/
Default drop-in folder for plugins. It may or may not exist.

One machine can host multiple T-Plan Robot Enterprise installations. If you however execute more than one program instance at the same time under the same user account, they will overwrite the user specific configuration files because there's no synchronization or locking mechanism in place.

4. License Key

T-Plan Robot Enterprise requires a valid license key to run. It is an encrypted file with the .tlic extension which contains details of your license, such as:
When you purchase a T-Plan Robot Enterprise license, you should also receive a license key. For security purposes the file may be delivered to you separately from the product, for example by an E-mail from a T-Plan sales representative. There are several options to install it:
  1. Save the key file to the T-Plan Robot Enterprise installation directory. As the tool checks the folder for any license key files on startup, it will be picked up right away. There might be any number of license files in the installation directory.
  2. Alternatively save the key file to a custom location on your hard drive and take advantage of the License Key Manager to register it. To open the Manager start T-Plan Robot Enterprise in the GUI mode (with no custom CLI arguments). If you have no valid license installed, the tool will display an error message window informing you of missing license key and it allows you to start the License Key Manager. If you already have a valid license installed, you may start the window through the Tools->License Key Manager menu item. The window will allow you to browse the file and add it to the list of registered license keys. Be aware that the list of such files (meaning keys outside of the installation directory) is saved to a list in the user preferences and it may get lost during migration unless you copy the user configuration file as well. Any change in license key configuration requires product restart.
License keys may be freely combined. It means that you may have any number of license keys installed at a moment regardless of whether the files are in the installation folder or outside of it. The number of connections will be then equal to the sum of licensed connections of all installed valid licenses. This system allows you to purchase additional licenses and plug them into the product easily when you need to scale up.


5. Upgrade And Migration

To upgrade T-Plan Robot Enterprise v2.0 or higher with a new release follow these steps:

Alternative 1: Automatic Upgrade (v2.3 and higher)

Automatic upgrade offers a comfortable and reliable way of promoting your product to a newer version through the GUI. Unlike manual upgrade the automatic process is secured against file corruption (CRC32), detects customized/modified product files and it is able to restore the original product in case of update failure. Steps:
  1. Select Tools->Update & Upgrade in the GUI. If Robot complains of insufficient write permissions, restart it with administrator privileges:
cd "C:\Program Files\T-Plan\Robot\robot"
robot
cd "C:\Program Files (x86)\T-Plan\Robot\robot"
robot
  1. Select the target release in the tree, hit Download & Install, leave the window with OK and restart the application. Details of the upgrade process are available in the Update & Upgrade help topic.

Alternative 2: Manual Upgrade (all versions)

  1. Download the desired standalone cross-platform ZIP release. You may get it from any of these resources:
  2. If you have modified or customized any of the product files (such as for example the start scripts of robot.sh or robot.bat), make a back up and restore them after the update process. You don't need to back up test scripts, template images or configuration files because they will not be affected.
  3. Unzip the ZIP archive to the installation folder and say yes to overwrite the files. The install folder is the directory which contains the robot.jar file:

Migration of T-Plan Robot Enterprise is fairly straightforward. Standalone ZIP releases may be simply copied and moved across the file system or even to another machine or machines with different operating systems. If you migrate to another machine, copy also  user specific configuration files to the user's home folder to keep any preference changes.

Migration of product installed by Windows Installer is possible only through reinstallation. You may however create a standalone cross-platform Robot instance by copying the product files from the installation folder to another location. Such a product may be then started through the robot.bat script or through a direct Java command as is described in the Startup chapter.

A Mac OS X release may be simply moved and/or copied as long as you copy the whole /Applications/TPlanRobot.app folder. You may also create a standalone cross-platform Robot instance by copying the product files from the /Applications/TPlanRobot.app/Contents/Resources/Java folder to another location. Such a product may be then started through the robot.sh script or through a direct Java command as is described in the Startup chapter.


Should you expect any unexpected start up or desktop connection errors after an upgrade or downgrade (migration to a lower version), perform the following steps to restore the factory settings:

T-Plan Robot Enterprise 2.3.5 preserves compatibility with VNCRobot 1.x and later in the following areas:
- Compatibility with the v1.x scripting language. It means that you will be able to migrate test scripts created with VNCRobot 1.x onto the 2.0 version without any modifications. Format of the outputs like screenshots and HTML reports may however change a bit.

T-Plan Robot Enterprise 2.3.5 introduces incompatibilities with VNCRobot 1.x in the following areas:
- Open API (http://www.t-plan.com/robot/docs/v1.3/api/index.html). As interfaces were radically redesigned, the methods and objects have changed. This impacts just a very few users who plugged in their own Java extensions. Some Java development efforts are needed to migrate such extensions onto 2.0. A migration guide may be provided on request.

- Configuration file. As some of the parameter names were updated, T-Plan Robot Enterprise may fail to read some of the preferences saved previously with VNCRobot. Should you experience any issues after migration, delete the config.properties and tplanrobot.cfg files from the user home folder.

- The command line interface (CLI) is compatible with the 1.x versions in terms of supporting the same set of CLI options. Names of the product JAR file and start scripts have however changed as a result of rebranding. If you integrated VNCRobot CLI calls into your test framework, you will have to update the starting commands or eventually rename these files to their old names (robot.jar to vncrobot.jar, robot.sh to vncrobot.sh, robot.bat to vncrobot.bat).
 
Upgrade from VNCRobot 1.3.3 and earlier runs additional compatibility risks documented in the VNCRobot 1.3 Install Instructions.

6. Uninstallation

If you installed T-Plan Robot Enterprise through the Windows installer, you may uninstall it through the Windows software manager (Control Panel->Add Or Remove Software on older Windows versions, Control Panel ->Programs And Features on Windows Vista).

To uninstall T-Plan Robot Enterprise installed from the ZIP file delete the files unzipped during installation. You may also delete the user configuration files. The tool doesn't create any other files or registry entries except automation outputs such as screenshots, template images and automated test reports.

7. Startup

If you installed T-Plan Robot Enterprise through the Windows installer, you may start the tool from the Windows Start menu (Start->Programs->T-Plan->T-Plan Robot). Should you need to start the program with custom CLI arguments, follow the instructions below.

To run the tool on any system from the command prompt change to the directory where you installed T-Plan Robot Enterprise and run one of the wrapper scripts robot.sh (for Unix/Linux) or robot.bat (for Windows). For help on CLI commands run robot.sh -h, resp. robot.bat --help. For a complete reference see the T-Plan Robot Enterprise 2.3.5 CLI Reference. If the tool fails to start, review the Troubleshooting chapter at the end of this document.

The wrapper scripts actually just start Java with proper options. Please note that the wrapper can't handle more than 9 parameters. If you need to pass more parameters or customize the T-Plan Robot Enterprise start command, use the following command syntax: Though it is also possible to run the JAR file directly either as "java -Xmx128m -jar robot.jar" or through double clicking of the robot.jar file on most systems, it is not recommended because it fails to populate class path of the Java compiler. The tool may refuse to compile or even run the Java source code (such as Java test scripts and Java code blocks embedded in regular scripts).

T-Plan Robot Enterprise can be run in two modes: Please see the CLI Options Specification document available in the T-Plan Robot Enterprise Help or online in the T-Plan Robot Enterprise 2.3.5 CLI Reference document on http://www.t-plan.com/robot/docs/v2.1ee/cli/clioptions.html.

Once the GUI is up and running, open Help for instructions on how to use T-Plan Robot Enterprise. There should be a complete documentation set included. All the documents/document collections are also available online on http://www.t-plan.com/robot/docs.

T-Plan Robot Enterprise can be also used for offline image comparison through a simple CLI interface. To explore this feature either run one of the wrapper scripts imgcompare.sh (for Unix/Linux) or imgcompare.bat (for Windows) or invoke Java directly as follows:

8. Integration With T-Plan Professional

T-Plan Robot Enterprise may be on Windows tightly integrated with T-Plan Professional 7.0 or later. It means that T-Plan Professional offers in its GUI actions starting T-Plan Robot Enterprise. This integration is based entirely on the public CLI parameters described in the Robot's CLI reference. Integration principles are well described in the Integration Reference.

There are two ways to configure how T-Plan Professional starts T-Plan Robot Enterprise:
  1. To configure T-Plan Robot Enterprise installation path navigate to the Installed Extensions module of T-Plan Professional as is described in the T-Plan Professional 7.0 Integration Overview chapter of the Integration Reference.
  2. Should you need to modify the T-Plan Robot Enterprise base start command (for example in order to use a custom Java environment or to raise the amount of heap memory allocated by JVM), perform the following steps:
    1. Locate Robot's extension configuration file RobotExtn.ini. The file gets created when T-Plan Robot Enterprise is called for the first time from T-Plan Professional GUI. It is saved to the application data folder whose location depends on the Windows version and configuration. Typical paths are:
    2. Edit the file. It contains a bunch of command templates where each one corresponds to a specific action invoked from T-Plan Professional GUI, such as:
      Run=java -Xmx256m -cp "%1\robot.jar;%1\jh.jar;%1\activation.jar;%1\mail.jar;%1\poi-3.6-20091214.jar" com.tplan.robot.ApplicationSupport
    3. Adjust the commands to your needs. The %1 variable in the example above will be replaced with the product install path specified in the previous paragraph. Each command may contain additional variables which are populated with CLI option values by T-Plan Professional.
    4. Save the file and restart T-Plan Professional to pick up the changes.

9. Optimizing Performance

As T-Plan Robot Enterprise can be employed in various automated testing scenarios and environments, its performance may be significantly improved through fine tuning based on specific requirements.

Memory Adjustments

As T-Plan Robot Enterprise employs memory intensive image processing, the Java Virtual Machine (JVM) may occasionally run out of memory, especially on larger deployments which execute multiple automated processes (threads) on a single machine and/or inside one Robot instance. This is usually experienced as a crash of Java with the java.lang.OutOfMemoryError exception stack trace seen in the console window (command prompt on Windows). To raise the amount of memory assigned to your JVM perform the following steps:

  1. Locate the Robot's java start command based on your start up preference:
  1. The -Xmx128m parameter after the java  (or javaw) command indicates how much memory is your Java Virtual Machine allowed to use at a maximum. In this example it is 128 MB. Raise this number to a higher value. For example -Xmx512m allows the JVM heap grow up to 512MB if needed. This limit doesn't mean that the memory is allocated immediately.
Though Java is likely to accept any number up to the size of your RAM, it is typically not able to allocate more than about 1GB of memory on 32-bit systems. This is caused by two factors. First of all Java requires contiguous (uninterrupted) chunk of memory. Second, most 32-bit systems are not able to address directly more than 2GB of RAM. As the OS consumes a significant amount of memory on its own, the largest contiguous space that Java is typically able to allocate on such environment is about 1GB. For Deployments requiring larger memory are recommended to be hosted on 64-bit systems (where both the OS and Java are 64-bit) with sufficient amount of physical RAM.

Client Side Configuration

T-Plan Robot Enterprise supports a large number of configurable parameters which may improve performance of both the Robot application as well as the VNC connection. The following table lists the most important ones.

Parameter Name (Location)
Description
Encodings
(GUI:Preferences->RFB (VNC) 3.x Client)
Encodings specify how the image data transferred between Robot and VNC server are encoded. They are represented by an ordered list where the first (topmost) item has the highest priority. Each encoding uses a different algorithm of encoding the image data to trade off between the volume of data transferred over the network (better compression = less data) and the local CPU resources needed to decode the data.
  • If your VNC server is in a remote location or the network is slow and your local CPU is reasonably fast, move one of the encodings with high compression such as Tight, Zlib or Hextile to the first place.
  • If your local CPU is slow and the network is fast, try Hextile, RRE or CoRRE which have low compression but are cheap to decode.
  • Do not prefer the Raw encoding which is the least efficient one because it transfers pixels in raw form with no compression. Keep it however somewhere low in the list because some simple servers (such as mobile device or embedded system ones) support just this one and require it to be present in the list.
  • Keep the Cursor encoding in the list (in any place) unless you experience problems (some servers don't like it and tend to crash when it is present). It makes the client (Robot) render the cursor locally rather then encoding it into the desktop image which leads to significant desktop performance improvements on slow network environments.
To observer efficiency of encodings set the "Console debug logging" parameter in the same panel to "Full" and check the console window (command prompt) for performance data.
Update driven comparison
(GUI:Preferences->WaitFor Command)
Update driven comparison mode is a new optional behavior of image comparison performed through the WaitFor match/mismatch command or the corresponding Java method. It schedules comparison based on the image updates rather than at scheduled time intervals. Setting it on may make your scripts execute faster because it avoids the idle time caused by interval scheduling. This mode is however also more CPU and memory intensive.
Script editor behavior (GUI: Preferences->Execution)
The script editor in Robot's GUI is by default configured to compile any script changes after a preset amount of idle time. This may lead to slower GUI performance, especially where long scripts are being edited and/or there are multiple open editors and/or one or more scripts are Java source code or call Java source code through the technology of Java code blocks. Consider setting off the auto compilation and compile manually only when needed through the editor context menu or Script->Compile in the main application menu.
Connection pooling (Java API)
Connection pooling allows to reuse server connections which avoids the overhad of reconnection. This mechanism can be applied just from the Java API. See the RemoteDesktopClientFactory class documentation for details.


Server Side Configuration

There are several simple recommendations which may significantly improve performance of the client-server connection:

10. Troubleshooting

This chapter is intended to document the most common install and set up errors. If you meet an issue which is not described in here, report it through the Enterprise contacts at http://t-plan.com/robot/docs/contacts.html.

T-Plan Robot Enterprise fails to start with a message "java: command not found"

There's no Java installed on your machine or path to the Java executable is not included in your OS path. Read chapter 1. Client System Requirements of this document.

T-Plan Robot Enterprise fails to start with a message "Exception in thread "main" java.lang.NoClassDefFoundError: com/tplan/robot/ApplicationSupport"

This indicates that the T-Plan Robot Enterprise JAR (Java ARchive) file robot.jar is not correctly included in the Java class path.

T-Plan Robot Enterprise starts but prints out a message "JavaHelp libraries not found. Please make sure that file jh.jar is included in the Java class path."

This indicates that the JavaHelp JAR file jh.jar is not correctly included in the Java class path. The tool will run but you will not have access to the online help. Some links which open in a web browser may however work fine. As all the help documents are available online at http://www.t-plan.com/robot/docs, you may switch to the online documentation and ignore this error. To resolve it:

T-Plan Robot Enterprise fails to start with a NoClassDefNotFoundError, NoSuchFieldError or any other severe Java error

Unless one of the cases listed above applies, these problems are typically experienced when you use Java of version lower than the required one. See the 1. Client System Requirements chapter for required Java version and run java -version to find out which version you have installed.

Either the robot.sh or robot.bat script fails to pass some CLI options

The wrapper script can't handle more than 9 options. All options above this limit are ignored. You must run Java directly as is described in chapter 6. Startup.

T-Plan Robot Enterprise crashes with java.lang.OutOfMemoryError

Raise the memory limit as is described in Memory Adjustments above.