CLI Options

Content:

1. Startup CLI Options
  1.1 Standard CLI Options
  1.2 T-Plan Integration CLI Options
2. Offline Image Comparison CLI Options

1. Startup CLI Options

Supported standard options in alphabetical order:

--autosave
-c, --connect
--cfg
--createscript
-e, --edit
-h, --help
-l, --listen
--license
--licensekey
--licenseserver
--locale
-m, --resultmanager
-n, --nodisplay
--nologin
--nooutput
-o, --option
--outputdir
-p, --password
--params
-r, --run
--rapdirs (removed in v7)
--rapmasks (removed in v7)
--rapserver (removed in v7)
--remotecontrol
--safepass
--templatedir
-u, --user
-v, --variable
--variable-session

1.1 Standard CLI Options

Synopsis | Options | Examples

SYNOPSIS

To run T-Plan Robot Enterprise switch to the installation folder and use one of the following commands:

MS Windows: 

robot.bat [options]

Mac OS, Linux and Unix:

./robot.sh [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. 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  may be also established through the Connect command call in a TPR script or through a call of the connect() method of a Java 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".

--variable-session [variablename]=[value]

Create a read/write session variable which will be visible by all scripts See the Varg command for details. Supported since v6.3.

-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 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 script (.tpr, .java) or a workitem (.xml). Version 7 and higher also accepts an executable package (.zip). The file name can be either relative or absolute. Relative path is resolved against the T-Plan Robot Enterprise installation folder. This option can be used in both the GUI and CLI (with -n/--nodisplay) modes.

-n, --nodisplay

Do not display the GUI. This option can be used only with the -r/--run option to run a script from a command line without any graphical interface. Running in the CLI mode is recommended for production deployments because it has many advantages:

• • Better performance and significantly lower memory requirements.
  • Unlike in the GUI mode scripts can be started in parallel to reduce the time needed to complete a test campaign. Parallel script execution can be achieved through a workitem (since v4.0), using the Script Starter tool or through writing of a simple Java program on top of the Java API.
  • It allows to start 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 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 scripts executed in the CLI mode. The window opens when the first script finishes and produces test results. When all 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.

--remotecontrol <port>

Start the Remote Control server. It allows the Robot instance to be controlled remotely using the Remote Control tool or telnet. The port number is optional and must be between 1024 and 65535. If the port is omitted it defaults to 5899. The option is supported since v3.5.

--rapserver <port>


This option is no longer supported in v7. Since RAP v3 Robot does not communicate with the RAP server directly. This functionality has been replaced by the RAP Agent.

--rapdirs <path(s)>

This option is no longer supported in v7. Since RAP v3 Robot does not communicate with the RAP server directly. This functionality has been replaced by the RAP Agent.

--rapmasks <ip_mask(s)>

This option is no longer supported in v7. Since RAP v3 Robot does not communicate with the RAP server directly. This functionality has been replaced by the RAP Agent.

--restricted

Display a minimum GUI with only a few execution control buttons. It is intended to be used with the -r/--run option to execute automation in the GUI mode without displaying the whole Robot window. This mode is forced when an encrypted executable package is being run. Supported since v7. 

--safebox [safebox_file]

Location of the Safe Box file. Supported since v7. 

--safepass [password]

Password to unlock the Safe Box to grant scripts access to protected variables. Supported since v4.4.2. 

--params [JSON_file]

Apply CLI options from the specified JSON file (from 4.4.2). The JSON properties will be option names without the preceding minus character(s). If the JSON file contains an option which is also specified on the command line the latter one is preferred. The JSON file format is:

• • Options that are not followed by a value should specify the value as null. For example -n will result in { "n": null }
  • Options followed by a value may specify it either as a string or a number. For example: -r <file> will be { "r": "<file>" }
  • Options which accept value in form of <param>=<value> such as -v/--var or -o/--option may be specified either as a single value { "v": "MYVAR=test" } or an object { "v": { "MYVAR" : "test" }}. The object variant is suitable for multiple calls of the same option.

For example a command like:

robot.bat -n -r C:\Robot\script.tpr --var MYVAR1=abc --var MYVAR2=def

is equivalent to 

robot.bat -params myparams.json

where the JSON file contains

{
    "n": null,
    "r": "C:\Robot\script.tpr",
    "v": {
        "MYVAR1": "abc",
        "MYVAR2": "def"
    }
}

--licensekey [file(s)]

Start up using a license key from the argument file or a semicolon separated list of files. Supported since v4.0. There are four alternatives of passing the license key file(s) to T-Plan Robot Enterprise which can be freely combined:

• Using this option.
• By saving the key to the T-Plan Robot Enterprise installation folder. Robot searches the location for any *.tlic files and loads them automatically on the start up.
• Through the Tool->License Key Manager window in the GUI. This will store the key location(s) to the user configuration file.
• Through the robot.licenseKey system property (since v4.0.3). This way is suitable for projects integrating Robot with 3rd party Java applications. See the Release Notes document for an example.

--licenseserver [server_address[:port]]

Connect to the license server at the specified address to obtain a license to run (since v4.3). The server address consists of the host name (for example "mymachine" or "mymachine.com") and the optional port ("mymachine:8881"). If the port is not specified it defaults to 8880. There are three alternatives of passing the license server address to T-Plan Robot Enterprise:

• • Using this option.
  • Through the Tools->License Key Manager window in the GUI. This will store the server address under the ls.address key to the user configuration file. You may alternatively pass this option through o/-option.
  • Through the robot.licenseServer system property (since v4.4). This way is suitable for projects integrating Robot with 3rd party Java applications. See the Release Notes document for an example.

When the option is not specified, there's no file based license key and the server is not set through the preferences Robot looks for the server running on the default port of the local machine (localhost:8880).

--cfg [file]

Use the specified user configuration file instead of the the default one at <user_home>/.tplanrobot/tplanrobot.cfg. This option allows to repackage the product with a specific configuration for distribution inside a single organization. Supported since v4.0.

--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 script belongs to a project the GUI will open it 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 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 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.

--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 successfully but they will not produce any files. This can be used for debug purposes when you want to re-execute 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.

--license

Prints out the T-Plan Robot Enterprise 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 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 script test.txt located in the T-Plan Robot Enterprise installation folder:

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 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 script, T-Plan Robot Enterprise instance and Java. The 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.

tplan.url

tplan.user

tplan.password

tplan.database

tplan.group

tplan.debug

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.

tplan.importScriptNumber

tplan.scriptName

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.

tplan.autoExport

tplan.mode

tplan.suiteNumber

tplan.newSuiteName

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 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. Offline Image Comparison CLI Options

Synopsis | Options | Exit Codes | Examples

SYNOPSIS

T-Plan Robot Enterprise 4.4.3Beta 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 Enterprise 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 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

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 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 ':'.