VNCRobot 1.3 Install Notes
(C) 2007 Robert Pes. All rights reserved. Last update: October
14,
2007
Table of contents:
- System Requirements
- Prerequisities and Dependencies
- Installation
- Uninstallation
- Upgrade And Compatibility
- Startup
- Windows Notes
- 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:
- Java Runtime Environment (JRE) or Java Development Kit (JDK, also
J2SE) - required
- 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:
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:
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:
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:
- 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:
- 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.
- 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.
- 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.
- 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:
Linux/Unix: |
java -jar vncrobot.jar <VNCRobot
CLI parameters>
or
java -classpath jh.jar:vncrobot.jar com.vncrobot.VNCRobot <VNCRobot
CLI parameters>
|
Windows: |
java -jar vncrobot.jar <VNCRobot
CLI parameters>
or
java -classpath jh.jar;vncrobot.jar
com.vncrobot.VNCRobot <VNCRobot CLI parameters> |
VNCRobot can be run in two modes:
- GUI Mode - Displays the graphical interface in your window
system (MS Windows, X-Windows). This is the default mode when you start
VNCRobot without any CLI options.
- CLI Mode - No GUI is displayed. VNCRobot starts in this
mode only when invoked with the
-n
or --nodisplay
option. Use this way for automated execution of test scripts. Other
parameters like -c/--connect
and -r/--run
must
be supplied. Please see the CLI Options Specification document
available
in the VNCRobot Help or online in the VNCRobot 1.3 GUI Reference
document on http://www.vncrobot.com/docs.
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:
- This VNCRobot 1.3 Install Notes document,
- VNCRobot 1.3 GUI Reference (description of GUI components and
features),
- VNCRobot 1.3 Language Reference (specification of the VNCRobot
scripting language).
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.
- Switch to the directory where you unzipped VNCRobot and make
sure that the
vncrobot.jar
file is there and that you
have
permission to read it.
- Re-run the
vncrobot.sh
or vncrobot.bat
from this directory.
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.
- Switch to the directory where you unzipped VNCRobot and make
sure that the
jh.jar
file is there and that you have
permission to read it.
- Re-run the
vncrobot.sh
or vncrobot.bat
from this directory.
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:
- Edit
vncrobot.sh
or vncrobot.bat
The -Xmx128m
parameter indicates how
much memory is your Java Virtual Machine allowed to use. Raise this
number to a higher value, e.g. -Xmx256m
which allocates
256MB of your RAM for JVM heap.