VNCRobot 1.3 Language Reference

Last update: June 19, 2009

Contents

1. Language Syntax
1.1 Language Structure
1.2 Time Values
1.3 Procedures
1.4 Numeric Expressions
1.5 Boolean Expressions
1.6 If/Else Statement
1.7 For Statement
1.8 Local Variables
1.9 Return Values
2. Command Syntax
2.1 Commands Representing RFB Client To Server Messages
2.1.1 Connect
2.1.2 Disconnect
2.1.3 Press
2.1.4 Type / Typeline
2.1.5 Mouse
2.2 Administrative & Execution Control Commands
2.2.1 Var
2.2.2 Eval
2.2.3 Include
2.2.4 Run
2.2.5 Pause
2.2.6 Exit
2.2.7 Wait
2.2.8 Waitfor
2.2.9 Compareto
2.2.10 Exec
2.3 Report Commands
2.3.1 Screenshot
2.3.2 Report
2.3.3 Warning
2.3.4 Sendmail


1. Language Syntax


1.1 Language Structure

VNCRobot language is a text-based programming language. The following general rules apply:
# This is a comment
Examples:
This is a text containing spaces
- Will be parsed into 6 tokens: 'This', 'is', 'a', 'text', 'containing', 'spaces'.

This "is a text" containing spaces
- Will be parsed into 4 tokens, 'This', 'is a text', 'containing', 'spaces'.

This text contains "double quote (\")"
- Will be parsed into 4 tokens, 'This', 'text', 'contains', 'double quote (")'

Variable SAMPLE_VAR_1="value with spaces" SAMPLE_VAR_2=no_spaces "NO_VAR=not_a_variable"
- Will be parsed into 4 tokens: 'Variable','SAMPLE_VAR_1="value with spaces"', 'SAMPLE_VAR_2=no_spaces' and 'NO_VAR=not_a_variable'.The second and third tokens will be further parsed into identificator/value pairs. The fourth token will not be parsed as it does not comply with the required format.
  1. The very first token is considered to be a command or procedure name and is matched against command and procedure tables. Command names are NOT case sensitive.
  1. Further processing and syntax validation is then performed by the command/procedure handlers as described below in the Command Syntax and Procedures chapters.

1.2 Time Values

Time values like Wait command argument and wait/timeout/delay parameters of other commands support the following syntax:
Floating point variables are acceptable in the English format only, i.e. '3.5h' will be parsed as 3.5 hrs (3 hrs 30 mins).

Examples:
Wait "1.5d"
- Wait one and a half days (36 hours)

Press Ctrl+C wait=5s
- Press Ctrl+C and pause for 5 seconds.

1.3 Procedures

VNCRobot v1.3 supports simple procedures. A procedure is a named block of commands written in required format which can be executed by calling its name. Procedure format is:

procedure <procedure_name> {
command1
command2
...
commandN
}

Procedure name must meet the rules listed in the Language Syntax chapter. Procedure can be called anywhere in the script AFTER its definition. It is possible to pass any number of parameters to a procedure call as follows:

<procedure_name> parameter1 "parameter2 with spaces" .... parameterN

Parameters are then available as variables with names '0', '1', ... 'N'. Please note that the first variable with index 0 always contains the procedure name. The following example illustrates how to write and use a simple procedure which will create a screenshot with variable image format:

# Procedure definition. Expected parameters are:
# {1} ... file name without extension
# {2} ... image extension (must be either jpg, jpeg or png)
procedure take_screenshot {
Screenshot {1}.{2} desc="This screenshot was created by procedure called {0}"
}

take_screenshot image1 jpg
take_screenshot image2 png


Procedures always return exit code of the last executed command within the procedure body. To exit a procedure with a specific exit code use the Exit command with the scope parameter set to procedure. An example follows:

# Procedure definition
procedure exit2 {
Exit 2 scope=procedure
}

# Procedure call
exit2

if ({_EXIT_CODE} == 2) {
     # Any code here will be executed because exit2 returns 2
}

Procedure content is never validated during procedure definition because without parameters it is not possible to resolve whether the code is correct or not. VNCRobot validates the procedure calls instead. If you e.g. type

take_screenshot image3 tiff

VNCRobot will report an error in this line because 'tiff' is not a supported image format.

1.4 Numeric Expressions

Numeric expressions are supported since v1.3. The following rules apply:
Numeric expressions are accepted anywhere in the language where a number is expected, e.g.

# Wait 1 hour - in miliseconds
Wait "1*60*60*1000"

# Search for an image and then click onto it 10 points from its left upper corner
Compareto "pattern.png" method="search"
Mouse click to="x:{_SEARCH_X}+10,y:{_SEARCH_Y}+10"

To define a variable based on a numeric expression use the Eval command instead of the Var one, e.g. 'Eval HOUR_IN_MS=1*60*60*1000'.

1.5 Boolean Expressions

Boolean expressions are supported since v1.3 to facilitate constructions like if/else and for. The following operators and rules apply: Boolean expressions are exclusively used by the if/else and for constructions,e.g.

# Look for an image on the remote desktop
Compareto "pattern.png" method="search"

# Exit if the image is not found,
if ({_EXIT_CODE} > 0) {
    Exit 1
}

For more information read the If/Else Statement and For Statement chapters.

1.6 If/Else Statement

VNCRobot v1.3 supports if/else statements with a similar functionality known from other programming languages. The general format is:

if (<boolean expression>) {
    <commands>
} else if (<boolean expression>) {
    <commands>
} else {
    <commands>
}

The 'else if' and 'else' branches are optional. While the number of 'else if' branches is not limited, there can be just one 'else' construction. Example:

# Look for an image on the remote desktop
Compareto "pattern.png" method="search"

# Exit if the image is not found,
if ({_EXIT_CODE} > 0) {
    Exit 1

# If the image was found more times, take a screenshot and add a warning to the HTML report
} else if ({_SEARCH_MATCH_COUNT} > 1) {
    Screenshot unexpected.png
    Warning "Unexpected behavior - the template image was found {_SEARCH_MATCH_COUNT} times!" image=unexpected.png
}

If/else statements can be nested and combined with other constructions like the for statement as is usual in any other structured language.

1.7 For Statement

VNCRobot v1.3 supports for statements which allows to iterate over a range of values or loop until a particular condition is satisfied. There are two general forms of the for statement.

1. Conditional For Statement
First variant of the for statement allows to execute until a boolean expression results true:

for (<statement1>; <boolean expression>; <statement2>) {
    <commands>
}

Statements statement1 and statement2 are evaluated using the Eval command and should have a syntax like '<variable>=<numeric expression>'. They can be also empty. The following examples are equivalent and loop for values of variable 'index' ranging from 0 to 5. Both code snippets will type '012345':

for (index=0; {index}<6; index={index}+1) {
    Type {index}
}

Eval index=0
for ( ; {index} < 6; ) {
    Type {index}
    Eval index={index}+1
}

2. For Statement Iterating over a Predefined Set of Values
This form allows to iterate over a predefined set of values:

for <variable name> in <list of space separated values> {
    <commands>
}

The following example will type a sentence "I speak English, Spanish, Brazilian Portuguese."

Type "I speak "
for language in English Spanish "Brazilian Portuguese" {
    if ("{language}" == "Brazilian Portuguese") {
        Type "{language}."
    } else {
        Type "{language}, "
    }
}

Execution of the for statement can be interrupted by a break command. If there are nested loops, the break command will always interrupt the innermost for statement. The following example illustrates how to use a combination of for and Waitfor to hold on execution until the remote desktop stops to update.

# Infinite loop
for (; 0 == 0; ) {

    # Wait for at least 20% update of the remote screen.
    # If it doesn't update for 10 seconds, break the loop.
    Waitfor update extent=20% timeout="10s" ontimeout="break"
}

1.8 Local Variables

As VNCRobot v1.3 introduces elements of structured programming into the scripting language, a concept of local variables was introduced. In versions 1.2 and older were all the variables global, i.e. every variable created through the Var command inserted into the global variable table and it was then accessible for the whole time of script execution.

Version 1.3 introduces a new variable model and distinguishes two variable types depending on where they are created in the code for the first time:
  1. Variables created in the main script body are considered to be global and they are accessible from the moment of creation until the end of script execution.
  2. Variables created within a structured block of code (procedure,if/else and for statements) are considered to be local and they are available only within the block of code.
The same rules are applied to files loaded using Include and Run commands.

A local variable cannot override a global one. This means that if you run a Var command in a block of code and the variable name matches an already existing global variable, you'll rather modify the global variable than define a local one with the same name. The following example demonstrates the principles.

# Create a global variable
Var GLOBAL=global

if (1 == 1) {

    # Create a local variable and change the value of GLOBAL to 'modified'
    Var LOCAL=local GLOBAL=modified

    if (1 > 0) {
        Var LOCAL2=local2

        # Here GLOBAL, LOCAL and LOCAL2 are available.
        # The command will type "GLOBAL=modified, LOCAL=local, LOCAL2=local2"
        Type "GLOBAL={GLOBAL}, LOCAL={LOCAL}, LOCAL2={LOCAL2}"
    }

    # Here GLOBAL and LOCAL are available and LOCAL2 doesn't exist any more.
    # The command will type "GLOBAL=modified, LOCAL=local, LOCAL2={LOCAL2}"
    Type "GLOBAL={GLOBAL}, LOCAL={LOCAL}, LOCAL2={LOCAL2}"

}

# Here GLOBAL is available and LOCAL and LOCAL2 don't exist any more.
# The command will type "GLOBAL=modified, LOCAL={LOCAL}, LOCAL2={LOCAL2}"
Type "GLOBAL={GLOBAL}, LOCAL={LOCAL}, LOCAL2={LOCAL2}"

Note that this new model may cause incompatibility with scripts created by VNCRobot 1.2 and older. If you need to preserve the old behavior and make all variables global, you can switch on the compatibility flags in the Scripting panel of the Preferences window.

1.9 Return Values

Since v1.3 all commands return an integer exit code which is available as a variable called _EXIT_CODE. Value of 0 (zero) usually means success while any other number indicates a failure. See documentation of particular commands for defined exit codes and their meanings.

Return values (also called "exit codes") can be effectively used to control the script execution and define how to handle both expected and unexpected results. The Compareto command e.g. returns 0 when image comparison passes and non-zero value otherwise. The Waitfor command returns 0 when the expected event is received and non-zero value when timeout is reached. The following example illustrates how to use these return values.

# Alt+F2 opens the Run Program window on Gnome
Press Alt+F2 wait=3s

# Start the Gnome Text Editor
Typeline gnome-text-editor

# Wait for the remote desktop update
Waitfor update extent=30% timeout="10s"

# If Waitfor returns non-zero value, the timeout was reached
# and the text editor probably failed to open
if ({_EXIT_CODE} > 0) {

    # Take a screenshot
    Screenshot failure.png

    # Send the screenshot via E-mail to the tester
    Sendmail to="tester@vncrobot.com" from="vncrobot@vncrobot.com" server="mail.vncrobot.com" subject="Gnome editor failed to open!" attach="{_REPORT_DIR}/failure.png"

    # Pause the execution and wait for the tester to fix it
    Pause "Paused because Gnome Text Editor failed to start"
}

Note that the if/else, for, break and procedure calls do not return any value.

2. Command Syntax


VNCRobot v1.3 supports the following commands:

2.1 Commands Representing RFB Client To Server Messages 2.2 Administrative & Execution Control Commands 2.3 Report Commands


2.1 Commands Representing RFB Client To Server Messages


2.1.1 Connect


DESCRIPTION
Connect - Connect to a VNC server. If a connection gets established, implicit variables _MACHINE and _DISPLAY are updated.

SYNOPSIS
connect <server[:display] | [::port]> [password=<password>] [force=<false|true>] [onpass=<command>][onfail=<command>]
* Red color indicates obligatory parameters

OPTIONS
server[:display]

- Server and an optional display or port number to connect to. When the remote VNC server listens e.g. on port 5901, the string is 'myserver:1' or 'myserver.mydomain.com:1' (using desktop numbers) or 'myserver::5901' or 'myserver.mydomain.com::5901' (using direct port). If no display number/port is passed, VNCRobot tries to connect to display number :0 (port 5900, typical for Windows). Default Unix/Linux port is typically 5901 (display :1).

password=<password>

- Password to authenticate to the VNC server. It is up to VNC server configuration whether a password is required or not. If server is configured not to require password, this parameter is ignored.

force=<false|true>

- If VNCRobot is already connected to the same server and display as is defined in the command, no reconnection is performed (force=false). If you want to force VNCRobot to terminate current connection and reconnect to the server,set this parameter to true. Default value is false.

onpass=<command>

- A command to be executed when VNCRobot successfuly connects to a server. It must be one single command. If you need to define a sequence of command to be executed, use a procedure.

onfail=<command>

- A command to be executed when VNCRobot fails to connect to a server. It must be one single command. If you need to define a sequence of command to be executed, use a procedure.

RETURNS
The command returns 0 (zero) on success or 1 when it fails to connect. VNCRobot 1.3.15 and higher returns a value of 10 when connection fails on an unsupported authentication method.

EXAMPLES
Connect localhost:1 password=test

- Connect to a VNC server running on display number 1 of the local machine and use the given password to authenticate. This is typical for Linux/Unix systems where port 5900 is usually occupied by X-Windows server and VNC servers usually occupy displays number 1 and higher.

Connect mywindows.companyxy.com::5902 password=mypassword force=true onfail="exit 2"

- Connect to a VNC server running on server called mywindows.companyxy.com. If VNCRobot is already connected to this server, terminate the session and reconnect. If connection fails, terminate execution of the script with an exit code 2.


2.1.2 Disconnect


DESCRIPTION
Disconnect - Disconnect VNCRobot from a VNC server. If there's no connection, the command is ignored. When the connection gets closed, implicit variables _MACHINE and _DISPLAY are cleared.

SYNOPSIS
disconnect

RETURNS
The command returns 0 (zero) on success or 1 when it fails to disconnect.

EXAMPLES
Disconnect

- Disconnect from a VNC server.


2.1.3 Press


DESCRIPTION
Press - Send a key to the VNC server. It is analogical to pressing a key on the keyboard.

SYNOPSIS
press [<modifier_1>+...+<modifier_N>+]<key | modifier> [count=<number>] [wait=<time>]

* Red color indicates obligatory parameters

OPTIONS
modifier

- Any combination of modifiers Shift, Alt and Ctrl separated by the plus '+' sign, e.g. 'Ctrl+Alt+Shift'. Modifier names are not case sensitive.

key

- Majority of key names corresponds to what is written on your keyboard, e.g. 'A', 'Insert', 'Tab' etc. Key names are not case sensitive. Complete list of supported keys is defined by the KeyEvent Java class. The Press command accepts any <key_name> key name for which the class defines a VK_<key_name> constant. VNCRobot also provides a window showing all supported key names. See Supported Keys Window.

count=<number>

- How many times the key should be sent. Default value is 1.

wait=<time>

- Time to wait after the events are sent. It has the same effect as if the following command was 'Wait <time_in_ms>'. This parameter is useful if the server needs some time to react on the pressed key/keys. A plain number is by default parsed as miliseconds. See the syntax of time values paragraph for more time formats.

RETURNS
The command returns 0 (zero) on success or 1 when it fails.

EXAMPLES
Press Ctrl+Alt+Del

- Send the Ctrl+Alt+Del key combination to the VNC server.

Press Tab count=5 wait=2s

- Simulate pressing of the Tab key five times and then wait for two seconds before proceeding to the next command.

Var KEY_TO_PRESS=Alt+F4
<...>
Waitfor update area=x:340,y:220,w:240,h:160 extent=80% timeout=10s ontimeout="Var KEY_TO_PRESS=Right"
Press {KEY_TO_PRESS} wait=2s

- This example illustrates how to solve the unwanted popup windows. If a window pops up at the given coordinates, the 'Press {KEY_TO_PRESS}' command ensures that it gets closed using Alt+F4. If the window doesn't show up, the Alt key gets pressed which usually doesn't cause any harm to the window.

2.1.4 Type, Typeline


DESCRIPTION
Type, Typeline - Send a text to the VNC server. These two commands are analogical to typing the text on user keyboard. Typeline is just a convenience command which types the text and then presses Enter, i.e. it has the same effect as a combination of 'Type <text>' and 'Press Enter'.

SYNOPSIS
type <text> [wait=<time>] [count=<number>]
typeline <text> [wait=<time>] [count=<number>]
* Red color indicates obligatory parameters

OPTIONS
text

- Text to type. If the text contains spaces or equal signs '=', it must be enclosed in double quotes, e.g. "This is a text containing spaces". If you need to include the double quote character into your text, place a leading backslash before it, e.g. "This is double quote - \"". If you need to display a backslash followed by a double quote, use '\\"', e.g. "This is a backslash followed by a double quote - \\"".

Please note that multibyte characters (i.e. characters of national alphabets) outside the Latin-1 (ISO8859-1) code page can't be used because they are currently not supported by the RFB protocol.

wait=<time>

- Time to wait after the text is typed. It has the same effect as if the following command was 'Wait <time_in_ms>'. This parameter is useful if the server needs some time to react on the pressed key/keys. A plain number is by default parsed as miliseconds. See the syntax of time values paragraph for more time formats.

count=<number>

- How many times the command should be repeated. Default value is 1.

RETURNS
The command returns 0 (zero) on success or 1 when it fails.

EXAMPLES
Type hello

- Type 'hello'.

Typeline "mkdir /usr/vncrobot" wait=2s

- If you run this in an active Linux/Unix terminal window, it will invoke the 'mkdir /usr/vncrobot' OS command and wait for two seconds before proceeding to the next command.


2.1.5 Mouse


DESCRIPTION
Mouse - Generate a mouse event. This command can simulate a wide range of mouse actions like mouse pointer movement, mouse click, press, release or even a drag.

SYNOPSIS
mouse [<modifier_1>+...+<modifier_N>+]<event_id> [btn=<button_name>] [to=[x:<x>][,y:<y>]] [from=[x:<x>][,y:<y>]] [count=<number>] [wait=<time>]
* Red color indicates obligatory parameters

OPTIONS
modifier

- Any combination of modifiers Shift, Alt and Ctrl separated by the plus '+' sign, e.g. 'Ctrl+Alt+Shift'.

event_id

- Supported event IDs are 'move', 'click', 'press', 'release' and 'drag'.

btn

- This parameter is used to identify the mouse button to click or drag with. Allowed values are 'left', 'middle' and 'right'.

to=[x:<x>][,y:<y>]

- Destination coordinates.

The coordinates have format of 'x:<x>,y:<y>', where each coordinate can be specified in pixels (e.g. 'x:225') or as a percentage (e.g. 'x:23%'). If x or y is omitted, the current mouse pointer location will be used to determine the missing coordinate.

from=[x:<x>][,y:<y>]

- Start coordinates.

The coordinates have format of 'x:<x>,y:<y>', where each coordinate can be specified in pixels (e.g. 'x:225') or relatively as a percentage (e.g. 'x:23.5%'). Relative coordinates are rounded if they are not integer. If x or y is omitted, the current mouse pointer location will be used to determine the missing coordinate.

count=<number>

- How many times the mouse event should be sent. Default value is 1. This value makes sense only with the click event.

wait=<time>

- Time to wait after the events are sent. It has the same effect as if the following command was 'Wait <time>'. A plain number is by default parsed as miliseconds. See the syntax of time values paragraph for more time formats.

RETURNS
The command returns 0 (zero) on success or 1 when it fails.

EXAMPLES
Mouse click count=2

- Perform a mouse double click at the current mouse pointer coordinates.

Mouse move to=x:25,y:122

- Move the mouse pointer to the given coordinates

Mouse drag from=x:10%,y:450 to=x:22.5%,y:450 wait=2s

- Drag the mouse pointer from the given start position to the destination position and wait for two seconds. The x coordinate is given in the relative form. If your display resolution is e.g. 800x600 pixels, the 'x:10%' will be equal to 'x:60' and 'x:22.5%' will be 'x:135'.


2.2 Administrative & Execution Control Commands


2.2.1. Var


DESCRIPTION
Var - Define a script variable. Variables can be used in all other commands where dynamic content is needed. VNCRobot will replace in all commands all occurencies of '{<var_name>}' with the <var_name> variable value. Variable names are case sensitive. Variable values may contain any Latin-1 characters. 

A typical example can be:

Var PATH=/tmp
Typeline "mkdir -p {PATH}; cd {PATH}"

Please note that if a variable is not defined, no replacement is done and the following example will rather type 'cd {PATH}' than 'cd ':

# Var PATH=/tmp
Typeline "cd {PATH}"


Variable values may be overrided in script executions through CLI. See the -v parameter specified in the VNCRobot 1.3 CLI Options document. Redefinition of a variable from CLI makes the variable 'read only' and fixes its value for the whole time of script execution. All commands modifying this variable executed in the script will be ignored.

VNCRobot formerly used regular expressions for variable substitution until version 1.2.5. Version 1.3 and higher use plain text processing and version 1.3.4 also added support of nested variables (see the paragraph describing this further on). There are options in the Preferences window which allow you to disable these new feature and switch back to the 1.2.x compatibility mode. If you do so, avoid using regexp special characters in the variable names. If you are not familiar with regular expressions, use just alphabet characters ('a'-'z', 'A'-'Z'), numbers ('0'-'9') and underscore ('_') in your variable names.

Also do not use variable name consisting of plain numbers, e.g. 'Var 1="test"'. These variables are reserved for procedure parameters. VNCRobot will not report any violation of this rule and rewrite the variables once a procedure is executed.

VNCRobot version 1.3.4 introduces support of nested variables. This functionality is necessary to process multiple matches of the 'search' image comparison method where coordinates of the matches are stored as _SEARCH_X_<number> and it is necessary to generate the variable names dynamically in a loop. The following example illustrates such a usage: Let's suppose that you are searching the remote desktop image for an icon and you want to click onto each of the occurencies.

Compareto "search.png" method="search"

for (i=1; {i}<{_SEARCH_MATCH_COUNT}+1; i={i}+1) {
  # Nested variables compose the variable names of a suffix and an index
  Mouse click to=x:{_SEARCH_X_{i}},y:{_SEARCH_Y_{i}}
}

Variables starting with underscore ('_') are predefined variables. They are typically provided by VNCRobot or by its commands and contain useful values providing information about the execution context. They are not processed in any special way so you are free to use them and modify them as you wish. A table of the most important ones follows.

Who Creates and When Variable Name Description
VNCRobot when
a ServerCutText RFB
message is received
_SERVER_CLIPBOARD_CONTENT
Content of the remote desktop clipboard. Note that it may
contain only Latin-1 characters. This variable is typically used together
with the Waitfor clipboard command.
VNCRobot when
a script execution
is started.
_DATE=<yyyyMMdd> Date of the execution start in the "yyyyMMdd" format.
E.g. May 8, 2005 will be defined as "20050508".
_TIME=<HHmmss> Time of the execution start in the "HHmmss" 24-hrs. format.
E.g. 3:10:33 pm will be defined as "151033".
_FILE=<file> Absolute path of the executed script, e.g. "/root/test.txt".
_FILENAME=<filename>
Script file name, e.g. "test.txt".
_REPORT_DIR=<path>
Target directory for screenshots and reports. It is set to
your home directory by default. All screenshots and reports
will be saved there unless they are specified via absolute path.
_TEMPLATE_DIR=<path>
Source directory containing template images for image comparison.
Default value is the user home directory.
_SCRIPT_DIR=<path>
Directory where the currently executed script is located (absolute path).
_WARNING_COUNT=<number>
Number of warnings which have been generated by the Warning
command during the script execution.
VNCRobot whenever
the variable is used.
_CURTIME=<time_in_miliseconds>
Whenever this variable is used, it is dynamically replaced by
the current system time in miliseconds since midnight
of January 1, 1970 UTC. You may use this variable to calculate
how long a command or a block of commands took to execute or
to measure performance of the remote system.
VNCRobot when
a script execution
is started. Also updated by
Connect and Disconnect
commands.
_MACHINE=<servername> VNC server machine name to which VNCRobot is connected.
The variable is empty if there is no VNC connection.
_DISPLAY=<servername>:[<display#>] Display variable which is useful for display redirection
on Unix/Linux systems. It is in the "server:port" format,
e.g. "mymachine:2" defines a machine called 'mymachine'
running a VNC server on port 5902.
The variable is empty if there is no VNC connection.
_DESKTOP_WIDTH=<width_in_pixels> Width of the currently connected remote desktop (in pixels).
_DESKTOP_HEIGHT=<width_in_pixels> Height of the currently connected remote desktop (in pixels).
Waitfor command
when an update event
complying with
the given criteria occurs
_X=<number_in_pixels>
The 'x' coordinate of the last update event that met the criteria.
_Y=<number_in_pixels> The 'y' coordinate of the last update event that met the criteria.
_W=<number_in_pixels> The 'width' coordinate of the last update event that met the criteria.
_H=<number_in_pixels> The 'height' coordinate of the last update event that met the criteria.
Waitfor command after
every execution
_TIMEOUT=true | false If timeout is defined and reached, the Waitfor command will set
this variable to 'true', otherwise to 'false'.
Report command
whenever a report gets
generated
_REPORT_FILE=<file> Report file (absolute path), e.g. '/root/report.html'.
_REPORT_FILENAME=<filename> Report file name, e.g. 'report.html'.
Compareto command,
Screenshot
comparisons and
'Waifor match' calls
_COMPARETO_TEMPLATE=<file>
Image file (absolute path) used for last image comparison.
_COMPARETO_RESULT=<number>
Comparison result percentage. It is always a number between 0
and 100. It indicates how much the images matched.
_COMPARETO_PASS_RATE=<number>
Pass rate percentage used for the last image comparsion. It is
always a number between 0 and 100.
Compareto command,
Screenshot
comparisons and
'Waifor match' calls
when "search" comparison
method is used
_SEARCH_MATCH_COUNT=<number>
Number of matches found. It is always an integer greater than
or equal to zero.
_SEARCH_X=<number_in_pixels> The 'x' coordinate of the first match. If the template image was
not found, the value is -1.
_SEARCH_Y=<number_in_pixels> The 'y' coordinate of the first match. If the template image was
not found, the value is -1.
_SEARCH_X_<n>=<number_in_pixels>
_SEARCH_Y_<n>=<number_in_pixels>
The 'x' and 'y' coordinates of the n-th match where n is between
1 and value of _SEARCH_MATCH_COUNT.
Exec command after
every execution
_EXEC_OUTPUT=<text>
Standard output of the executed command, i.e. messages which
are printed into the console.
_EXEC_ERROR=<text> Error output of the executed command, i.e. error messages which
are printed into the console.
_EXEC_COMMAND=<command> Last executed OS command, i.e. the Exec argument.
_EXEC_VALUE=<integer>
Exit code of the executed OS command.

You may use the Variable Browser window to view the list of variables which are present in the current execution repository.

SYNOPSIS
var <var_name_1>=<value_1> [<var_name_2>=<value_2> ... <var_name_N>=<value_N>]
* Red color indicates obligatory parameters

OPTIONS
var_name

- A name for the variable. The name is case sensitive and must not contain spaces.

value

- Variable value. If the value contains spaces, it must be enclosed in double quotes, e.g. "This is a text containing spaces". If you need to include the double quote character into your variable value, place a leading backslash before it, e.g. "This is double quote \"". If you need to include a backslash followed by a double quote, use '\\"', e.g. "This is a backslash followed by a double quote - \\"".

RETURNS
The Var command always returns 0 (zero).

EXAMPLES
Var PATH=/tmp path=/tmp DESCRIPTION="Path to change to" EMPTY=

- Create four variables PATH, path, DESCRIPTION and EMPTY with the given values.

Compareto "search.png" method="search"

for (i=1; {i}<{_SEARCH_MATCH_COUNT}+1; i={i}+1) {
  # Nested variables compose the variable names of a suffix and an index
  Mouse click to=x:{_SEARCH_X_{i}},y:{_SEARCH_Y_{i}}
}

- Search the remote desktop image for an icon represented by the template image search.png and click onto each of the occurencies.

2.2.2. Eval


DESCRIPTION
Eval - Define a script variable where the value is evaluated as numeric expression. See the Numeric Expressions chapter of this manual for more info. The behavior is otherwise exactly the same as the Var command.

SYNOPSIS
eval <var_name_1>=<numeric_expression_1> [<var_name_2>=<numeric_expression_2> ... <var_name_N>=<numeric_expression_N>]
* Red color indicates obligatory parameters

OPTIONS
var_name

- A name for the variable. The name is case sensitive and must not contain spaces.

numeric_expression

- A numeric expression. If the expression contains spaces, it must be enclosed in double quotes, e.g. "1 + 1". See the Numeric Expressions chapter of this manual for more info on expression syntax and supported numeric operators.

RETURNS
The Eval command always returns 0 (zero).

EXAMPLES
Eval POSITION=2*(10+1)

- Create a variable POSITION with a value of 22.


2.2.3 Include


DESCRIPTION
Include - Include another script. This will load ONLY procedures and variables from the script into the execution context. Use this command to link libraries containing globally used variables and procedures.

The name of the included file can be also specified dynamically through a variable. This allows to configure the script with e.g. variables or procedures from another file which can be passed via the '-v' CLI command.

SYNOPSIS
include <file>
* Red color indicates obligatory parameters

OPTIONS
file

- A file to be included. File name can be either relative (e.g. sayHello.txt) or absolute (e.g. /root/scripts/sayHello.txt). VNCRobot will check if the file exists and is readable during every script validation and report an error if not. The file can be also specified via a variable (see examples).

RETURNS
The command always returns 0 (zero). If the specified file is not found, VNCRobot reports a syntax error rather than returning a non-zero return value.

EXAMPLES
Include sayHello.txt

- Load all variables and procedures from a script called sayHello.txt which is located in the same directory as the script calling this command.


Include /root/scripts/sayHello.txt

- Load all variables and procedures from a script called sayHello.txt which is located in the /root/scripts/ directory.


Var PROFILE=
profile1.txt
Run {PROFILE} - Include a script specified by a variable. If you have more scripts with different configurations, you may then include another script from CLI using '-v PROFILE=profile2.txt'.


2.2.4 Run


DESCRIPTION
Run - Execute another script. VNCRobot will process its commands as if they were written in the calling script, which means that all procedures, variables, screenshots and report generators defined by the executed script will remain in the execution repository and can be accessed once the Run command finishes.

Run commands can be effectively used to implement generic snippets of code (libraries) or to separate test code of individual test cases. Exit command with scope set to file can be used to return from a script executed through Run to the main script.

SYNOPSIS
run <file>
* Red color indicates obligatory parameters

OPTIONS
file

- A file to be executed. File name can be either relative (e.g. sayHello.txt) or absolute (e.g. /root/scripts/sayHello.txt). VNCRobot will check if the file exists and is readable during every script validation and report an error if not. The file can be also specified via a variable (see examples).

RETURNS
Run always returns the code returned by the last executed command. If the specified file is not found, VNCRobot reports a syntax error rather than returning a non-zero return value.

EXAMPLES
Run sayHello.txt

- Execute a script called sayHello.txt which is located in the same directory as the script calling this command.


Run /root/scripts/sayHello.txt

- Execute a script called sayHello.txt which is located in the /root/scripts/ directory.


Var SCRIPT_TO_EXECUTE=
sayHello.txt
Run {SCRIPT_TO_EXECUTE}

- Execute a script specified by a variable.



2.2.5 Pause


DESCRIPTION
Pause - Pause the script execution. If VNCRobot is executing in GUI mode, the Pause button/menu item get selected and user can deselect the button or the menu item to resume the execution. If the script is being executed in CLI mode, a message is printed out into the console and user can press a key to resume the execution.

The Pause command can be used e.g. to pause execution when a runaway behavior is detected. Though the usual way is to exit the script with an error exit code (e.g. 'Exit 1'), some test suites may prefer to send an E-mail to the responsible person, pause the execution and wait for human help.

SYNOPSIS
pause <description>

OPTIONS
description

- Optional description of the reason why the script was paused. This description will be displayed in the report (if defined) and printed out to the console in case of CLI mode execution.

RETURNS
The command always returns 0 (zero).

EXAMPLES
Compareto "application.png"

if ({_EXIT_CODE} > 0) {

    # Cry for help - send a screenshot via E-mail and pause
    Screenshot runaway.png
    Sendmail to="tester@vncrobot.com" from="vncrobot@vncrobot.com" server="mail.vncrobot.com" subject="
Runaway behavior detected - see attached picture. Please help!" attach="{_REPORT_DIR}/runaway.png"
    Pause "Runaway behavior detected"
}

- When image comparison fails, send a screenshot by E-mail to the tester and pause the execution.



2.2.6 Exit


DESCRIPTION
Exit - Terminate the script, procedure or structured block of code and return an exit code. If an exit command with the 'process' scope is called during script execution, it will terminate VNCRobot and return the indicated exit code to the underlying operating system. See documentation on VNCRobot CLI Options and its automatic script execution examples for more information.

SYNOPSIS
exit  <exit_code_number>  [scope=<process|file|procedure|block>]

OPTIONS
exit_code_number

- Exit code. It must be an integer. A value of zero is usually used to indicate success while non-zero values indicate an error or unexpected result or behavior. If the command is used to terminate VNCRobot, the exit code is passed to the underlying operating system and can be used to identify the reason of the script termination.

scope=<process|file|procedure|block>

- Controls the scope of the exit command. The default value is process which terminates the script execution and the JVM (Java Virtual Machine).

The file value terminates the currently executed file. If a script is being executed from another script using the Run command, only the called script is terminated and control is returned to the master script.

The procedure value exits from the innermost procedure. If no procedure is executed, the Exit command is ignored.

The block value exits from the innermost structured block of code, i.e. one of the if/else of for statements. If the command gets called out of any such a statement, it is ignored.

RETURNS
The command returns the exit code which is specified as its argument.

EXAMPLES
Exit 10

- Terminate the executed script and return 10 as the exit code.

Typeline myapplication
Waitfor update extent=40% timeout=20s ontimeout="Exit 2"

- This is a typical usage of the Exit command. It shows a situation when you start a GUI application called myapplication from a terminal window. Let's suppose that the myapplication window has a fixed size equal to at least 40% of the screen size. If the GUI starts properly, the script will continue. The Waitfor command will otherwise wait for 20 seconds and then terminate the test script with an exit code of 2.


2.2.7 Wait


DESCRIPTION
Wait - Wait for a specified amount of time. Use this command to pause the script execution for a specified period of time.

SYNOPSIS
wait <time>
* Red color indicates obligatory parameters

OPTIONS
time

- Time to wait before proceeding to the next command. It must be a number greater than zero. A plain number is by default interpreted as miliseconds. See syntax of time values for specification of time formats.

RETURNS
The command always returns 0 (zero).

EXAMPLES
Wait 30000

- Wait 30 seconds before proceeding to the next command. The command can be also written as 'Wait 30s' or 'Wait 0.5m'.

2.2.8 Waitfor


DESCRIPTION
Waitfor - Pause execution of a script and wait for an RFB event or state of the remote desktop image. Currently supported events are screen update (i.e. RFB message FramebufferUpdate), bell (RFB message Bell), delivery of text copied on the remote system (RFB message ServerCutText; not working correctly on all VNC servers) and match (waiting for a positive or negative image comparison result).

Please note that this command inserts some specific variables into the execution context. 'Waitfor match' in addition performs image comparison which modifies image comparison specific variables in the execution context.

SYNOPSIS
Waitfor <event_id> [<specific options>] [timeout=<time>] [ontimeout=<command>] [onpass=<command>] [count=<number>] [wait=<time>]
* Red color indicates obligatory parameters

event_id

- Supported event IDs are 'bell', 'update', 'match' ,'mismatch' and 'clipboard'.

NOTE: There's currently no other way how to send text from the server to client. It is likely to be provided in one of the future versions.

COMMON OPTIONS

timeout=<time>

- Timeout specifying how long to wait at maximum. A plain number is by default parsed as miliseconds. See the syntax of time values paragraph for more information on time formats. Note that the Waitfor command typically offers a menu item 'Continue' in the VNCRobot editor context menu which enables user to interrupt execution of the Waitfor command and resumes execution of the script. Such a user action is considered as if the required event happened successfuly. This affects execution of the commands defined by parameter onfail (will not be executed) and onpass (will be executed).

ontimeout=<command>

- A command to be executed when the timeout is reached. It must be one single command. If you need to define a sequence of command to be executed, use a procedure. See the example section below.

onpass=<command>

- A command to be executed when the the condition is met (i.e. expected update or bell is received). It must be one single command. If you need to define a sequence of command to be executed, use a procedure.

count=<number>

- How many events to wait for. Default value is 1. This parameter is ignored if used with 'Waitfor match'.

wait=<time>

- Time to wait after the Waitfor condition is met. It has the same effect as if the following command was 'Wait <time_in_ms>'. This parameter is ignored if the timeout defined by the timeout parameter is reached. A plain number is by default parsed as miliseconds. See the syntax of time values paragraph for more time formats.


Waitfor bell [<common options>]

SPECIFIC OPTIONS - BELL

None.


Waitfor update
[area=[x:<x>][,y:<y>][,w:<width>][,h:<height>]] [extent=<number>[%]] [cumulative=<false|true>][<common options>]

SPECIFIC OPTIONS - UPDATE

area=[x:<x>][,y:<y>][,w:<width>][,h:<height>]

- Screen area of interest. This parameter is applicable only to the update event and enables user to define a custom area and watch it for updates. The area coordinates have format of 'x:<x>,y:<y>,w:<width>,h:<height>', where each coordinate can be specified in pixels (e.g. 'x:225') or as a percentage (e.g. 'x:23%'). If any of x, y, width or height is omitted, VNCRobot will use the full screen values to determine the missing parameters, i.e. 'x:0, y:0, w:<screen_width>, h:<screen_height>'. You may also define the update area using the status bar Update Coordinates feature.

extent=<number>[%]

- Extent of the screen update. This parameter is applicable only to the update event and defines how large the screen update must be. The value can be either a number of updated pixels (e.g. 'extent=400') or percentage (e.g. 'extent=22%'). If a custom area is defined by the area parameter, the percentage/pixel value will be computed against this area.

cumulative=<false|true>

- Switches on/off cumulative updates. If your VNC server prefers gradual screen updates and sends many small updates instead of a larger expected one, switch this feature on and VNCRobot will sumarize all partial updates falling into the defined area. The default value is false.


Waitfor match | mismatch
[template=<template_image_file>] [passrate=<pass_rate>%] [interval=<comparison_interval>] [method=<comparison_method>] [methodparams=<custom_params>] [cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]] [<common options>]
* Template file is obligatory only if it is required by the selected image comparison algorithm. Both two algorithms provided by VNCRobot v1.3 DO require a template file.

SPECIFIC OPTIONS - MATCH AND MISMATCH

template=<template_image_file>

- File name of the template image which will be compared to the remote desktop image. File name can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. Please note that it is not a good idea to perform image comparison against images with lossy compression like e.g. JPEG. Use PNG for your template image files instead which preserves 100% of the image information and guarantees reliable and stable comparison results. Image comparison method is discussed in the Compareto command specification.

passrate=<pass_rate>%

- Pass rate for image comparison. This parameter is applicable only to the match and mismatch events. It must be a number followed by the percentage character (e.g. 'passrate=95%'). If this parameter is omitted, default value defined in user preferences is applied. This default value can be configured in the Compareto preferences panel of the Preferences window.

interval=<time>

- This parameter defines time interval for image comparisons. This parameter is applicable only to the match event. If you set it e.g. to 2 seconds, the desktop image will be compared against the given template image every 2 seconds. A plain number is by default parsed as miliseconds. See the syntax of time values paragraph for more time formats. If this parameter is omitted, default value defined in user preferences is applied. This default value can be configured in the Compareto preferences panel of the Preferences window.

method=<comparison_method>

- Algorithm to be used for image comparison. If omitted, VNCRobot will use the default algorithm defined by a parameter in the configuration file. VNCRobot 1.3 provides two image comparsion algorithms. You may also write your own one using the VNCRobot 1.3 Open API.

methodparams=<custom_params>

- Custom parameters to be passed to the image comparison algorithm. As VNCRobot 1.3 default image comparsion algorithms don't support any custom parameters, you don't need to specify this parameter unless you write your own algorithm using the VNCRobot 1.3 Open API.

cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]

- Custom comparison area. You can specify here the area of the remote desktop to be compared to a template. If you omit this parameter, the whole remote desktop will be used. The area coordinates have format of 'x:<x>,y:<y>,w:<width>,h:<height>', where each coordinate can be specified in pixels (e.g. 'x:225') or as a percentage (e.g. 'x:23%'). If any of x, y, width or height is omitted, VNCRobot will use the full screen values to determine the missing parameters, i.e. 'x:0, y:0, w:<screen_width>, h:<screen_height>'. You may also define the comparison area using the Waitfor window.

Waitfor clipboard [<common options>]

SPECIFIC OPTIONS - CLIPBOARD

None.


RETURNS
The command generally returns 0 (zero) when the condition (event) is met. Non-zero value (usually 1) is returned when the timeout is reached. 'Waitfor match' and 'Waitfor mismatch' mimick behavior of the Compareto command and return 0 (zero) when the comparison passes, 1 when it fails and 2 when the template image is not found or cannot be read.

EXAMPLES
Typeline "export MYDOC=`find / -name mydoc.txt`; sleep 1; echo -e '\007\007'"
Waitfor bell count=2
Typeline "gnome-text-editor $MYDOC"

- This is a typical example on how to use the bell event on a Unix/Linux system. Let's suppose that you need to find a file on your hard drive and edit it. The first command will run the search in a terminal window and proceed to the Waitfor command. Once the search finishes, two bell characters are printed using the echo OS command and your machine beeps twice. This will cause the Waitfor command to proceed and run the third command which will open the document in a Gnome text editor.

Please note the 'sleep 1' command in the first line. If your VNC server is very fast and your machine running VNCRobot is somewhat slower, it may happen that the document search finishes before VNCRobot manages to proceed to the Waitfor command. The 'sleep 1' prevents this problem because the server will wait 1 second before printing the two bell characters.

procedure terminate {
    Screenshot error.jpg
    Report report.html
    Exit {1}
}
Typeline myapplication
Waitfor update extent=40% timeout=20s ontimeout="terminate 2"

- This is a typical usage of the 'Waitfor update' command. It shows a situation when you are starting a GUI application called myapplication from a terminal window. Let's suppose that the application window has a fixed size equal to at least 40% of the screen size. If the GUI starts properly, the script will continue. The Waitfor command will otherwise wait for 20 seconds and then will run the exit procedure with the given exit code.

Waitfor match template=application.png passrate=95% interval=5s timeout=5m ontimeout="exit 1"

- Compare the remote desktop image to image application.png every 5 seconds until there's at least 95% match. If this condition is not met within 5 minutes, terminate the script execution using the Exit command and return exit code 1.


Press Ctrl+C
Waitfor clipboard timeout=5s
if ({_EXIT_CODE} == 0) {
  Screenshot copied_text.jpg desc="Received text copied on the remote desktop: {_SERVER_CLIPBOARD_CONTENT}"
}

- Pressing of Ctrl+C on the remote desktop typically copies selected text to the remote system clipboard. Some VNC servers are capable of sending this text to the clients. VNCRobot can decode such a message and provide the text into the script in form of the _SERVER_CLIPBOARD_CONTENT variable. The example above shows how to verify reception of the copied text through Waitfor clipboard and how to use it e.g. in description of a screenshot.


2.2.9 Compareto


DESCRIPTION
Compareto - The Compareto command is intended to compare the current remote desktop image to an image stored in a file using a specified image comparison method and perform an action when the comparison passes or fails. If you want to display the comparison result in the HTML report generated by the Report command, use Screenshot. If you want to wait until the screen matches your template image, use 'Waitfor match'. Both Screenshot and 'Waifor match' commands use the methods of the Compareto command internally and support the same parameters.

Version 1.3 contains two simple image comparison algorithms named default and search. You may take advantage of the VNCRobot 1.3 Open API to write your own image comparison module and plug it into VNCRobot.

Aspects of image comparison with VNCRobot are also discussed in a separate document called How To Use Image Comparison.

1. Comparison Method 'default'
This is the default image comparison method. It is based a very simple color histogram algorithm. Both images are processed pixel by pixel and number of pixels of the same color is counted. The color counters are then compared and a sum of different colors is generated. The sum is then divided by the total pixel count to get the comparison ratio.

Let's suppose you are comparing to an image of 100x100 pixels (total of 10,000 pixels). There are 3,000 pixels of red, 3,000 pixels of green and 4,000 pixels of black color. Your desktop image contains just 5,000 red and 5,000 black pixels. The sum of differences is counted as (5000 red - 3000 red) + (4000 black - 5000 black) + 3000 green, which results in 4000 different pixels. The computed comparison rate is then 60% (6,000/10,000) which actually indicates that the images have 6,000 pixels of the same color.

Though this is a very primitive comparison algorithm, it is sufficient e.g. in cases when you need to verify whether the desktop displays correct application. If you have a solid color desktop background, this algorithm is also quite robust in terms of changes in window positions because it doesn't affect the color histogram. To have reliable comparison results:
2. Comparison Method 'search'
This method searches the remote desktop or its part for an image, usually and icon or a fragment of the remote desktop. A plain pixel comparison is used. Coordinates of the found instances are then provided through variables _SEARCH_MATCH_COUNT, _SEARCH_X and _SEARCH_Y. See the table of implicit variables in the Var command chapter.

The older implementation of this module was not able to handle the passrate option. It was always looking for an exact pixel-by-pixel match regardless of the desired pass rate. This behavior was changed in VNCRobot 1.3.6 and the new implementation is able to search even for image occurencies which have a certain amount of pixels different from the template image. The pass rate is newly converted to a number of pixels (template_pixel_count * (1 - passrate)) and the remote desktop image is searched for all instances having a number of different pixels lower than or equal to this number. If your template image size is e.g. 100x100 pixels and you specify 99% pass rate, VNCRobot will find all areas of remote server desktop having up to 100 different pixels. Note that the lower pass rate you specify, the lower the performance will be and the longer the search will take.

The method returns 100% match if at least one instance of the template image is located and 0% if it is not found. Note that the number of occurencies is limited by a parameter in the Compareto command preferences which can be customized in the VNCRobot Preferences window.

This method is quite useful for remote desktop verification. If you want to verify that it displays a correct window, cut a unique piece of the window image, save it to a template file and than use the search comparison method to find it on the screen. Another way to use this algorithm is to get coordinates of a button with an icon before clicking it.

SYNOPSIS
compareto <image> [passrate=<pass_rate>%] [onpass=<command>] [onfail=<command>] [method=<comparison_method>] [methodparams=<custom_params>] [cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]]
* Red color indicates obligatory parameters

OPTIONS
image

- File name of the template image which will be compared to the remote desktop image. Supported image formats are PNG, JPG, GIF and BMP. File name can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. This variable allows you to define a common repository of template images.

passrate=<pass_rate>%

- Pass rate for image comparison. It must be a number followed by the percentage character (e.g. 'passrate=95%'). If this parameter is omitted, default pass rate defined in the VNCRobot preferences will be used (default values are 95% for the 'default' and 100% for the 'search' methods). You may customize these default values in the VNCRobot Preferences window.

onpass=<command>

- A command to be executed when VNCRobot successfuly connects to a server. It must be one single command. If you need to define a sequence of command to be executed, use a procedure or branch the code using the if/else statement.

onfail=<command>

- A command to be executed when VNCRobot fails to connect to a server. It must be one single command. If you need to define a sequence of command to be executed, use a procedure.

method=<comparison_method>

- Algorithm to be used for image comparison. If omitted, VNCRobot will use the default algorithm defined by a parameter in the configuration file. You may customize this parameter in the VNCRobot Preferences window. VNCRobot 1.3 provides two image comparsion algorithms, 'default' and 'search'. You may also write your own one using the VNCRobot 1.3 Open API.

methodparams=<custom_params>

- Custom parameters to be passed to the image comparison algorithm. As VNCRobot 1.3 default image comparsion algorithms don't support any custom parameters, you don't need to specify this parameter unless you write your own algorithm using the VNCRobot 1.3 Open API.

cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]

- Custom comparison area. You can specify here the area of the remote desktop to be compared to a template. If you omit this parameter, the whole remote desktop will be used. The area coordinates have format of 'x:<x>,y:<y>,w:<width>,h:<height>', where each coordinate can be specified in pixels (e.g. 'x:225') or as a percentage (e.g. 'x:23%'). If any of x, y, width or height is omitted, VNCRobot will use the full screen values to determine the missing parameters, i.e. 'x:0, y:0, w:<screen_width>, h:<screen_height>'. You may also define the comparison area using the Compareto window.

RETURNS
The command returns 0 (zero) when the comparison passes, 1 when it fails and 2 when the template image is not found or cannot be read.

EXAMPLES
Compareto netscape.png passrate=95% onfail="exit 1"

- Compare the image of the current remote desktop to image netscape.png. If there is not at least 95% match, terminate the script execution using the Exit command and return exit code 1.

Compareto button.png method=search
if ({_EXIT_CODE} == 0) {
  Mouse click to="x:{_SEARCH_X}+5,y:{_SEARCH_Y}+5"
}

- Search the remote desktop image for a button (template image button.png). If it is found, click on it. Note that we add 5 pixels to the x and y coordinates to make sure you click in the middle of the button.

Compareto "search.png" method="search"

for (i=1; {i}<{_SEARCH_MATCH_COUNT}+1; i={i}+1) {
  # Nested variables compose the variable names of a suffix and an index
  Mouse click to=x:{_SEARCH_X_{i}},y:{_SEARCH_Y_{i}}
}

- Search the remote desktop image for an icon represented by the template image search.png and click onto each of the occurencies.

2.2.10 Exec


DESCRIPTION
Exec - Execute an OS command on the local system (i.e. on the machine which runs VNCRobot). The argument must be a single command, e.g. 'ls -l' on Unix/Linux. Pipes and redirection of the output are not allowed. If you need to save the output to a file, use the outfile parameter.

If you need to execute a Windows command which is provided by the command line interpreter, you need to specify the interpreter in the Exec command. This applies to commands like dir, cd,copy,md,mkdir,rd,rmdir,del,erase etc. A complete list of commands depends on the Windows system and is available at the Microsoft site. Another good source is the COMMAND.COM page at Twikipedia. An example of running 'dir' on Windows would then look like:

Exec "command.com /C dir"

Exec command inserts four values into the variable table. They are _EXEC_COMMAND (last executed OS command), _EXEC_ERROR (error output), _EXEC_OUTPUT (standard output) and _EXEC_VALUE (OS command exit code). See the table of implicit variables in the Var command chapter.

SYNOPSIS
exec <command> [count=<number>][onpass=<command>] [onfail=<command>] [outfile=<file_name>] [wait=<time>]
* Red color indicates obligatory parameters

OPTIONS
command

- OS command to be executed on the local system.

count=<number>

- How many times to execute the command. The default value is 1.

onpass=<command>

- A VNCRobot command to be executed if the execution succeeds (i.e. exit code 0 is returned). It must be one single command. If you need to define a sequence of command to be executed, use a procedure or an if/else construction based on the Exec command return value.

onfail=<command>

- A VNCRobot command to be executed if the execution fails (i.e. non-zero exit code is returned). It must be one single command. If you need to define a sequence of command to be executed, use a procedure or an if/else construction based on the Exec command return value.

outfile=<file_name>

- File name to save the command output to. If you specify just the file name, it will be created in the current directory.

wait=<time>

- Time to wait after the command is executed.

RETURNS
The command returns 0 (zero) if the command is successfuly executed or the exit code of the OS command otherwise.

EXAMPLES
Exec "ls -l"

- List the contents of the current directory (Unix/Linux).

Exec "date"
Screenshot image.png desc="This screenshot was taken on {_EXEC_OUTPUT}."

- Use the date OS command to insert a time stamp into a screenshot description (Unix/Linux).

Exec "C:\Program Files\Internet Explorer\iexplore.exe http://www.google.com"
Exec "rundll32 url.dll,FileProtocolHandler http://www.google.com"

- Both commands should start Internet Explorer on Windows and open the Google site.

Report index.html
Exec "mozilla file://{_REPORT_FILE}"

- Create an HTML report and open it in a Mozilla browser.


2.3 Report Commands


2.3.1 Screenshot


DESCRIPTION
Screenshot - Take a screenshot of the current remote desktop and save it to a file. The command currently supports just two default Java image formats, JPEG/JPG and PNG.

The Screenshot command has been closely integrated with the Compareto command. Comparison is performed when a corresponding template image is found in the template directory (see the _TEMPLATE_DIR variable) and at least one of the following conditions is met:
Unless you specify a template image explicitly through the 'template' parameter, the command will search the template directory for a template with matching name and extension PNG, GIF, BMP and JPG (in this order). You can switch this feature off in the Screenshot preferences to force the command to search for templates with exactly the same file name as the screenshot images.

Please note that any image comparison performed by this command modifies some image comparison specific variables in the execution context.

SYNOPSIS
screenshot <file> [desc=<description>] [area=[x:<x>][,y:<y>][,w:<width>][,h:<height>]][attach=<list_of_files>] [template=<image>] [passrate=<pass_rate>%] [onpass=<command>] [onfail=<command>] [method=<comparison_method>] [methodparams=<custom_params>] [cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]]
* Red color indicates obligatory parameters

OPTIONS
file

- File name to save the image to. It MUST have a supported extension, i.e. one of 'jpg', 'JPG', 'jpeg', 'JPEG', 'png', 'PNG'. VNCRobot will check during every script validation if the path/file can be created and report an error if not. File name can be either relative (e.g. img.jpg) or absolute (e.g. /root/report/img.jpg). If the path doesn't exist, it is created. If you use relative path or just a file name, the image will be saved to a directory defined by the _REPORT_DIR variable.

desc=<description>

- Image description. It will be displayed in the report. As it will be used in an HTML report, it may contain any HTML tags.

area=[x:<x>][,y:<y>][,w:<width>][,h:<height>]

- This parameter can be used to specify which part (subimage) of the remote desktop will be saved. If you omit this parameter, the whole remote desktop will be used. The area coordinates have format of 'x:<x>,y:<y>,w:<width>,h:<height>', where each coordinate can be specified in pixels (e.g. 'x:225') or as a percentage (e.g. 'x:23%'). If any of x, y, width or height is omitted, VNCRobot will use the full screen values to determine the missing parameters, i.e. 'x:0, y:0, w:<screen_width>, h:<screen_height>'. You may also define the comparison area using the Screenshot window.

attach=<list_of_files>

- A file or a list of semicolon (';') separated files to be attached to a report. It provides a way to link e.g. log files and documents to a screenshot in the report. The report generator will list the attachments in the screenshot title in the HTML report and creates a hyperlink for each attached file. Please note that you have to copy the files to the target location on your own as VNCRobot neither copies the attached files to the report directory nor validates whether they exist there.

template=<image>

- File name of the template image which will be compared to the remote desktop image. File name can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. This parameter originates from the Compareto command.

passrate=<pass_rate>%

- Pass rate for image comparison. It must be a number followed by the percentage character (e.g. 'passrate=95%'). This parameter originates from the Compareto command. If you omit this value, the default pass rate of the Compareto command will be used.

onpass=<command>

- A command to be executed when VNCRobot successfuly connects to a server. It must be one single command. If you need to define a sequence of command to be executed, use a procedure. This parameter originates from the Compareto command.

onfail=<command>

- A command to be executed when VNCRobot fails to connect to a server. It must be one single command. If you need to define a sequence of command to be executed, use a procedure. This parameter originates from the Compareto command.

method=<comparison_method>

- Algorithm to be used for image comparison. If omitted, VNCRobot will use the default algorithm defined by a parameter in the configuration file. VNCRobot 1.3 provides two image comparsion algorithms. You may also write your own one using the VNCRobot 1.3 Open API.

methodparams=<custom_params>

- Custom parameters to be passed to the image comparison algorithm. As VNCRobot 1.3 default image comparsion algorithms don't support any custom parameters, you don't need to specify this parameter unless you write your own algorithm using the VNCRobot 1.3 Open API.

cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]

- Custom comparison area. You can specify here the area of the remote desktop to be compared to a template. If you omit this parameter, the whole remote desktop will be used. The area coordinates have format of 'x:<x>,y:<y>,w:<width>,h:<height>', where each coordinate can be specified in pixels (e.g. 'x:225') or as a percentage (e.g. 'x:23%'). If any of x, y, width or height is omitted, VNCRobot will use the full screen values to determine the missing parameters, i.e. 'x:0, y:0, w:<screen_width>, h:<screen_height>'. You may also define the comparison area using the Screenshot window.

RETURNS
The command returns 0 (zero) if the screenshot is successfully saved and eventual image comparison passes. If image comparison takes place and fails, a value of 1 is returned. If the screenshot cannot be saved (e.g. not enough space), the command returns 2.

EXAMPLES
Screenshot image.jpg

- Take a screenshot of the current remote desktop and save it as a JPEG image into a file called image.jpg in a directory defined by value of the _REPORT_DIR variable.


Screenshot /root/images/image2.png desc="This image shows what happened after I had clicked the Start button."

- Take a screenshot of the current remote desktop and save it as a PNG image into a file called image.png to the /root/images/ directory. If the executed script generates a report, the provided description will be displayed there.


2.3.2 Report


DESCRIPTION
Report - Create and start a report generator for the executed script. It is an object which builds an HTML report from the script information, screenshots and warnings. A report generator has typically the following lifecycle:
See a sample report at http://www.t-plan.com/robot/samples/samplereport.html.

Report generator always processes all images and warnings taken during a script execution. It means that even if you call the Report command at the very end of your script, the HTML report will list all screenshots and warnings including those that were taken before the Report command was executed. The list of images can be currently restricted only depending on the image origin (see the scope parameter below).

HTML reports can also contain a table of results of performed image comparisons. This feature can be configured in the VNCRobot Preferences window to display all or just failed comparison results executed through the Screenshot commands. Note that image comparisons performed through the Compareto and Waitfor match/mismatch commands are never listed. The rationale is that you have to create a screenshot anyway to provide a functional link in the table. See the sample report at the link listed above for an example.

Report command also inserts specific values at the end of HTML reports. They are embedded in HTML comments and they are not displayed in browser. They provide information about the report state, length of execution, number of failed image comparisons etc. These values can be parsed by third party applications in order to interpret the report state and result. A list of provided variables with sample values follows:

<!-- version=1.3-20061210 -->
Indicates which VNCRobot version and build was used to generate this report.
<!-- running=false -->
Indicates whether execution of the script is running or has already finished.
<!-- stopped=false -->
A value of 'true' indicates that execution of the script has been manually stopped by user via Stop button in GUI mode or by Ctrl+C in CLI.
<!-- paused=false -->
A value of 'true' indicates that execution of the script has been either manually or programatically (via the Pause command) paused.
<!-- exitCode=0 -->
Exit code. Zero indicates success while any other positive number is interpreted as failure. See the Exit command.
<!-- imageCount=3 -->
Number of images in the report.
<!-- failedComparisons=0 -->
Number of failed image comparisons.
<!-- warningCount=0 -->
Number of warnings added by the Warning command.
<!-- executionTimeInSec=44 -->
Time of script execution in seconds.

Note that the v1.3 implementation of the Report command is quite simple. Users are only allowed to enable/disable linking of executed scripts and define the status screenshot refresh period via Preferences window. A more flexible model allowing to create customized reports and to configure the generator behavior will be provided in one of the future versions.

SYNOPSIS
report <file> [desc=<description>] [scope=<scope_id>]
* Red color indicates obligatory parameters

OPTIONS
file

- File name to save the report to. VNCRobot will then check whether the path and file can be created and report an error if not. No other validation of the name is performed so be sure to give it an .htm or .html extension. Future versions may require a valid extension once a support for other document formats is implemented (MS Word/Excel/PowerPoint etc.).

File name can be either relative (e.g. report.html) or absolute (e.g. /root/report/report.html).If the path doesn't exist, it is created. If you use a relative path, the image will be saved to a directory defined by the _REPORT_DIR variable.

desc=<description>

- Report description. It will be displayed in the report header. It may contain any HTML tags.

scope=<scope_id>

- The scope parameter provides a way to define which images should be included in the report based on the screenshot creator. There are three acceptable values:

RETURNS
The Report command returns 0 (zero) if the report assembler is started and the first report is created and saved successfuly. If any error occurs, i.e. the report file cannot be created, the command returns 1.

EXAMPLES
Report index.html desc="This is my report."

- Create a report generator and start to generate a report. As relative file is provided, the report will be saved to a directory defined by value of the _REPORT_DIR variable. The provided description will be displayed in the report header.


Var _REPORT_DIR=/var/apache/htdocs/vncrobot
Report index.html scope=file
Screenshot start_state.jpg desc="Initial state of the {_MACHINE} desktop. Starting execution of the {_FILE} script..."
...

- This is a typical example on how to use the report command. The first command defines the output path for the report file and screenshots which actually resides inside the Apache document root. This is very convenient as users can watch the report on the web server via a web browser. Both report and screenshot commands then provide relative path so thet they get saved into the output directory.



2.3.3 Warning


DESCRIPTION
Warning - Insert a warning into the report. A warning can be associated with a specific screenshot through the image parameter. Such a warning will be displayed below the image description in the report. If there's no associated image, the warning will be displayed in the report as a single component.

When a script is being executed and there's a running report assembler (i.e. the script contains a Report command), an execution of a Warning command will trigger refresh of the report. If there's no active report assembler, a warning is created in the internal tables but it is not reported in any way.

SYNOPSIS
warning <description> [image=<screenshot_name>]
* Red color indicates obligatory parameters

OPTIONS
description

- Text of the warning to be displayed in the report.

image=<screenshot_name>

- A screenshot to be associated with the warning. The screenshot name should correspond to an image created by the Screenshot command.

RETURNS
The Warning command always returns 0 (zero).

EXAMPLES
Report index.html
Exec "mozilla
file://{_REPORT_FILE}"
if ({_EXIT_CODE} > 0) {
Warning "Mozilla failed to start.<br>Error output: {_EXEC_ERROR}"
}

- Try to open the HTML report in a Mozilla browser using the Exec command and add a warning if it fails.

Screenshot image.jpg template=template1.png onfail="Warning \"The image image.jpg doesn't seem to display what is expected.\" image=image.jpg"

- Take a screenshot and compare it to a template called template1.png. If the comparison fails, add a warning to the image description.



2.3.4 Sendmail


DESCRIPTION
Sendmail - Send an E-mail. The command acts as an SMTP client and can send E-mails with eventual attachments through SMTP servers with no security (public mail servers) or servers requiring password authentication. The communication is unencrypted (no SSL support at the moment). Attachments are sent using Base64 encoding.

Note that it is possible to set the default values of the 'from','to', 'server' and 'user' parameters in the Sendmail preferences and the parameters may be then omitted in the command.

SYNOPSIS
sendmail [from=<sender_address>] [to=<recipient_address>] [server=<server[:port]>] [subject=<subject>] [text=<mail_body>] [attach=<attachments>] [user=<userId>] [passwd=<password>]  [debug=<true|false>]
* Red color indicates obligatory parameters

OPTIONS
from=<sender_address>

- Sender address.

to=<recipient_address>

- Recipient address.

server=<server[:port]>

- SMTP server. If just a host name without a port number is used, the command attempts to connect the server on standard SMTP port 25.

subject=<subject>

- Mail subject text.

text=<mail_body>

- Mail body text. To indicate a line break use '\n'. If you need to use '\n' in the normal text, double the backslash character ('\\n').

attach=<attachments>

- List of attachments, i.e. files to attach to the E-mail. Separator is platform dependent. On Linux/Unix it is typically the colon character (':') while on Windows it is semicolon (';'). If an attachment is not found, it is ignored and the mail is sent without it.

user=<username>

- User ID to be used to authenticate to the SMTP server. This option should be used together with the 'passwd' parameter. Supported from VNCRobot 1.3.13.

passwd=<password>

- Password to be used to authenticate to the SMTP server. This option should be used together with the 'user' parameter. Supported from VNCRobot 1.3.13.

debug=<true|false>

- Debug flag. Use debug=true to switch on the JavaMail debugging console output. This is useful if you need to find out why the mail feature doesn't work.

RETURNS
The command returns 0 (zero) on success or 1 if the E-mail cannot be sent.

EXAMPLES
Screenshot scr.png
Sendmail to="tester@vncrobot.com" from="vncrobot@vncrobot.com" server="mail.vncrobot.com" subject="Screenshot of the remote desktop" text="Please check the attached screenshot." attach="{_REPORT_DIR}/scr.png"

- Take a screenshot of the current remote desktop and send it by E-mail to user tester@vncrobot.com.


Sendmail subject="Hello" text="This is a multiline E-mail.\nSecond line.\nThird line."

- Example of a multiline E-mail. This command will only work if you have set correct default values of the 'from','to' and 'server' parameters in the Sendmail command preferences.