T-Plan Robot Enterprise 4.4.7 CLI Options

1.1 Standard CLI Options
1.2 T-Plan Integration CLI Options

./robot.sh [options]

ALTERNATIVE 2 (suitable for customization, debugging and integration with 3rd party components):

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]

robot.bat [options]

ALTERNATIVE 2 (suitable for calls with 9+ CLI arguments, customization, debugging and integration with 3rd party components):

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]

Display a shorter version of this help.

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

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.

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.

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.

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".

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".

Run a test script (.tpr, .java) or a schedule (.xml). 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 GUI and CLI modes.

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 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 test scripts can be started in parallel to reduce the time needed to complete a test campaign. Parallel script execution can be achieved through a schedule (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.

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.

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.

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.

Start the RAP server to enable communication with the Robotic Automation Portal (RAP). The portal is a web application allowing to monitor, analyze and control Robot processes over the network. The port number is optional and must be between 1024 and 65535. If the port is omitted it defaults to 11298. The server may be also controlled through the GUI using the Tools->RAP Server Manager  menu item. Supported since v4.2.1.

Path or a list of paths of Robot project(s). Scripts and schedules ("work items") of each specified project will be synchronized with the RAP portal once the connection gets established. It will make the items visible in the portal and eligible for management (remote execution). If the specified path is not a project home folder it will be searched recursively for projects. This option does not export test results which are synchronized in a different way. For details read the RAP documentation.

This option is intended to be used together with the --rapserver one. It allows to export work items to RAP where the GUI can't be used, for example on headless environment deployments. Supported since v4.3.

IP address(es) or subnet mask(s) to restrict the incoming connections to the RAP server to. Multiple masks must be separated by semicolon. The option accepts the following mask formats:

• To limit the access to a single machine provide the plain RAP portal IP address such as: 192.168.1.9
• To grant access to machines from a subnet enter a subnet mask such as 192.168.1.9/255.255.255.0 or 192.168.1.9/24
  

Supported since v4.3.

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

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"
    }
}

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.

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).

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.

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 it instead of the recently used one.

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).

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).

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

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 reexecute a script and avoid to overwrite the previous results.

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.

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

Prints out the T-Plan Robot Enterprise 4.4.7 license to the console.

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.

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)

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)

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.

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)

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.

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.

./imgcompare.sh <source_image> <template_image> [options]
java -classpath robot.jar com.tplan.robot.ImageComparison <source_image> <template_image> [options]

imgcompare.bat <source_image> <template_image> [options]
java -classpath robot.jar com.tplan.robot.ImageComparison <source_image> <template_image> [options]

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.

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.

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.

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%).

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.

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).

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

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

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