Var

3.2.16 Var

DESCRIPTION

Var - Define a script variable. See the Variables chapter for a general description of script variable support.

For the creation of formatted text (multiple lines, tabs, ...) use the Varf command. To evaluate (calculate) value of a numeric expression and store it to a variable use the Eval command.

Variables starting with an 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.

Who Creates and When

Variable Name

Description

Robot when the client receives a clipboard change from desktop server

_SERVER_CLIPBOARD_CONTENT=<text>

Content of the remote desktop clipboard. It is typically populated after the server clipboard changes, for example as a result of a copy action (Ctrl+C) performed on the remote desktop. This mechanism is referred to as the "server to client transfer".

Version 3.4 and higher supports bi-directional clipboard update. The script may set the variable using the Var or Eval command to change the server clipboard content. This mechanism is referred to as the "client to server transfer".

The ability to transfer text to/from the clipboard is subject to the connection type and the server vendor.

The VNC connection type supports bi-directional transfer where the server is either UltraVNC or RealVNC. TightVNC doesn't support the client to server transfer, and it requires an additional utility to enable the server to client transfer. Other servers are available.

The Local Desktop connection supports the bi-directional transfer of data. As the local clipboard is being checked using a polling mechanism every 200ms, it is necessary to make the script wait at least 200ms after pressing the Ctrl+C, to make sure the variable gets populated properly. The clipboard content may also change after a call of TypeTypeline or Press which partially rely on the local clipboard to perform the keyboard output.

Other connection types do not support clipboard transfer. For more clipboard related functionality see the Waitfor clipboard command.

Robot when the client receives a clipboard change from desktop server_SERVER_CLIPBOARD_CONTENT_TEXT=<text>This variable follows the same rules as the _SERVER_CLIPBOARD_CONTENT one above save for two exceptions. If the clipboard contains an HTML document or a chunk of HTML code the variable gets populated with the plain text content extracted from the HTML. Otherwise, the content of the two variables is equal. The setting of this variable also won't update the server clipboard. Supported since 4.1.1.
Robot when script execution is started or when a script is compiled._DATE=<yyyyMMdd>

Date of the execution starts in the "yyyyMMdd" format. 

For example, May 8, 2005, will be defined as "20050508". The format may be customized in the Language panel of user preferences. To get the current date see the _CURDATE variable below.

_TIME=<HHmmss>

Time of the execution starts in the "HHmmss" 24-hrs. format.

For example, 3:10:33 pm will be defined as "151033". The format may be customized in the Language panel of user preferences. To get the current time in milliseconds see the _CURTIME variable below. Should you need a formatted version of current time use _CURDATE with a custom format.

_FILE=<file>The absolute path of the executed script, e.g. "/root/test.txt".
_FILENAME=<filename>The script file name, e.g. "test.txt". 

_REPORT_DIR=<path>

The target directory for screenshots and reports. All screenshots and reports will be saved to this directory unless they are specified via absolute path. The explicit setting of this variable in the script overrides the default path which is defined as follows:
  1. The global path in the Language panel of user preferences has the highest priority if it is populated.
  2. If the script is part of a project the path defaults to a unique folder created in the project's report directory (since v4.0). Otherwise, it falls back to the user home folder (the default behaviour of v3.x).
The path can be comfortably set through the Paths component.
_REPORT_FILE=<file>Absolute path to the report (if the report is being created by the script). Supported since v4.0.
_REPORT_FILE_RELATIVE=<file>Path of the report file relatively to the report folder specified by _REPORT_DIR. Supported since v4.1.3.

_TEMPLATE_DIR=<path>

Source directory containing template images for image comparison. Commands employing image comparison will search this directory for all templates specified by relative path. The explicit setting of this variable in the script overrides the default path which is defined as follows:
  1. The global path in the Language panel of user preferences has the highest priority if it is populated.
  2. If the script is part of a project the path defaults to the project template directory (since v4.0). Otherwise, it falls back to the user home folder (the default behaviour of v3.x).
The path can be comfortably set through the Paths component.
_SCRIPT_DIR=<path>Directory where the currently executed script is located (absolute path).
_WARNING_COUNT=<number>The number of warnings which have been generated by the Warning command during the script execution.

_CURDATE_FORMAT=<format>

Date/time format for the _CURDATE dynamic variable. It must be a string complying with the java.text.SimpleDateFormat specification.

For example, setting the variable to "yyyy" will cause any later use of _CURDATE to produce "2010" (the current year in 4-digit format). The setting of this variable to an empty string will revert the format to the default value.

_RANDOM_MIN=<integer_number>
_RANDOM_MAX=<integer_number>

Minimum and maximum values for the random value generator used for the dynamic variable _RANDOM. Default values are 1 and 100000.

_RGB_X=<x_coordinate>
_RGB_Y=<y_coordinate>

Coordinates used to retrieve RGB from the desktop image. Users are advised to set these two variables to the desired coordinates to retrieve the pixel colour through the _RGB dynamic variable.

_INSTALL_DIR=<installation_path>

Installation directory. It is equal to the location of the robot.jar file. The directory is absolute and does not end with the file separator. Supported since v2.3.

_ENV_<variable_name>=<value>

Environment variables. These are OS-specific variables provided by the hosting operating system. These variables may not be populated if such an option is selected in the Scripting->Language panel of the Preferences window. Supported since v2.3.

_EXECUTION_SPEED_FACTOR=<float_number>

The factor to multiply all the 'wait' and 'timeout' script times with. This allows to speed up or slow down the script execution. The variable is initialized to the value specified in the Preferences->Execution panel. The default value is 1 which means '100%'.

For example, to slow down the script and make all wait times 50% longer set the value to '1.5'. Supported since 3.2.

_FS=<local_OS_file_separator>

_FPS=<local_OS_file_path_separator>

