T-Plan Robot Enterprise 4.3.1 Doc Collection

25/09/17

T-Plan Robot Enterprise 4.3.1 Language Reference

1. Introduction

1.1 Purpose

This document provides a complete specification of the test script language supported by T-Plan Robot Enterprise version 4.3.1. Its goal is to provide a complete syntax and functionality reference to those who write automated test scripts using this tool and its testing framework. As the scripting language is tightly coupled with the Java Test Script API, it is also intended to provide a complementary functionality reference for design of Java test scripts.

Test scripts in the language described by this document are called TPR test scripts. Test scripts based on the Java Test Script API are called Java test scripts.

The document is based on specification of its predecessor VNCRobot 1.3, with which it maintains backward compatibility, and describes test script requirements, parsing and processing rules, language structure and syntax of particular elements, such as statements, expressions, commands and image comparison methods.

1.2 Overview

T-Plan Robot Enterprise supports a simple scripting language allowing to write automated test scripts. It is a structured procedural language somewhat similar to shell scripting on Linux/Unix. It supports structures and elements well known from moder programming languages, such as:

• Variables (both global and local),
• Numeric and boolean expressions,
  
• Procedures with parameters, which together with the Run and Include commands allow to create libraries of functions and subroutines,
• Looping and conditional structures such as for and if/else,
• Set of functional commands indicating result through a numeric return value.
  

As T-Plan Robot Enterprise is designed to work with most common remote and local desktop technologies, the scripting language supports commands fall into roughly four functionality areas:

1. Desktop Commands typically involve client to server communication, such as connecting to/disconnecting from a desktop and transfer of mouse and keyboard inputs (press a key, type a text, perform a mouse move, click, drag or wheel event).
2. Administrative And Execution Control Commands provide necessary infrastructure for test script execution control (pause, stop, desktop image analysis, waiting for a specified time period or particular event) as well as support of variables, libraries and external OS command calls.
3. Reporting Commands define automated testing outputs and report them to the user. Commands in this category allow for example to take a screenshot of the desktop image or its part, create a report, send an E-mail or upload the test results to an associated test management tool.
4. I/O Commands deal with input from and output to various data sources.
   

1.3 Enterprise Features

T-Plan Robot Enterprise is a functionally rich and mature product, and is built upon the language specifications developed in the previous versions. In general terms T-Plan Robot Enterprise delivers additional features on top of the previous product versions, and its language is extended with additional commands and service providers, such as report generators, image comparison algorithms and desktop clients. Scripts designed with previous product version are always compatible with the T-Plan Robot Enterprise language. On the other hand a script designed with T-Plan Robot Enterprise may or may not to be compatible with the previous versions, depending on whether it uses the Enterprise language extensions.

This is a complete list of language extensions in T-Plan Robot Enterprise 4.3.1:

1. Script command.
2. Step command.
3. Enterprise report provider under the Report command.
4. Enhanced image search algorithm with improved performance and support of automatic transparency (since v2.1) and RGB-level tolerance (since 2.2).
5. Support of drawing of image search results in the Screenshot command (since v2.1).
6. Input/Output (I/O) commands such as File and Excel (since v2.1). The Excel one has been enhanced to provide better error reporting and to support MS Excel 2007 XML format (.xlsx) in v2.3.
   
7. Support of nested Java code through Java Code Blocks (since v2.1, enhanced with import clause support since v2.2).
8. Support of Image Meta Data and folder based Image Collections (since v2.2).
9. Additional image comparison methods such as Object Search ("object") and Tesseract OCR ("tocr") (since v2.2).
   
10. Enhanced Run command supporting parametrized call of Java test scripts (since v2.2).
11. Image client supported by the Connect/Disconnect commands (since v2.2).
12. String command and enhanced boolean expressions allowing to test strings and perform common text operations (since v2.2).
13. Timer command (since v2.3).
14. Fallback procedures (since v2.3).
15. Exit command enhanced with optional description (since v2.3).
16. Log and Mouse swipe commands (since v3.0),
17. Images Search v2 and Image Based Text Recognition comparison methods (since v3.0).
18. Android Over ADB connection (since v3.1).
19. Local Desktop connection (since v3.2).
20. The ability to slow down or speed up the script execution through the _EXECUTION_SPEED_FACTOR variable or the corresponding preference (since v3.2).
21. iOS Mirror connection (since v3.3).
22. Retrieval of coordinates of text recognized through the Tesseract OCR (since v3.4).
23. Drawing of tolerant image search difference into screen shots through the "drawdiff" parameter of the Screenshot command (since v3.4).
24. The "nowait" (since v3.4) and "kill"/"autokill" (since v3.5.2)  Exec command parameters allowing to start a local OS command in a non-blocking mode and kill it eventually later.
25. Mouse pinch and zoom support (since v3.5).
26. Imagedoctor command (since v3.5).
27. The "mode", "filter" and "fontsize" parameters of the Tesseract OCR comparison method (since v3.5).
28. Varf command (since v3.5.1).
29. Fuzzy text matching through the String matches and String indexof commands (since v3.5.2).
30. The "scale" parameter of the Image Search v2 algorithm (since v4.0).
31. Setting of the iOS Mirror screen size through the _DESKTOP_SIZE variable (since 4.0.2)
32. Click and Drag commands (since 4.1)
33. Paste command (since 4.1.2)
34. Support of delayed mail sending and STARTTLS connection security in the Sendmail command (since 4.1.3)
35. The 'terminal' parameter of the Log command (since 4.1.3).
    
36. Support of multiple reports, ZIP format and the 'onexit' parameter in the Report command (since 4.1.3)
37. Support of the Continue command (since 4.1.3)
38. The Tesseract OCR's "pattern" parameter allowing to locate text segments matching the specified regular expressions and retrieve their coordinates (since 4.1.4)
    
39. The "move", "continue" and "step" parameters of the Click command (since 4.2)
40. The "continue" and "step" parameters of the Drag command (since 4.2)

2. Language Syntax

2.1 Language Structure

• ISO8859-1 (Latin-1) characters are recommended. Characters out of this set may be used in command arguments and parameter values but their support is subject to the particular remote desktop client and its protocol capabilities. Please read the client documentation before using other than ISO8859-1 characters.
  
• The language is NOT case sensitive unless where explicitly stated in this documentation.

• Scripts are processed line by line. A single command or expression can not be split to multiple lines unless the specification explicitly says so.
• 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. Version 2.3 and newer also accepts Java/C++ style comments starting with double slash '//':
  

