T-Plan Robot Enterprise 3.3 Release Notes
Build No. 3.3-20130108.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)
3. Tesseract OCR (optional) if text recognition on the SUT screen is
required (details).
|
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
the 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 connection type (protocol)
selected for the System Under Test (SUT) control. T-Plan Robot Enterprise
3.3 by default supports these connections:
Connection
Type
|
Description
|
VNC Server
|
Testing over the RFB (VNC) 3.3, 3.7 or 3.8 protocol.
|
Static Image
|
Testing of image files.
|
Android
Over
ADB
|
Testing of Android devices
connected through the USB cable over the Android Debug Bridge (ADB)
tool.
|
Local
Desktop
|
Testing of applications and
system components displayed on the local desktop. |
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 suitable 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. |
Remote Desktop
(Ubuntu feature compatible
with VNC)
|
Ubuntu Linux
|
Tested by
us. To enable the access:
- Select System->Preferences->Remote
Desktop in the OS menu
- Set on the "Allow other
users to view your desktop" and "Allow
other
users
to
control
your
desktop"
check boxes
- Set off the "You must
confirm each access to this machine" check box
- As the
desktop server runs on the default VNC port of 5900, to connect from
Robot use either the IP alone (such as "192.168.100.10")
or
the
IP
with
the
port
number
("192.168.100.10:5900").
|
Apple
Remote
Desktop
(ARD; Mac OS feature
compatible with VNC)
|
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 from
Robot use either the IP alone (such as "192.168.100.10")
or
the
IP
with
the
port
number
("192.168.100.10:5900").
|
Canon
Remote
Operator’s
Software
Kit |
|
Reported to
work by users. Requires T-Plan Robot Enterprise version 3.1.1 or higher to display
the desktop in correct colors.
|
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 Windows
Mobile
Network article 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 the 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).
|
VMLite
VNC
Server |
Android |
The VMLite VNC Server is a commercial
software available for a small fee from the Google Play store. It can
run both on on rooted and unrooted
devices. The only difference is that while the server can be started
directly on the rooted device, on an unrooted one it must be done
through the Android Debug Bridge (ADB) over the USB cable. The ADB tool
is available for free as part of the Android SDK.
|
Droid VNC
Server
|
Android
|
The Droid
VNC
Server is a free VNC server for the Android
platform. It however requires a rooted
phone. For automation of devices which are not rooted see the Android Over ADB alternative.
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 from
the PC through the Android SDK's "adb install xxx.apk" or through the
Astro
File Manager on the Android device itself. |
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
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 introduced the 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.
As there's a mechanism making the client to reload the image when the
file gets updated, this connection type may be also used to test
applications generating
graphical output to an image in the file system. The connect URL is of
the
standard form of "file://<image_path>"
with a special handling of relative paths and images bundled
inside a ZIP or JAR file. For details see the ImageClient
class documentation.
2.3 Android Over ADB
Version 3.1 introduced the Android
Over ADB connection type which
enables to automate Android devices over the Android Debug Bridge (ADB). This way
is non-intrusive and it doesn't require any software installation on
the device (only a configuration change). For details see the documentation.
2.4 Local Desktop
Version 3.2 introduced the Local
Desktop connection type which
allows to automate applications displayed on the local desktop (the one
that runs Robot). For details see the documentation.
2.5 iOS Mirror
The iOS Mirror connection type
was introduced in 3.3. It allows
to automate iOS devices (iPhone, iPad) using a combination of AirPlay
screen mirroring and VNC server. Compared to a plain VNC connection,
this solution has much faster screen performance and it supports OpenGL
content, for example games and graphical programs. For
details see the documentation.
3. Installation
T-Plan Robot Enterprise 3.3 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). Used to display Online Help
(OLH) window in the GUI. Though this library is required to
compile the code, it is not needed to run an already compiled
product because the OLH functionality falls back to the web browser
when the
library is not found.
|
activation.jar
|
JavaBeans(TM) Activation
Framework (JAF) v1.1.1 library, distributed by Sun Microsystems Inc.
under BCL. Required by the JavaMail
library. Not used directly by the product. |
mail.jar
|
JavaMail(TM) v1.4.1 library,
distributed by Sun Microsystems Inc. under BCL. It provides E-mail
infrastructure
for the SendMail
command/Java API method call. |
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. The library provides connectivity to MS
Excel files through the Excel
command. |
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. The source code of the library packaged with the product
is available here.
The source code is equivalent to release 1.0.8 and it was not modified.
|
jna-3.5.1.jar
platform-3.5.1.jar
|
Java Native Access (JNA) 3.5.1
libraries distributed under GNU
Lesser GPL (LGPL). To upgrade the library simply replace the file
and put it on the
class path. If the files are not put onto the class path Robot will
search for any "jna- " and "platform-" prefixed JAR files and load them
dynamically. The source code of the library packaged with the product
is available here.
The source code is equivalent to release 3.5.1 and it was not modified.
|
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.3 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 with time limited support. Trial
licenses are available on request from the T-Plan Sales.
- Number
of seats (users) and licensed SUT connections. The product is
licensed on a "per seat" basis. For details see the Chapter 2 of
the LICENSE.txt file located in the installation folder.
When you purchase a T-Plan Robot Enterprise license, you should also receive one
or more
license keys. 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 (where
the
robot.jar
file is located). 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 a "No license" error message 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. Then add the file 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.3 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.3 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
3.3 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
-Xmx512m
-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
-Xmx512m
-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.3
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
" com.tplan.robot.ApplicationSupport
- 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.
Memory Adjustments
As T-Plan Robot Enterprise performs memory intensive image processing, the tool
may eventually
run out of memory. This is usually experienced as a crash with a java.lang.OutOfMemoryError
or java.lang.StackOverflowError
stack
trace seen in the console window (command prompt on Windows). The first
aid is to raise
the amount of memory assigned to the Robot process:
- 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 the Robot 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 with the default heap size of (usually 128MB).
- When Robot fails with a
java.lang.OutOfMemoryError
you need to raise the heap size. The -Xmx
parameter after
the java
(or javaw
) command indicates how
much heap memory is your Java Virtual Machine allowed to use at a
maximum.
Raise this
number to a higher value. For example, -Xmx512m
allows
the
JVM heap to grow up to 512MB if needed. This limit doesn't mean that
the
memory is allocated
immediately.
- When Robot fails with a
java.lang.StackOverflowError
raise the stack size through the -Xss
parameter. The
syntax is the same as the -Xmx
one. As the defauIt
stack
size is typically between 384k and 512k for x86 systems and
1MB for x64 ones it is usually sufficient to increase the stack memory
to 1MB on x86 (-Xss1m
) or to 2MB on x64 (-Xss2m
).
Though Java is likely to accept any number up to the size of your RAM
through the -Xmx
switch, the behavior is further subject
to the system architecture:
- Java is not able to
allocate more than approx. 1GB of memory on 32-bit systems (x86). This is caused
by two factors. Java
requires contiguous (uninterrupted) chunk of memory for the heap. Most
32-bit systems are also 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 able to allocate on
such environment is typically about 1GB.
- 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. Be aware that
the Robot application takes up twice as much memory on a 64-bit JVM
than on a 32-bit one. This is because all references (pointers) that
occupy most of the memory are double size (64-bit opposed to 32-bit).
From this point of view moving Robot from a 32-bit environment with 1GB
of RAM to a 64-bit one with 2GB of RAM doesn't make much sense because
the application will not be able to allocate any extra memory. In such
a case it may be equal or even better to use the x64 system together
with a 32-bit Java installation.
Tips to minimize the memory consumption:
- Keep the number of open script editors at a minimum. One usually
doesn't need to edit tens of scripts at a time.
- Prefer the "search2" image comparison method for the search of
components on the screen. It has much lower memory requirements than
the legacy "search" one.
- If your test script creates lots of output objects such as screen
shots, logs, warnings or test steps, move the Report call to the end of
the script. It will make the it run much faster and consume less memory
because it will avoid numerous generations of the result XML/HTML along
the way. This step will have no effect on the final report content.
- The default "Graphite"
Look And Feel (LAF) looks neat but it also consumes more CPU and RAM.
You may see a decent performance gain if you go to the Appearance &
Accessibility panel of the Preferences
window and set the LAF to the first OS default one (requires
Robot restart).
- Robot by default stores data from up to 20 most recent script
executions for the needs of the Result
Manager and Export To
T-Plan wizards. If you run a high number of larger scripts in the
GUI mode over the day, setting this limit to a lower value through the Resource Manager panel of the Preferences window may
get you a bit of extra memory.
- It is recommended to run the production automation in the CLI
mode. It avoids the GUI and it has very low memory requirements. For
details see the -n CLI switch
documentation.
If you experience memory problems that can't be resolved using the
hints above please get us a memory dump from the failing Robot process.
You may create it through clicking onto the memory monitor at the
bottom right corner of the Robot 3.1.1+ GUI. Alternatively start
Robot with the -XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=./java_pid<pid>.hprof
switches
after the java
(javaw
) command to make the
process create the dump automatically. See the Oracle
documentation for details.
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 is encoded. They are specified as 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
it.
- 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 (set as the first) the Raw
encoding. It is the least efficient one where the pixels
are transferred 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.
- 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. This leads to significant desktop
performance improvements on slow network environments. It also makes
the image comparison easier and more reliable.
To observe 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.
|
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://www.t-plan.com/support.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 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 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 the
Startup
chapter.
T-Plan Robot Enterprise
crashes with java.lang.OutOfMemoryError