1. Introduction

1.1 Purpose

This document provides a complete specification of the script language supported by T-Plan Robot. Its goal is to provide a complete syntax and functionality reference to those who write automated scripts using this tool and its testing framework. As the scripting language is tightly coupled with the Java Script API, it is also intended to provide a complementary functionality reference for the design of Java scripts.
Scripts in the language described by this document are called TPR scripts. Scripts based on the Java Script API are called Java scripts.
The document describes 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 scripts. It is a structured procedural language somewhat similar to shell scripting on Linux/Unix. It supports structures and elements well known from modern 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 Language Reference and if/else,
• Set of functional commands indicating result through a numeric return value.

As T-Plan Robot 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 the 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 the necessary infrastructure for script execution control (pause, stop, desktop image analysis, waiting for a specified time period or particular event) as well as the 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 results to an associated test management tool.
4. I/O Commands deal with input from and output to various data sources.

Be aware that the behaviour of some commands may be customized through user preferences. Such parameters are implementation-specific and do not always form part of this documentation. To explore whether there are any configurable values open the Preferences window in the T-Plan Robot  GUI and check whether there is a command preference panel under the Plugins section. Though the scripting language provides a fast and easy way of automation, it has limited functionality and it lacks an object-oriented approach. For this reason, T-Plan Robot version 2.0 introduced Java Script API allowing to write scripts in pure Java through calls of methods accessing the functionality of commands specified by this reference. That is why you should refer to this specification even if you plan on sticking to Java. See the Java API documentation for details, in particular the Developing Java Scripts document. Scripts may be also customized with embedded snippets of Java source code (see the Java Code Blocks chapter). Another way of enhancing the language with your custom actions coded in Java is the Run command which supports parametrized calls of Java since v2.2.

1.3 Robot 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 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 versions are compatible with the T-Plan Robot language.

2. Language Syntax

• Language Structure
• Time Values
• Variables
• Procedures
• Fallback Procedures
• Numeric Expressions
• Boolean Expressions
• Functions
• If/Else Statement
• For Statement
• Return Values
• Java Code Blocks
• Arrays

2.1 Language Structure

T-Plan Robot Enterprise language is a text-based programming language and scripts are typically saved as plain text files. The following general rules apply:

• 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 interpreted according to the following rules:

• Scripts are processed line by line. A single command or expression cannot 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, tabulators 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 '//':

# This is a comment
// This is also a comment

• 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 'identifier=value' or 'identifier="value with spaces"' are considered to be one single token and they are further parsed into identifier/value pairs.
   
   Examples:
   This is a text containing spaces
   - Will be parsed into 6 tokens: 'This', 'is', 'a', 'text', 'containing', 'spaces'. 
   
   This "is a text" containing spaces
   - Will be parsed into 4 tokens, 'This', 'is a text', 'containing', 'spaces'. 
   
   This text contains "double quote (\")"
   - Will be parsed into 4 tokens, 'This', 'text', 'contains', 'double quote (")'
   
   Var SAMPLE_VAR_1="value with spaces" SAMPLE_VAR_2=no_spaces "NO_VAR=not_a_variable"
   - Will be parsed into 4 tokens: 'Var,'SAMPLE_VAR_1="value with spaces"', 'SAMPLE_VAR_2=no_spaces' and 'NO_VAR=not_a_variable'. The second and third tokens will be further parsed into identifier/value pairs. The fourth token will not be parsed as it does not comply with the required format.
   
   This design doesn't allow to specify a value with a trailing backslash:
   
   Var SAMPLE_VAR="This is a backslash \"
   
   The compiler reports an error because the trailing '\"' sequence is interpreted as escaped double quote instead of a backslash followed by the closing double quote. Version 4.4.4 introduced the '&bs;' keyword which gets replaced internally by a backslash:
   
   Var SAMPLE_VAR="This is a backslash &bs;"
   
2. The very first token is considered to be a command or procedure name and is matched against command and procedure tables. Command names are NOT case sensitive.
3. Further processing and syntax validation are then performed by the command/procedure handlers as described below in the Command Syntax and Procedures chapters.

2.2 Time Values

Time values such as the Wait command argument and wait/timeout/delay parameters of other commands support the following syntax:

• "1" is parsed as 1 millisecond,
• "1s" is 1 second,
• "1m" is 1 minute,
• "1h" is 1 hour,
• "1d" is one day.
• "1w" is one week (since 7.0.2).
• "1M" is one month (since 7.0.2)
• "1y" is one year (since 7.0.2).

Floating point variables are acceptable in the English format only, i.e. '3.5h' will be parsed as 3.5 hrs (3 hrs 30 mins). Time values may contain numeric expressions - check the Numeric Expressions chapter for syntax.

Examples:

Wait "1.5d"
- Wait one and a half days (36 hours)

Press Ctrl+C wait=5s 
- Press Ctrl+C and pause for 5 seconds.

2.3 Variables

Variables may be created through the Var and Eval commands. A variable has a case sensitive name and a value. Variables can be referred to in anywhere where dynamic content is needed (including the Var/Eval commands themselves). T-Plan Robot Enterprise's text preprocessor will replace all occurrences of {<var_name>} with the <var_name> variable value before parsing of each command line.

A typical example:

Var PATH=/tmp
Typeline "mkdir -p {PATH}; cd {PATH}"

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:

# Var PATH=/tmp
Typeline "cd {PATH}" 

The preprocessor supports nested variable references. This functionality is necessary to process multiple matches of the 'search' image comparison method where coordinates of the matches are stored as SEARCH_X<number> and it is necessary to generate the variable names dynamically in a loop. The following example illustrates such usage. Let's suppose that you are to search the remote desktop for an icon and you click onto each of the occurrences:

Compareto "search.png" method="search"
for (i=1; {i}<{_SEARCH_MATCH_COUNT}+1; i={i}+1) {
  # Nested variables compose the variable name from a suffix and an index
  Mouse click to=x:{_SEARCH_X{i}},y:{SEARCH_Y{i}}_ 
}

T-Plan Robot Enterprise also supports a concept of global and local variables which is similar to member class and local variables in object-oriented programming (OOP). The variable type is not explicitly declared but depends on where in the code it is created:

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

A local variable cannot override a global one. This means that if you run a Var or Eval command in a block of code and the variable name matches an already existing global variable, you'll rather modify the global variable than define a local one with the same name. The following example demonstrates the principles.

# Create a global variable
Var GLOBAL=global

if (1 == 1) {

    # Create a local variable and change the value of GLOBAL to 'modified'
    Var LOCAL=local GLOBAL=modified

    if (1 > 0) {
        Var LOCAL2=local2

        # Here GLOBAL, LOCAL and LOCAL2 are available.
        # The command will type "GLOBAL=modified, LOCAL=local, LOCAL2=local2"
        Type "GLOBAL={GLOBAL}, LOCAL={LOCAL}, LOCAL2={LOCAL2}" 
    }

    # Here GLOBAL and LOCAL are available and LOCAL2 doesn't exist any more.
    # The command will type "GLOBAL=modified, LOCAL=local, LOCAL2={LOCAL2}"
    Type "GLOBAL={GLOBAL}, LOCAL={LOCAL}, LOCAL2={LOCAL2}" 
}

# Here GLOBAL is available and LOCAL and LOCAL2 don't exist any more.
# The command will type "GLOBAL=modified, LOCAL={LOCAL}, LOCAL2={LOCAL2}"
Type "GLOBAL={GLOBAL}, LOCAL={LOCAL}, LOCAL2={LOCAL2}"

The same rules are applied to variables defined inside scripts loaded through the Include and Run commands. T-Plan Robot Enterprise provides a set of predefined (also called explicit) variables which may be referenced from any script. They include various useful data, such as execution start date, desktop server hostname, name of the executed script etc. For a complete list of predefined variables see the Var command specification. Variable values may be overridden in script executions through CLI. See the v/-variable parameter specified in the CLI Options document. This allows to parametrize particular script executions and/or avoid exposure of sensitive information in the script code (user names, passwords ...). Setting through the CLI makes the variable 'read-only' and fixes its value for the whole time of script execution. Any Var/Eval commands modifying this variable executed in the script will be ignored and they will have no impact on its value. This applies to any variable including the explicit (predefined) ones.

2.4 Procedures

T-Plan Robot supports simple procedures. A procedure is a named block of language elements written in required format which can be executed by calling its name. A procedure has a header, body and terminating right curly brace.

Procedure format is:

procedure <procedure_name> {

command1
command2
...
commandN

}

The following rules apply:

• 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:

procedure "Perform action A" {

...

}
...
"Perform action A"

• 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.
• A procedure can be called anywhere in the script AFTER its definition.
• Procedures defined in another script (file) may be imported through the Include command.

It is possible to pass any number of space-separated parameters to a procedure call as follows:

<procedure_name> parameter1 "parameter2 with spaces" .... parameterN

Parameters are then available as variables with names '0', '1' ... 'N'. The first variable with index 0 always contains the procedure name. Note that parameters accepted by a procedure are not declared anywhere in the procedure header.

A number of input arguments are available from the _PROCEDURE_ARG_COUNT variable since version 2.1. They may be used for branching of behaviour depending on the number of parameters or for populating of omitted parameters with default values.

The following example illustrates how to write and call a simple procedure creating a screenshot with variable image format. Note that the default value assignment (Var extension=png) must be specified after the parameter assignment (Var extension={2}) because the script otherwise reports an error. This is due to a compiler limitation which executes all variable assignments at the compile-time regardless of the if/else structures to verify the correct command syntax.

# Procedure definition. Expected parameters are:
# {1} ... file name without extension
# {2} ... image extension (either jpg, jpeg or png). Defaults to "png" when omitted.
procedure take_screenshot {
    Var extension={2}
    if ({_PROCEDURE_ARG_COUNT} == 1) {
        Var extension=png
    }
    Screenshot {1}.{extension} desc="This screenshot was created by procedure called {0}"
}

take_screenshot image1 jpg
take_screenshot image2

