T-Plan Home
T-Plan Robot 2.0.6 Doc Collection
18/04/11

T-Plan Robot 2.0.6 Release Notes

Build No.  2.0.6-20110418.1


Contents
  1. Client System Requirements
  2. Server System Requirements
    1. VNC Server
    2. Java Client
  3. Installation
  4. Migration And Upgrade
  5. Uninstallation
  6. Startup
  7. Troubleshooting

1. Client System Requirements

T-Plan Robot has been designed to run in a client-server scenario where the client machine executes T-Plan Robot and automates the server (System Under Test, SUT) through one of the supported remote desktop technologies (such as RFB/VNC), usually (but not necessarily) over TCP/IP. As the client and server may be two fundamentally different platforms, we list the client system (discussed in this chapter) and server system requirements (the following chapter) separately. In some scenarios one machine may act as a client and server at the same time, for example local VNC server on Unix/Linux or the Java client accessing the local display. In such a case the platform has to comply with both the client and server requirement sets.

As T-Plan Robot is a Java application, the client system may be any platform supported by Java 1.6 (Java 6) or higher. Though there are more Java producers, this software 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:
Java is being shipped in two distributions, 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 runs with both but certain functionality requires JDK, such as development and on-the-fly execution of Java test scripts. 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 Sun Microsystems together with the JDK in one software bundle. Both components are open source and free. We provide detailed steps of how to set up the project with NetBeans 6.5 in the Build Instructions document.

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, it displays its version. On Unix/Linux systems also check if the /usr directory contains a folder like 'java' or 'jdk' and look for the java executable in there. If Java is not present, you may download JDK for free from the following location:
As Java is known for high memory consumption, 128 MB RAM or higher is recommended to execute T-Plan Robot. 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.

If you install JDK on MS Windows, you will have to perform additional configuration steps to make sure that Windows will use the JDK binaries instead of the JRE ones:
  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.
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. A back up option which works on all systems is to replace "java" in the T-Plan Robot start command with absolute path to the JDK's "java" binary.

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 2.0.6 by default supports RFB protocol version 3.3 (better known as VNC). The Enterprise version also provides Java native client. 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.

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 should work fine with any VNC server which is RFB 3.3 compatible.

The following matrix lists servers that either we have tested or our users reported them to work fine. Should you want to contribute to the list, contact us through the T-Plan Robot Contacts web page.

VNC Server
Platforms
Status/Notes
Tight VNC
all supported by server
Tested by us on Linux & Windows; reference development server. 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.
Real VNC
all supported by server
Marginally tested by us; reported to work by a number of users.
UltraVNC
all supported by server Marginally tested by us; reported to work by users.
Pocket VNC
Windows mobile phones, such as HTC
Tested by us. PocketVNC v1.4.3 contains a bug which breaks the desktop image transfer. There's a workaround:

  1. Go to Preferences in T-Plan Robot 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 connectable from T-Plan Robot. 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.
 
NOTE: Pocket VNC in combination with T-Plan Robot is one of the very few real black box GUI automation solutions for Windows mobile OS and application testing.
mVNC
Symbian OS mobile devices
Reported to work by users.
Apple Remote Desktop (ARD; Mac OS feature)
10.4 PPC Mac
10.5 Intel Mac
Reported to work. Bug fixes delivered in VNCRobot 1.3.15 to address issues with 10.4 PPC compatibility.

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. If you plan on using clipboard changes to transfer text from server to client, get a VNC server which has it, such as UltraVNC. Read further on for other alternatives.

VNC Servers On Linux/Unix
On Unix or Linux you may run a VNC server on the same machine as T-Plan Robot. 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) 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 (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 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 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 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. From the three servers we tested these keys work fine on RealVNC and UltraVNC and fail on TightVNC 1.3.10. As this is a problem on the server side, don't file a bug against T-Plan Robot.

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 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 Java Client

Java client is a feature delivered with T-Plan Robot 2.0.6 Enterprise Edition. It allows to access the local desktop image, mouse and keyboard on the OS level. As the connection to the desktop takes place through the OS native drivers inside the Java VM instance, the server requirements are the same as the client ones (just Java is required).

The client is also able to connect to remote desktops through the Remote Method Invocation (RMI) protocol. The SUT is required to have a compatible Java installed and it must run the RMI registry (part of JDK) as specified in the Java client specification. There are no other requirements on the server save for Java.

As the Java client emulates key strokes on the local keyboard, it may only automate keys supported by the local keyboard layout. It means that if your client computer is using a Russian keyboard, you may automate pressing and typing of Russian characters but not for example Spanish ones.
 

3. Installation

T-Plan Robot binaries are distributed as a self contained platform independent ZIP archive which contains all necessary files. There's no installer. 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 classes.
robot-src.zip
Java source code.
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.
robot.sh T-Plan Robot start script for Unix/Linux. See the 6. Startup chapter for more information.
robot.bat T-Plan Robot 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 2.0.6 Release Notes document.
LICENSE.txt License text. Please read carefully before you start using T-Plan Robot.

One machine can host multiple T-Plan Robot 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. Migration And Upgrade

As T-Plan Robot is delivered in form of a ZIP file of standalone binaries, it may be easily copied and moved accross the file system and even multiple machines. As the tool saves just a few user specific configuration files to the user's home folder, it is safe to overwrite the install folder (meaning unzip the build there to replace the binaries) with a new version without running a risk of purging your configuration. If you need to migrate to another machine and you want to preserve your preferences and installed plugins, copy these config files together with any plugin binaries you installed.

T-Plan Robot 2.0.6 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 2.0.6 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 may fail to read some of the preferences saved previously with VNCRobot.

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

5. Uninstallation

To uninstall T-Plan Robot 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.

6. Startup

Change to the directory where you installed T-Plan Robot 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 2.0.6 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 start command, use the following command syntax: T-Plan Robot can be run in two modes: Please see the CLI Options Specification document available in the T-Plan Robot Help or online in the T-Plan Robot 2.0.6 CLI Reference document on http://www.t-plan.com/robot/docs/v2.0/cli/clioptions.html.

Once the GUI is up and running, open Help for instructions on how to use T-Plan Robot. 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 can be also used for offline image comparison through a simple CLI interface described at http://www.t-plan.com/robot/docs/v2.0/cli/clioptions.html#comparison. 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:

7. 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, review open bugs at http://vncrobot.com/docs/bugs.html and eventually report a new bug using the contacts at http://vncrobot.com/docs/contacts.html.

T-Plan Robot 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 fails to start with a message "Exception in thread "main" java.lang.NoClassDefFoundError: com/tplan/robot/ApplicationSupport"

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

T-Plan Robot 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/v2.0/index.html, you may switch to the online documentation and ignore this error. To resolve it:

T-Plan Robot 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 crashes with java.lang.OutOfMemoryError

T-Plan Robot provides many features which are based on image processing. This has unfortunately impact on memory requirements and the Java Virtual Machine (JVM) may occasionally run out of memory. To raise the amount of memory assigned to your JVM perform the following steps: