T-Plan Robot Enterprise 4.3.1 Release Notes
Build No. 4.3.1-20170925.2
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. Some features such as
for example the iOS Mirror connection require
Java 1.7. 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. Installation
of a JDK requires an update of the system path as is described in
the following chapter.
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
4.3.1 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 or systems with image file output.
|
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. |
iOS Mirror
|
Testing of iOS devices using a combination
of AirPlay screen mirroring and the T-Plan or VNC server. |
iOS Over
Xcode
|
Testing of iOS 9 devices from Mac OS X with
Xcode installed.
|
RDP Server
|
Testing over the RDP protocol.
|
3. Installation
T-Plan Robot Enterprise 4.3.1 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 JNA release 3.5.1 and it
was not modified. |
JTattoo.jar
|
JTattoo Look And Feel
(JTattoo binary license).
|
JNativeHook.jar
|
JNativeHook 2.0.1 library distributed under GNU Lesser
GPL (LGPL) v3. 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 2.0.1 and it was
not modified. |
cron4j-2.2.5.jar
|
Cron4J 2.2.5 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 2.2.5 and it was
not modified. |
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 4.3.1 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.
|
T-Plan Robot Enterprise also relies on unmodified FFmpeg libraries version
3.0.1 which are distributed under GNU Lesser GPL
(LGPL) v3. These are packaged inside the robot.jar file
where they can be replaced with a newer version provided that the
file names are preserved. The FFmpeg 3.0.1 source code is available
at Zeranoe or
at our site.
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.
- Specify the key path(s) through the
--licensekey CLI
option.
- Solutions integrating Robot into 3rd
party Java frameworks and/or applications may specify the
license key path or a list of semicolon separated paths
through the
robot.licenseKey
system property.
It must be done before the ApplicationSupport
class gets instantiated. This option is available from v4.0.3.
Example:
System.setProperty("robot.licenseKey
",
"C:\\MyData\\robot.tlic");
...
ApplicationSupport robot = new
ApplicationSupport();
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 4.3.1 preserves compatibility with VNCRobot 1.x and later in the
following areas:
- Compatibility with the v1.x scripting language. It means
that you will be able to migrate test scripts created with
VNCRobot 1.x onto the 2.0 version without any modifications.
Format of the outputs like screenshots and HTML reports may
however change a bit.
T-Plan Robot Enterprise 4.3.1 introduces incompatibilities with VNCRobot 1.x in the following
areas:
-
Open
API (
http://www.t-plan.com/robot/docs/v1.3/api/index.html).
As interfaces were radically redesigned, the methods and objects
have changed. This impacts just a very few users who plugged in
their own Java extensions. Some Java development efforts are
needed to migrate such extensions onto 2.0. A migration guide may
be provided on request.
-
Configuration file. As
some of the parameter names were updated, T-Plan Robot Enterprise may fail to
read some of the preferences saved previously with VNCRobot.
Should you experience any issues after migration, delete the
config.properties
and
tplanrobot.cfg
files from the user home folder.
- The
command line interface
(CLI) is compatible with the 1.x versions in terms of supporting
the same set of CLI options. Names of the product JAR file and
start scripts have however changed as a result of rebranding. If
you integrated VNCRobot CLI calls into your test framework, you
will have to update the starting commands or eventually rename
these files to their old names (robot.jar to vncrobot.jar,
robot.sh to vncrobot.sh, robot.bat to vncrobot.bat).
Upgrade from VNCRobot 1.3.3 and earlier runs additional
compatibility risks documented in the VNCRobot
1.3 Install Instructions.
6. Uninstallation
If you installed T-Plan Robot Enterprise through the Windows installer, you may
uninstall it through the Windows software manager (Control Panel->Add Or Remove
Software on older Windows versions, Control Panel ->Programs And
Features on Windows Vista).
To uninstall T-Plan Robot Enterprise installed from the ZIP file delete the
files unzipped during installation. You may also delete the user configuration files.
The tool doesn't create any other files or registry entries except
automation outputs such as screenshots, template images and
automated test reports.
7. Startup
If you installed T-Plan Robot Enterprise through the Windows installer, you may
start the tool from the Windows Start menu (Start->Programs->T-Plan->T-Plan Robot).
Should you need to start the program with custom CLI arguments,
follow the instructions below.
To run the tool on any system from the command prompt change to the
directory where you installed T-Plan Robot Enterprise and run one of the
wrapper scripts robot.sh
(for Unix/Linux) or robot.bat
(for Windows). For help on CLI commands run robot.sh -h
,
resp. robot.bat --help
. For a complete reference see
the T-Plan Robot Enterprise 4.3.1 CLI
Reference. If the tool fails to start, review the Troubleshooting chapter at the end of
this document.
The wrapper scripts actually just start Java with proper options.
Please note that the wrapper can't handle more than 9 parameters. If
you need to pass more parameters or customize the T-Plan Robot Enterprise start
command, use the following command syntax:
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.
See the CLI Options Specification document available in the
T-Plan Robot Enterprise Help or online in the T-Plan Robot Enterprise 4.3.1 CLI
Reference document on http://www.t-plan.com/robot/docs/latest/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 "Limit the recent list to"
preference of the Result Manager panel in 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