T-Plan Robot Enterprise 2.3.5 CLI Options
Content:
1. T-Plan Robot Enterprise 2.3.5 Startup CLI
Options
2. T-Plan Robot Enterprise 2.3.5 Offline Image
Comparison CLI
Options
1. T-Plan Robot Enterprise 2.3.5 Startup CLI
Options
1.1 Standard CLI Options
Synopsis | Options
| Examples
SYNOPSIS
To run T-Plan Robot Enterprise use one of the following commands. Note that
the
wrapper scripts robot.sh
and robot.bat
can't handle more than 9 parameters. If you need to
pass
more parameters or customize the start command, use the syntax
with java.
Unix/Linux:
./robot.sh [options]
java
-Xmx128m -classpath
jh.jar:activation.jar:mail.jar:
poi-3.6-20091214.jar
:
robot.jar
com.tplan.robot.ApplicationSupport
[options]
MS Windows:
robot.bat [options]
java
-Xmx128m -classpath
jh.jar;activation.jar;mail.jar;
poi-3.6-20091214.jar
;
robot.jar
com.tplan.robot.ApplicationSupport
[options]
OPTIONS
-h, --help
Display a shorter version of this help.
-c, --connect
[protocol://host[:port]]
-c, --connect
[host[:display]]
-c, --connect
[host[::port]]
Connect to a desktop or image. The argument must be a valid URL in
form of <protocol>://<host_or_IP>[:<port>]
where the protocol must be equal to one of the installed client plugin
(protocol) codes. T-Plan Robot Enterprise supports two clients, RFB
(VNC) v3.x (plugin code
"rfb") and static
image (code "file"). If port is not explicitly specified, it
defaults to
the default protocol-specific port (for RFB/VNC it is
5900; static image client doesn't use the port). Examples:
-c rfb://myserver:5900
-c rfb://myserver
Connect to a VNC server running on
machine "myserver". As server runs on the default port of 5900
(typically a Windows machine), it is not necessary to specify the port
and that's why both examples above are equal.
-c rfb://192.168.100.9:5901 -p welcome
Connect to a VNC server running on port
5901 of machine with IP 192.168.100.9. The server requires password of
"welcome".
-c file://C:\TestData\Screen.png
Load the specified image file and test
it instead of a live desktop.
-c file://C:\TestData\images.jar!/examples/screen.png
Load an image which is zipped inside a
JAR file and test it instead of a live desktop (support of JAR bundles
was introduced in 2.3).
-c file://desktop.bmp
Load an image located in the
installation directory. Relative file path in the URL is always
resolved against the installation directory (supported since 2.3).
If protocol is omitted in the URL, the host defaults to the RFB
(VNC) protocol to provide backward compatibility with VNCRobot 1.x.
Port number is in this case considered to be a display number rather
than real port. To get a real port take the display number and add it
to 5900 which is the default RFB port. Direct port can be in this mode
specified through double colon, for example both "localhost:1
"
and
"localhost::5901
" refer to the same local VNC server
running on port
5901. To specify the same address in the standard URL form one has to
list the real port and the equivalent URL is
"rfb://localhost:5901"
.
Note that connection to a desktop or image may be also established
through
either Connect command
call from a proprietary language test script or through a call of the connect()
method of a Java test script. Connections can be also initiated
manually through the Login Dialog in
the GUI.
-l, --listen [:display]
-l, --listen
[::port]
This is an RFB (VNC) specific parameter
which makes T-Plan Robot Enterprise listen on port 5500+display for a reverse
connection from an RFB server. This mode allows to establish
connections with servers which do not have public IP addresses, such as
for example mobile phones or portable devices.
When this parameter is specified, the connection protocol is
automatically set to RFB and the -c/--connect
parameter
can not be specified. Connection must be then initiated from the
server. This step is server and platform specific. While Linux/Unix
systems use a utility called vncconnect
, VNC servers on
Windows usually allow to initiate the connection either from GUI or
through a command line option. Refer to the documentation of your VNC
server for more information.
-u, --user [username]
User name (ID) to use for
authentication to the desktop server. If the server doesn't require it,
this parameter is ignored. As neither the RFB (VNC) nor the static
image client supported by this product requires a user name, this
option is currently not used and it is reserved for future use and
third party client extensions.
-p, --password [password]
Password to authenticate to the desktop
server (usually RFB/VNC). If the server doesn't require a password,
this parameter is
ignored. See the
-c/--connect parameter for examples.
-v,
--variable
"
[variablename]=[value]"
Override a script variable value. See
the documentation on the
Var
command. Variable values defined through this parameter will remain
unmodified for the whole time of script execution and they will
override
any variable modifications declared in the script. You may use this
feature
to run the same script for different configurations. As the CLI parser
looks for the first equals character '=' to separate variable name from
value, the variable name may not contain it. It is highly recommended
to enclose the whole name-value pair with double quotes because it
works well with values containing spaces and some systems such as MS
Windows tend to remove the value otherwise. Example:
-v
"MYVARIABLE=This is variable value
with spaces"
.
-o, --option
"[optionname]=[value]"
Redefine a user preference value.
Anything that is configurable via the Preferences dialog can be
redefined here. Any preference value overriden this way will be
maintained only for the time of the script execution and it will not be
written to the user configuration file. See the
T-Plan Robot Enterprise default configuration file for
info about preference names and acceptable values. As the CLI parser
looks for the first equals character '=' to separate the option name
from value, the name may not contain it. It is highly recommended to
enclose the whole name-value pair with
double quotes because it works well with values containing spaces and
some systems such as MS Windows tend to remove the value otherwise.
Example:
-o "some.file=C:\Program
Files\T-Plan\file.dat"
.
-r,
--run
[filename]
Run a test script. The file name can be
either relative or absolute. When relative path is specified, it is
resolved against the T-Plan Robot Enterprise installation folder. This option can
be used in both GUI and
CLI
modes.
-n, --nodisplay
Do not display the GUI. This
option can be used only with the -r/--run
option to run a
test script from a command line without any graphical output. Running
in CLI mode is faster and requires less memory and system resources. On
Unix/Linux systems it also allows to run automated tasks remotely from
a terminal without a graphical display, for example through telnet or
rsh.
-e, --edit [filename]
Start the GUI and open a particular
file for editing in the script editor. This option overrides the
default T-Plan Robot Enterprise's behavior of restoring open scripts from the last
session. The file name can be
either relative or absolute. When relative path is specified, it is
resolved against the T-Plan Robot Enterprise installation folder. The option makes
sense only in GUI mode and will be ignored otherwise.
-m, --resultmanager
Force the
Result Manager window appear even in
CLI mode (with the
-n/--nodisplay
option). This is
typically used to review results of one or more test scripts executed
in the CLI mode. The window opens when the first script finishes and
produces test results. When all test scripts finish, the Java process
is not terminated as long as the window is open to allow the user to
review the results and eventually save them or export them to the
T-Plan Professional database. When this option is used in GUI mode
(without
the
-n/--nodisplay
option), it is ignored because the
window is by default available in the GUI. The option is supported
since v2.3.
--createscript
[filename]
To be used when you execute in
GUI mode. The option will create a new script or overwrite an existing
one and open it in the editor. This option overrides the default
T-Plan Robot Enterprise's behavior of restoring
open scripts from the last session. The file name can be
either relative or absolute. When relative path is specified, it is
resolved against the T-Plan Robot Enterprise installation folder. The option makes
sense only in GUI mode and will be ignored otherwise.
--outputdir [path]
Initialize the output path of the
script created through --createscript
. The option will
create a variable 'Var _REPORT_DIR=<path>'
and
insert
it into the script.
--templatedir [path]
Initialize the template path of the
script created through --createscript
. The option will
create a variable 'Var _TEMPLATE_DIR=<path>'
and
insert it into the script.
--autosave
Automatically save the script created
through --createscript
when you close the GUI.
--fromlabel [label]
Execute a script from a label specified
in the script code. A label is a script line starting with a colon ':'.
If your script e.g. contains a label ':start'
, then CLI
option '--fromlabel start'
will execute just the commands
after the label.
--tolabel [label]
Execute a script to a label specified
in the script code. A label is a script line starting with a colon ':'.
If your script e.g. contains a label ':end'
, then CLI
option '--tolabel end'
will execute just the commands
before the label.
--nooutput
Dry run - execute a script but don't
produce any output. If you specify this option, all
Screenshot and
Report commands will be
executed successfuly but they will not produce any files. This can be
used for debug purposes when you want to reexecute a script and avoid
to
overwrite the previous results.
--nologin
Do not display Login Dialog at start up
and proceed to the main GUI. If there's no desktop connection specified
either through -c
or by a script passed with -r
,
the
GUI
starts
in
offline
mode
with
the
Welcome
panel on.
--locale [locale]
Start the product in the specified
locale (language). The
locale
argument must correspond to
file name suffix one of the installed language packs. It consists of a
mandatory language
ISO-639
2-letter code, optionally followed by an
underscore and country code (
ISO-3166,
2-letter)
which
may
be
further
on
followed
by
an
optional underscore
and variant (which is a vendor or browser-specific code). For example
"--locale
de"
will attempt to start the program in German while
"--locale
es_MX"
will look for the Mexican Spanish language pack.
When the requested language is not available, the program defaults to
English. See the
Login Dialog's
Language component for the list of
installed language packs. Should you want to learn more about the
product localization support, read the
Localization Instructions manual
in the T-Plan Robot Enterprise 2.3.5 documentation.
--license
Prints out the T-Plan Robot Enterprise
2.3.5 license to the console.
EXAMPLES
./robot.sh --connect fox.robot.com:2
./robot.sh --connect fox.robot.com::5902
./robot.sh --connect rfb://fox.robot.com:5902
All three commands are equal and
connect to a VNC server running on
machine fox.robot.com on port 5902. If the server doesn't require
any
authentication,
T-Plan Robot Enterprise GUI
starts
and
displays the server desktop in the
desktop
viewer.
If
the
server
requires
password,
a
login
dialog gets displayed and user
has to provide a valid password.
./robot.sh --connect java://localhost
Connect to the local system display
(meaning the very same desktop you see on your screen or other display
device) through the Java native client. No other piece of software than
Java and T-Plan Robot Enterprise are required. (Enterprise version only)
./robot.sh --connect java://192.168.1.1:1099
Connect to the display of the host with
IP address 192.168.1.1 through the Java native client using RMI. The
host machine must have Java installed and it must be executing
T-Plan Robot Enterprise in the Java server mode. See the Java client documentation
for more. (Enterprise version only)
./robot.sh -r self_connect.java
Execute a Java test script self_connect.java
in GUI mode. The tool will compile it into the .class format internally
and execute it. As no path is provided, the file must be located in the
T-Plan Robot Enterprise installation folder. Also as the -c/--connect
option is not specified, the script must contain its own connection
code.
Let's have a test script test.txt
located in the
T-Plan Robot Enterprise installation folder:
# This script opens an
application on GNOME
# We
take advantage of the feature that Alt+F2
#
opens the Run Application window
Var
APPLICATION=""
Press Alt+F2 wait=5000
Typeline "{APPLICATION}"
wait=5000
:screenshot
Screenshot
application.png
|
Then commands:
java
-Xmx128m -classpath
jh.jar;activation.jar;mail.jar;
poi-3.6-20091214.jar
;
robot.jar
com.tplan.robot.ApplicationSupport
-c
fox.robot.com:2 -p
mypassword -r
test.txt -o scripting.delayBeforeAutomaticExecutionSeconds=5 -v
APPLICATION=gnome-terminal
Connect to a VNC server running on
machine fox.robot.com on port 5902 and start automatic execution of
a
script called test.txt
in GUI mode. If authentication
succeeds and connection to the server gets established, the GUI gets
displayed and a timeout countdown is started. It will last 5 seconds
instead of the standard 15 secs because the parameter -o redefines the
timeout value. Once the time is out, execution of the script starts. As
the APPLICATION variable is redefined by the -v option, the script
starts a GNOME terminal window and take a screenshot. A shutdown
countdown of standard 15 seconds is then initiated. When the time is
out, the GUI gets disposed and T-Plan Robot Enterprise exits.
java
-Xmx128m -classpath
jh.jar;activation.jar;mail.jar;
poi-3.6-20091214.jar
;
robot.jar
com.tplan.robot.ApplicationSupport
-c fox.robot.com:2 -p mypassword -r test.txt -o
scripting.delayBeforeAutomaticExecutionSeconds
=5
-v
APPLICATION=gnome-terminal
-n
This command should provide the same
result as the previous one except that no GUI gets displayed and
T-Plan Robot Enterprise runs in the CLI mode. Execution logs are printed out to
the console.
java
-Xmx128m -classpath
jh.jar;activation.jar;mail.jar;
poi-3.6-20091214.jar
;
robot.jar
com.tplan.robot.ApplicationSupport
-c fox.robot.com:2 -p mypassword -r test.txt
-v
APPLICATION=gnome-terminal --fromlabel screenshot
This command will execute just the 'Screenshot
application.png'
command because it is the only command after
the screenshot
label.
robot.sh -c java://localhost -r
test.txt -v
APPLICATION=gnome-terminal
Execute the test.txt
test
script on the local desktop through the Java native client. The local
machine doesn't have to be executing any desktop software. The
automation will take place through Java native interfaces accessing the
display on the local OS level. This allows to create relocatable, self
contained and locally executable test suites which consist of a test
script, T-Plan Robot Enterprise instance and Java. The test script in our example
doesn't require any modification to run through Java though it was
originally designed on an RFB server. (Enterprise version only)
1.2 T-Plan Integration CLI
Options
T-Plan Integration CLI Options are an extension to the existing
standard interface to support integration with other T-Plan products,
in particular with T-Plan Professional 7.0. For more details read the Integration Reference document. As
this interface takes advantage of the user preference overriding
mechanism supported by the -o/--option
, it doesn't really
define any new options in the standard interface. This ensures
compatibility with the open source version of T-Plan Robot which simply
ignore any such parameters because it doesn't contain any features
consuming them. Each option must be used together with -o
or --option
, for example "-o
tplan.url=http://localhost:4000"
.
The integration options are designed to instruct T-Plan Robot Enterprise to
perform one of the integration tasks on of the T-Plan test management
database, such as:
- Import
a T-Plan Professional script entity into an automated script,
- Export
test results from automation to the T-Plan database.
There are common options and task specific ones.
Common Integration Options
The common options include mainly credentials which have to be provided
for each task. Default values for all these options may be stored
persistently to the user configuration file through the T-Plan Connector panel of the Preferences window. Options having
a default value may be then omitted on the command line.
Option
Name
|
Description
|
tplan.url |
SOA web service URL, for example
"http://tplandb.mycompany.com:4000". All communication between
T-Plan Robot Enterprise and T-Plan database is realized through a web service
which is typically running on port 4000 on the database server. This
parameter is mandatory for each integration task.
|
tplan.user |
Database user name. It is the
same parameter which has to be provided to log in to T-Plan
Professional. This parameter is mandatory for each integration task. |
tplan.password |
Password for authentication to
the database. It is the same parameter which has to be provided to log
in to T-Plan Professional. This parameter is mandatory for each
integration task. |
tplan.database |
Database name to connect to. It
is the same parameter which has to be provided to log in to T-Plan
Professional. This parameter is mandatory for each integration task. |
tplan.group |
Database user group. It is the
same parameter which has to be provided to log in to T-Plan
Professional. This parameter is mandatory for each integration task. |
tplan.debug |
Debug flag (optional). The value
may be either "true" or "false". The
value of "true" causes the tool to print out integration debugging
messages into the console. Default value is "false".
|
Import Options
Import options are handled just once when the GUI starts. A script is
either imported successfully and opened in an editor or the task fails
and an error message gets displayed. In both cases the options are
discarded then.
Option
Name
|
Description
|
tplan.importScriptNumber |
Number of an existing T-Plan
Professional script entity to import to. Mandatory for the import task.
|
tplan.scriptName |
Name of the imported script
entity (optional). If provided it will be added as attribute of the Script command.
|
Export Options
Though the export options are typically used with automated executions
together with the -r/--run
parameter, they apply to all
scripts executed by the T-Plan Robot Enterprise instance. It means that if you
start the GUI with the export options and then manually execute several
scripts, each result set will be exported to the specified T-Plan test
suite. To exit this export mode restart the application without the CLI
arguments.
Option
Name
|
Description
|
tplan.autoExport |
A flag indicating whether to
export test results after script execution (usually through the
-r/--run option). The value must be "true" to perform this task. It is
mandatory for the export task.
|
tplan.mode |
Test result export mode.
Acceptable values are:
- "create" creates a
new test suite to import the test results to. The
tplan.newSuiteName
must be provided along with this mode. If the tplan.suiteNumber
option is also provided, the test suite specified by this parameter
will serve as parent of the new one. Otherwise the test suite gets
created right under the Manage root node.
- "rewrite" rewrites
test results of an existing test suite specified by the
tplan.suiteNumber
option.
- "append" appends
test results to an existing test suite specified by the
tplan.suiteNumber
option.
|
tplan.suiteNumber |
Test suite number for export of
test results. The parameter either identifies target test suite or
parent for the new one depending on value of the tplan.mode
option.
|
tplan.newSuiteName |
Name for the new test suite.
This option must be provided when the export mode is "create" ("tplan.mode=create" ).
Otherwise
it
is
ignored.
|
EXAMPLES
java
-Xmx128m -classpath
jh.jar;activation.jar;mail.jar;
poi-3.6-20091214.jar
;
robot.jar
com.tplan.robot.ApplicationSupport
--createscript
test.tpr
-o
tplan.url=http://localhost:4000 -o
tplan.user=admin
-o
tplan.password=dbadmin -o
tplan.database=testdb
-o "tplan.group=System Administrators" -o
tplan.importScriptNumber=101
Start T-Plan Robot Enterprise in GUI mode, create
a test script called test.tpr and open it in the script editor. If the
file already exists, overwrite it (to open a file in append mode use -e/--edit
instead of --createscript
). Then import structure of
T-Plan sript entity number 101 into the editor.
java
-Xmx128m -classpath
jh.jar;activation.jar;mail.jar;
poi-3.6-20091214.jar
;
robot.jar
com.tplan.robot.ApplicationSupport
-c
fox.robot.com:2
-p
welcome
-r
test.tpr
-o
tplan.url=http://localhost:4000
-o
tplan.user=admin -o
tplan.password=dbadmin
-o
tplan.database=testdb
-o
"tplan.group=System Administrators" -o
tplan.autoExport=true
-o
tplan.mode=rewrite -o
tplan.suiteNumber=111
Execute the test.tpr script on VNC
server fox.robot.com. Then export test results to test suite number 111
in the T-Plan database. As the export mode is set to "rewrite", any
existing results of the same script will be overwritten by the new ones.
2. T-Plan Robot Enterprise 2.3.5 Offline
Image Comparison CLI Options
Synopsis | Options | Exit Codes | Examples
SYNOPSIS
T-Plan Robot Enterprise 2.3.5 can be also used for offline image
comparison
through a simple CLI interface. To run it use one of the following
commands. Note that the
wrapper scripts can't handle more than 9 parameters. If you need to
pass
more parameters or customize the T-Plan Robot start command, use the
command
with java.
Unix/Linux:
./imgcompare.sh
<source_image>
<template_image>
[options]
java -classpath robot.jar
com.tplan.robot.ImageComparison
<source_image>
<template_image> [options]
MS Windows:
imgcompare.bat
<source_image>
<template_image>
[options]
java -classpath robot.jar
com.tplan.robot.ImageComparison
<source_image> <template_image>
[options]
All image comparison modules available in T-Plan Robot Enterprise can be invoked
including the custom ones plugged into the tool through the Plugin API. Be aware that this
CLI also loads the user configuration and it will use all image
comparison preferences customized through the GUI, such as
default comparison method (module), default pass rate values and
maximum number of search hits for the 'search'
comparisons.
OPTIONS
-s
Silent mode. This option suppresses all
output except error messages. This mode is to be used when you are
interested just in the return code.
-c
Concise mode. When used
together with the 'search'
method it prints out exactly one coordinate per line in the [x,y]
format. This output is language independent, the format will be
preserved accross future versions and language mutations and it is
suitable for parsing by third party tools.
The switch has the same functionality as -s
when called
together with the 'default'
method. When both -s
and -c
are specified
in one command, the tool will run in silent mode.
-m [module]
Image comparison module (method) to be
used. T-Plan Robot Enterprise defines two of them,
'default' for histogram based
comparisons and
'search' for
image searches. For more information on image comparisons see the
Compareto command
specification and also the
Image
Comparison
With T-Plan Robot Enterprise document.
Any custom modules plugged into the tool through the
Plugin API can be also used
and value of the
-m
parameter should correspond to the
name retuned by the
getMethodName()
method of the module.
If the option is omitted, a default value from user configuration will
be used.
-p [passrate]
Pass rate in %. It must be a float or
integer number between 0 and 100 indicating how much the source and
template images must match for the image comparison result to be 'PASS'
(exit code of 0).
If the option is omitted, a default value from user configuration will
be used. Note that there are separate default pass rates for the 'default' method (typically 95%)
and 'search' (100%).
-r [rectangle]
Limit the image comparison to a certain
area of the source image. This is rather to be used with the 'search' method where it makes
sense to search for an icon or a subimage just in part of the image.
The value must be in the T-Plan Robot Enterprise rectangle format, e.g. 'x:0,y:25,w:350,h:200'
.
If
x
or y
are omitted, a value of 0 will be
used. If the w
(width) or h
(height)
parameters are omitted, their value will be calculated as the maximum
possible value with regards to the source image size. When your source
image is e.g. 640x480 and you specify '-r x:100,h:300'
,
the rectangle will be calculated as 'x:100,y:0,w:540,h:300'
.
If
the
option
is
omitted,
image
comparison
will
be
performed on the
entire source image.
-h [max_number_of_search_hits]
Maximum number of search matches. It
must be an integer value greater than 0. When the max number of search
matches is reached, the image comparison will finish and behave as if
it passed.
This option applicable only to 'search'
comparisons. If it is used together with the 'default'
method, it will be ignored and no error will be reported. If the option
is omitted, a default value from user configuration will be used
(typically 100).
EXIT CODES
Exit
Code
|
Meaning
|
0 |
Image comparison passed.
|
1 |
Image comparison failed ('default':
pass
rate
was
not
met,
'search':
no match found with the given pass rate)
|
2 |
Error: couldn't load the source image.
|
3 |
Error: couldn't load the template image.
|
4
|
Syntax error in input arguments
(a message describing the error is printed out).
|
5 |
Internal error - please report to the
T-Plan Robot Enterprise support.
|
EXAMPLES
java -classpath robot.jar;
poi-3.6-20091214.jar
com.tplan.robot.ImageComparison
image.png pattern.png -m search -r x:0,y:20,w:120,h:300
./imgcompare.sh
image.png pattern.png
-m
search
-r
x:0,y:20,w:120,h:300
Search for template image pattern.png
in the [0,20,120,320] rectangle of source image image.png
.
The
command
above
is valid for Windows. For Linux/Unix replace the
semicolon ';' in the class path with colon ':'.
java -classpath
robot.jar;
poi-3.6-20091214.jar
com.tplan.robot.ImageComparison
image.png pattern.png -m search -p 99.9 -h 1
./imgcompare.sh
image.png pattern.png
-m
search
-p
99.9 -h 1
Search for the first 99.9% match
occurence of template image pattern.png
in the source
image image.png
. The command above is valid for Windows.
For Linux/Unix replace the semicolon ';' in the class path with colon
':'.
java -classpath
robot.jar;
poi-3.6-20091214.jar
com.tplan.robot.ImageComparison
image1.png image2.png -m default -p 99
./imgcompare.sh
image.png pattern.png
image1.png image2.png -m default -p 99
Compare histograms of images image1.png
and image2.png
and return PASS (exit code 0) if they
match at least 99%. The command above is valid for Windows. For
Linux/Unix replace the semicolon ';' in the class path with colon ':'.