VNCRobot 1.3 CLI Options

Content:
1. VNCRobot 1.3 Startup CLI Options
2. VNCRobot 1.3 Offline Image Comparison CLI Options

1. VNCRobot 1.3 Startup CLI Options

Synopsis | Options | Examples

SYNOPSIS
To run VNCRobot 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 VNCRobot start command, use the command with java.

Unix/Linux:
./vncrobot.sh [options]
java -classpath jh.jar:vncrobot.jar com.vncrobot.VNCRobot [options]

MS Windows:
vncrobot.bat [options]
java -classpath jh.jar;vncrobot.jar com.vncrobot.VNCRobot [options]


OPTIONS
-h, --help
Display a shorter version of this help.


-c [server[:display]], --connect [server[:display]]

Connect to a VNC server, e.g. 'localhost', 'localhost:1' etc. The display number corresponds to the port number on which your VNC server is running, :1 is port 5901, :2 is 5902 etc.. If no display number is provided, VNCRobot defaults to 0, i.e. 'localhost' and 'localhost:0' are equivalent.

-p [password], --password [password]
Password to authenticate to the VNC server. The server may or may not require it depending on its configuration.


-v [variablename]=[value], --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 done in the script. You may use this feature to run the same script for different configurations.


-o [optionname]=[value], --option [optionname]=[value]
Redefine a user preference value. Anything that is configurable via the Preferences dialog can be redefined here. Any preference changes redefined this way will be maintained only for the time of the script execution and they are not written to the user configuration file. See the VNCRobot default configuration file for info about option names and acceptable values.


-r [filename], --run [filename]
Run a test script. The file name can be either relative or absolute. This option can be used in both GUI and CLI modes.


-n, --nodisplay
Do not display the VNCRobot 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.

--createscript [filename]
To be used when you execute VNCRobot in GUI mode. The option will create a new script or overwrite an existing one and open it in the editor.

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

EXAMPLES
./vncrobot.sh --connect fox.vncrobot.com:2
Connect to a VNC server running on machine fox.vncrobot.com on port 5902. If the server doesn't require any authentication, VNCRobot GUI starts and displays the server desktop in the VNC viewer. If the server requires password, a login dialog gets displayed and user has to provide a valid password.


Let's have a test script test.txt:

# 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 delay=5000
Typeline "{APPLICATION}" delay=5000
:screenshot
Screenshot application.png

Then commands:

vncrobot.sh -c fox.vncrobot.com:2 -p mypassword -r test.txt -o com.vncrobot.scripting.delayBeforeAutomaticExecutionSeconds=5 -v APPLICATION=gnome-terminal
Connect to a VNC server running on machine fox.vncrobot.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 VNCRobot exits.

vncrobot.sh -c fox.vncrobot.com:2 -p mypassword -r test.txt -o com.vncrobot.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 VNCRobot runs in the CLI mode.

vncrobot.sh -c fox.vncrobot.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.


2. VNCRobot 1.3 Offline Image Comparison CLI Options

Synopsis | Options | Exit Codes | Examples

SYNOPSIS
VNCRobot 1.3.8 and higher 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 VNCRobot start command, use the command with java.

Unix/Linux:
./imgcompare.sh <source_image> <template_image> [options]
java -classpath vncrobot.jar com.vncrobot.VNCRobotImageComparison <source_image> <template_image> [options]

MS Windows:
imgcompare.bat <source_image> <template_image> [options]
java -classpath vncrobot.jar com.vncrobot.VNCRobotImageComparison <source_image> <template_image> [options]

All image comparison modules available in VNCRobot can be invoked including the custom ones plugged into the tool through the VNCRobot 1.3 Open API. Be aware that this CLI also loads the user configuration and it will use all image comparison preferences customized through the VNCRobot 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.

-c
Concise mode (since 1.3.10). 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. VNCRobot 1.3 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 VNCRobot 1.3 document.

Any custom modules plugged into the tool through the VNCRobot 1.3 Open 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 VNCRobot 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 VNCRobot team.

EXAMPLES
java -classpath vncrobot.jar com.vncrobot.VNCRobotImageComparison 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.

java -classpath vncrobot.jar com.vncrobot.VNCRobotImageComparison 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.

java -classpath vncrobot.jar com.vncrobot.VNCRobotImageComparison 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%.