• Lines beginning with a colon ':' are considered to be labels and they are not further processed. Labels indicate a position in the code and they are used as entry or exit points for execution (this functionality is similar to the goto command supported by other programming languages). See the --fromlabel and --tolabel T-Plan Robot Enterprise CLI options for more label info.
• Other text lines which are not eliminated by the rules above may contain one element of the scripting language, such as a command, procedure header, procedure call, an if/else/for statement or its terminating right curly brace ('}'). Each such a text line is 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.2 Time Values

• "1" is parsed as 1 millisecond,
• "1s" is 1 second,
• "1m" is 1 minute,
• "1h" is 1 hour,
• "1d" is one day.

2.3 Variables

A typical example:

Avoid variable names consisting of plain numbers, e.g. 'Var 1="test"'. These variables are reserved for procedure parameters and they will be rewritten by any procedure execution without any warning.

If a variable is not defined, no replacement is performed. The following example will rather type 'cd {PATH}' than 'cd /tmp' because the variable definition is commented out:

1. Variables created in the main script body are considered to be global and they are accessible from the moment of definition 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 (including any nested blocks it may contain).
   

2.4 Procedures

• Procedure names are not case sensitive and they must not conflict with any other command or language element name. Since v3.0.1 the name may contain spaces if it is enclosed with double quotes, for example:

• The left curly brace '{' must be on the same line as the procedure header.
  
• The terminating right curly brace '}' must be alone on a single line.
  
• A procedure definition overrides any eventual already defined procedure of the same name.
  
• Procedure can be called anywhere in the script AFTER its definition.
  
• Procedures defined in another test script (file) may be imported through the Include command.
  

2.5 Fallback Procedures

• A procedure called DisconnectFallback will be called when connection to the VNC server crashes either in the init phase (inside the Connect command) or any time later on, for example when the server is terminated (killed) or a network error is experienced. A call of the Disconnect command will not start the procedure because it is an expected connection termination. If a Connect is called in the fallback procedure body, it will not call the procedure again on failure to prevent infinite connection looping. If the connection crash is detected in the normal operation phase during script execution, the procedure gets called right after the currently executing command finishes. Be aware that the procedure may not be used in such a case for a safe recovery (meaning reconnection and resuming of the script) because the scope of data transferred to the server correctly is not known. This is a problem when the crash happens for example in the middle of text typing where it is not possible to determine how many characters were typed successfully before the connection failure.
• A procedure called ComparisonFailureFallback gets executed every time a CompareTo or Waitfor match/mismatch fails and no explicit fail action is specified through the onfail or ontimeout parameter. The first procedure argument which may be retrieved inside the procedure body as "{1}" will always contain the numeric exit code of the calling comparison command. This is typically "1" when the object is not found or "2" when one or more of the template images are not found or can not be read.
  

2.6 Numeric Expressions

• English format of floating point variables is expected, e.g. '1.25'.
• Time variables like '5s' (five seconds) are not accepted except the cases where the time modifier is at the very end of the expression. Examples:
• CORRECT:  Wait 5+5s
• INCORRECT:   Wait 5s+5s
• Supported numeric operators are:
• Parenthesis '(' and ')'
  
• Plus '+'
• Minus '-'
• Unary minus '-' (negative numbers)
  
• Multiplication '*'
• Division '/'
• Modulo division '%'
  

2.7 Boolean Expressions

• Parenthesis '(' and ')'
• Greater than '>' and lower than '<'. These two operators require numeric arguments.
• Equal to '==' 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:
• Result of 'yes == no' will be false
• Result of 'yes != no' will be true
  
• Result of '1.0 == 1' will be true because both arguments can be converted to a number and the numeric values are equal.
• Operators '&&' and '||' - logical "and" and "or". These operators require boolean arguments, i.e. other expressions. Example:
• Expression '1 > 0 || yes != no' will be true because one of the two expressions is true
• Expression '1 > 0 && yes != no' will be false because one expression is false

• Unary operator 'exists <variableName>' tests existence of a variable. Example:
  
• Expression 'exists _REPORT_FILE' will be true if the script creates a report through the Report command
• Operator 'contains' tests whether the first string argument contains the other one (case sensitive). Example:
  
• Expression '"{_MACHINE}" contains "sourceforge"'will be true if the connected VNC server name contains 'sourceforge'
  
• Operator 'startswith' tests whether the first string argument starts with the other one (case sensitive). Example:
• Expression '"{_DISPLAY}" startswith "localhost"'will be true if the connected VNC desktop name starts with 'localhost', for example 'localhost:1'.
• Operator 'endswith' tests whether the first string argument ends with the other one (case sensitive). Example:
• Expression '"{_DISPLAY}" endswith ":3"'will be true if the connected VNC server runs on port 5903 (which is typically indicated by the ':3' display number in the desktop name).
• Operator 'matches' compares the first string argument to a java.util.regex.Pattern compliant regular expression. Example:
• Expression '"{_DATE}" matches "201008[12][1-5]"' will be true if the current date is between 11 and 15 or between 21 and 25 August 2010 .
  
  

2.8 If/Else Statement

2.9 For Statement

2.10 Return Values

2.11 Java Code Blocks

import com.tplan.robot.scripting.*;
import java.io.*;
import java.util.*;
import java.util.Date;

public class SomeDynamicName extends DefaultJavaTestScript {
   public void test() {
       System.out.println("Current date: "+new Date());
   }
}

• As Java code blocks require access to Java compiler, T-Plan Robot Enterprise must run on Java Development Kit (JDK) or it must be configured with a valid JDK installation path (v2.3.3 and newer). If the tool runs just on Java Runtime Environment (JRE) and no JDK is available the compiler will report an error. Refer to chapter 1 of the Release Notes document for instructions.
• Avoid using too many Java code blocks in your script. Be aware that each one must be dynamically compiled in the memory before use and it may degrade performance of your test script and the whole tool. Should you want to create reusable parametrized pieces of precompiled Java code, explore the Run command functionality.
  
• The template by default imports all classes from the com.tplan.robot.scripting, java.io and java.util packages. If you want to use a class from another package, place the import clause before the Java code. Other alternatives are to either reference the class by fully qualified name (such as for example java.awt.Point) or go to the Java code block preferences and add the import to the class template. If you choose the template way, make sure to reapply it when the script is migrated to another machine.
• As each Java code block behaves as a standalone Java class, local variables and objects created in one block are not visible in another one. If you need to share an object accross multiple Java blocks, store them into the context. It is basically a map which exists for the whole time of script compilation or execution and holds references to important automation framework objects. To store an object to the context use getContext().put(), to retrieve an object use getContext(). get(). Make sure to use a unique key so that you don't overwrite reference of an already existing framework object. For more information see the ScriptingContext interface specification.
• Java code blocks may share global variables with the TPR script through the context's getContext().getVariable() and getContext().setVariable() methods. As the code block extends DefaultJavaTestScript class, it may also call its methods corresponding to the scripting language commands.

3. Command Syntax

• Connect
• Disconnect
• Mouse
• Press
• Type / Typeline

• Break
• Click
  
• Compareto
• Drag
  
• Eval
• Exec
• Exit
• Imagedoctor
  
• Include
• Pause
• Run
• String
  
• Var
• Wait
• Waitfor

• Log
  
• Report
• Screenshot
• Script
• Sendmail
• Step
• Timer
• Warning

3.4 I/O Commands

• Excel
• File

3.1 Desktop Commands

3.1.1 Connect

OPTIONS
URL

- The argument must be a known connection name (since v4.2) or a valid URL in form of <protocol>://<host_or_IP>[:<port>] except for the legacy format described below. The protocol must be equal to one of the supported protocol codes. T-Plan Robot by default supports two clients (protocols):

As T-Plan Robot provides an interface allowing to plug in other clients, there might be more protocols supported by additional plugins.

If port is not explicitly specified, it defaults to the protocol-specific well known port. For example, RFB/VNC server runs by default on port 5900, Java RMI starts  by on port 1099 and RDP (Windows Terminal Services) default to 3389. If you want to connect to a VNC running on Linux/Unix, you typically have to specify the port of 5901 or higher because the default RFB port is occupied by the X-Windows server.

If protocol is omitted in the URL, the script defaults to the RFB (VNC) protocol to provide backward compatibility with VNCRobot 1.x. The port number is in this case treated as the display number which is equal to the port number minus 5900. Direct port can be in this mode specified through double colon. For example both "localhost:1" and "localhost::5901" refer to the same local VNC server running on port 5901. The same address in the standard URL form is "rfb://localhost:5901".

password=<password>

onpass=<command>

onfail=<command>

params=<param_name_and_value_pairs>

paramseparator=<delimeter>

RETURNS
The command returns 0 (zero) on success or 1 when it fails to connect for unspecified reason. The command returns a value of 10 when it fails on an unsupported authentication method, such as for example when the UltraVNC server requests MS Logon.

EXAMPLES
Connect rfb://localhost:5901 password=test
Connect localhost:1 password=test
Connect localhost::5901 password=test


- All three examples are equal and connect to a VNC server running on display number 1 (port 5901) of the local machine. Password authentication is expected. This is typical for Linux/Unix systems where port 5900 is usually occupied by the X-Windows server and VNC servers usually runs on ports 5901 and higher.

- Connect to the "Local VNC" connection registered with the Connect Manager. The server URL and password will be loaded from the connection record.

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

Connect file://C:\testdata\images\screen.png

- Load the specified image and display it in place of the desktop.

Connect file://C:\testdata\images\images.jar!/data/screen.png

- Load an image which is zipped as /data/screen.png in the specified JAR file (ZIP is also supported) and display it in place of the desktop.

Connect file://screen.png

- Load the specified image and display it in place of the desktop. As the URL is relative, the image will be loaded from the product installation path.

Connect file://{_SCRIPT_DIR}/screen.png

- Load an image located in the same folder as the test script calling this command and display it in place of the desktop.

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

Connect adb://default

- Connect to to the first Android device connected to the local PC through the USB cable.

Connect adb://MB104PY14322

- Connect to the Android device of the specified serial number through the USB cable.

Connect java://localhost

Connect apple://192.168.100.8:5901

3.1.2 Disconnect

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

EXAMPLES
Disconnect

- Disconnect from the currently connected desktop.

3.1.3 Mouse

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

OPTIONS
modifier

event_id

- Supported events are:

• "move", a mouse pointer move from the optional destination to the target point,
• "click", one or more clicks at the target point using the specified mouse button,
• "press", a mouse button press (without release),
• "release", a mouse button release (logically requires a preceding press event),
• "drag", mouse drag from the optional destination to the target point using the specified mouse button,
• "swipe", a mouse drag with adjusted timing for devices with a touch display (such as Android or iOS devices),
  
• "wheelup", one or more mouse wheel rotation steps upwards (wheel rotating away from user),
  
• "wheeldown", one or more mouse wheel rotation steps downwards (wheel rotating towards user),
• "pinch", one or more pinch events where two fingers move towards a shared center point on a touch screen (also known as "pinch close"). This event is supported just on certain environments, for example on Apple iOS devices running the T-Plan Server connected over the iOS Mirror connection type,
• "zoom", one or more zoom events where two fingers move away from a shared center point on a touch screen (also known as "pinch open"). This event is supported just on certain environments, for example on Apple iOS devices running the T-Plan Server connected over the iOS Mirror connection type. 

btn

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

modifiers

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

- Target coordinates.

• If the event is "move" they define where to move the mouse pointer (target point).
• If the event is "click", "press", "release", "wheelup" or "wheeldown" the mouse pointer will be first moved to this location and then the associated action is performed.
• If the action is "drag" or "swipe" the mouse pointer will be dragged from its actual position (or from the position specified by the from option) to this target 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.

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.

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

- The pinch/zoom center point (optional). It is used only for the "pinch" and "zoom" actions. If the parameter is omitted the action will default to the screen center.

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.

start=<number> end=<number>

- The pinch/zoom start and end distances. It is used only for the "pinch" and "zoom" actions. The parameters must be always specified together. If they are omitted the action will calculate default values based on the center point position and the current screen size.

The distances specify how many pixels the fingers are apart at the beginning ("start") and the end ("end") of the gesture. When the event is "pinch" the start distance must be naturally greater than the end one because the fingers move closer to each other. The "zoom" event requires the opposite setting. The distances must be specified in a way that the fingers don't get too close to each other (30 pixels at a minimum) or closer than 10 pixels to the screen borders. 

count=<number>

- How many times the mouse event should be performed. The default value is 1. This value makes sense only with the click and wheel events and it is ignored by other event types.

wait=<time>

- Time to wait after the events are sent. It has the same effect as if the following command was 'Wait <time>'. The value must be either a number of milliseconds or a valid time value.

RETURNS
The command returns 0 (zero) on success or 1 when it fails,for example for an I/O error.

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 move to=x:{_MOUSE_X}+50

- Move the mouse pointer 50 pixels to the right from its current position.

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



Mouse swipe from=x:161,y:124 to=x:161,y:226



Compareto "icon.png" method=search onfail="Exit 1"
Mouse move to=x:{_SEARCH_X}+10,y:{_SEARCH_Y}+10
Mouse press
Mouse move to=x:{_SEARCH_X}+110 wait=500
Mouse release

Mouse pinch


- Pinch the screen. If the current connection supports pinch it will zoom out the current application.

Mouse zoom center=x:220,y:450 start=125 end=180


- Zoom in the screen. If the current connection supports pinch it will zoom in the current application. The command uses a custom center point and start and end distances.

3.1.4 Paste

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

OPTIONS
text

- The text to paste. 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 - \\"".

Supported text characters are subject to limitations applied by the desktop client (protocol). For example the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On contrary the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to. Read the particular client documentation for more information.

wait=<time>

- Time to wait after the text gets pasted. It has the same effect as if the following command was 'Wait <time>'. The value must be either a number of milliseconds or a valid time value.

count=<number>

- How many times the command should be repeated. The default value is 1 (paste just once).

RETURNS
The command returns 0 (zero) on success or 1 when it fails, for example for an I/O error.

EXAMPLES
Paste "hello world!"

- Paste 'hello world!'.

3.1.5 Press

SYNOPSIS
press [<modifier_1>+...+<modifier_N>+]<key | modifier> [location=<standard|numpad|left|right>] [release=<true|false>] [count=<number>] [wait=<time>]

OPTIONS
key

location=<standard|numpad|left|right>

- Key location. This option makes sense only with keys which are present on a typical keyboard more than once. Examples of such keys are the digit keys '0'-'9' (standard location and num pad) or modifier keys (Ctrl and Alt on the keyboard left and right). Supported location values are standard (default), numpad, left and right.

Note that the command doesn't verify whether the [key,location] pair makes sense. For example, alphabet characters are present on most keyboard just once and the only logically valid location is the default standard one. Most clients however use the location only as a hint and ignore it by keys where it is not applicable.

release=<true|false>

- Supported since 2.3.4. When this parameter is present the command performs just a key press (release=false) or a key release (release=true) instead of the full pres-release sequence. This allows to automate long key presses and/or composed press and mouse events. If you use this parameter to simulate a press make sure that you release the key properly when it is not needed any more.

count=<number>

- How many times the key should be sent. The default value is 1. Delays among multiple press actions are defined by a value in the Press Command user preferences.

wait=<time>

- Time to wait after the events are sent. This parameter is useful if the server needs some time to react on the pressed key/keys. It has the same effect as if the following command was 'Wait <time>'. The value must be either a number of miliseconds or a valid time value.

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

EXAMPLES
Press Ctrl+Alt+Del

- Press the Ctrl+Alt+Del key on the desktop.

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.

Press Ctrl location=right

- Press the right Ctrl key.

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

3.1.5 Type, Typeline

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

OPTIONS
text

- The 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 - \\"".

Supported text characters are subject to limitations applied by the desktop client (protocol). For example the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On contrary the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to. Read the particular client documentation for more information.

wait=<time>

- Time to wait after the text gets typed. This parameter is useful if the server needs some time to react on the pressed key/keys. It has the same effect as if the following command was 'Wait <time>'. The value must be either a number of milliseconds or a valid time value.

location=<standard|numpad|left|right>

- Key location. When specified the command makes an attempt to map the typed characters onto the specififed keyboard location. Though supported location values are standard (default), numpad, left and right, this option makes sense only with the numeric pad which is the only keyboard part containing characters accepted by the command.

Support of this parameter is intended to make testing of mobile devices easier. Numeric keys on mobile devices (especially mobile phones) are often mapped to numpad keys and it is inconvenient to handle each key press through the Press command. For example, to type and call a phone number +0123456789 on the mobile one can simply use "Typeline +0123456789 location=numpad" .

count=<number>

- How many times the command should be repeated. The default value is 1 (type the text/type the line just once).

RETURNS
The command returns 0 (zero) on success or 1 when it fails, for example for an I/O error.

EXAMPLES
Type hello

- Type 'hello'.

Typeline "mkdir /tmp/mydir" wait=2s

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

Type "100*4" location=numpad

- Type the formula on the numeric keyboard.

Typeline "+111222333444" location=numpad

- Type the formula on the numeric keyboard and press Enter. When the system under test is a mobile device with keyboard mapped onto the num pad such as a Nokia phone with Symbian OS, it will place a call to the specified number.

3.2 Administrative & Execution Control Commands

3.2.1 Break

RETURNS
The command doesn't modify the exit code and leaves its value on the one returned by the previously executed command.

EXAMPLES

- Use a combination of for, Waitfor and break to hold on execution until the remote desktop stops to update.

3.2.2 Click

Click <comparison_method>  [timeout=<time>]  [cmparea=<[x:<x>][,y:<y>][,w:<width>][,h:<height>]>]  [number=<component_number>]  [move=<[x:<x>][,y:<y>]>]  [btn=<button>]  [modifiers=<modifiers>]  [count=<number>]  [continue=<true|false>]  [step=<step_name>]  [wait=<time>]  [<method specific options>]
* Red color indicates obligatory parameters

comparison_method

- Supported methods are:

• 'image' - search for a component by the image or an image collection using the search2 method,
• 'object' - search for a component by its color using the object method,
• 'ocr' - recognize text on the screen using OCR (the tocr method) and find the specified string or pattern.
  

COMMON OPTIONS

timeout=<time>

- Timeout specifying how long to wait for the component to appear on the screen at a maximum. The value must be either a number of milliseconds or a valid time value. The default value is 30 seconds.

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

- Ordinary number of the component on the screen to apply the click to. Components (objects) located on the screen are sorted in the reading order, from the top to the bottom and from the left to the right. The default value is 1 (click the first located component). If the number of components found on the screen is lower than the specified number the command exits the script.

- Specifies the click location relatively from the center of the target object (since 4.2). This allows to click a nearby location instead of the object itself. If the comparison method is image the parameter overrides the image click point and uses the image center as the base point. For example, the command of "Click image template=button.png move=x:-40" will click 40 pixels to the left from the button center.

- The mouse button to click. Allowed values are "left", "middle" and "right".

modifiers=<modifiers>

- How many times to click. The default value is 1.

continue=<number>

- The value of true will not terminate the script if the object is not found (since 4.2). The default value is false (terminate on failure).

step=<step_name>

- Simple integration with the Step command (since 4.2). When specified it creates a test step of the given name with the result of pass (object found and clicked) or fail (object not found).

wait=<time>

- Time to wait after the click. It has the same effect as if the following command was 'Wait <time_in_ms>'. The value must be either a number of milliseconds or a valid time value.

Click image template=<image_collection>  [passrate=<pass_rate_in_%>]  [<search2_specific_params>]  [<common options>]
* Red color indicates obligatory parameters

SPECIFIC OPTIONS - IMAGE

template=<image_collectio>

- An image collection - one or more image file names or folders with images separated by 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 relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. Supported image formats are subject to the Java version. 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 and skips any remaining templates in the list. Predefined variable _COMPARETO_TEMPLATE_INDEX may be then used to determine index of the matching template image. See image comparison specific variables for a complete list of supported variables.

passrate=<pass_rate_in_%>

- Pass rate for image comparison. It must be a number between 0 and 100 which may optionally followed by the percentage character (for example "passrate=95" or "passrate=95%"). If this parameter is omitted, the default search2 pass rate of 50% will be used.

search2_specific_params

- Any parameters supported by the search2 comparison method (optional).

Click object  [<object_specific_options>]  [<common options>]

SPECIFIC OPTIONS - OBJECT

object_specific_params

- Any parameters supported by the object comparison method (optional). It is typically necessary to specify at least the object color.

Click ocr  [<tocr_specific_options>]  [<common options>]

SPECIFIC OPTIONS - OCR

tocr_specific_options

- Any parameters supported by the tocr comparison method. It is necessary to specify the target text to apply the click to either through the text or pattern options.

RETURNS
The command always returns 0 on success or exits the script on failure returning the error code from the specified comparison method.

- Click the second button specified by the google_button.png image on the screen. If the button is not found or the number of buttons on the screen is lower than two the command will fail the script. 

- Click an object which is red and its width is not greater than 20 pixels. The tolerance ensures that the method will find more shades of red.

- Read the text on the screen using OCR and click the word of "Cancel". The distance ensures that the word will be found even if the OCR engine omits or fails to recognize a single character, for example "Cancal" etc.

3.2.3 Compareto

1. Image Search v2 ("search2", since v3.0) is successor of the "search" method and performs tolerant search of the desktop screen for the object represented by the template image(s).
   
2. Image search ("search", since v2.0) performs tolerant search of the desktop screen for the object represented by the template image(s).
   
3. Object search ("object", since v2.2) searches objects on the screen by a single RGB color or a range of similar colors.
4. Tesseract OCR ("tocr", since 2.2) performs optical character recognition (OCR) on the desktop image using the free open source Tesseract OCR Engine.
5. Image Based Text Recognition ("text", since 3.0) extracts text from the screen using a collection of presaved character images.
   
6. Histogram based comparison (code "default", since v2.0) is the legacy algorithm comparing histograms of the desktop image and the specified template image(s).
   

OPTIONS
image_collection

- An image collection - one or more image file names or folders with images separated by 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 relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. Supported image formats are subject to the Java version. 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 and skips any remaining templates in the list. Predefined variable _COMPARETO_TEMPLATE_INDEX may be then used to determine index of the matching template image. See image comparison specific variables for a complete list of supported variables.

passrate=<pass_rate_in_%>

- Pass rate for image comparison. It must be a number between 0 and 100 which may optionally 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).

onpass=<command>

onfail=<command>

method=<comparison_method>

methodparams=<custom_params>

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

method_specific_params

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 using the "default" image comparison method. If there is not at least 95% match, terminate the script execution using the Exit command and return exit code 1.

- Search the remote desktop image for a button matching either button1.png or button2.png. If it is found, click on it. The command adds 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}}
}


- Use regular expression to exit the script when the text recognized through Teseract OCR doesn't start either with the 'Application' or 'application' word.

3.2.4 Continue

RETURNS
The command doesn't modify the exit code and leaves its value on the one returned by the previously executed command.

EXAMPLES

3.2.5 Drag

Drag <comparison_method>  [shift=x:<relativeX>,y:<relativeY>]  [template2=<target_component_template>]  [number2=<target_component_number>]  [timeout=<time>]  [cmparea=<[x:<x>][,y:<y>][,w:<width>][,h:<height>]>]  [number=<component_number>]  [btn=<button>]  [modifiers=<modifiers>]  [count=<number>]  [continue=<true|false>]  [step=<step_name>]  [wait=<time>]  [<method specific options>]
* Red color indicates obligatory parameters

comparison_method

- Supported methods are:

• 'image' - search for a component by the image or an image collection using the search2 method,
• 'object' - search for a component by its color using the object method,
• 'ocr' - recognize text on the screen using OCR (the tocr method) and find the specified string or pattern.
  

COMMON OPTIONS

timeout=<time>

- Timeout specifying how long to wait for the component to appear on the screen at a maximum. The value must be either a number of milliseconds or a valid time value. The default value is 30 seconds.

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

- Ordinary number of the source component on the screen to apply the drag to. Components (objects) located on the screen are sorted in the reading order, from the top to the bottom and from the left to the right. The default value is 1 (drag the first located component). If the number of components found on the screen is lower than the specified number the command exits the script.

- The mouse button to click. Allowed values are "left", "middle" and "right".

modifiers=<modifiers>

shift=x:<relativeX>,y:<relativeY>

- Relative coordinates specifying where to drag the component to from its current location. The target (drop) location may be alternatively specified through template2. 

template2=<target_component_template>

- The drop component. When specified the command performs an image search using search2 for the specified component and drags the object to its location. The number2 parameter may be used to specify the drop component number if there are more than one on the screen. When template2 is specified the shift parameter should not be present.

number2=<target_component_number>

- Target component ordinary number. Components (objects) located on the screen are sorted in the reading order, from the top to the bottom and from the left to the right. The default value is 1 (drop at the first located component). If the number of components found on the screen is lower than the specified number the command exits the script. To be used only together with the template2 parameter.

continue=<number>

- The value of true will not terminate the script if the object is not found (since 4.2). The default value is false (terminate on failure).

step=<step_name>

- Simple integration with the Step command (since 4.2). When specified it creates a test step of the given name with the result of pass (object found and dragged) or fail (object not found).

wait=<time>

- Time to wait after the click. It has the same effect as if the following command was 'Wait <time_in_ms>'. The value must be either a number of milliseconds or a valid time value.

Drag image template=<image_collection>  [passrate=<pass_rate_in_%>]  [<search2_specific_params>]  [<common options>]
* Red color indicates obligatory parameters

SPECIFIC OPTIONS - IMAGE

template=<image_collectio>

- An image collection - one or more image file names or folders with images separated by 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 relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. Supported image formats are subject to the Java version. 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 and skips any remaining templates in the list. Predefined variable _COMPARETO_TEMPLATE_INDEX may be then used to determine index of the matching template image. See image comparison specific variables for a complete list of supported variables.

passrate=<pass_rate_in_%>

- Pass rate for image comparison. It must be a number between 0 and 100 which may optionally followed by the percentage character (for example "passrate=95" or "passrate=95%"). If this parameter is omitted, the default search2 pass rate of 50% will be used.

search2_specific_params

- Any parameters supported by the search2 comparison method (optional).

Drag object  [<object_specific_options>]  [<common options>]

SPECIFIC OPTIONS - OBJECT

object_specific_params

- Any parameters supported by the object comparison method (optional). It is typically necessary to specify at least the object color.

Drag ocr  [<tocr_specific_options>]  [<common options>]

SPECIFIC OPTIONS - OCR

tocr_specific_options

- Any parameters supported by the tocr comparison method. It is necessary to specify the target text to apply the click to either through the text or pattern options.

- Find the first lever component on the screen and drag it 100 pixels to the right.

- Example of swapping of two table columns. The command will locate the second column header in the table and drags it onto the third one. If the column is not found or the number of columns  on the screen is lower than three the command will fail the script. 

- Find a green object which is not greater than 20x20 pixels and drag it 50 pixels rightwards and 100 pixels upwards. The tolerance ensures that the method will find more shades of green.

- Read the text on the screen using OCR and drag the word of "Flower" 220 pixels to the bottom.

3.2.6 Eval

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 or a string which results into a numeric expression after all variable calls located in the argument are resolved. If it 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 in always returns 0 (zero) up to version 2.3.2. Version 2.3.3 and newer return 0 if the numeric expression was evaluated correctly or a value other than 0 if the expression could not be evaluated, for example when it contains call of a variable which doesn't exist. This mechanism allows to test whether the value was populated correctly and branch the code through the if/else statement checking the _EXIT_CODE variable value.

EXAMPLES
Eval POSITION=2*(10+1)

- Create a variable POSITION with a value of 22.

- Increase the existing variable of SUM by 10. If the variable doesn't exist the script will terminate with the exit code of 1.

3.2.7 Exec

OPTIONS
command

- The OS command to be executed on the local system. See the command description for OS specific details.

count=<number>

nowait=<false|true>

onpass=<command>

onfail=<command>

outfile=<file_name>

wait=<time>

kill=<processes>

autokill=<false|true>

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). The listing will be available under the _EXEC_OUTPUT variable.

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 on the local machine. The _REPORT_FILE variable is populated by the Report command and contains full report file path.

// Directory to work with.
Var DIR=/tmp

// List the directory contents (Linux/Unix).
// For Windows replace the "ls" command with "cmd.exe /C dir /B"
Exec "ls {DIR}"

// Split the directory listing by lines
String split "{_EXEC_OUTPUT}" pattern="\r?\n"

for (i=1; {i}<{_STRING_COUNT}+1; i={i}+1) {

  // Replace floating point from index (not needed on 2.3.3+)
  String replace "{i}" pattern="[.].*" replacement=""

  Var f="{_STRING{i}}"

  // If the file is a .png or a .jpg image display it for 3 seconds
  if ("{f}" endswith ".png" || "{f}" endswith ".jpg") {
    Connect "file://{DIR}/{f}"
    Wait 3s
  }
}



3.2.8 Exit

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

OPTIONS
exit_code_number

- Mandatory 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 called to terminate the whole script and  there's a report file  created by the Report command it will display the exit code of 0 as "passed/successful" and all other codes are presented as failures. The exit code is also passed to the underlying operating system and can be used to identify the reason of the script termination by third party frameworks.

desc=<description>

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" cumulative=true

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

3.2.9 Imagedoctor

OPTIONS
action

- The action must be one of

• "on" - set on the Image Doctor,
• "off" - set off the Image Doctor,
• "skip" - make Image Doctor ignore eventual failure of the next image comparison command. This is equivalent to setting off Image Doctor before the command and setting it back on after it.

RETURNS
The command always returns 0 (zero).

EXAMPLES
Imagedoctor off

- Set off Image Doctor. No image comparison failure will be processed until it gets set back on.

- Make the Image Doctor wizard ignore eventual failure of the OCR. The second "search2" comparison is out of the scope of the "skip" action and it will be processed in case of failure provided that the Image Doctor is on. 

3.2.10 Include

OPTIONS
file

- A TPR test script file or a Java resource (JAR/ZIP file or a class path) to be included. File name can be either relative (e.g. sayHello.tpr) or absolute (e.g. /root/scripts/sayHello.tpr). T-Plan Robot will check if the file exists and is readable during every script compilation 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, T-Plan Robot reports a syntax error rather than returning a non-zero return value.

EXAMPLES
Include sayHello.tpr

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

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

- Load a Java library (JAR file) from the specified location and execute a test script from there. This presumes that the JAR file contains a package (directory) called "mypackage" with a compiled class called MyTestScript which is a valid Java test script (it extends the DefaultJavaTestScript class or at least implements the JavaTestScript interface). See the Run command below for more information.

3.2.11 Pause

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@dummyserver.com" from="robot@dummyserver.com" server="mail.dummyserver.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.

3.2.12 Run

1. TPR test script in the format described by this specification (typically a .tpr file). T-Plan Robot Enterprise 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. Exit command with the scope set to file can be used to return from a script executed through Run to the main script.
2. Java source file (must be a .java file; supported from version 2.2). The class must be a valid T-Plan Robot Enterprise Java test script which extends the DefaultJavaTestScript class or at least implements the JavaTestScript interface. The Run command compiles the source code, instantiates the class and executes its test() method. As this call requires access to Java compiler, T-Plan Robot Enterprise must run on Java Development Kit (JDK) or be configured with a path to the JDK installation }supported since 2.3.3). If the tool runs just on Java Runtime Environment (JRE) and no JDK is available the tool will report an error. Refer to chapter 1 of the Release Notes document for instructions.
3. Java class name (supported from version 2.2). It must be a fully qualified Java class name (package+class name) corresponding to a valid T-Plan Robot Enterprise Java test script which extends the DefaultJavaTestScript class or at least implements the JavaTestScript interface. The class must have the default (parameterless) constructor. The Run command instantiates the class by name and executes its test() method. As this method doesn't involve compilation of Java code, it is very fast with a minimum performance overhead and it is recommended for production scenarios. The compiled class code must be placed on the T-Plan Robot Enterprise class path in one of the three supported ways:
• Load the code (JAR, ZIP or class path) through the Include command. This way makes the test script load the code dynamically and make it available to the current Java/Robot instance.
  
• Add the JAR, ZIP or class path to the "-classpath" parameter of the Robot's start command described in the Release Notes. This will make the code available to the particular Java/Robot instance.
• Put the JAR file with the code to <java-home>\lib\ext (Windows) or <java-home>/lib/ext (Linux/Unix) of the Java installation used to execute Robot. This will make the code available to any instance of Java started from this installation (and thus to all Robot instances as well).

OPTIONS
file

- The file can be one of:

1. A TPR test script file (*.tpr) or a Java test script file (*.java). The file can be either relative to the current script file (for example sayHello.tpr) or absolute (/root/scripts/sayHello.tpr).  T-Plan Robot will check if the file exists and is readable during every script validation and report an error if not.
   
2. A fully qualified Java test script class name (for example org.mytests.DoSomething). The specified class must be on the Java class path. For details see the command description.

<param>=<value>

- Optional list of parameters and their values. They will be made available to the executed file in form of local variables.

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

EXAMPLES
Run sayHello.tpr

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

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

- Executes the specified Java source code file. It must be a class extending com.tplan.robot.scripting.DefaultJavaTestScript or at least implementing the com.tplan.robot.scripting.JavaTestScript interface. The file is first compiled using the Java Compiler API into the byte code format and then instantiated and executed. This will work only if T-Plan Robot Enterprise runs on Java from a JDK distribution or is configured with a valid path to a JDK installation (v2.3.3 and newer).

- Instantiates a Java test script class and executes it. The class must be on the Java class path and it must extend com.tplan.robot.scripting.DefaultJavaTestScript or at least implement the com.tplan.robot.scripting.JavaTestScript interface. The two parameters on the command line are made inserted into the context as variables; it is however up to the executed class to use them or not.

- Execute a script specified by a variable.

3.2.13 String

• indexof - Returns the index within the text of the first occurrence of the substring specified through the 'string' parameter. Since v3.5.2 the command may also perform a fuzzy text search similar to the functionality provided by the "tocr" comparison method. Indexing starts from zero. If the specified string is not found, the result is -1. For example, 'String indexof "Demo text" string=text'  will set the _STRING variable to 5. This operation is typically used in combination with the 'substring' one to text parsing. If you need to test existence of a substring in the given text and you are not interested in its position it is easier to take advantage of the 'contains' boolean operator.
  
• length - Returns the text length (number of characters). For example, 'String length  "Demo" '  will set the _STRING variable to 4.
• matches - Matches the text to a java.util.regex.Pattern compliant regular expression specified through the 'pattern' parameter and produces a boolean result (either 'true' or 'false'). For example, 'String matches "a20" pattern="[a-z][0-9]*" ' sets the _STRING variable to 'true' because the regular expression matches any sequence consisting of a lower case character followed by a sequence of digits. The 'matches' operation is also supported in form of a boolean operator for easy use with the if/else statements.

Since v3.5.2 the command also allows to perform fuzzy text matching. See the "matches" command for details.

• replace - Returns a new text resulting from replacing all occurrences of value specified by the 'string' parameter in the text with the string provided in the 'replacement' parameter. The operation may be also used with 'pattern' instead of 'string' to perform replacement of all occurencies matching the specified java.util.regex.Pattern regular expression. For example, 'String replace "fox" string=f replacement=s' will set the _STRING variable to 'sox'.
• split - Splits the text into a set of strings around matches of the given string ('string' parameter) or java.util.regex.Pattern regular expression ('pattern'). For example, 'String split "brown fox" string=" " ' will produce two values, _STRING1=brown and _STRING2=fox and sets the _STRING_COUNT variable to 2.
• substring - Returns a substring of the text which is defined by the input 'start' and/or 'end' index numbers. Indexing starts from zero and the value of 0 refers to the text beginning (first character). For example, 'String substring "someone" start=4' will set the _STRING variable to 'one'.
• tostring - Creates a new text from one or more semicolon separated numeric ASCII or Unicode values. This can be used to produce special characters and/or characters of national alphabets. For example, 'String tostring "49;43;49" ' will set the _STRING variable to '1+1'.
• trim (since 2.3.3) - Removes all leading and trailing whitespace characters (spaces, new line characters etc.). For example, 'String trim " apple   " ' will set the _STRING variable to 'apple'.
  

String indexof  "<text>"  string=<text> [start=<index>]  [end=<index>]  [distance=<number>]  [var=<variable_name>]
* Red color indicates obligatory parameters

OPTIONS
text

string

start

- Optional start index to start the search from. It must be a number or a valid numeric expression. Indexing starts from zero where zero refers to the text beginning (first character). The default start index value is 0.

end

- Optional end index to end the search at. It must be a number or a valid numeric expression. The default value is the text length (the end of the text).

distance

- Optional distance used in conjunction with the "string" parameter to perform tolerant text search (supported since 3.5.2). When the parameter is set to the default value of 0 (no distance) the command falls back to plain string search where the argument text is searched for the first occurrence of the provided string.

The tolerant (fuzzy) text search is performed for the distance values of 1 and higher. The text is searched for occurrence of a string which is similar enough to the specified one. The tolerance (similarity) is based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. The distance approximately specifies how many characters may be omitted or not recognized properly at a maximum to consider the sample text equivalent.

To perform fuzzy text matching instead of search use the String matches command.

var

- Optional name of the variable to store the resulting index to. If this parameter is not specified the result will be stored to the default _STRING variable.

RETURNS
The 'String indexof ' command returns 0 (zero) if the specified string was found in the text and 1 otherwise. The command further on stores the index (or -1 if not found) to the _STRING variable (or a custom variable specified by the 'var' parameter). Indexing starts from zero where zero refers to the text beginning (first character).

EXAMPLES
String indexof "Demo text" string="text" var=result 

- Get position (index) of "text" in "Demo text" and store the result of 5 into the "result" variable.

- Same as the previous example save that the word of "text" will be located by the specified string of "test" because it is within the distance of 1.

OPTIONS
var

- Optional name of the variable to store the resulting text length to. If this parameter is not specified the result will be stored to the default _STRING variable.

RETURNS
The 'String length' command always returns 0 (zero) and stores the argument text length (number of characters) to the _STRING variable or a custom variable specified by the 'var' parameter.

EXAMPLES
String length "Demo text" var=len 

- Stores the length of "Demo text" (9) into the "len" variable.

OPTIONS
pattern

- A java.util.regex.Pattern compliant regular expression. The regular expression of "." matches by default any character except for the line terminator. This behavior may be changed through the command preferences.

Be aware that the expression must match the whole text. The command will NOT search the text for its portion that would match the expression. For example, to search the text for the "test" word you have to use the expression of ".*test.*" which means "the word of 'test' which may or may not contain any (.*) preceding and/or trailing text". 

string

- A string to search the text for (supported since 3.5.2). 

- Optional distance used in conjunction with the "string" parameter to perform tolerant text matching (supported since 3.5.2). When the parameter is set to the default value of 0 (no distance) the command falls back to plain string comparison where the argument text is tested whether it is equal to the provided string.

The tolerant (fuzzy) text matching is performed for the distance values of 1 and higher. The text is tested whether it is similar enough to the specified string. The tolerance (similarity) is based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. The distance approximately specifies how many characters may be omitted or not recognized properly at a maximum to consider the sample text equivalent.

Be aware that the specified string must match the whole argument text. To perform a fuzzy text search to find a string similar to the specified one use String indexof instead.

var

- Optional name of the variable to store the resulting boolean flag (true/false) to. If this parameter is not specified the result will be stored to the default _STRING variable.

RETURNS
The 'String matches'command returns 0 (zero) if the text matches the regular expression or 1 when not. The command further on stores the result as 'true' or 'false' to the _STRING variable or a custom variable specified by the 'var' parameter.

EXAMPLES

File open file="C:\data.txt"
Var result=-1
for (i=1; {i}<{_FILE_LINE_COUNT}+1; i={i}+1) {
   File read line={i}
   String matches "{_FILE_READ}" pattern="[a-z]*"
   if ({_EXIT_CODE} == 0) {
       Var result={i}
       Break
      }
}

- Test the sample text in various ways.

OPTIONS
replacement

string

pattern

- A java.util.regex.Pattern compliant regular expression representing the strings to be replaced. The regular expression of "." matches by default any character except for the line terminator. This behavior may be changed through the command preferences.

var

- Optional name of the variable to store the resulting new text to. If this parameter is not specified the result will be stored to the default _STRING variable.

RETURNS
The 'String replace' command returns 0 (zero) if at least one replacement has been performed or 1 when no replacement has been done and the resulting text equals to the original one. The new text is stored to the _STRING variable or a custom variable specified by the 'var' parameter regardles of whether it has been changed or not.

EXAMPLES

String replace "bad fat cat" string="b" replacement="s"



OPTIONS
string

pattern

- A java.util.regex.Pattern compliant regular expression to split by. The regular expression of "." matches by default any character except for the line terminator. This behavior may be changed through the command preferences.

var

- Optional base name of the variables to store the resulting strings to. If this parameter is not specified the result will be stored to the default numbered _STRING<number> variables.

RETURNS
The 'String split' command always returns 0 (zero). Each parsed value is saved to a numbered variable such as _STRING1, _STRING2 etc. or to similarly numbered set of variables derived from name specified by the 'var' parameter. Number of values is then stored to the _STRING_COUNT variable.

EXAMPLES

String split "bad fat cat" string=" " var="s"



OPTIONS
start

end

var

- Optional base name of the variables to store the resulting substring to. If this parameter is not specified the result will be stored to the default _STRING variable.

RETURNS
The 'String substring' command returns 0 (zero) when the start and end indices refer to valid positions in the text. If the start position is invalid (meaning it is less than zero or equal to or larger than the text length), the command sets the start index to 0 and returns 1. Otherwise if the end position is invalid (meaning it is less than the start position or larger than the text length), the command sets the end index to the default value of text length and returns 2. Regardless of the returned value the _STRING variable (or the custom one passed through the 'var' parameter) is always populated with a new substring between the start and end positions.

EXAMPLES

String substring "bad fat cat" start="4" var="s"



OPTIONS
unicode

var

- Optional base name of the variables to store the resulting string to. If this parameter is not specified the result will be stored to the default _STRING variable.

RETURNS
The 'String tostring' command returns 0 (zero) on success and 1 when one or more codes do not correspond to valid ASCII/Unicode characters. The command on success populates the _STRING variable (or the custom one passed through the 'var' parameter) with the converted string.

EXAMPLES

String tostring "104;101;101;108;111" var="s"



OPTIONS
var

- Optional base name of the variables to store the resulting string to. If this parameter is not specified the result will be stored to the default _STRING variable.

RETURNS
The 'String trim' command always returns 0 (zero). The command on success populates the _STRING variable (or the custom one passed through the 'var' parameter) with the trimmed string.

EXAMPLES

String trim " Hello!  " var="s"



3.2.14 Var

Variables starting with underscore ('_') are so called predefined variables. They are typically provided by T-Plan Robot or by its commands and contain useful values providing information about the execution context and operation results.  A non-exhaustive 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

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


3.2.15 Varf

SYNOPSIS
varf <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 may 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". Escape sequences will be converted as follows:

    \b    /* \u0008: backspace BS */
    \t    /* \u0009: horizontal tab HT */
    \n    /* \u000a: linefeed LF */
    \f    /* \u000c: form feed FF */
    \r    /* \u000d: carriage return CR */
    \"    /* \u0022: double quote " */
    \'    /* \u0027: single quote ' */
    \\              /* \u005c: backslash \ */
    \uNNNN will be converted to the appropriate Unicode character as long as NNNN is a valid Unicode character hexadecimal value
  

RETURNS
The Varf command always returns 0 (zero).

EXAMPLES

Varf MULTILINE="Line #1\nLine #2"

- Populate the MULTILINE variable with two lines of text (the '\n' sequence will be converted to new line).

Varf MULTILINE="Line #1\u000aLine #2"

- Same example as above where the new line character is specified through escaped Unicode (new line is ASCII 10, 0x0a).

3.2.16 Wait

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 milliseconds. See syntax of time values for specification of time formats.

RETURNS
The command always returns 0 (zero).

EXAMPLES
Wait 30000
Wait 30s
Wait 0.5m

- All three commands are equivalent and make the script wait for 30 seconds (aka 30,000 milliseconds or half a minute) before proceeding to the next command.

3.2.17 Waitfor

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

Waitfor <event_id> [<event 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'.

• 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 Waifor 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 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 15 seconds.

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.

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, T-Plan 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 T-Plan Robot will sumarize 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.