T-Plan Home
T-Plan Robot Enterprise 3.4.2 Doc Collection
02/09/13

T-Plan Robot Enterprise 3.4.2 CLI Options

Content:
1. T-Plan Robot Enterprise 3.4.2 Startup CLI Options
1.1 Standard CLI Options
1.2 T-Plan Integration CLI Options
2. T-Plan Robot Enterprise 3.4.2 Offline Image Comparison CLI Options

1. T-Plan Robot Enterprise 3.4.2 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 -Xmx512m -classpath robot.jar:jh.jar:activation.jar:mail.jar:poi-3.6-20091214.jar:javaparser.jar:JTattoo.jar com.tplan.robot.ApplicationSupport [options]

MS Windows:
robot.bat [options]
java -Xmx512m -classpath robot.jar;jh.jar;activation.jar;mail.jar;poi-3.6-20091214.jar;javaparser.jar:JTattoo.jar com.tplan.robot.ApplicationSupport [options]

Some of the JAR files on the class path may be omitted. Robot in such a case switches off the functionality relying on the omitted library. See the Release Notes document for more details on the bundled JAR files.


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. For the list of supported connection types and their URLs see the Release Notes document. Examples:

-c fox.red.com:1 -p welcome
-c fox.red.com::5901 -p welcome
Connect to a VNC server running on port 5901 of the machine called fox.red.com with the password of "welcome".

If the protocol is omitted in the URL, the connection defaults to the RFB (VNC) one to provide backward compatibility with VNCRobot 1.x. The port number is in this case considered to be a display number rather than real port. To get the 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".

-c rfb://fox.red.com:5900
-c rfb://
fox.red.com
Connect to a VNC server running on machine fox.red.com. 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).
-c adb://default
Connect to an Android device over the USB cable using the Android Over ADB connection (since 3.1).

-c adb://MB104PY10519
Connect to Android device of the specified serial number using the Android Over ADB connection. This form is used when there are two or more devices connected to the Robot machine.

-c java://localhost
Attach to the local desktop using the Local Desktop connection (since 3.2).
-c apple://192.168.100.13:5901
Connect to an Apple device running the VNC server on port 5901 using the iOS Mirror connection (since 3.3).
 
-c apple://192.168.100.13:5909
Connect to an Apple device running the T-Plan server on port 5909 using the iOS Mirror connection (since 3.5).

Connection to the system under test may be also established through the Connect command call in a TPR 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. To pass a variable with spaces in the name or value enclose the whole argument with double quotes, for 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. To pass an option with spaces in the name or value enclose the whole argument with double quotes, for 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 the specified particular test  script for editing in the script editor. 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.

This option overrides the default T-Plan Robot Enterprise's behavior of restoring open scripts from the last session. If the test script belongs to a project the GUI will open the project instead of the recently used one.

-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]
The option will create a new script or overwrite an existing one and open it in the editor on the GUI start up. It is intended to enable integration with 3rd party frameworks that need to start the GUI with the predefined content. The option makes sense only in the GUI mode and will be ignored when the -n/--nodisplay option is specified.

The argument file name can be either relative or absolute. When a relative path is specified, it is resolved against the T-Plan Robot Enterprise installation folder.

The option overrides the default T-Plan Robot Enterprise's behavior of restoring open scripts from the last session.  If the test script belongs to a project the GUI will open the project instead of the recently used one.

--outputdir [path]
Initialize the output path of the script created through --createscript. The option will create a variable command of 'Var _REPORT_DIR=<path>' and insert it into the script. If --createscript is not specified this option is ignored.

NOTE: To specify the output path of an existing test script(s) from the CLI set the _REPORT_DIR variable through the -v/--variable option. For example, the -v "_REPORT_DIR=C:\reports" will fix the output path path to the specified one for the whole session (until T-Plan Robot Enterprise is terminated).

--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. If --createscript is not specified this option is ignored.

NOTE: To specify the template path of an existing test script(s) from the CLI set the _TEMPLATE_DIR variable through the -v/--variable option. For example, the -v "_TEMPLATE_DIR=C:\templates" will fix the template path to the specified one for the whole session (until T-Plan Robot Enterprise is terminated).

--autosave
Automatically save the script created through --createscript when you close the GUI. If --createscript is not specified this option is ignored.

--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 3.4.2 documentation.

--license
Prints out the T-Plan Robot Enterprise 3.4.2 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:
  1. Import a T-Plan Professional script entity into an automated script,
  2. 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 3.4.2 Offline Image Comparison CLI Options

Synopsis | Options | Exit Codes | Examples

SYNOPSIS
T-Plan Robot Enterprise 3.4.2 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 ':'.