T-Plan Robot Enterprise 3.0Beta Release Notes
Build No. 3.0Beta-20120328.1
Contents
1. Client System Requirements
2. Server System Requirements
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 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:
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):
- Create a new Java test script through the File->New Test Script->Java Test
Script in the T-Plan Robot Enterprise GUI.
- Right click the editor and select Compile.
- 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.
- 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.
- 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:
- Start Windows Explorer, right click the Computer node and select Properties in the context menu.
- Navigate to the Advanced
tab or item (depends on Windows version) and select Environment Variables.
- 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;").
- Save the variable and close all windows with OK.
- 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.
- 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 3.0Beta 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:
- Start System Preferences
from the system main menu (Apple icon)
- Open Sharing in
the Internet & Wireless
section
- Tick the Screen Sharing
check box in the list
- 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
- Confirm with OK
(authorization may be required)
- 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:
- Go to Edit->Preferences
in T-Plan Robot Enterprise GUI and locate the "RFB
(VNC)
Client" panel.
- Move the Hextile and Raw encodings to be first and second
in
the list.
- 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:
- Go to Edit->Preferences
in T-Plan Robot Enterprise GUI and locate the "RFB
(VNC)
Client" panel.
- 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.
- Download Android SDK to
your PC. It's just a zip package which you extract somewhere.
- 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.
- Download the server
binary onto your PC and place it to the
<AndroidSDK>/tools
folder.
- 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.
- 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).
- Copy the
androidvncserver binary to your
Android,
change it to executable and start it:
- Installation on a rooted
device:
adb push androidvncserver /data/
adb shell chmod 755 /data/androidvncserver
adb shell /data/androidvncserver
- 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
- 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:
- Download and install VirtualBox
- Create a virtual machine and install the guest OS in there
- Download and install one of the VNC servers on the target machine
- 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 3.0Beta is delivered in three forms:
- 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.
- 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.
- 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.
|
javaparser.jar
|
Java Parser 1.0.8 library
distributed under GNU
Lesser GPL (LGPL).
To upgrade the library simply replace the file and either put it on the
class path or keep the same name
to allow T-Plan Robot Enterprise to load it dynamically.
|
JTattoo.jar
|
JTattoo Look And Feel (JTattoo
binary license).
|
| 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 3.0Beta 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:
- Expiration
date. The program is by default licensed for one year (annual
license) or on a perpetual basis. Trial
licenses are available on request from the T-Plan Sales.
- Number
of licensed connections. The product is licensed on a "per
active
desktop connection" basis. It means that one license (one "seat" in
usual license terms) equals to one connection to a desktop (a single
VNC server or any other supported technology) at a time. In the
automation design phase this roughly equals to
one traditionally understood seat licensing because there's an engineer
who
typically uses the program to write or debug an automated test script
against one desktop. The tool however allows to run in the execution
phase one or more test scripts on multiple desktops in parallel and
number of such connections is subject to the license terms.
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:
- 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.
- 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:
- Select Tools->Update
&
Upgrade in the GUI. If Robot complains of insufficient write
permissions, restart it with administrator privileges:
- Windows:
- Alternative 1: Log in as
Administrator and restart Robot.
- Alternative 2: If you
are logged on as user who has admin privileges, right click on Accessories->Command Prompt in
the Windows menu and select Run As
Administrator. Then switch to the install folder in the command
line and run Robot:
cd "C:\Program
Files\T-Plan\Robot\robot"
robot
cd "C:\Program
Files (x86)\T-Plan\Robot\robot"
robot
- Linux,
Unix,
Mac
OS: Log in as root or run Robot with sudo (
"sudo
robot.sh")
- 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)
- Download the desired standalone
cross-platform
ZIP release. You may get it from any of these resources:
- 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.
- 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:
- If you have installed the product
using the Windows Installer
(.exe release), unzip the archive to
C:\Program
Files\T-Plan\Robot (or to the custom directory you selected at
the install time).
- If you have installed the Mac OS X release (.dmg), unzip the
archive to
/Applications/TPlanRobot.app/Contents/Resources/Java
- If you are using the standalone cross-platform ZIP release,
unzip
the
archive
to
the
folder
where
you
unzipped
the
previous
one.
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:
- Rename or delete the configuration files
<home>/tplanrobot.cfg
and the legacy VNCRobot's one <home>/config.properties.
This
step
resolves
eventual
incompatibility
of
user
preference
parameters.
- Rename or delete the plugin map
file
<home>/PluginMap.xml. This step
resolves eventual downgrade errors caused by missing plugin classes.
T-Plan Robot Enterprise 3.0Beta 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 3.0Beta 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).
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
3.0Beta 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:
| Linux/Unix: |
java
-Xmx128m
-classpath
jh.jar:activation.jar:mail.jar:poi-3.6-20091214.jar:robot.jar
com.tplan.robot.ApplicationSupport
<T-Plan Robot Enterprise
CLI
parameters> |
| Windows: |
java
-Xmx128m
-classpath
jh.jar;activation.jar;mail.jar;poi-3.6-20091214.jar;robot.jar
com.tplan.robot.ApplicationSupport <T-Plan Robot Enterprise CLI
parameters> |
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:
- GUI Mode - Displays the graphical interface in your window
system (MS Windows, X-Windows). This is the default mode when you start
T-Plan Robot Enterprise without any CLI options.
- CLI Mode - No GUI is displayed. T-Plan Robot Enterprise 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 -r/--run
must
be supplied.
Please see the CLI Options Specification document
available
in the T-Plan Robot Enterprise Help or online in the T-Plan Robot Enterprise 3.0Beta
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:
| Linux/Unix: |
java -classpath robot.jar;poi-3.6-20091214.jar
com.tplan.robot.ImageComparison <Image comparison
CLI parameters>
|
| Windows: |
java -classpath robot.jar;poi-3.6-20091214.jar
com.tplan.robot.ImageComparison <Image
comparison
CLI
parameters> |
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:
- 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.
- 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:
- 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:
- Windows XP:
C:\Documents
and
Settings\<user>\Local
Settings\Application
Data\T-Plan\Extensions\RobotExtn\RobotExtn.ini
- Windows Vista:
C:\Users\<user>\AppData\Local\T-Plan\Extensions\RobotExtn\RobotExtn.ini
- 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
- 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.
- 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:
- Locate the Robot's
java start command based on your
start up
preference:
- If you call Java directly as is described in the Startup chapter, modify the command
you use.
- If you take advantage of the
robot.sh, or robot.bat
scripts to start Robot, edit the script and modify
the startup java command in there.
- If you start Robot
from the Windows Start menu, update the command associated with the
menu item.
- If you start Robot from T-Plan Professional, refer to the
Integration With T-Plan Professional
chapter for the
information on where to find the Windows INI file with Robot's start
commands.
- If you double click the robot.jar file to start Robot, start
using the scripts instead. Starting of the JAR file makes the OS run
the program associated with the particular file extension, in this case
the "java" or "javaw" binary. As no custom options are applied in this
case, Java
starts with the default heap size of 128MB.
- 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:
- Change the server desktop background to a solid color which can
be efficiently compressed through encodings. Pictures or photographs
significantly increase volume of image data transferred over the
network.
- Remove all unnecessary dynamically updating objects from the
desktop, such as clocks or gadgets showing pictures in a loop. These
components are sources of frequent desktop updates and increase network
traffic.
- Try servers from different producers if available. Some products
come with custom video drivers or hook ups to boost performance.
- Use an appropriate remote desktop size (resolution). The volume
of image data is linear to the desktop size.
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.
- Switch to the T-Plan Robot Enterprise installation directory and make
sure that the
robot.jar file is there and that you
have
permission to read it.
- Re-run the
robot.sh or robot.bat
from this directory. Alternatively modify the java
command to include this library in the -classpath
argument.
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:
- Switch to the T-Plan Robot Enterprise installation directory and make
sure that the
jh.jar file is there and that you have
permission to read it.
- Re-run the
robot.sh or robot.bat
from this directory. Alternatively modify the java
command to include this library in the -classpath
argument.
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