The local OS file separator (backslash '\' on Windows, slash '/' on Linux/Unix) and the file path separator (semicolon ';' on Windows, colon ':' on Linux/Unix). 

The separators enable to construct OS independent relative paths and path lists to allow to execute a script from any system.

For example, if the relative Windows path of "..\data" is specified as "..{_FS}data" the script will work correctly also on any Unix/Linux system.

_STEP_SUMMARY_FORMAT=<format>

Format of the step summary produced by the _STEP_SUMMARY dynamic variable. The format can be any string defining how to append a single Step result to the summary. Rules: - All occurrences of "{<param>}" where <param> is a valid lowercase Step command parameter name (name, expected, actual, instruct, notes) or the result the keyword will be replaced with the corresponding Step attribute. - If the <param> string is in upper case (for example {RESULT}) it will be replaced with the upper case attribute value. - The string of "\n" will be replaced with the new line character.

The default format of:

Step "{name}": {RESULT}\n

will produce a summary like:

Step "Click button1": PASS
Step "Click button2": PASS
Step "Click button3": FAIL
Supported since 3.5.1.
Robot whenever the variable is used. As values of these variables are created at the time of the variable call, they are called "dynamic variables".

_CURTIME=<time_in_milliseconds>

Whenever this variable is used, it is dynamically replaced by the current system time in milliseconds since midnight of January 1, 1970, UTC. You may use this variable to calculate how long the command or a block of commands took to execute or to measure the performance of the remote system.
_CURDATE=<formatted_time_and_date>Produces a readable current time and/or date. The format may be specified in the script through the _CURDATE_FORMAT variable. If the variable is not set the format defaults to the value in user configuration (see the Language panel of user preferences). If neither the preference is set the format defaults to the default Java one produced by  java.util.Date().toString().

_MOUSE_X=<X_coordinate>
_MOUSE_Y=<Y_coordinate>

Return current mouse pointer X, Y coordinates. If the tool is not connected to a desktop or no mouse event has been registered yet since the connection, the coordinates return [0, 0].

_RANDOM=<random_integer>

Whenever used the variable produces a random integer number. The range is by default set to [1, 100000] and maybe changed through the _RANDOM_MIN and _RANDOM_MAX variables (see above).

_RGB=<RGB_color>

Whenever used the variable retrieves current colour of the desktop image pixel pointed to by coordinates specified by the _RGB_X and _RGB_Y variables. This can be used to test whether a location on the screen contains a particular colour or not. Users are advised to set the _RGB_X and _RGB_Y variables to the target coordinates and then call the _RGB variable to retrieve the colour.

The pixel value is returned in HTML-style format string, 6 characters long, with R, G, B components specified in this order as lower case hexadecimal values (2 characters per component). For example the white color of RGB(255, 255, 255) is presented as "ffffff" while the green color of RGB (0, 255, 0) produces "00ff00".

A typical example testing whether the pixel at [234,128] is green:

Var  _RGB_X=234 _RGB_Y=128
if ("{_RGB}" == "00ff00") {
   // The pixel is green
}
This mechanism is suitable for a simple exact colour matching only. For more general testing of a screen area for objects of a particular colour or colour shade, see the Object Search algorithm employed by the ComparetoScreenshot and 'Waifor match' commands.

_STEP_SUMMARY=<step_summary>

A plain text summary of step results (one line per step) recorded within the script so far. For example:
Step  "Click button1" 
Step  "Click button2" 
Step  "Click button3"  fail 
Var  SUMMARY= "{_STEP_SUMMARY}"
After execution of the code above the SUMMARY variable will contain:
Step "Click button1": PASS
Step "Click button2": PASS
Step "Click button3": FAIL
The summary format can be customized at the script scope through the _STEP_SUMMARY_FORMAT variable or globally through the Step command preferences. When both ways are used the variable has higher priority. Supported since 3.5.1.

_IOS_DEVICES=<list>

The variable expands into a semicolon separated list of names of mobile devices attached to the local USB ports on Mac OS X. Supported since 5.0.6.

Whenever called the variable populates additional variables:

_IOS_DEVICE_COUNT=<number>
_IOS_DEVICE_<n>=<n-th_deviceName>

Robot when script execution is started. Also updated by  Connect and Disconnect commands.

_MACHINE=<servername>

Desktop server machine name to which Robot is connected. The variable is empty if there is no connection.
_PORT=<portnumber>Desktop server port number. If the connected desktop doesn't use a TCP/IP connection (such as drivers attached directly to local displays), the variable is empty. 
_PROTOCOL=<protocolname>Name (code) of the current desktop connection protocol in upper case, for example, "RFB", "ADB" or "JAVA".
_URL=<desktop_url>Desktop URL containing protocol, machine (host) name and optionally port number.
_DESKTOP_WIDTH=<width_in_pixels>Width of the currently connected remote desktop (in pixels).
_DESKTOP_HEIGHT=<width_in_pixels>Height of the currently connected remote desktop (in pixels).

_DISPLAY_COUNT=<number_of_displays>

The number of displays (screens) managed by the connection. Supported since 4.3.1. As of this release, the only multi-display capable connection is the Local Desktop one. All other connections show the count as 1 (one).
_DISPLAY_X_<n>=<number_in_pixels>
_DISPLAY_Y_<n>=<number_in_pixels>
_DISPLAY_W_<n>=<number_in_pixels>
_DISPLAY_H_<n>=<number_in_pixels>

Coordinates (x, y, width and height) of the n-th display. Numbering starts at 1 and is subject to the local OS.

Connections that do not support multiple displays set the X and Y coordinates to zero and the width and height are set to the desktop ones. Supported since 4.3.1.

RFB (VNC) Client when connected or disconnected_DISPLAY=<servername>:[<display#>]

Display variable which is useful for display redirection on Unix/Linux systems.

It is in the "server:port" format, e.g. "mymachine:2" defines a machine called 'mymachine' running a VNC server on port 5902.

The variable is empty if there is no VNC connection.

Waitfor command when an update event complying with the given criteria occurs _X=<number_in_pixels>The 'x' coordinate of the last update event that met the criteria.
_Y=<number_in_pixels>The 'y' coordinate of the last update event that met the criteria.
_W=<number_in_pixels>The 'width' coordinate of the last update event that met the criteria.
_H=<number_in_pixels>The 'height' coordinate of the last update event that met the criteria.
Waitfor command after every execution _TIMEOUT=<true|false>If timeout is defined and reached, the Waitfor command will set this variable to 'true', otherwise to 'false'.
Report command whenever a report gets generated_REPORT_FILE=<file>Report file (absolute path), e.g. '/root/report.html'.
_REPORT_FILENAME=<filename>Report file name, e.g. 'report.html'.
_REPORT_FILE_RELATIVE=<file>Report file path relative to the report (output) directory, for example, 'MyTestScript.tpr.2a12fd2/report.xml'. Supported since 4.1.3.
Commands performing search for a component or text on the screen such as  ComparetoScreenshot , Waifor match/mismatchClick  and Drag_COMPARETO_TEMPLATE=<file>Image file (absolute path) used for last image comparison.
_COMPARETO_RESULT=<number>Comparison result percentage. It is always a number between 0 and 100. It indicates how much the images matched.
_COMPARETO_PASS_RATE=<number>Pass rate percentage used for the last image comparison. It is always a number between 0 and 100.
_COMPARETO_TIME_IN_MS=<milliseconds>Time in milliseconds spent by the image comparison. If there's a list of templates, the value represents a summary time of all performed comparisons.
_COMPARETO_TEMPLATE_INDEX=<number>Index of the template in the template list which produced the pass result. Indexing starts from zero. 
_COMPARETO_TEMPLATE_WIDTH=<number>
_COMPARETO_TEMPLATE_HEIGHT=<number>
Dimensions of the matching template image. Since v4.4 the variables are populated with the last template image used when the comparison fails.
_COMPARETO_SOURCE_X=<number>
_COMPARETO_SOURCE_Y=<number>

Source coordinates of the last compared template. These variables are populated only for templates created with version 2.2 and higher.

See the Image Meta Data chapter for details.

_COMPARETO_CLICK_X=<number>
_COMPARETO_CLICK_Y=<number>
Click point of the last compared template image. The coordinates by default point to the centre of the component located through the "search" image comparison algorithm or to the custom relative location. See the Image Meta Data chapter for details.
_COMPARETO_CLICK_X_<n>=<number>
_COMPARETO_CLICK_Y_<n>=<number>
Click point of the last compared template image of the <n>-th match. The coordinates by default point to the centre of the component located through the "search" image comparison algorithm or to the custom relative location defined by the click point when the template image was created. See the Image Meta Data chapter for details.
_COMPARETO_DISPLAY_NO=<display_number>
_COMPARETO_DISPLAY_NO _<n>=<display_number>

The number of the display the topmost or the n-th match was located on.

Numbering starts with 1 and is subject to the local OS. Supported since 4.3.1. As of this release the only multi-display capable connection is the Local Desktop one. All other connections show the number always as 1 (one).

User (customizable)_COMPARETO_SORT_MODE=<number>Desired sort mode to be applied to template images loaded from directories. See the Image Collections chapter for details.

_DESKTOP_SIZE=w:<width>;h:<height>

The target size of the iOS screen mirrored through the iOS Mirror connection. Whenever the Var command setting this variable is executed it will resize the mirrored screen to ensure that image comparison of template images created against the particular screen size will work correctly. Read the iOS Mirror connection document for details.
Compareto command,  Screenshot comparisons and 'Waifor match' calls when "search" comparison method is used_SEARCH_MATCH_COUNT=<number>Number of matches found through image search. It is always an integer greater than or equal to zero.
_SEARCH_X=<number>The 'x' coordinate of the first match. If the template image was not found, the value is -1.
_SEARCH_Y=<number>The 'y' coordinate of the first match. If the template image was not found, the value is -1.
_SEARCH_X_<n>=<number>
_SEARCH_Y_<n>=<number>
The 'x' and 'y' coordinates of the n-th match where n is between 1 and the value of _SEARCH_MATCH_COUNT.
Compareto command,  Screenshot comparisons and 'Waifor match' calls when "object" comparison method is used_OBJECT_COUNT=<number>The number of objects located through the "object" image comparison method.
_OBJECT_X_<n>=<number>
_OBJECT_Y_<n>=<number>
_OBJECT_W_<n>=<number>
_OBJECT_H_<n>=<number>
The 'x' and 'y' coordinates, width and height of the n-th object where n is between 1 and value of _OBJECT_COUNT.
Exec command after every execution_EXEC_OUTPUT=<text>The standard output of the executed command, i.e. messages which are printed into the console.
_EXEC_ERROR=<text>Error output of the executed command, i.e. error messages which are printed into the console.
_EXEC_COMMAND=<command>Last executed OS command, i.e. the Exec argument.
_EXEC_VALUE=<number>Integer exit code of the executed OS command.

Image comparison commands such as ComparetoScreenshot , Waifor match/mismatchClick  and Drag

_LAST_CMP_COMMAND=<command>Text of the last executed image comparison command. Supported since v4.4.2.
Script during execution

_TPR_LAST_COMMAND_1=<command>
_TPR_LAST_COMMAND_2=<command>
_TPR_LAST_COMMAND_3=<command>

Text of the last 3 executed commands with all variable calls resolved and substituted. Supported since 6.1.

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

- An example of nested variable references searching the remote desktop image for an icon represented by the template image search.png and clicking onto each of the occurrences.