Procedures always return exit code of the last executed command within the procedure body. To exit a procedure with a specific exit code use the Exit command with the scope parameter set to procedure. An example follows:

# Procedure definition
procedure exit2 {
    Exit 2 scope=procedure
}

# Procedure call
exit2

if ({_EXIT_CODE} == 2) {
     # Any code here will be executed because exit2 returns 2
}


Procedure content is never compiled at procedure definition because without parameters it is not possible to resolve whether the code is correct or not. T-Plan Robot Enterprise compiles the procedure calls instead. If you e.g. type

take_screenshot image3 tiff

T-Plan Robot will report an error in this line because 'tiff' is not a Java supported image format causing the Screenshot command in the example procedure body to throw a compilation error.

2.5 Fallback Procedures

T-Plan Robot Enterprise version 2.3 introduced so-called fallback procedures. These are procedures of reserved names which are automatically called when a particular condition (event) is met. Fallback procedures are otherwise standard ones which means that all general procedure rules described above apply to it. In short, (1) the name is not case sensitive, (2) the procedure may be in another file which is linked to the script through Include or Run and (3) the procedure must be defined before the code which may call it.

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

The following example shows how to use fall back procedures. Both will simply exit the script with a specific exit code. The comparison one, in addition, creates a screenshot to allow later debugging. The example may be easily extended to perform any other suitable action, for example sending of an E-mail through the SendMail command or pausing the script through Pause.

procedure DisconnectFallback {
  Exit 3 
}

procedure ComparisonFailureFallback {
  Screenshot comparison_failure.png 
  Exit {1} 
}

// Script body
Connect localhost:1 password=welcome
Compareto button.png method=search
// ...

Version 7.2.4 introduced support of the BrowserFailureFallback procedure. When it is defined in the script it gets called after each failed Browser open/find/close command. It exposes three extra arguments:

{1} is the command numeric exit code,
{2} indicates the operation. It can be used to filter out the irrelevant calls.

• • If the failed command is "Browser open/close" it is set to "open" or "close".

  • If the failed command is "Browser find" without the "elaction" parameter specified then the argument is set to "find".

  • Otherwise the argument specifies the failed element action, one of "click", "submit", "clear", "type" or "select".

{3} contains the error message, typically the same one that is logged to the execution log.

Here's an example (requires the Chromium plugin):

procedure BrowserFailureFallback {
  Log "Failed action: {2} (exit code: {1})"
  Log "Reported error: {3}"
}


Browser "open" url="https://www.t-plan.com" browser=chromium

// This command will fail for wrong button text and call the "BrowserFailureFallback" procedure
Browser "find" class="elementor-button-text" text="Why T-Plans" timeout=5s

2.6 Numeric Expressions

Numeric expressions are supported since v1.3. The following rules apply:
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 '%'
• Power operator '^'

Numeric expressions are accepted anywhere in the language where a number is expected, e.g.

# Wait 1 hour - in milliseconds
Wait "1*60*60*1000" 

# Search for an image and then click onto it 10 points from its left upper corner
Compareto "pattern.png" method="search"
Mouse click to="x:{_SEARCH_X}+10,y:{_SEARCH_Y}+10"

To define a variable based on a numeric expression use the Eval command instead of the Var one, e.g. 'Eval HOUR_IN_MS=1*60*60*1000'.

2.7 Boolean Expressions

Boolean expressions facilitate constructions like if/else and for. The following operators are supported:

• Parenthesis '(' and ')'
• Greater than '>', greater than or equal to '>=', lower than '<' and lower than or equal to '<='. These operators require numeric arguments.
• Equal to '==' and not equal to '!=' or '<>'. If at least one of the arguments is not a number (a string enclosed in double-quotes) 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

Version 2.2 and higher also supports a set of operators allowing to test the existence of variables and compare strings:

• 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 'hasphrase' verifies if the first string contains the other one (since 7.2.2). It is similar to the "contains" one save that it is tolerant to new lines and unnecessary spaces. This allows for an easier evaluation of text recognized through the OCR on the screen. Example:
  • Expression '"{_TOCR_TEXT}" hasphrase "Hello world I am here"' will be true if the text resulting from the previously performed OCR contains the specified phrase regardless of whether it is split to multiple lines or it contains multiple spaces.
• 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 .

Boolean expressions are exclusively used by the if/else and for constructions as is shown in the following example. A Boolean expression may be also passed to the Eval command which populates the specified variable with the result of 'true' or 'false'.

# Look for an image on the remote desktop
Compareto "pattern.png" method="search"

# Exit if the image is not found,
if ({_EXIT_CODE} > 0) {
    Exit 1 
}

For more information read the If/Else Statement and For Statement chapters.

2.8 Functions

Functions were introduced in release 5. They may be used anywhere where a boolean or numeric expression is expected, such as the if/else and for statements, the Eval command and any other command parameters that support numeric expressions by this specification. Function names are not case sensitive.

For example, the following 'for' statement will iterate 10 times:

for (i=0; i<MAX(6,10,9); i=i+1) {

...

}

Supported functions (contact support if you need a custom one):

2.9 If/Else Statement

T-Plan Robot supports if/else statements with similar functionality and syntax used by Java. The format is:

if (<boolean expression>) {
    <commands>
} else if (<boolean expression>) {
    <commands>
} else {
    <commands>
}

The 'else if' and 'else' branches are optional. While the number of 'else if' branches are not limited, there can be just one 'else' construction. Note that the enclosing curly braces '{' and '}' must be on the same line as their associated if/else/else if keyword exactly as is displayed above.

The right curly brace '}' terminating the whole structured block is the only exception and it must be alone on a single line. Example:

# Look for an image on the remote desktop
Compareto "pattern.png" method="search"

# Exit if the image is not found,
if ({_EXIT_CODE} > 0) {
    Exit 1 

# If the image was found more times, take a screenshot and add a warning to the HTML report
} else if ({_SEARCH_MATCH_COUNT} > 1) {
    Screenshot unexpected.png 
    Warning "Unexpected behavior - the template image was found {_SEARCH_MATCH_COUNT} times!" image=unexpected.png
}

If/else statements can be nested and combined with other constructions like the for statement as is usual in any other structured programming language.

2.10 For Statement

T-Plan Robot Enterprise supports for statements which allow to iterate over a range of values or loop as long as a particular condition is satisfied. There are two general forms of the for statement.

1. Conditional For Statement

First variant of the for statement executes as long as the specified Boolean expression results true:

for (<statement1>; <boolean expression>; <statement2>) {
    <commands>
}

As the Boolean expression is being evaluated before every loop, the commands inside the loop will not be executed at all if the expression results in false right from the beginning.

Statements statement1 and statement2 are evaluated using the Eval command and should have a syntax like '<variable>=<numeric expression>'. They can be also empty. The following examples are equivalent and loop for values of variable 'index' ranging from 0 to 5. Both code snippets will type '012345':

for (index=0; {index}<6; index={index}+1) {
    Type {index} 
}

Eval index=0
for ( ; {index} < 6; ) {
    Type {index} 
    Eval index={index}+1
}

Version 2.3 and newer also supports a simpler syntax where the variable calls inside the statement header omit the curly braces, such as for example:

for (index=0; index<6; index=index+1) {
}

2. For Statement Iterating over a Predefined Set of Values

This form allows to iterate over a predefined set of values:

for <variable name> in <list of space-separated values> {
    <commands>
}

The following example will type a sentence "I speak English, Spanish, Brazilian Portuguese."

Type "I speak " 
for language in English Spanish "Brazilian Portuguese" {
    if ("{language}" == "Brazilian Portuguese") {
        Type "{language}." 
    } else {
        Type "{language}, " 
    }
}

The value set can be also specified by a variable. Version 3.0.1 and higher support values containing spaces specified through a variable. The following code shows the previous example with the value set specified through variables.

Note that the variable call must NOT be enclosed with double quotes because it would be handled as a single value.

Type "I speak " 
Var VALUES="English Spanish \"Brazilian Portuguese\""
for language in {VALUES} {
    if ("{language}" == "Brazilian Portuguese") {
        Type "{language}." 
    } else {
        Type "{language}, " 
    }
}

Execution of the for statement can be interrupted by a break command. The current loop can be skipped by the continue command. If there are nested loops the break/continue commands will apply to the innermost for statement.

The following example illustrates how to use a combination of for and waitfor to hold on execution until the remote desktop stops to update. #

# Infinite loop
for (; 0 == 0; ) {

    # Wait for at least 20% update of the remote screen.
    # If it doesn't update for 10 seconds, break the loop.
    Waitfor update extent=20% timeout="10s" ontimeout="break"
}

2.11 Return Values

Since v1.3 all commands return an integer value which is available as a variable called _EXIT_CODE. Value of 0 (zero) usually means success while any other number indicates a failure. See the documentation of particular commands for defined exit code values and their meanings.

Return values (also called "exit codes") can be effectively used to control the script execution and define how to handle both expected and unexpected results. The compareto command e.g. returns 0 when image comparison passes and non-zero value otherwise. The waitfor command returns 0 when the expected event is received and non-zero value when timeout is reached. The following example illustrates how to use these return values.

# Alt+F2 opens the Run Program window on Gnome
Press Alt+F2 wait=3s

# Start the Gnome Text Editor
Typeline gnome-text-editor 

# Wait for the remote desktop update
Waitfor update extent=30% timeout="10s"

# If Waitfor returns non-zero value, the timeout was reached
# and the text editor probably failed to open
if ({_EXIT_CODE} > 0) {

    # Take a screenshot
    Screenshot failure.png 

    # Send the screenshot via E-mail to the tester
    Sendmail to="tester@dummyserver.com" from="robot@dummyserver.com" server="mail.dummyserver.com" subject="Gnome editor failed to open!" attach="{_REPORT_DIR}/failure.png"

    # Pause the execution and wait for the tester to fix it
    Pause "Paused because Gnome Text Editor failed to start" 
}

Note that the if/else, for and break calls do not return any value. If you access the _EXIT_CODE variable after one of these commands, it will rather contain exit code of the last previously executed command.

2.12 Java Code Blocks

Java code blocks allow calling Java code directly from TPR scripts. It was designed to support cases when it is desired to stick to the scripting language, but a certain custom functionality is needed.

To make Java code blocks work properly, make sure to run Robot on a JDK through the "java -classpath <libs> com.tplan.robot.ApplicationSupport" command rather than the "java -jar robot.jar" one. The latter syntax fails to populate the 'CLASSPATH' for the Java compiler on some environments which results in failures to compile and execute Java source code. See the startup chapter of the Release Notes document for more information.

The general syntax of a Java code block follows. Be aware that support of the import clauses was delivered in v2.2. Prior versions must reference classes by fully qualified name or add the imports to the test class template managed in preferences.

java {
  <import clauses>
  <Java code>
} endjava

Each such a block is internally converted to a Java script extending DefaultJavaTestScript class and the Java code inside the block is inserted into its test() method. The class template is exposed in the Java code block configuration and may be customized through the Preferences window. The following example shows an example:

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());
   }
}

This mechanism has a few practical impacts:

• As Java code blocks require access to Java compiler, T-Plan Robot 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 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 across 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.

The following example illustrates sharing of variables. The script first sets the template path to "C:/templates". The Java code retrieves the path through the context, lists all PNG files in the directory and stores them as numbered variables called FILE<n> together with the file counter FILECNT to the context variables. When the TPR script resumes, it iterates over the listed files and performs image comparison against each PNG file.

Var _TEMPLATE_DIR="C:\templates"

# This line declares dummy values of variables populated by the Java code.
# It prevents the compiler from reporting error in the for() loop and CompareTo command.
Var FILECNT=0 FILE1=dummy.png

java {
         File files[] = getContext().getTemplateDir().listFiles();
         int i = 0;
         for (File file : files) {
             if (file.isFile() && file.getName().endsWith(".png")) {
                 i++;
                 getContext().setVariable("FILE"+i, file.getName());
             }
         }
         getContext().setVariable("FILECNT", Integer.toString(i));
} endjava

for (i=1; {i}<{FILECNT}+1; i={i}+1) {
  Compareto "{FILE{i}}" method=search
}

3. Command Syntax

• Desktop Commands
  • Browser
  • Connect
  • Disconnect
  • Gesture
  • Mobile
  • Mouse
  • Paste
  • Press
  • Type, Typeline
• Administrative & Execution Control Commands
  • Alert
  • Break
  • Click
  • Compareto Command
  • Continue
  • Date
  • Drag
  • Eval
  • Exec
  • Exit
  • Imagedoctor
  • Include
  • Moveto
  • Pause
  • Run
  • String
  • Var
  • Varf
  • Varg
  • Wait
  • Waitfor Command
• Reporting Commands
  • Log
  • Report
  • Screenshot Command
  • Script
  • Sendmail
  • Step
  • Timer
  • Warning
• I/O Commands
  • Excel
  • File
  • Mail

3.1 Desktop Commands

• Browser
• Connect
• Disconnect
• Gesture
• Mobile
• Mouse
• Paste
• Press
• Type, Typeline

3.1.1 Browser

Browser - Automate a Selenium driven web browser (since v5). An overview of the technology and configuration steps are being maintained in a separate document. The command supports the following actions:

• "Browser open" opens the selected web browser and loads the specified web page. The browser can be a local one or a remote one (Selenium Grid, supported since 6.3). Since version 8 the command can also open a new tab or a window.
• "Browser find" searches the web page for an element (an HTML tag) by the specified criteria and applies an optional action to it (click, type, submit, clear).
  • If the command does NOT specify an action and the element is not found it allows the script to continue. The search result (found/not found) is indicated to the script by the command exit code and the existence of the _WEB variables containing the element attributes.
  • If the command specifies the action and the element is not found it terminates the script. This behaviour is consistent with the Click and Drag commands.
  • To script actions like "apply action to an element if it exists and continues" use a pair of "Browser find" commands where the first one verifies the element existence and the second one applies the action.
• "Browser switch" switches among tabs or windows and/or updates the variables describing them. Supported since v8.
• "Browser close" closes the tab, window or the whole browser and eventually terminates the Selenium session.

Starting with release 8 most Browser command operations populate a set of variables describing the available tabs and windows as follows. You may also force refresh them by running "Browser switch" without any additional parameters:

SYNOPSIS

Local browser:

Browser open browser=<browser_code> [url=<web_page>] [args=<CLI_arguments>] [opt-<name>=<value>]

Remote browser:

Browser open browserName=<browser_code> hub=<hub_address> [url=<web_page>]

Open a new URL in an already opened browser:

Browser open url=<web_page> [target=<self|window|tab>]

* Red colour indicates obligatory parameters

OPTIONS

browser=<browser_code>

- The browser code name. The currently supported values are:

• "ie" - Microsoft Internet Explorer
• "edge" - Microsoft Edge
• "firefox" - Firefox (Gecko)
• "chrome" - Google Chrome
• "safari" - Safari (Mac OS X)
• "chromium" - requires the Chromium web driver plugin to be installed (v7.0+)

url=<web_page>

- The web page to be loaded, for example "https://www.t-plan.com".

args=<CLI_arguments>

- CLI arguments to be passed to the browser process if supported by the browser type. Supported since v7.0. See the CLI Arguments discussion in the Selenium document. 

opt-<name>=<value>

- A preference value to be passed to the browser process if the browser type supports it. Supported since v7.0. For example, Chrome uses the "download.default_directory" preference to set the default download directory. To redirect your downloads to C:\MyStuff use opt-download.default_directory="C:\MyStuff".

hub=<hub_address>

- The Selenium Grid hub address.

browserName=<browser_name>

- The hub recognized browser name.

target=<self|window|tab>

- Where to open the specified web page, one of "self" (open in the current window), "window" or "tab" (open in a new window/tab). The default value is "self". Supported since v8.

Browser find  [timeout=<time_interval>]  [elaction=<action>]  [elnumber=<element_number>]  [eltext=<text>]  [elindex=<dropdown_item_index>]  [elvalue=<dropdown_item_value>] [continue=<true|false>]  [<attributes>]

OPTIONS

timeout=<time_value>

- Optional time to keep looking for the element. It must be a valid time value.

• If no timeout is specified the command looks for the element just once.
• If the timeout is specified and is greater than zero the command will keep trying to find the element until the time expires or the element is found.

elaction=<action>

- Optional action to apply to the resulting element. If the search produces multiple elements you may use the elnumber parameter to select the target element. Supported actions are:

• "click" - Click the element. It applies only to clickable elements such as links, buttons etc.
• "type" - Type the text specified by the eltext parameter. Applicable to text elements only.
• "clear" - Clear the element text. Applicable to text elements only.
• "submit" - Submit the form.
• "select" - Select a drop-down item by one of the visible text (eltext), item index (elindex) or its value specified by the "value" attribute of the "option" HTML tag (elvalue).

elnumber=<element_number>

- The ordinal number of the element to target with the action specified by elaction. The default value is 1 (use the first element). If the number of elements is lower than elnumber the command throws an error.

eltext=<text>

- If the elaction action is "type" the parameter specifies the text to type into the text element. If the action is "select" the parameter is used to specify the visible text of the drop-down to be selected. It must be used together with the elaction=type parameter.

elindex=<dropdown_item_index>

- Index of the drop-down item to select. Indexing starts from zero. Applicable only to drop down elements represented by the "select" HTML tag.

elvalue=<dropdown_item_value>

- Value of the drop-down item to be found and selected. It is specified through the "value" attribute of the "option" HTML tag. Applicable only to drop down elements (the "select" HTML tag).

continue=<true|false>

- Specifies how to handle the failure. If the element is not found and this parameter is not specified or is false the command terminates the script. If the parameter is true the script is allowed to continue and the command returns a non-zero exit code.

<attributes>

- The list of attributes (search criteria) in the form of name=value pairs such as:

• "xpath=<xpath_expression>" - Perform search by the XPath expression. When this option is used no other attribute may be specified.
• "css=<css_selector>" - Search by the CSS selector. When this option is used no other attribute may be specified.
• "id=<element_id>" - Search by the element ID.
• "class=<class(es)>" - A CSS class or a list of space-separated classes the element must be of.
• "tagname=<tag_name>" - An HTML tag name such as "a", "div", "img" etc.
• "text=<text>" - The exact element text.
• "parttext=<partial_text>" - Find element(s) whose text contains the specified partial text. Be aware that the element text is inherited by its parent elements so these criteria are not unique. For example, to get the text of the whole page search for the "HTML" or "body" tag.
• "link=<link_text>" - Search for a link of the specified text.
• "partlink=<partial_link_text>" - Search for a link whose text contains the specified string.
• Besides the parameters supported by Selenium, the command accepts any HTML tag attributes and their values. For example, to identify a form button by its name use name=<name>.

For an informative overview of HTML, attributes see the Mozilla dev docs. Support of attributes may be browser-specific and some of them may fail to recognize.

Browser switch [id=<window_ID>]  [title=<title_or_part>]  [number=<window_number>]  [url=<URL_or_part>]  [continue=<true|false>]

- Switch to the tab or window identified by exactly one of the supported parameters of title, URL, number or window ID. If no identification parameter is specified the command refreshes the window variables.

OPTIONS

id=<window_ID>

- The window/tab ID. It is a unique string assigned to each tab or window by Selenium. You may get the available IDs from the window variables.

title=<title_or_part>

- The window/tab title or its part. See the window variables for the list of available titles. The title search is case sensitive. For example, if you have a tab titled "Google" then you may switch to it using title="Goo". If there are multiple tabs matching the specified title then the first one found will be selected. If no matching tab is found the command terminates the script unless the "continue=true" parameter is specified.

number=<window_number>

- The ordinal number of the window/tab starting with 1 (one). The order of windows is determined by Selenium and it typically reflects the order in which they were created. The number of currently available windows is reflected by the _BROWSER_WINDOW_COUNT window variable. If the number of available windows is lower than the requested one the command terminates the script unless the "continue=true" parameter is specified.

url=<URL_or_part>

- The window/tab URL or its part. See the window variables for the list of available URLs. The search is case sensitive. For example, if you have a tab for "https://www.google.com" then you may switch to it using url="google". If there are multiple tabs matching the specified title then the first one found will be selected. If no matching tab is found the command terminates the script unless the "continue=true" parameter is specified.

continue=<true|false>

- Specifies how to handle the failure. If the target window or tab is not found and this parameter is not specified or is false the command terminates the script. If the parameter is true the script is allowed to continue and the command returns a non-zero exit code.

Browser close
* Red colour indicates obligatory parameters

OPTIONS

scope=<tab|all>

- The close scope. The value of "all" is default and it will close the whole browser (all tabs & windows) and terminate the Selenium connection. The value of "tab" will close just the current tab or window and the connection is terminated only if it there are no remaining tabs or windows.

EXAMPLES

Browser open browser=edge url=https://www.t-plan.com

3.1.2 Connect

DESCRIPTION

Connect - Connect to a desktop. The protocol, hostname or IP address and optional port are specified in the argument URL. If a connection gets established the implicit variables of _MACHINE and _DISPLAY are updated.

See the DisconnectFallback fallback procedure for information on how to set up a central point of failure for server connections.

SYNOPSIS

connect <URL> [user=<user>] [password=<password>] [force=<false|true>] [onpass=<command>] [onfail=<command>] [params=<parameters>] [paramseparator=<delimeter>]
* Red colour indicates obligatory parameters

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 seven clients (protocols):

1. Remote Frame Buffer (RFB) v3.3 client (protocol code "rfb"). It is better known as Virtual Network Computing or VNC. The client is compatible and can connect to any RFB v3.3 complying VNC server such as TightVNC, RealVNC or UltraVNC. See the Release Notes document for the list of tested environments. Client implementation details are maintained in the client documentation.
2. Static Image (protocol code "file"; since v2.2) allows to load image from a file and test it the same way as a live desktop. The client supports all Java-compliant lossless image formats such as PNG, BMP, WBMP and GIF. As there's a mechanism causing the client to reload the image when the file gets updated, the client may be also used to test applications generating graphical output to an image in the file system. The connect URL is of the standard form of "file://<image_path>" with special handling of relative paths and images bundled inside a ZIP or JAR file. For details see the client documentation.
3. Android over ADB (protocol code "adb", since 3.1) enables to automate Android devices over the Android Debug Bridge (ADB). For details see the client documentation.
4. Local Desktop (protocol code "java", since 3.2) allows automating applications and system components displayed on the local desktop. For details see the client documentation.
5. iOS Mirror (protocol code "apple", since 3.3) allows automating iOS devices (iPhone, iPad) using a combination of AirPlay screen mirroring and VNC server. Compared to a plain VNC connection, this solution has much faster screen performance and it supports OpenGL content, for example, games and graphical programs. For details see the client documentation.
6. iOS Over Xcode (protocol code "xcode", since 4.3.1) allows automation of iOS devices connected both to a WiFi network and to a Mac OS X machine through the Lightning USB cable. For details see the client documentation.
7. RDP Server (protocol code "rdp", since 4.3) supports automation through the RDP protocol, also known as Microsoft Terminal Services. For details see the client documentation.

As T-Plan Robot provides an interface allowing to plug in other clients, there might be more protocols supported by additional plugins. 
If a 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 a protocol is omitted in the URL, the script defaults to the RFB (VNC). The port number is in this case treated as the display number which is equal to the port number minus 5900. A direct port can be specified through a 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".

user=<username>
- User name (ID) to authenticate to the desktop. This parameter is reserved for future use and/or for third party extensions and it is not used by any of the currently supported protocols.

password=<password>
- Password to authenticate to the desktop server. If the server is configured not to require a password, this parameter is ignored.

force=<false|true>
- If the same server and port (display) is already connected no reconnection is performed (force=false). To force termination of the current connection and reconnection to the server set this parameter to true. The default value is false.

onpass=<command>
- A command to execute when the server is connected successfully. It must be a single command. To call a sequence of commands either use a procedure or a subsequent if/else construction testing the command exit code.

onfail=<command>
- A command to execute when Connect fails to connect. It must be a single command. To call a sequence of commands either use a procedure or a subsequent if/else construction testing the command exit code.

params=<param_name_and_value_pairs>
- List of custom client parameters. This option together with the paramseparator one is not used in any of the currently supported protocols and they are reserved for future use and/or for custom extensions. They are intended to support the generic transfer of any login data to third party client plugins. The list may contain any number of parameter name and value pairs separated by comma (',') or a custom separator specified by the paramseparator argument.

For example, to specify two parameters PARAM_A=value_A  and  PARAM_B=value_B  the argument should look like "PARAM_A,value_A,PARAM_B,value_B". 
paramseparator=<delimeter>
- Optional separator for the list of parameter names and values specified by the params argument. If it is not specified, it defaults to comma (",").

RETURNS

The command returns 0 (zero) on success or 1 when it fails to connect for an 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 "Local VNC"


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

Connect rfb://mywindows.companyxy.com:5902 password=mypassword force=true onfail="exit 2"

- Connect to an RFB (VNC) server running on a server called mywindows.companyxy.com. If the tool is already connected to this server, terminate the session and reconnect. If the 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 script calling this command and display it in place of the desktop.

Connect rfb://mywindows.companyxy.com:5902 password=mypassword force=true onfail="exit 2"

- Connect to an RFB (VNC) server running on a server called mywindows.companyxy.com. If the tool is already connected to this server, terminate the session and reconnect. If the 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 to the local desktop.

Connect apple://192.168.1.2:5901

- Connect to an iOS device using the iOS Mirror connection. The example presumes that the device is connected to the network, it has the specified IP address and it runs a VNC server on the port of 5901.

3.1.3 Disconnect

DESCRIPTION

Disconnect - Disconnect from a desktop server. If there's no connection, the command does nothing. When the connection gets closed, predefined variables _MACHINE and _DISPLAY are cleared.

SYNOPSIS

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

Gesture - Design and execute a touch screen gesture (since v6.2). It is supported only by mobile device connections such as:

• Android Over ADB
• iOS Over Xcode

The command supports the following actions:

• "Gesture press" records press of a finger at the specified location to the gesture buffer.
• "Gesture move" records move (drag) of the specified finger to a new location.
• "Gesture release" records the specified finger release.
• "Gesture save" saves the gesture under the given name and clears the gesture buffer.
• "Gesture execute" performs the gesture on the connected device and clears the gesture buffer.
• "Gesture clear" clears the gesture buffer and makes it ready for design of a new gesture. This does not affect saved gestures. As the buffer gets cleared by default by "Gesture execute" and "Gesture save" you normally don't need this command.

A typical gesture scenario:

1. Design your gesture using combinations of 'press', 'move' and 'release' actions. Gestures using multiple fingers will always execute them in parallel. For example, a single finger L-shape drag:
   
   Gesture press finger=0  to=x:200,y:200
   Gesture move finger=0  to=x:200,y:500
   Gesture move finger=0  to=x:350,y:500
   Gesture release finger=0
   
   
2. One time gestures may be executed right away and discarded:
   
   Gesture execute
   
   
3. Should you want to reuse the gesture save it first and then execute it by name at any time:
   
   Gesture save name=L-shape
   Gesture execute name=L-shape
   
   
4. Saved gestures may by started from a custom location. The default gesture start point is the 'press' location of the lowest finger ID (typically finger #0 though you may number your fingers in any way within the allowed range). For example, in our example it is [200,200]. To make it start more to the right from [350,200] use:
   
   Gesture execute name=L-shape start=x:350,y:200
   
   Make sure that the moved gesture fits the screen. The command will otherwise trim the gesture to the screen bounds which may change the gesture functionality.

SYNOPSIS

Gesture press  finger=<fingerID>  to=x:<X-coordinate>,y:<Y-coordinate>
* Red colour indicates obligatory parameters

OPTIONS

finger=<fingerID>

- The finger ID. It is a number starting from 0. The maximum number of supported fingers is subject to the connection and device but it's typically not less than 5.

to=x:<X-coordinate>,y:<Y-coordinate>

- The finger press location.

Gesture move  finger=<fingerID>  to=x:<X-coordinate>,y:<Y-coordinate>
* Red colour indicates obligatory parameters

OPTIONS

finger=<fingerID>

- The finger ID. It is a number starting from 0. The maximum number of supported fingers is subject to the connection and device but it's typically not less than 5.

to=x:<X-coordinate>,y:<Y-coordinate>

- The location to move (drag) the finger to from the last position.

Gesture release  finger=<fingerID>
* Red colour indicates obligatory parameters

OPTIONS

finger=<fingerID>

- The finger ID. It is a number starting from 0. The maximum number of supported fingers is subject to the connection and device but it's typically not less than 5.

Gesture save  name=<name>  clear=<true|false>
* Red colour indicates obligatory parameters

OPTIONS

name=<name>

- The gesture name. Gesture names are case sensitive. Repeated use of the same name will overwrite the original gesture.

Saved gestures are never cleared by the 'clear' action or parameter. They are available from the moment of their creation until the script terminates. To create a set of standard gestures for your environment create a library (a script) of named gestures and link them to your script using the Include or Run command.

clear=<false|true>

- Indicates whether to clear the gesture buffer and make it ready for design of a new gesture. Clearing discards all 'press', 'move' and 'release' actions recorded so far. It does not affect saved gestures. The default value is 'true' (clear the buffer).

Gesture execute  name=<name> start=x:<X-coordinate>,y:<Y-coordinate> duration=<time> clear=<true|false> count=<number> wait=<time>
* Red colour indicates obligatory parameters

OPTIONS

name=<name>

- The gesture to execute. It must be name of an existing gesture that has been created by the script and saved through 'Gesture save'. Gesture names are case sensitive.

If no gesture name is specified the command executes the content of the gesture buffer,

start=x:<X-coordinate>,y:<Y-coordinate>

- Execute the gesture from a custom start point. The default gesture start point is the 'press' location of the lowest finger ID (typically finger #0 though you may number your fingers in any way within the allowed range). This parameter allows you to perform the gesture from another location on the screen.

If the relocated gesture fails to fit the screen the command will trim it to the screen bounds. This may lead to unexpected results.

duration=<time>

- The gesture duration. The value must be either a number of milliseconds or valid time value. The default value is 500 milliseconds (0.5 seconds).

clear=<false|true>

- Indicates whether to clear the gesture buffer and make it ready for design of a new gesture. Clearing discards all 'press', 'move' and 'release' actions recorded so far. It does not affect saved gestures. The default value is 'true' (clear the buffer).

count=<number>

- How many times to perform the gesture. The default value is 1 (perform once).

wait=<time>

- Time to wait after the gesture gets executed. It has the same effect as if the following command was 'Wait <time>'. The value must be either a number of milliseconds or valid time value. The default value is 0 (don't wait). Scripts may set the default value through populating of the _GESTURE_WAIT variable with the desired delay, for example "Var _GESTURE_WAIT=1s".

Gesture clear
* Red colour indicates obligatory parameters

OPTIONS

None.

EXAMPLES

Gesture press finger=0  to=x:125,y:202
Gesture release finger=0
Gesture save name=press
Gesture execute name=press duration=1s

- Perform a 1 second long press at the specified location.

Gesture press finger=0  to=x:300,y:200
Gesture press finger=1  to=x:100,y:500
Gesture move finger=1  to=x:500,y:500
Gesture release finger=1
Gesture release finger=0
Gesture save name=rotate
Gesture execute name=rotate

- Press and hold one finger while dragging another one in the horizontal direction below it. This will for example rotate the Google Maps.

3.1.5 Mobile

The Mobile command is supported since 7.1. It delivers mobile specific features on the Android Over ADB and iOS Over Xcode connections.

The command replaces the legacy Android and iOS extensions (plugins) which were being delivered as separate products. The goal is to provide a common language for automation of mobile devices and to avoid the overhead of the plugin installation. Due to the different nature of the iOS and Android operating systems not all the Mobile command functionality is supported the same way by both connections. For example, downloading and uploading of files is supported only on Android while keyboard map operations are specific to iOS. If you intend to write a single script targeting both platforms please pay attention to the feature compatibility notes in this document.

A complete list of supported operations follows:

The command delivers enhanced functionality of the legacy plugins plus a new feature called Mobile find. It allows to identify a UI component on the device screen by its attributes (text, type etc.s), retrieve its properties and optionally apply an action to it (click it). It is based on the ability of iOS and Android to retrieve the tree of UI components in form of an XML document. It is fairly similar to how the Browser find command identifies components in a Selenium driven web browser.

• The advantage of Mobile find is reliability. Unlike image search or OCR this method is more accurate and reliable to identify standard UI components on the screen.
• The disadvantages are speed (retrieval of the XML hierarchy is slow) and failure to identify any custom content such as graphical output (games) or mobile web browser content.

The algorithm used to identify components is also exposed to image comparison commands such as Compareto and Waitfor as a method called "mobile".The "passrate" parameter is not used and ignored by this method.The "cmparea" one is also ignored though it may change in a future release.

SYNOPSIS

Mobile alert  action=get

- Test out if there's an alert window on the mobile device screen.

Mobile alert  action=dismiss  [button=<button>]  [text=<text_to_type>]  [accept=<true|false>]

- Dismiss the alert. If there's no alert do nothing.

OPTIONS

action=<get|dimiss>

- The alert action name. The currently supported values are:

• "get" - Test out if there's an alert displayed on the mobile device. If there's an alert the method populates the _MOBILE_ALERT_TEXT, _MOBILE_ALERT_BUTTON_COUNT and _MOBILE_ALERT_BUTTON[n] variables with the alert text and number of buttons and their labels.
• "dismiss" - Dismiss the alert. You may optionally specify how to close the alert using the button, text and accept parameters.
  

button=<button>

- Name of the button to dismiss the alert with (optional). You may use one of the button names stored to the _MOBILE_ALERT_BUTTON[n] variables by a previous call of "Mobile alert action=get". If the button is not specified the command will choose one.

text=<text_to_type>

- The text to be typed into the alert's text field before dismissing it (optional). If the alert does not contain a text field the parameter will be ignored.

accept=<true|false>

- If the button is not specified use this parameter to indicate whether you wish to accept or cancel the alert. This is taken into account only if the alert contains two or more buttons, for example "OK" and "Cancel". If the parameter is omitted the command will choose how to close the alert.

RETURNS:

The "get" action returns 0 if there's an alert and 1 if there is none. The "dismiss" action returns 0 on successful alert dismissal or 1 otherwise.

Mobile app

Retrieve ID of the active (currently displayed) application into the _MOBILE_ACTIVE_ID variable.

RETURNS:

The command always returns 0.

Mobile find  [timeout=<time_interval>]  [action=<action>]  [number=<element_number>]  [continue=<true|false>]  [<attributes>]

 - Find a UI element on the device screen by the specified attributes and optionally click it. Attributes of the element(s) are stored to variables with the _MOBIlE_FIND prefix. When click is required use the continue parameter to determine whether to crash the script or allow it to continue when the element is not found.

The element search algorithm is also exposed to image comparison commands such as CompareTo and WaitFor. Look for the method called "mobile".

OPTIONS

timeout=<time_value>

- Optional time to keep looking for the element. It must be a valid time value.

• If no timeout is specified the command looks for the element just once.
• If the timeout is specified and is greater than zero the command will keep trying to find the element until the time expires or the element is found.

action=<action>

- Optional action to apply to the resulting element. If the search produces multiple elements you may use the number parameter to select the target element. Supported actions are:

• "click" - Click the element. It applies only to clickable elements such as links, buttons etc. 

number=<element_number>

- The ordinal number of the element to target with the action specified by action. The default value is 1 (use the first element). If the number of elements is lower than number then the command throws an error and terminates the script.

continue=<true|false>

- Specifies how to handle the failure. If the element is not found and this parameter is not specified or is false the command terminates the script. If the parameter is true the script is allowed to continue and the command returns a non-zero exit code.

<attributes>

-The list of attributes (search criteria) in the form of name=value pairs such as:

• "xpath=<xpath_expression>" - Perform search by an XPath expression. When this option is used no other attribute may be specified.
• "type=<button|input|text>" - The element type, one of "button" (a standard button of any recognized type), "input" (an editable text component) or "text" (a component displaying a static text).
• "text=<text>" - The exact element text.
• "parttext=<partial_text>" - Find element(s) whose text contains the specified partial text.Besides the above parameters the command accepts any UI hierarchy tree attributes and their values. Such a search will be however iOS or Android specific. For example, to identify a currently focused on Android use focused=true.

RETURNS:

When called without the action parameter the command returns 0 if at least one element is found or 1 otherwise. The number of identified elements is stored to the _MOBILE_FIND_COUNT variable and attributes of individual elements are exposed as numbered variables with the 
MOBILE FIND_ prefix.

When the action parameter is present and the action is successfully applied to an element the command returns 0. The failure behavior is subject to the continue parameter:

• If continue is not specified or is false the command throws an error and terminates the script.
• If continue is true the script is allowed to continue executing and the command returns either 1 (no elements found) or 2 (not enough elements found to match the element by number).

Mobile install [file=<app_file>] [reinstall=<true|false>]

* Red colour indicates obligatory parameters

- Install an application from the specified local file on the device. When successful the command populates the _MOBILE_INSTALLED_ID variable with the application ID which may be then used to start, kill or uninstall the app.

OPTIONS

file=<app_file>

- Path to the Android application file (.apk).

reinstall=<true|false>

- The value of true will force reinstallation if the app is already present on the device.

RETURNS:

The command returns 0 on successful completion or throws an error and terminates the script otherwise.

Mobile keyboard action=get

- Populate the _MOBILE_KEYBOARD_VISIBLE variable with true/false to indicate if the soft keyboard is visible. The command returns 0 or terminates the script on a failure to determine the keyboard status (unsupported OS, ...).

Mobile keyboard action=show

- Android only: Make an attempt to display the soft keyboard on the device and indicate the result through the exit code. Note that this functionality often fails because it is subject to whether an editable UI component is currently in focus and other conditions. Make sure to test the return code for the result. The command may throw an error and terminate the script on a failure to determine the keyboard status (unsupported OS, ...).

Mobile keyboard action=dismiss  [keys=<semicolon_separated_list>]

- Make an attempt to dismiss the currently showing soft keyboard on the device and indicate the result through the exit code. Note that the keys parameter is required only on iOS and is not required and ignored on Android. The command may throw an error and terminate the script on a failure to determine the keyboard status (unsupported OS, ...).

Mobile keyboard action=load [file=<map_file>]

- iOS only: Load a stored keyboard map. If the file is not available or is in a wrong format the command throws an error and terminates the script.

Mobile keyboard action=remap

- iOS only: Perform immediate remapping of the currently displayed soft keyboard. If the soft keyboard is not displayed or an unexpected error is experienced the command throws an error and terminates the script.

* Red colour indicates obligatory parameters

OPTIONS

action=<get|show|dismiss|load|remap>

- The action name, one of "get", "show", "dismiss", "load" or "remap".

file=<map_file>

- Path to the keyboard map file (.keymap).

keys=<semicolon_separated_keys>

- The list of semicolon separated key names to tap to close the keyboard. This parameter is required only on iOS and is ignored on Android.

RETURNS:

See the individual action descriptions for the returned exit codes and error throwing.

Mobile kill [id=<application_id>]  [force=<true|false>]  [timeout=<time_interval>]  [log=<true|false>]

- Kill the specified application or send it to the background eventually.

OPTIONS

id=<application_id>

- The application ID. On iOS it is the application bundle name, for example "com.apple.mobilesafari" for the Safari browser. On Android it is either the application package alone (the "kill" and "uninstall" actions), such as "com.android.chrome" for Chrome app or the package followed by a slash and the activity (the "start" action), for example "com.android.chrome/com.google.android.apps.chrome.Main". If the application ID is not specified the command kills the application installed recently by a call of "Mobile install" (Android only) or provided by a call of "Mobile app" (the ID is retrieved from the _MOBILE_ACTIVE_ID variable). To kill the currently displayed app use a sequence of "Mobile app" and "Mobile kill" commands. If no application ID can be resolved the command throws an error and terminates the script.

force=<true|false>

- The value of true tells the command to try harder to kill the app. The internal implementation is subject to the target OS and the flag may be even ignored. The default value is true.

timeout=<time_value>

- Optional time to wait for the shell command to finish. It must be a valid time value. It is being used only by Android where app are being killed through a shell command. The parameter is ignored by iOS.

log=<true|false>

- The value of true will log the operation output to the execution log for debugging purposes. The default value is false.

RETURNS:

The command returns 0.

Mobile orientation action=get

- Populate the _MOBILE_SCREEN_ORIENTATION_NAME and _MOBILE_SCREEN_ORIENTATION variables with the current screen orientation name and code. The names are "Portrait" (code 0), "LandscapeLeft" (1) , "UpsideDown" (2) and "LandscapeRight" (3).

Mobile orientation action=set [set=<orientation>]

* Red colour indicates obligatory parameters

- Set the screen orientation and populate the same variables as the "get" action.

OPTIONS

action=<get|set>

- The action name, one of "get" or "set".

set=<orientation>

- The target orientation identified either by the name or its numeric code. Acceptable values are "Portrait" (code 0), "LandscapeLeft" (1) , "UpsideDown" (2) and "LandscapeRight" (3). Android also supports "Auto" (code 4) to reset the screen orientation to the gyroscope indicated one.

RETURNS:

The command returns 0.

Mobile pull [remote=<remote_file>] [local=<local_file>]

* Red colour indicates obligatory parameters

- Android only: Pull (download) a file from the device to the local file system.

OPTIONS

remote=<remote_file>

- The file on the device.

local=<local_file>

- The file in the local file system.

RETURNS:

The command returns 0 on success or throws an error and terminates the script on a failure.

Mobile push [local=<local_file>] [remote=<remote_file>]

* Red colour indicates obligatory parameters

- Android only: Push (upload) a file to the device.

OPTIONS

local=<local_file>

- The file in the local file system.

remote=<remote_file>

- The file on the device.

RETURNS:

The command returns 0 on success or throws an error and terminates the script on a failure.

Mobile shell [command=<command>] [remote=<remote_file>]  [timeout=<time_interval>]  [log=<true|false>]

* Red colour indicates obligatory parameters

- Android only: Execute a shell command on the device. The command output is then stored to the _MOBILE_OUTPUT variable.

OPTIONS

command=<command>

- The shell command to be executed.

timeout=<time_value>

- Optional time to wait for the shell command to finish. It must be a valid time value.

log=<true|false>

- The value of true will log the operation output to the execution log for debugging purposes. The default value is false.

RETURNS:

The command returns 0 on success or throws an error and terminates the script on a failure.

Mobile start [id=<application_id>] [timeout=<time_interval>]  [log=<true|false>]

- Start an application on the device. Unless the timeout is specified the app start command is kicked off but no efforts are made to verify whether the app displays correctly. The command just may indicate through the exit code whether the start process was performed properly and populate the _MOBILE_OUTPUT variable with an error output. To make sure that the app started and displayed on the screen use the timeout parameter. 

OPTIONS

id=<application_id>

- The application ID. On iOS it is the application bundle name, for example "com.apple.mobilesafari" for the Safari browser. On Android it is must be the package followed by a slash and the activity, for example "com.android.chrome/com.google.android.apps.chrome.Main". If the application ID is not specified on Android the command starts the application installed recently by a call of "Mobile install" (the ID is retrieved from the _MOBILE_INSTALLED_ID variable). If no application ID can be resolved the command throws an error and terminates the script.

timeout=<time_value>

- Optional time to wait for the shell command to finish. It must be a valid time value.

log=<true|false>

- The value of true will log the operation output to the execution log for debugging purposes. The default value is false.

RETURNS:

If the timeout parameter is not specified or is set to 0 the command just kicks off the application and returns 0. The command may return 1 or another code for known error states, for example when the app is not installed.

When a timeout is set the command verifies that the app is started and displaying on the screen by testing the active app against the argument id within the specified time period. If the app fails to show it throws an error and terminates the script.

Mobile uninstall [id=<application_id>] 

- Android only: Uninstall an application from the device. If the operation fails it populates the _MOBILE_OUTPUT variable with the reason.

OPTIONS

id=<application_id>

- The application ID. It is either the Android application package alone such as "com.android.chrome" for Chrome app or the package followed by a slash and the activity (the "start" action), for example "com.android.chrome/com.google.android.apps.chrome.Main". If the application ID is not specified the command uninstalls the application installed recently by a call of "Mobile install" (the ID is retrieved from the _MOBILE_INSTALLED_ID variable). To uninstall the currently displayed app use a sequence of "Mobile app" and "Mobile uninstall id="{_MOBILE_ACTIVE_ID}" commands. If no application ID can be resolved the command throws an error and terminates the script.

RETURNS:

The command returns 0 on success or 1 on failure. It throws an error and terminate the script if the app ID can not be resolved or in case of an unexpected I/O error.

3.1.6 Mouse

DESCRIPTION

Mouse - Perform a mouse event. This command can automate a wide range of mouse actions such as a mouse pointer movement, mouse click, press, release, drag and mouse wheel events. The command also supports custom drags composed of a sequence of mouse press, mouse move and mouse release events (since 2.0.2). Should you see any composed events (clicks, drags) fail, please see the Mouse command preferences for calibration parameters.

The current mouse pointer coordinates are available in the script through the _MOUSE_X and _MOUSE_Y dynamic variables (since version 2.1).

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 colour indicates obligatory parameters

OPTIONS

modifier

- Any combination of modifiers Shift, Alt and Ctrl separated by the plus '+' sign, e.g. 'Ctrl+Alt+Shift'.

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

- This parameter provides an alternative way of specifying the mouse event modifiers (the other way is to place modifiers before the event ID). The value may be any combination of Shift, Alt and Ctrl separated by the plus '+' sign, e.g. "Ctrl+Alt+Shift". If modifiers are specified with the event ID as well, this parameter prevails.

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

- The 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 the format of 'x:<x>,y:<y>', where each coordinate can be specified in pixels (e.g. 'x:225') or as a percentage (e.g. 'x:23%'). If x or y is omitted, the current mouse pointer location will be used to determine the missing coordinate.

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

- Start coordinates.

• If the action is "drag" or "swipe" the mouse pointer will be dragged from this position to the coordinates specified by the to option.
• If the event is "click", "press", "release", "wheelup" or "wheeldown", this parameter will be ignored.

The coordinates have the 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 an 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 centre.

The coordinates have the 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 an 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, wheel, pinch and zoom 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 valid time value. The default value is 0 (don't wait). Scripts may set the default value through populating of the _MOUSE_WAIT variable with the desired delay, for example "Var _MOUSE_WAIT=1s".

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

- Drag the mouse pointer from the given start position to the destination position and wait for two seconds. The x coordinate is given in the relative form. If your display resolution is e.g. 800x600 pixels, the 'x:10%' will be equal to 'x:60' and 'x:22.5%' will be 'x:135'.

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


- Swipe the touch screen from the start position to the destination one.

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

- Example of a "composed drag" applied to an object located through image comparison. The script first searches the desktop for an object represented by the icon.png template. If it is found, the mouse pointer is moved to the area (plus ten pixels in each direction) and the object is dragged 100 pixels to the right using a sequence of press, move and release events.

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

Paste - Paste (insert) text using the system clipboard. Instead of typing the text character by character on the keyboard the command copies it into the clipboard and simulates pressing of Ctrl+V (Command+V on Mac OS X) to trigger the system Paste action. This is much faster than typing the text through Type/Typeline.

The command targets connections which support clipboard operations, such as the Local Desktop one. For other connections, the command silently falls back to the Type command functionality.

SYNOPSIS

paste <text> [wait=<time>] [count=<number>]
* Red colour 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 the 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 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.8 Press

DESCRIPTION

Press - Send a key to the desktop. It is analogical to pressing a key on the keyboard.

SYNOPSIS

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

* Red colour indicates obligatory parameters

OPTIONS

key

- Name of the keyboard key to press. Most key names correspond to what is written on the keyboard, e.g. 'A', 'Insert', 'Tab' etc. The key may also consist of modifiers only. Keys are not case sensitive and may be specified in any character case.

Key names are internally derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string after the VK_ prefix. For example, as there is a VK_ENTER constant, the key name may be "ENTER", "Enter" or "enter". As the names are in fact extracted from the KeyEvent class at runtime using Java Reflection API, the range of supported keys may differ depending on the version of Java used to execute T-Plan Robot. A complete map of the supported key names may be obtained through the Supported Keys Window.

The key may be optionally preceded by any combination of the Shift, Alt and Ctrl modifiers separated by the plus '+' sign, for example, "Ctrl+Alt+Delete". Modifier names are not case sensitive.

Be aware that the names map rather to particular physical keys and not to the characters they represent. For example, the pressing of the standard '-' minus key generates a different internal keycode than the one on numpad. These two cases may be also represented by two Press commands, "Press -" (standard) and "Press SUBTRACT location=numpad" (numpad). In most cases, the target system interprets them in the same way but there may be situations when it fails. For example, control plus ("Press Ctrl++") is generated as a sequence of \[press Ctrl, press '+', release '+', release Ctrl\]. As such a key combination is impossible to create on a US keyboard where one needs to press Shift as well to get the standard '+' ASCII character (0x2b), this sequence may or may not be interpreted correctly by the desktop. If the key is not recognized try using the numpad one instead ("Press Ctrl+ADD location=numpad"). To get the key name for your particular Numpad key open the Supported Keys Window and press it while the focus is on the "Press a key.." text field. It is recommended to specify the location=numpad parameter though it may also work without it.

The command accepts besides key names also most plain ASCII characters since 2.0.3. It is possible to use commands like "Press * " or "Press @". In addition, it supports the mapping of these characters onto the numeric keyboard through the localion="numpad" parameter. For example, pressing of the "0" key on the numeric keypad required to call "Press NUMPAD0" while the new version also supports more intuitive "Press 0 location=numpad". This also applies to other numpad keys such as ADD (mapped to plus, '+'), SUBTRACT (minus, '-'), MULTIPLY (asterisk, '*' ), DIVIDE (slash, '/'), DECIMAL (period, '.') and SEPARATOR (comma ',' ).

Transferable keys and key combinations are further on 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 and support of Windows native keys such as Win and ContextMenu is supported just by some products. On the 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 Release Notes and particular client documentation for more information.

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 keyboards 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 keypress (release=false) or a key release (release=true) instead of the full pres-release sequence. This allows to automate long keypresses 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 milliseconds or valid time value. The default value is 0 (don't wait). Scripts may set the default value through populating of the _PRESS_WAIT variable with the desired delay, for example "Var _PRESS_WAIT=1s".

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

- This example illustrates how to solve unwanted popup windows. If a window pops up at the given coordinates, the 'Press {KEY_TO_PRESS}' command ensures that it gets closed using Alt+F4. If the window doesn't show up, the Alt key gets pressed which usually doesn't cause any harm to the window.

3.1.9 Type, Typeline

DESCRIPTION

Type, Typeline - Type text on the desktop. The Typeline command is just a convenient one which types the text and then presses Enter. This has the same effect as a combination of 'Type <text>' and 'Press Enter'.

SYNOPSIS

type <text> [wait=<time>] [count=<number>]
typeline <text> [wait=<time>] [count=<number>]
* Red colour 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 the 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 valid time value. The default value is 0 (don't wait). Scripts may set the default value through populating of the _TYPE_WAIT or _TYPELINE_WAIT variable with the desired delay, for example "Var _TYPE_WAIT=1s". 

location=<standard|numpad|left|right>

- Key location. When specified the command makes an attempt to map the typed characters onto the specified 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 keypress 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

• Alert
• Break
• Click
• Compareto Command
• Continue
• Date
• Drag
• Eval
• Exec
• Exit
• Imagedoctor
• Include
• Moveto
• Pause
• Run
• String
• Var
• Varf
• Varg
• Wait
• Waitfor Command

3.2.2 Break

DESCRIPTION

Break - immediately terminate the innermost for loop and proceed to the first command after the loop's enclosing right curly brace '}'. If the command is used outside of a for loop it reports a syntax error.

To skip the current loop without breaking the for command use the continue command.

SYNOPSIS

break

RETURNS

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

EXAMPLES

# Infinite loop
for (; 0 == 0; ) {

    # Wait for at least 20% update of the remote screen.
    # If it doesn't update for 10 seconds, break the loop.
    Waitfor update extent=20% timeout="10s" ontimeout="break"
}

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

3.2.3 Click

DESCRIPTION

Click is a combination of Waitfor match and Mouse click commands. It searches the desktop for a component image, a solid colour object or a text and clicks it. If the object is not found it exits the script.

SYNOPSIS

Click <comparison_method>  [timeout=<time>]  [cmparea=<[x:<x>][,y:<y>][,w:<width>][,h:<height>]>]  [number=<component_number>]  [btn=<button>]  [modifiers=<modifiers>]  [count=<number>]  [wait=<time>]  [<method specific options>]
* Red colour 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 colour 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 valid time value. The default value is 30 seconds.

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

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

number=<component_number>

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

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

- Specifies the click location relatively from the centre of the target object (since 4.2). This allows clicking a nearby location instead of the object itself. If the comparison method is an image the parameter overrides the image click point and uses the image centre 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 centre.

btn=<button>

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

modifiers=<modifiers>

- The mouse event modifiers (optional). The value may be any combination of Shift, Alt and Ctrl separated by the plus '+' sign, e.g. "Ctrl+Alt+Shift".

count=<number>

- 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). Since release 4.4.2 the command also observes the value of the _CLICK_CONNECT variable and uses it as the default value. For example, to make all Click commands in a script not terminate the script by default set the variable at the beginning to true ("Var _CLICK_CONTINUE=true"). 

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

Click image template=<image_collection> [passrate=<pass_rate_in_%>]  [<search2_specific_params>] [<common options>]

* Red colour indicates obligatory parameters

SPECIFIC OPTIONS - IMAGE

template=<image_collection>

- An image collection - one or more image file names or folders with images separated by a semicolon (';') to be compared to the remote desktop image. On Linux/Unix make sure the file name doesn't contain semicolon because the list would be incorrectly parsed. File names can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use a relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. 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 the index of the matching template image. See image comparison specific variables for a complete list of supported variables.

passrate=<pass_rate_in%>_

- The pass rate for image comparison. It must be a number between 0 and 100 which may optionally be followed by the percentage character (for example "passrate=95" or "passrate=95%"). If this parameter is omitted, the default 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 colour.

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.

EXAMPLES

Click image template="google_button.png" number="2"

 - 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 object tolerance="10" color="255;0;0" max="w:20"

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

Click ocr text="Cancel" distance="1"

 - Read the text on the screen using OCR and click the word "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, "Cancel" etc.

3.2.4 Compareto

Compareto - The Compareto command is intended to perform a one-time comparison of the current remote desktop image and a single image or an image collection using the specified image comparison method. An optional action may be executed based on the result either in the "onfail" and "onpass" parameters or through testing of the command exit code using an if/else structure. T-Plan Robot Enterprise 4.4.2Beta contains six image comparison methods which are in details described in the Image Comparison Capabilities chapter:

1. Image Search v2 ("search2", since v3.0) is the successor of the "search" method and performs a tolerant search of the desktop screen for the object represented by the template image(s).
2. Image search ("search", since v2.0) performs a 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 colour or a range of similar colours.
4. Text OCR ("tocr", since 2.2) performs optical character recognition (OCR) on the desktop image using the OCR engine of choice.
5. Image-Based Text Recognition ("text", since 3.0) extracts text from the screen using a collection of pre-saved 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).

Besides the method-specific variables the command populates a set of COMPARETO prefixed variables as follows:

The command further supports one input variable which if defined controls the order of processing of the images loaded from image collections:

To make image comparison more reliable consider the factors listed in the Image Comparison Recommendations chapter. For information on how to set up a central point of failure for image comparisons see the ComparisonFailureFallback fallback procedure.

To display comparison result in the HTML report generated by the Report command use Screenshot. If you want to wait until the screen matches your template image, use 'Waitfor match'. Both Screenshot and 'Waitfor match' commands use the methods of the Compareto command internally and support the same parameters.

SYNOPSIS

compareto <image_collection> [passrate=<pass_rate_in_%>] [onpass=<command>] [onfail=<command>] [method=<comparison_method>] [methodparams=<custom_params>] [cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]]  [<method_specific_params>]
* Red colour indicates obligatory parameters

OPTIONS

image_collection

- An image collection - one or more image file names or folders with images separated by a semicolon (';') to be compared to the remote desktop image. On Linux/Unix make sure the file name doesn't contain semicolon because the list would be incorrectly parsed. File names can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use a relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. 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 the index of the matching template image. See image comparison specific variables for a complete list of supported variables.

passrate=<pass_rate_in_%>

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

onpass=<command>

- A command to be executed when the comparison succeeds (the selected method reports success). It must be a single command. To call a sequence of commands to use either a procedure or a  subsequent if/else construction testing the command exit code.

onfail=<command>

- A command to be executed when the comparison fails (the selected method reports failure). It must be one single command. If you need to define a sequence of command to be executed, use a procedure.

method=<comparison_method>

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

methodparams=<custom_params>

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

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

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

method_specific_params

- See the documentation of individual comparison methods for the list of supported method-specific parameters.

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.

Compareto button1.png;button2.png method=search
if ({_EXIT_CODE} == 0) {
  Mouse click to="x:{_SEARCH_X}+5,y:{_SEARCH_Y}+5"
}


- Search the remote desktop image for a button 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}}
}

- Search the remote desktop image for an icon represented by the template image search.png and click onto each of the occurrences.

Var _TOCR_LINE_COUNT=0
Compareto method="tocr" cmparea="x:33,y:2,w:200,h:22"
for (i=1; {i}<{_TOCR_LINE_COUNT}+1; i={i}+1) {
   Typeline "{_TOCR_LINE{i}}"
}

- Extracts text from the specified desktop area using OCR and types it onto the desktop.

Compareto method="tocr" cmparea="x:33,y:2,w:200,h:22" pattern="[aA]pplication.*"
if ({_EXIT_CODE} > 0) {
  Exit 1
}


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

Compareto method="object" color="FF0000" draw="true"

- Find all solid colour red objects (RGB = (256, 0, 0)) on the screen and highlight them in the GUI.


Compareto circle.png method="object" color="00FF00" tolerance="100" passrate="80%" draw="true" rotations="30"

- Find all green-like objects which are at least 80% similar to the one in the circle.png image and highlight them in the GUI. The tolerance parameter defines the size of the palette of acceptable green colours. As the rotations parameter is set to 30, the algorithm will search the screen for objects rotated in 12-degree steps (360 degrees / 30).

3.2.5 Continue

DESCRIPTION

Continue - skip the current innermost for loop iteration. If the command is used outside of a for loop it reports a syntax error. Supported since 4.1.3.

To break (exit) the whole for loop use the break command.

SYNOPSIS

continue

RETURNS

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

EXAMPLES

# Increment X for each even loop (the resulting SUM will be 5)
Var SUM=0
for (i=0; i<10; i={i}+1) {
   if ({i} % 2 == 1) {
      continue
   } 
   Eval SUM={SUM}+1 
}

3.2.7 Drag

DESCRIPTION

Drag is a combination of Waitfor match and Mouse drag commands. It searches the desktop for a source component by an image, by a solid colour or by a text and drags it to a location specified by relative coordinates or to the target component located by another image search. If the object is not found it exits the script.

The command is fairly similar to the Click one.

SYNOPSIS

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 colour 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 colour 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 valid time value. The default value is 30 seconds.

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

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

number=<component_number>

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

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

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

btn=<button>

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

modifiers=<modifiers>

- The modifiers to hold during the drag (optional). The value may be any combination of Shift, Alt and Ctrl separated by the plus '+' sign, e.g. "Ctrl+Alt+Shift".

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). Since release 4.4.2 the command also observes the value of the _DRAG_CONNECT variable and uses it as the default value. For example, to make all Drag commands in a script not terminate the script by default set the variable at the beginning to true ("Var _DRAG_CONTINUE=true").

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

Drag image template=<image_collection>  [passrate=<pass_rate_in_%>]  [<search2_specific_params>]  [<common options>]

* Red colour indicates obligatory parameters

SPECIFIC OPTIONS - IMAGE

template=<image_collection>

- An image collection - one or more image file names or folders with images separated by a semicolon (';') to be compared to the remote desktop image. On Linux/Unix make sure the file name doesn't contain semicolon because the list would be incorrectly parsed. File names can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use a relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. 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 the index of the matching template image. See image comparison specific variables for a complete list of supported variables.

passrate=<pass_rate_in%>

 -The pass rate for image comparison. It must be a number between 0 and 100 which may optionally be followed by the percentage character (for example "passrate=95" or "passrate=95%"). If this parameter is omitted, the default 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 colour.

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.

RETURNS

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

EXAMPLES

Drag image template="lever.png" shift="x:100"

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

Drag image template="column.png" number="2" template2="column.png" number2="3"

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

Drag object tolerance="10" color="0;255;0" max="w:20,h:20" shift="x:50,y:-100"

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

Drag ocr text="Flower" shift="y:220"

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

3.2.8 Eval

Eval - Define a script variable where the value is evaluated as a numeric expression. See the Numeric Expressions chapter of this manual for more info. The behaviour is otherwise exactly the same as the Var command.

SYNOPSIS

eval <var_name_1>=<numeric_expression_1> \[<var_name_2>=<numeric_expression_2> ... <var_name_N>=<numeric_expression_N>\]

* Red colour 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 in 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 the call of a variable which doesn't exist. This mechanism allows testing of 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.

Eval SUM={SUM}+10
if ({_EXIT_CODE} != 0) {
   Exit 1
}

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

Var A=1 B=2 C=3
// As Var resolves the variable calls and concatenates 
// the strings the ABC1 value will be a string of "123+1". 
Var ABC1="{A}{B}{C}+1"
// As Eval resolves the variable calls and evaluates the result 
// as a numeric expression the ABC2 value will be "124". 
Eval ABC2="{A}{B}{C}+1"


 - This example demonstrates the difference between how the Var and Eval commands construct the variable value.

3.2.9 Exec

DESCRIPTION

Exec - Execute an OS command on the local system (meaning on the machine which runs T-Plan Robot). The argument must be a single command, for example 'ls -l' on Unix/Linux. Due to a limitation of the interface between Java and the underlying OS pipes and redirection of the output are not allowed in the command. If you need to save the output to a file, use the outfile parameter. If you need to use pipes or redirection, put the command into a shell script or a batch file and make the Exec command call it instead.

If you need to execute a Windows command which is provided by the command line interpreter, you need to specify the interpreter in the Exec command. This applies to commands like dir, cd, copy, md, mkdir, rd, rmdir, del, erase etc. A complete list of commands depends on the Windows system and is available at the Microsoft site. Another good source is the COMMAND.COM page at Wikipedia. An example of running 'dir' on Windows would then looks like:

Exec "cmd.exe /C dir"

As each call to the underlying operating system requires some overhead, it is more efficient to create a shell script (Linux/Unix) or a batch file (.bat on MS Windows) where a sequence of OS commands need to be executed in one go. The following example shows the call of a batch file 'list.bat' located in the script directory on Windows. The batch file accepts a directory as a parameter and lists its contents into a file called dir.txt. Note that as the script path may contain spaces, it is necessary to enclose both the batch file and the parameter with double quotes which have to be escaped because they are inside a script command argument.

The list.bat file:

@echo off dir %1 > %1\dir.txt

The Exec call:

Exec "\"{_SCRIPT_DIR}\list.bat\" \"C:\Program Files\" "

Environment variables are visible to scripts in form of _ENV_ prefixed variables. You may see them for example in the Variables tab of the tool panel.

• Up to release 7.2.9 they are read only and any variable changes are not being passed to the process created by Exec.
• Starting with 7.2.10 you may set these variables for the process.

This example demonstrates setting of a variable on MS Windows. The echo command will print the variable value which will be logged to the execution log:

Var _ENV_Hello =Hello!
Exec "cmd /c echo Var Hello value: %Hello%"
Log "{_EXEC_OUTPUT}"

If you need to revert the change for the next process then simply delete the variable using "Varg delete":

Varg "delete" name="_ENV_Hello"
Exec "cmd /c echo Var Hello value: %Hello%"
Log "{_EXEC_OUTPUT}"

The Exec command populates four _EXEC prefixed variables as follows:

SYNOPSIS

exec <command> \[count=<number>\]  \[nowait=<false|true>\]  \[onpass=<command>\]  \[onfail=<command>\]  \[outfile=<file_name>\]  \[wait=<time>\]  \[kill=<process(es)>\]{_}  {_}\[autokill=<false|true>\]
exec kill=<process(es)> \[wait=<time>\]

* Red colour indicates obligatory parameters

OPTIONS

command

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

count=<number>

- How many times to execute the command. The default value is 1 (execute once).

nowait=<false|true>

- A flag specifying whether Exec should make the script wait until the OS command finishes (supported since v3.4). The default value is false which makes it wait.

When the value is set to true the Exec command does not wait for the result and the script continues immediately after the process is started. The _EXEC_OUTPUT and _EXEC_ERROR variables are not populated because the output is not known when the Exec command returns the control to the calling script. The _EXEC_ERROR variable may be created if the underlying OS fails to start the specified command and reports it immediately to Robot.

onpass=<command>

- A T-Plan Robot command to be executed if the execution succeeds (when exit code 0 is returned). It must be one single command. If you need to define a sequence of command to be executed, use a procedure or an if/else construction based on the Exec command return value.

onfail=<command>

- A T-Plan Robot command to be executed if the execution fails (i.e. non-zero exit code is returned). It must be one single command. If you need to define a sequence of command to be executed, use a procedure or an if/else construction based on the Exec command return value.

outfile=<file_name>

- Optional file name to save the command output to. If you specify just the file name, it will be created in the current working directory (the directory where Robot was started from). To set the path relative to the script location or Robot's install directory use the _SCRIPT_DIR or _INSTALL_DIR variable. For example, to store the output file to the script folder use outfile="{_SCRIPT_DIR}\out.txt".

wait=<time>

- Optional time to wait after the command is executed. The default value is 0 (don't wait). Scripts may set the default value through populating of the _EXEC_WAIT variable with the desired delay, for example "Var _EXEC_WAIT=1s".

kill=<processes>

- Kill process(es) identified by the specified ordinary number or a semicolon-separated list of numbers. Supported since v3.5.2. Whenever the Exec command executes with nowait=true it gives the started process an ordinary number. The number can be then used to kill the process. Killing can't be applied to processes started without the nowait parameter or with nowait=false. Such processes are also not being numbered.

Numbering starts at 1. Complicated scripts which execute multiple calls of "Exec nowait=true" may learn the process number from the _EXEC_PROCESS_ID variable. Example:

// Start myapp.exe and save its ID
Exec "myapp.exe" nowait="true"
Var MYAPP_ID="{_EXEC_PROCESS_ID}"

...
Exec kill="{MYAPP_ID}"

NOTE: On Windows, it is only possible to kill the immediate child process using Exec Kill due to the way Windows OS internally organizes and accesses processes. Therefore, in order to kill sub (grandchild) processes please use CMD taskkill e.g.: Exec "cmd.exe /C taskkill /f /im <processName>".

autokill=<false|true>

- A flag specifying whether to kill the process after the script finishes (supported since v3.5.2). It is applied only to processes started with nowait=true. The default value is false (do not kill).

RETURNS

The command returns 0 (zero) if the command is successfully 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 the 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 
  }
} 

- Perform an image slide show on a directory. The Exec command is here called to list contents of a directory which is then parsed using "String split" to individual files (one file per line is expected). The parsed strings (file names) are then checked for a known image extension and displayed in the Robot's desktop view for 3 seconds.

3.2.10 Exit

Exit - Terminate the script, procedure or structured block of code and return an exit code. If an exit command with the 'process' scope is called during script execution, it will terminate T-Plan Robot and return the indicated exit code to the underlying operating system. See the documentation on T-Plan Robot CLI Options and its automatic script execution examples for more information.

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 behaviour. 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 for the script termination by third-party frameworks.

scope=<process|file|procedure|block>

- Controls scope of the exit command. The default value is a process which terminates the script execution. If the execution is an automated one and there are no more running automated processes, the command also terminates the JVM (Java Virtual Machine) and returns the specified exit code to the underlying operating system.

The file value terminates the currently executed file. If a script is being executed from another script using the Run command, only the called script is terminated and control is returned to the master script.

The procedure value exits from the innermost procedure. If no procedure is executed, the Exit command is ignored.

The block value exits from the innermost structured block of code, i.e. one of the if/else of for statements. If the command gets called out of any such a statement, it is ignored.

desc=<description>