T-Plan Home
 T-Plan Robot Enterprise 2.2.1 Doc Collection
 23/11/10

T-Plan Robot Enterprise 2.2.1 Release Notes

Build No.  2.2.1-20101123.1


Contents
1. Client System Requirements
2. Server System Requirements
2.1 VNC Server
2.2 Static Image Testing
3. Installation
4. License Key
5. Migration And Upgrade
6. Uninstallation
7. Startup
8. Integration With T-Plan Professional
9. Troubleshooting

1. Client System Requirements

T-Plan Robot Enterprise has been designed to run in a client-server scenario where the client machine executes T-Plan Robot Enterprise 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 Enterprise 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 Enterprise 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.

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 Enterprise. 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 Troubleshooting chapter.

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 Enterprise 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 Enterprise 2.2.1 by default supports RFB protocol version 3.3 (better known as VNC). The Enterprise version also static image. 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 Enterprise should work fine with any VNC server which is RFB 3.3 compatible.

Summary of tested servers by the target platform:

Desktop PC Platforms
Portable Devices

NOTE: For mappings of the phone keyboard onto standard PC keyboard events see documentation of the particular server you are using.
 The following matrix describes the 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 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.
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 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.
mVNC
 Symbian OS mobile devices
 Reported to work by users.
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) phone. There's no alternative because the iOS API does not contain interfaces providing access to the necessary features.

Should you experience freezing display image navigate to Edit->Preferences in Robot's GUI, select the "RFB (VNC) v3.3 Client" panel and move the Raw encoding to the top of the list. On newer Robot versions also remove the Cursor encoding from the list (move it to Available).
Android VNC Server
 Android
 Tested by us for basic functionality. There seems to be a "Droid VNC Server" application based on this project available through the Android Market; this one can be run without Android SDK directly from the device but it requires a rooted phone.

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 instead.
  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 screen of your Android. 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 may have to run it with root privileges (sudo):
adb kill-server
adb start-server
adb devices

The last command should display a list containing your connected device.
  1. Copy the androidvncserver binary to your Android, change it to executable and start it:
    1. Installation on a rooted device:
adb push fastdroid-vnc /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 fo a folder which has the set of permissions like "drwxrwxrwt", for example:

drwxrwxrwt root     root              2010-11-22 12:53 app-cache

Use this location for installation instead of /data. Note that as most such folders are temporary, you may have to reinstall the server after every restart of the Android device.
adb push fastdroid-vnc /app-cache/
adb shell chmod 755 /app-cache/androidvncserver
adb shell /app-cache/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:

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. 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 the server must be started as follows:

adb shell <dir>/androidvncserver -t /dev/input/event1 -k /dev/input/event4
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 its tips described above apply to Fastdroid as well. 

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.2.1 is delivered in two forms:
  1. T-Plan Robot Enterprise Windows installer. Installation through this way will allow you to manage the software as a standard Windows program. The installer installs the tool into the C:\Program Files\T-Plan\Robot directory by default.
  2. 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. 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
 Apache POI 3.6 library, distributed under Apache License v2.0
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.2.1 Release Notes document.
LICENSE.txt License text. Please read carefully before you start using T-Plan Robot Enterprise.

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. Migration And Upgrade

T-Plan Robot Enterprise delivered in form of a ZIP file is a standalone distribution and it may be easily copied and moved across the file system and even multiple machines with different operating systems. 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.

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 installation to the factory settings:
T-Plan Robot Enterprise 2.2.1 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.2.1 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.2.1 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.2.1 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. 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 7.0 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. 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/v2.1ee/index.html, 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

T-Plan Robot Enterprise 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: