# This is a comment
--fromlabel
and --tolabel
for more info.identificator=value
' or 'identificator="value with
spaces"
' are considered to be one single token and they are
further parsed into identificator/value pairs. This is a text containing spaces
This
',
'is
', 'a
', 'text
', 'containing
',
'spaces
'.This "is a text" containing
spaces
This
',
'is
a
text
', 'containing
',
'spaces
'.This text contains "double quote (\")"
This
',
'text
', 'contains
', 'double quote (")
'Variable SAMPLE_VAR_1="value with spaces" SAMPLE_VAR_2=no_spaces
"NO_VAR=not_a_variable"
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. wait
/timeout
/delay
parameters of other commands support the following syntax:'1'
is parsed as 1 milisecond,'1s'
is 1 second,'1m'
is 1 minute,'1h'
is 1 hour,'1d'
is one day.'3.5h'
will be parsed as 3.5 hrs (3 hrs 30 mins).Wait "1.5d"
Press Ctrl+C wait=5s
procedure <procedure_name> {
command1
command2
...
commandN
}
<procedure_name> parameter1
"parameter2 with spaces" .... parameterN
# 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
take_screenshot image3 tiff
'1.25'
.'5s'
(five seconds) are not
accepted except the cases where the time modifier is at the very end of
the expression. Examples:Wait 5+5s
Wait 5s+5s
'('
and ')'
'+'
'-'
'-'
(negative numbers)'*'
'/'
# 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"
'Eval HOUR_IN_MS=1*60*60*1000'.
if/else
and for
. The following operators and rules apply:
'('
and ')'
'>'
and lower than '<'
.
These two operators require numeric arguments.'=='
and not equal to '!='
.
Arguments are first converted to numbers and compared. If at least one
of the argument is not a number, a plain string comparison is
performed.
Examples:'yes == no'
will be false'yes != no'
will be true'1.0 == 1'
will be true because both
arguments can be converted to a number and the numeric values are equal.'&&'
and '||'
-
logical "and" and "or". These operators require boolean arguments, i.e.
other expressions. Example:'1 > 0 || yes != no'
will be true
because at least one expression is true'1 > 0 && yes != no'
will
be
false because both expressions are not trueif/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
}
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>
}
'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.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. for
statement allows to execute
until
a boolean expression results true:for (<statement1>;
<boolean expression>; <statement2>) {
<commands>
}
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
}
for <variable name> in
<list of space separated values> {
<commands>
}
Type "I speak "
for language in English Spanish "Brazilian Portuguese" {
if ("{language}" == "Brazilian Portuguese") {
Type "{language}."
} else {
Type "{language}, "
}
}
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"
}
procedure
,if/else
and for
statements) are considered to be local and they are available only
within the block of code.if/else
, for
, break
and procedure
calls do not return any value.OPTIONS
server[:display]
- Server and an
optional display number to connect to. An example is 'myserver:1'
or 'myserver.mydomain.com:1'
. If no display number is
passed, VNCRobot tries to connect to display number 0 (port 5900,
typical for Windows).
password=<password>
force=<false|true>
onpass=<command>
onfail=<command>
RETURNS
The command returns 0 (zero) on success or 1 when it fails to
connect.
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 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.
RETURNS
The command returns 0 (zero) on success or 1 when it fails to
disconnect.
EXAMPLES
Disconnect
- Disconnect from a
VNC server.
SYNOPSIS
press [<modifier_1>+...+<modifier_N>+]<key | modifier> [count=<number>]
[wait=<time>]
OPTIONS
modifier
key
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.
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.
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
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.
If the event is 'move
',
they define where to move the mouse pointer.
If the event is 'click
',
'press
' or 'release
', the mouse pointer
will be first moved to this location and then the associated click is
performed.
If the action is 'drag
', the mouse pointer will be
dragged from its actual position (or from the position specified by the
from
option) to this location.
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.
If the action is 'drag
',
the mouse pointer will be dragged from this position to the coordinates
specified by the to option.
If the event is 'move
', 'click
', 'press
'
or 'release
', this parameter will be ignored.
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
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
'.
{<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}"
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. |
VNCRobot
when a script execution is started. |
_DATE=<YYMMdd> | 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}}
}
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.
'-v'
CLI command.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'
.
Run
command finishes.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
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
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.
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.
SYNOPSIS
exit <exit_code_number>
[scope=<process|file|procedure|block>]
OPTIONS
exit_code_number
- Exit code. It must be an integer. An
exit code is in case of automatic execution passed to the underlying
operating system and can be used to identify the reason of the script
termination.
process
which terminates
the
script execution and the JVM (Java Virtual Machine). file
value terminates the currently executed file. If
a script is being executed from another script using the Run
command, only the current script is terminated and the control is
returned to the master script.procedure
value exits from the innermost procedure.
If
no procedure is executed, the Exit command is ignored.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 exit with an exit code of 2.
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 parsed as miliseconds. See the syntax of time values paragraph for more 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'
.
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'
.
_SERVER_CLIPBOARD_CONTENT
variable (see also the Var command).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>
methodparams=<custom_params>
cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]
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.
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.
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.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.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>
if/else
statement.onfail=<command>
method=<comparison_method>
methodparams=<custom_params>
cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]
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}}
}
'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.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"
OPTIONS
command
- OS command to be executed on the local system.
count=<number>
onpass=<command>
if/else
construction
based
on the Exec command return value. onfail=<command>
if/else
construction
based
on the Exec command return value.outfile=<file_name>
wait=<time>
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.
'template'
, 'passrate'
,'onpass'
,'onfail'
.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>
area=[x:<x>][,y:<y>][,w:<width>][,h:<height>]
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>
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>
onfail=<command>
method=<comparison_method>
methodparams=<custom_params>
cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]
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.
scope
parameter
below).Compareto
and Screenshot
commands. See the sample report at the link listed above for an example.
<!-- 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. |
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>
scope=<scope_id>
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:all
- This value is the default one. All images
taken
during the script execution will be included in the report.file
- Include only those images that were taken
within the current script and in procedures called by this script.
Other
screenshots created by the master script (i.e. a super script calling
this script) and by the scripts executed using the Run
command will be excluded. This approach is suitable when you
execute
a number of smaller scripts using one superscript and you prefer to
have
a couple of shorter reports instead of a large one. combined
- Include just those images that haven't
been included by another report generator. If both a master script and
subscript run the Report command, the master will rather link the
report
of the subscript instead of including its images into the report. Note
that this mode is not likely to be supported in earlier versions. 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.
OPTIONS
description
- Text of the warning to be displayed in the report.
image=<screenshot_name>
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.
'from'
,'to'
and 'server'
parameters in the Sendmail preferences and
the
parameters may be then omitted in the command.OPTIONS
from=<sender_address>
- Sender address.
to=<recipient_address>
server=<server[:port]>
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>
application/base64
.debug=<true|false>
debug=true
to switch on the console debugging messages. 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.