VNCRobot 1.0 Language Reference

1. Language Syntax

• Only ASCII characters are allowed.
• Scripts are processed line by line.
• The language is NOT case sensitive unless it is explicitly stated in this documentation.
  
• Lines may contain any number of leading and/or trailing white space characters, i.e. spaces, tabelators etc. They will be trimmed before further processing. Empty lines are ignored.
• Lines beginning with hash '#' are considered to be comments and they are ignored:

• Other text lines which are not eliminated by the rules above are processed in the following way:
  

1. The text is broken into tokens by one or more spaces. Any text preceded by a space and enclosed between a pair of double quotes ("...") is considered to be a single token. An escaped double quote (\") is not considered to indicate the beginning or end of a token and for further processing is replaced with a double quote. Strings which have a form of 'identificator=value' or 'identificator="value with spaces"' are considered to be one single token and they are further parsed into identificator/value pairs.

2. Command Syntax

• Press
• Type / Typeline
• Mouse
• Var
• Exit
• Wait
• Waitfor
• Run
• Include
• Screenshot
• Report
  

2.1. Press

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

OPTIONS
modifier

key

count=<number>

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

wait=<time_in_ms>

- Time in miliseconds 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.

EXAMPLES
Press Ctrl+Alt+Del

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

Press Tab count=5 wait=2000

- 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=10000 ontimeout="Var KEY_TO_PRESS=Right"
Press {KEY_TO_PRESS} wait=2000

- 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.2. Type, Typeline

SYNOPSIS
type <text> [wait=<time_in_ms>]
typeline <text> [wait=<time_in_ms>]
* 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 code page can't be used because they are currently not supported by the RFB protocol.

wait=<time_in_ms>

- Time in miliseconds 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.

EXAMPLES
Type hello

- Type 'hello'.

Typeline "mkdir /usr/vncrobot" wait=2000

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

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_in_ms>]
* 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_in_ms>

- Time in miliseconds to wait after the events are sent. It has the same effect as if the following command was 'Wait <time_in_ms>'.

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=2000

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

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

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.

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

- Name for the variable. A 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 - \\"".

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

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

2.5. Exit

SYNOPSIS
exit [<exit_code_number>]

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.

EXAMPLES
Exit

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

Exit 10

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

Typeline myapplication
Waitfor update extent=40% timeout=20000 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.

2.6 Wait

SYNOPSIS
wait <time_in_ms>
* Red color indicates obligatory parameters

OPTIONS
time_in_ms

- Number of miliseconds to wait before proceeding to the next command. It must be an integer greater than zero.

EXAMPLES
Wait 5000

- Wait 5 seconds before proceeding to the next command.

2.7. Waitfor

SYNOPSIS
Waitfor <event_id> [area=[x:<x>][,y:<y>][,w:<width>][,h:<height>]] [extent=<number>[%]] [timeout=<timeout_in_ms>] [ontimeout=<command>] [count=<number>] [wait=<time_in_ms>]
* Red color indicates obligatory parameters

OPTIONS
event_id

- Supported event IDs are 'update' and 'bell'.

• An update means that you wait for an update of the frame buffer, e.g. you expect a window to pop up.
• A bell event indicates that your server beeped, i.e. an application printed out the bell character (ASCII 0x07).

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 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 value will be computed against this area.

timeout=<time_in_ms>

- Timeout in miliseconds. It defines how long to wait at maximum.

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.

count=<number>

- How many events to wait for. Default value is 1.

wait=<time_in_ms>

- Time in miliseconds 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.

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

2.8 Run

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.

EXAMPLES
Run sayHello.txt

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

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

2.9 Include

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.

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.

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

2.10 Screenshot

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, the image will be saved to a directory defined by the _REPORT_DIR variable.

desc

attach=<list_of_files>

EXAMPLES
Screenshot image.jpg

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

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

2.11 Report

• Every execution of the Report command creates a new instance of a report generator. It immediately generates the very first HTML report using the predefined script variables and internal list of screenshots.
• A status daemon is created and started. It wakes up periodically after a predefined period of time (typically 10 seconds) and takes a screenshot of the frame buffer. A link to this image is provided in the HTML report and enables users to view the recent state of the VNC server.
• The generator then attaches to the Screenshot command. Whenever a new image is taken, the generator wakes up and rebuilds the report to include the new image.
• When execution of the script finishes, the status daemon wakes up and refreshes the status image to reflect the exit state. Then the generator wakes up for the last time and rebuilds the report to reflect the execution result based on the exit code (see the Exit command).

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

scope=<scope_id>

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.

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

3. Procedures