Waitfor Command

3.2.21 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, bell (desktop server emitted a beep through the printing of the ASCII character 0x07), delivery of text copied on the remote system (desktop server clipboard change) and match/mismatch (waiting for a positive or negative image comparison result).

Support for particular events is subject to protocol capabilities. T-Plan Robot has an open and flexible architecture allowing to plug-in clients with just a subset of capabilities commonly provided by remote desktop technologies. If a Waitfor event is not supported by the selected desktop protocol the script will report an error. The following table lists the capabilities of the two supported protocols:

All Waitfor commands populate the following variable:

The Waitfor update command populates additional variables:

The Waitfor match and mismatch commands maintain result compatibility with the Compareto command and populate two more variable groups:

1. All the _COMPARETO prefixed variables specified in the Compareto command,
2. Variables populated by the selected image comparison method.

Though the Waitfor clipboard describes the _SERVER_CLIPBOARD_CONTENT variable it is not created by the Waitfor command and it is being populated by the core framework independently from any commands.

SYNOPSIS

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

event_id

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

• • A bell event indicates that your server beeped, i.e. an application printed out the bell character (ASCII 0x07).
  • An update means that you wait for an update of the remote desktop image, for example for a window to pop up. If the expected event is received, the Waitfor command resumes script execution and updates the execution context with variables representing the update coordinates (see the table of Waitfor predefined variables).
  • The match event makes the command wait until the selected comparison method produces a positive result (waits until the desktop matches). The mismatch event makes the command wait as long as the method produces a positive result (wait until the desktop stops matching).
  • Clipboard waits for delivery of the remote server clipboard content. When a text gets selected on the remote desktop and a copy action is invoked (e.g. through Ctrl+C), some desktop servers send the text to the client. Once the message is received, the remote clipboard content is available through the _SERVER_CLIPBOARD_CONTENT variable (see also the Var command).

COMMON OPTIONS

timeout=<time>

- Timeout specifying how long to wait at a maximum. The value must be either a number of milliseconds or a valid time value. The default value is not set and the command will wait indefinitely if the timeout value is not specified.

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.

onpass=<command>

- A command to be executed when the condition is met (when the expected event is received or the image comparison fails to return the expected result). It must be a single command. To call a sequence of commands, use either a procedure or a subsequent if/else construction testing the command exit code.

count=<number>

- How many events to wait for. The default value is 1. This parameter is ignored by image comparison events (Waitfor match/mismatch).

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. The value must be either a number of milliseconds or a valid time value. The default value is 0 (don't wait). Scripts may set the default value through populating of the _WAITFOR_WAIT variable with the desired delay, for example "Var _WAITFOR_WAIT=1s".

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

- The screen area to wath for updates. 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, Robot 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 (scope) 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 desktop server prefers gradual screen updates and sends many small image fragments instead of a larger expected one, switch this feature on and Robot will summarize all partial updates falling into the defined area. The default value is false.

As Windows VNC servers are known to update the screen in a series of smaller updates it is recommended to set the mode to true.

Waitfor match | mismatch [template=<image_collection>] [passrate=<pass_rate>%] [interval=<comparison_interval>] [method=<comparison_method>] [methodparams=<custom_params>] [cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]] [<common options>]  [<method_specific_params>]
* Image collection is obligatory only if it is required by the selected image comparison algorithm (parameter "method"). See the Compareto command specification for details.

SPECIFIC OPTIONS - MATCH AND MISMATCH

template=<image_collection>

- An [image collection|#imgcol] - one or more image file names or folders with images separated by a semicolon (';') to be compared to the remote desktop image. On Linux/Unix make sure the file name doesn't contain semicolon because the list would be incorrectly parsed. File names can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use a relative path, the image will be searched in the directory defined by the [_TEMPLATE_DIR variable|#_template_dir]. Supported image formats are subject to the Java version and installed extensions (such as the Java Advanced Imaging library, JAI). Java 1.6 supports at least PNG, JPG, GIF and BMP.

Template images will be compared with the remote desktop image in the specified list order. If a template comparison produces a positive result (either match or mismatch depending on the specified event), the condition is considered to be met and the command finishes with an exit code of 0. Predefined variable _COMPARETO_TEMPLATE_INDEX may be used to determine the index of the matching template in the list. See [image comparison specific variables|#compareto_vars] for more.

Image comparison should not be performed against images with lossy compression such as JPEG. Use PNG or BMP instead. They preserve 100% of the image information and guarantee reliable and stable comparison results. Image comparison is discussed in the [Compareto command specification|#compareto].

interval=<time>

-This parameter defines the time interval for image comparisons. The default value is 3 seconds which means that the desktop image will be compared against the given template image(s) every 3 seconds. A plain number is by default parsed as milliseconds. See the syntax of time values paragraph for more time formats. The default value can be configured in the Waitfor preferences panel of the Preferences window.

passrate=<pass_rate>%

- The pass rate for image comparison. It must be a number between 0 and 100 which may optionally be followed by the percentage character (for example "passrate=95" or "passrate=95%"). If this parameter is omitted, the default pass rate defined by the method or in the Robot preferences will be used (default values are 95% for the "default" and 100% for the "search" and "search2" methods).

method=<comparison_method>

- - The method (algorithm) to be used for image comparison. It must be one of the supported method names (codes) described in the Image Comparison Capabilities chapter or the name of a third party method enabled through the plugin interface. If omitted the command will use the default one.

methodparams=<custom_params>

- Custom parameters to be passed to the image comparison algorithm. As T-Plan Robot 2.0 default image comparison algorithms don't support any custom parameters, you don't need to specify this parameter unless you write your own algorithm.

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

- The rectangular area of the desktop to be limit the comparison to. If you omit this parameter the whole remote desktop will be used. The area coordinates have the format of 'x:,y:,w:,h:', where each coordinate can be specified in pixels (for example. "x:225") or as a percentage ("x:23%"). If any of x, y, width or height are omitted, T-Plan Robot will use the full-screen values to determine the missing parameters (x:0, y:0, w:, h:).

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' mimic behaviour 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 of 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 desktop server is very fast and your machine running T-Plan Robot is somewhat slower, it may happen that the document search finishes before T-Plan Robot 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;application2.png passrate=95% interval=5s timeout=5m ontimeout="exit 1"

- Compare the remote desktop image to images application.png and application2.png every 5 seconds until there's at least 95% match with one of them. 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 desktop servers are capable of sending this text to the clients. Robot can decode such a message and provide the text into the script in the 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 the description of a screenshot.