VNCRobot 1.3 Install Notes

(C) 2007 Robert Pes. All rights reserved. Last update: October 14, 2007


Table of contents:
  1. System Requirements
  2. Prerequisities and Dependencies
  3. Installation
  4. Uninstallation
  5. Upgrade And Compatibility
  6. Startup
  7. Windows Notes
  8. Troubleshooting

1. System Requirements

VNCRobot is a Java application and runs on all platforms supported by Java 1.5.0_12 or higher. Lists of supported system configurations are maintained at http://java.sun.com:
As Java is known for high memory consumption, 128 MB RAM or higher is recommended to execute VNCRobot 1.3.

2. Prerequisities and Dependencies

VNCRobot depends on two software packages:
  1. Java Runtime Environment (JRE) or Java Development Kit (JDK, also J2SE) - required
  2. VNC Server - optional
Java Runtime Environment
VNCRobot requires Java Runtime Environment (JRE) version 1.5.0_12 or higher. To verify whether Java is installed on your machine, open a terminal window (Unix/Linux) or a comand line window (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 your /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 JRE for free from the following location:

http://java.sun.com/javase/downloads/index_jdk5.jsp


VNC Server
You also need to install a VNC server. If someone else is providing a server for you, you may skip this step. If you use Unix or Linux, you may run a VNC server on the same machine as VNCRobot. As most Windows systems are not capable of running multiple window servers, you can't run a server and a client (i.e. VNCRobot) on the same machine. See the Windows Notes chapter for a list of Windows limitations.

You may download the VNC server software for free from one of the following locations:

Tight VNC - http://www.tightvnc.com (recommended and tested)
Real VNC - http://www.vnc.com/

Most Linux distributions already contain VNC server or allow to install it through their package managers. To find out whether the software is installed on your machine try to run vncserver in a terminal.

3. Installation

VNCRobot binaries are distributed as a 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. There should be at least the following files:

File Name
Description
vncrobot.jar Java archive with VNCRobot classes.
jh.jar JavaHelp Java archive.
vncrobot.sh Start script for Unix/Linux.
vncrobot.bat Start script for Windows.
install.html A copy of this VNCRobot 1.3 Install Notes document.
LICENSE.txt Freeware license text. Please read carefully before you start using VNCRobot.

4. Uninstallation

To uninstall VNCRobot delete the files unzipped during installation. You may also delete the configuration file config.properties in your home folder. The tool doesn't create any other files or registry entries.

5. Upgrade And Compatibility

If you are already using an older version of VNCRobot, simply overwrite the old installation with the new build. Only the files listed in the table above will be replaced. Your test scripts and configuration file config.properties located in your home directory will not be affected.

There is one update which may cause incompatibility with scripts created by VNCRobot 1.3.3 and earlier:
  1. Bug fix 13022. As 1.3.4 introduced support of the nested variables, it was necessary to modify the algorithm which replaces variables in the script text. There is a flag in the Preferences->Scripting window which allows to switch back to compatibility mode. It is by default off.
There are three updates which can cause incompatibility with scripts created by VNCRobot 1.2 and earlier:
  1. Bug fix 12034. Variable instances ('{<var_name>}') were originally processed using regular expressions. This was sometimes causing problems with regexp control characters contained in the variable values. VNCRobot v1.3 performs plain text processing instead.
  2. The new concept of local variables may cause that some variables will be considered local and will not be visible in your old scripts. Read the VNCRobot 1.3 Language Reference on http://www.vncrobot.com/docs for more info.
  3. The VNCRobot 1.3 Open API was updated and the ImageComparisonModule is not compatible with VNCRobot 1.2. Users who implemented their own image comparison algorithms will need to do minor adjustments in order to use the module in v1.3.
  4. The VNCRobot 1.3 Open API was also updated in VNCRobot 1.3.6 and is incompatible with lower 1.3.x versions. The difference is that there's a new argument passRate in methods compare() and compareToBaseImage(). The reason for this change was to allow the built-in "search" image comparison module to handle custom pass rates and be able to search non-exact matches of template images. See also bug 13035.
There are two flags in the Preferences->Scripting window which allow to switch back to compatibility mode. They are by default off.

6. Startup

Change to the directory where you installed VNCRobot and run one of the wrapper scripts vncrobot.sh (for Unix/Linux) or vncrobot.bat (for Windows). For help on CLI commands run vncrobot.sh -h, resp. vncrobot.bat --help. If VNCRobot doesn't start, review the Troubleshooting chapter at the end of this document. If you meet an issue which is not described in this document, review open bugs at http://vncrobot.com/docs/bugs.html or eventually report a new bug using the contacts at http://vncrobot.com/docs/contacts.html.

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 VNCRobot start command, use the following command syntax: VNCRobot can be run in two modes: Once the GUI is up and running, open Help for instructions on how to use VNCRobot. There should be at least three document collections there: All these documents/document collections are also available online on http://www.vncrobot.com/docs.

7. Windows Notes

Note that most Windows systems are not capable of running multiple window servers (desktops). The impact is that you can't run a server and a client (i.e. VNCRobot) on the same machine. To use this tool on Windows you need at least two machines, one with a VNC server and another one which will run VNCRobot. It should be theoretically possible to run VNCRobot in CLI mode on a Windows VNC server; this configuration has however never been tested.

It is recommended that you run VNC server on Windows as a service. This will allow you to restart Windows from VNCRobot 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 VNCRobot GUI.

If you connect VNCRobot 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.

Note that Windows specific keys like 'Windows' and 'Properties' are not supported in this version and they cannot be used in the scripts.

8. Troubleshooting

1. vncrobot.sh or vncrobot.bat script fails with a message "java: command not found"

There's no Java installed on your machine or the path to the Java executable is not included in your OS path. Read chapter 2. Prerequisities and Dependencies of this document.

2. vncrobot.sh or vncrobot.bat script fails with a message "Exception in thread "main" java.lang.NoClassDefFoundError: com/vncrobot/VNCRobot"

This indicates that the VNCRobot JAR (Java ARchive) file vncrobot.jar is not correctly included in the Java class path.


3. vncrobot.sh or vncrobot.bat script fails with 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.

4. vncrobot.sh or vncrobot.bat script fails with a NoClassDefNotFoundError, NoSuchFieldError or any other severe Java error

These problems are typically met when you use Java of version lower than required 1.5.0_12. Run java -version to find out.

5. The vncrobot.sh or vncrobot.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 5. Startup.

6. VNCRobot crashes with OutOfMemoryError

VNCRobot 1.3 introduces many features which are based on image processing. This has unfortunately impact on memory requirements. To raise the amount of memory assigned to your JVM perform the following steps: