T-Plan Home
 T-Plan Robot Enterprise 3.0.1 Doc Collection
 20/07/12

T-Plan Robot Enterprise 3.0.1 Language Reference

Last update: 26 June 2012

Contents

1. Introduction
1.1 Purpose
1.2 Overview
1.3 Enterprise Features
2. Language Syntax
2.1 Language Structure
2.2 Time Values
2.3 Variables
2.4 Procedures
2.5 Fallback Procedures
2.6 Numeric Expressions
2.7 Boolean Expressions
2.8 If/Else Statement
2.9 For Statement
2.10 Return Values
2.11 Java Code Blocks
2.12 Image Collections
2.13 Image Meta Data
3. Command Syntax
3.1 Desktop Commands
3.1.1 Connect
3.1.2 Disconnect
3.1.3 Mouse
3.1.4 Press
3.1.5 Type / Typeline
3.2 Administrative & Execution Control Commands
3.2.1 Break
3.2.2 Compareto
3.2.3 Eval
3.2.4 Exec
3.2.5 Exit
3.2.6 Include
3.2.7 Pause
3.2.8 Run
3.2.9 String
3.2.10 Var
3.2.11 Wait
3.2.12 Waitfor
3.3 Reporting Commands
3.3.1 Log
3.3.2 Report
3.3.3 Screenshot
3.3.4 Script
3.3.5 Sendmail
3.3.6 Step
3.3.7 Timer
3.3.8 Warning
3.4 I/O Commands
3.4.1 Excel
3.4.2 File
4. Image Comparison Capabilities
4.1 Image Comparison Overview
4.1.1 Image Collections
4.1.2 Image Meta Data
4.1.3 Image Comparison Recommendations
4.2 Image Search Methods
4.2.1 Image Search v2 ("search2")
4.2.2 Image Search ("search")
4.2.3 Object Search ("object")
4.3 Text Recognition Methods
4.2.1 Tesseract OCR ("tocr")
4.2.2 Image Based Text Recognition ("text")
4.3 Other Methods
4.3.1 Histogram Based Comparison ("default")

1. Introduction


1.1 Purpose

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

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

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


1.2 Overview

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

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

  1. Desktop Commands typically involve client to server communication, such as connecting to/disconnecting from a desktop and transfer of mouse and keyboard inputs (press a key, type a text, perform a mouse move, click, drag or wheel event).
  2. Administrative And Execution Control Commands provide necessary infrastructure for test script execution control (pause, stop, desktop image analysis, waiting for a specified time period or particular event) as well as support of variables, libraries and external OS command calls.
  3. Reporting Commands define automated testing outputs and report them to the user. Commands in this category allow for example to take a screenshot of the desktop image or its part, create a report, send an E-mail or upload the test results to an associated test management tool.
  4. I/O Commands deal with input from and output to various data sources.
Be aware that behavior 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 Enterprise 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 object oriented approach. For this reason T-Plan Robot version 2.0 introduced Java Test Script API allowing to write test scripts in pure Java through calls of methods accessing 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 Test Scripts document.

Test 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 Enterprise Features

As T-Plan Robot Enterprise is based on the open source T-Plan Robot, their language specifications are mostly equal. In general T-Plan Robot Enterprise just delivers additional features on top of the open source product and its language is extended with additional commands and service providers, such as report generators, image comparison algorithms and desktop clients. Scripts designed with the open source product version are always compatible with the T-Plan Robot Enterprise language. On the other hand a script designed with T-Plan Robot Enterprise may or may not to be compatible with the open source version depending on whether it uses the Enterprise language extensions.

This is a complete list of language extensions in T-Plan Robot Enterprise 3.0.1:
  1. Script command.
  2. Step command.
  3. Enterprise report provider under the Report command.
  4. Enhanced image search algorithm with improved performance and support of automatic transparency (since v2.1) and RGB-level tolerance (since 2.2).
  5. Support of drawing of image search results in the Screenshot command (since v2.1).
  6. Input/Output (I/O) commands such as File and Excel (since v2.1). The Excel one has been enhanced to provide better error reporting and to support MS Excel 2007 XML format (.xlsx) in v2.3.
  7. Support of nested Java code through Java Code Blocks (since v2.1, enhanced with import clause support since v2.2).
  8. Support of Image Meta Data and folder based Image Collections (since v2.2).
  9. Additional image comparison methods such as Object Search ("object") and Tesseract OCR ("tocr") (since v2.2).
  10. Enhanced Run command supporting parametrized call of Java test scripts (since v2.2).
  11. Image client supported by the Connect/Disconnect commands (since v2.2).
  12. String command and enhanced boolean expressions allowing to test strings and perform common text operations (since v2.2).
  13. Timer command (since v2.3).
  14. Fallback procedures (since v2.3).
  15. Exit command enhanced with optional description (since v2.3).
  16. Log and Mouse swipe commands (since 3.0),
  17. Images Search v2 and Image Based Text Recognition comparison methods (since 3.0).

2. Language Syntax

2.1 Language Structure

T-Plan Robot Enterprise language is a text-based programming language and test scripts are typically saved as plain text files. The following general rules apply:
Test scripts are interpreted according to the following rules:
# This is a comment
// This is also a comment
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 identificator/value pairs. The fourth token will not be parsed as it does not comply with the required format.
  1. 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.
  1. Further processing and syntax validation is 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:
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 occurencies 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 a usage. Let's suppose that you are to search the remote desktop for an icon and you click onto each of the occurencies:

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 test script. They include various useful data, such as execution start date, desktop server host name, name of the executed script etc. For a complete list of predefined variables see the Var command specification.

Variable values may be overriden in script executions through CLI. See the -v/--variable parameter specified in the T-Plan Robot Enterprise 3.0.1 CLI Options document. This allows to parametrize particular test script executions and/or avoid exposure of sensitive information in the test 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.

Compatibility Note: VNCRobot formerly used regular expressions for variable substitution until version 1.2.5. Versions 1.3 and higher (including the recent T-Plan Robot 2.0) use plain text processing and version 1.3.4 also added support of nested variables (see the paragraph describing this further on). There are options in the Preferences window which allow you to disable these new feature and switch back to the 1.2.x compatibility mode. Be aware that the legacy mode requires you to avoid regexp special characters in the variable names. If you are not familiar with regular expressions, use just alphabet characters ('a'-'z', 'A'-'Z'), numbers ('0'-'9') and underscore ('_') in your variable names.

2.4 Procedures

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

procedure <procedure_name> {
command1
command2
...
commandN
}

The following rules apply:
procedure "Perform action A" {
...
}
...
"Perform action A"
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.

Number of input arguments is available from the _PROCEDURE_ARG_COUNT variable since version 2.1. It may be used for branching of behavior 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 Enterprise 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.
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 screen shot 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
// ...


2.6 Numeric Expressions

Numeric expressions are supported since v1.3. The following rules apply:
Numeric expressions are accepted anywhere in the language where a number is expected, e.g.

# Wait 1 hour - in miliseconds
 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: Version 2.2 and higher also supports a set of operators allowing to test existence of variables and compare strings:
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 If/Else Statement

T-Plan Robot Enterprise supports if/else statements with a 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 is 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.9 For Statement

T-Plan Robot Enterprise supports for statements which allows 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 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. If there are nested loops, the break command will always interrupt 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.10 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 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.11 Java Code Blocks

Java code blocks allow to call 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 class path 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.

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

Java Code Block
Resulting Java Test Script Class
java {
  import java.util.Date;
  System.out.println("Current date: "+new Date());
} endjava		              
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:
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 test 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

T-Plan Robot Enterprise 3.0.1 supports the following commands (the categories are sorted in alphabetical order):

3.1 Desktop Commands 3.2 Administrative & Execution Control Commands 3.3 Reporting Commands

3.4 I/O Commands


3.1 Desktop Commands


3.1.1 Connect

DESCRIPTION
 Next | Previous | Top^
Connect - Connect to a desktop. The protocol, host name 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 color indicates obligatory parameters

OPTIONS
URL

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

  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 RfbClientImpl class documentation.
  2. Image Client (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 a special handling of relative paths and images bundled inside a ZIP or JAR file. For details see the ImageClient class documentation.

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

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

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

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 server is configured not to require 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 use either 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 use either 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 are 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 generic transfer of any logon 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 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 rfb://mywindows.companyxy.com:5902 password=mypassword force=true onfail="exit 2"

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

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

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

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

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

Connect file://screen.png

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

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

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


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

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

Connect rdp://winhost

- Connect to host winhost using RDP. This is just an illustrative example because RDP support is not yet implemented.


3.1.2 Disconnect

DESCRIPTION
 Next | Previous | Top^
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.3 Mouse

DESCRIPTION
 Next | Previous | Top^
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) to fail 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>]] [count=<number>] [wait=<time>]
* Red color 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:

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

- Target coordinates.

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

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

- Start coordinates.

The coordinates have format of 'x:<x>,y:<y>', where each coordinate can be specified in pixels (e.g. 'x:225') or relatively as a percentage (e.g. 'x:23.5%'). Relative coordinates are rounded if they are not integer. If x or y is omitted, the current mouse pointer location will be used to determine the missing coordinate.

count=<number>

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

wait=<time>

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

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

EXAMPLES
Mouse click count=2

- Perform a mouse double click at the current mouse pointer coordinates.

Mouse move to=x:25,y:122

- Move the mouse pointer to the given coordinates

Mouse move to=x:{_MOUSE_X}+50

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

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

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


3.1.4 Press

DESCRIPTION
 Next | Previous | Top^
Press - Send a key to the desktop. It is analogical to pressing of 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 color 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, pressing of the standard '-' minus key generates a different internal key code 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 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 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 keyboard just once and the only logically valid location is the default standard one. Most clients however use the location only as a hint and ignore it by keys where it is not applicable.

release=<true|false>

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

count=<number>

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

wait=<time>

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

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

EXAMPLES
Press Ctrl+Alt+Del

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

Press Tab count=5 wait=2s

- Simulate pressing of the Tab key five times and then wait for two seconds before proceeding to the next command.

Press Ctrl location=right

- Press the right Ctrl key.

Var KEY_TO_PRESS=Alt+F4
<...>
Waitfor update area=x:340,y:220,w:240,h:160 extent=80% timeout=10s ontimeout="Var KEY_TO_PRESS=Right"
Press {KEY_TO_PRESS} wait=2s

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

3.1.5 Type, Typeline

DESCRIPTION
 Next | Previous | Top^
Type, Typeline - Type text on the desktop. The Typeline command is just a convenience 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 color indicates obligatory parameters

OPTIONS
text

- The text to type. If the text contains spaces or equal signs '=', it must be enclosed in double quotes, e.g. "This is a text containing spaces". If you need to include the double quote character into your text, place a leading backslash before it, e.g. "This is double quote - \"". If you need to display a backslash followed by a double quote, use '\\"', e.g. "This is a backslash followed by a double quote - \\"".

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

wait=<time>

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

location=<standard|numpad|left|right>

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

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

count=<number>

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

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

EXAMPLES
Type hello

- Type 'hello'.

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

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

Type "100*4" location=numpad

- Type the formula on the numeric keyboard.

Typeline "+111222333444" location=numpad

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


3.2 Administrative & Execution Control Commands


3.2.1 Break

DESCRIPTION
 Top^
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 is reported as syntax error.

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

DESCRIPTION
 Next | Previous | Top^
Compareto - The Compareto command is intended to perform 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.

3.0.1 3.0.1 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 successor of the "search" method and performs tolerant search of the desktop screen for the object represented by the template image(s).
  2. Image search ("search", since v2.0) performs tolerant search of the desktop screen for the object represented by the template image(s).
  3. Object search ("object", since v2.2) searches objects on the screen by a single RGB color or a range of similar colors.
  4. Tesseract OCR ("tocr", since 2.2) performs optical character recognition (OCR) on the desktop image using the free open source Tesseract OCR Engine.
  5. Image Based Text Recognition ("text", since 3.0) extracts text from the screen using a collection of presaved character images.
  6. Histogram based comparison (code "default", since v2.0) is the legacy algorithm comparing histograms of the desktop image and the specified template image(s).
Besides the method specific variables the command populates a set of _COMPARETO_ prefixed variables as follows:

Variable Name Description
_COMPARETO_TEMPLATE=<file>
 Image file (absolute path) used for last image comparison.
_COMPARETO_RESULT=<number>
 Comparison result percentage. It is always a number between 0
and 100. If the method used for comparison supports the ouput
result it indicates how much the images matched.
_COMPARETO_PASS_RATE=<number>
 Pass rate percentage used for the last image comparsion. It is
always a number between 0 and 100.
_COMPARETO_TIME_IN_MS=<milliseconds>
 Time in miliseconds spent by the image comparison. If there's a list
of templates, the value represents a summary time of all performed
comparisons.
_COMPARETO_TEMPLATE_INDEX=<number>
 Index of the template in the template list which produced the pass
result. Indexing starts from zero.
_COMPARETO_TEMPLATE_WIDTH=<number>
_COMPARETO_TEMPLATE_HEIGHT=<number>		 On successful comparison the variables contain dimensions of the matching
template image. Supported since 2.0.2.
_COMPARETO_SOURCE_X=<number>
_COMPARETO_SOURCE_Y=<number>
 Source coordinates of the last compared template. These variables
are populated only for templates created with version 2.2 and higher.
See the Image Meta Data chapter for details.
_COMPARETO_CLICK_X=<number>
_COMPARETO_CLICK_Y=<number>		 Click point of the last compared template image. The coordinates by default
point to the center of the component located through the "search" image
comparison algorithm or to the custom relative location.
See the Image Meta Data chapter for details.

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

Variable Name Description
_COMPARETO_SORT_MODE=<number>

 Desired sort mode to be applied to template images loaded from directories.
See the Image Collections chapter for details.

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>%] [onpass=<command>] [onfail=<command>] [method=<comparison_method>] [methodparams=<custom_params>] [cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]]  [<method_specific_params>]
* Red color indicates obligatory parameters

OPTIONS
image_collection

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

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

passrate=<pass_rate>%

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

onpass=<command>

- 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 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 a name of a third party method enabled through the plugin interface. If omitted the command will use the default one.

methodparams=<custom_params>

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

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

- The rectangular area of the desktop to be limit the comparison to. If you omit this parameter the whole remote desktop will be 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, T-Plan Robot will use the full screen values to determine the missing parameters (x:0, y:0, w:<screen_width>, h:<screen_height>).

method_specific_params

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

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 Tesseract 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 Teseract OCR doesn't start either with the 'Application' or 'application' word.

Compareto method="object" color="FF0000" draw="true"
- Find all solid color 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 size of the pallete of acceptable green colors. 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.3 Eval

DESCRIPTION
 Next | Previous | Top^
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 behavior 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 color indicates obligatory parameters

OPTIONS
var_name

- A name for the variable. The name is case sensitive and must not contain spaces.

numeric_expression

- A numeric expression or a string which results into a numeric expression after all variable calls located in the argument are resolved. If it contains spaces it must be enclosed in double quotes, e.g. "1 + 1". See the Numeric Expressions chapter of this manual for more info on expression syntax and supported numeric operators.

RETURNS
The Eval command in always returns 0 (zero) up to version 2.3.2. Version 2.3.3 and newer return 0 if the numeric expression was evaluated correctly or a value other than 0 if the expression could not be evaluated, for example when it contains call of a variable which doesn't exist. This mechanism allows to test whether the value was populated correctly and branch the code through the if/else statement checking the _EXIT_CODE variable value.

EXAMPLES
Eval POSITION=2*(10+1)

- Create a variable POSITION with a value of 22.


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

DESCRIPTION
 Next | Previous | Top^
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 Twikipedia. An example of running 'dir' on Windows would then looks like:

Exec "command.com /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 needs to be executed in one go. The following example shows 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\" "

The Exec command populates four _EXEC_ prefixed variables as follows:

Variable Name Description
_EXEC_OUTPUT=<text>
 Standard output of the executed command (the text which
is printed into the console).
_EXEC_ERROR=<text> Error output of the executed command (the error messages which
are printed into the console).
_EXEC_COMMAND=<command> Last executed OS command (the Exec command argument).
_EXEC_VALUE=<number>
 Integer exit code of the executed OS command.


SYNOPSIS
exec <command> [count=<number>][onpass=<command>] [onfail=<command>] [outfile=<file_name>] [wait=<time>]
* Red color 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).

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

RETURNS
The command returns 0 (zero) if the command is successfuly executed or the exit code of the OS command otherwise.

EXAMPLES
Exec "ls -l"

- List the contents of the current directory (Unix/Linux). The listing will be available under the _EXEC_OUTPUT variable.

Exec "date"
Screenshot image.png desc="This screenshot was taken on {_EXEC_OUTPUT}."

- Use the date OS command to insert a time stamp into a screenshot description (Unix/Linux).

Exec "C:\Program Files\Internet Explorer\iexplore.exe http://www.google.com"
Exec "rundll32 url.dll,FileProtocolHandler http://www.google.com"

- Both commands should start Internet Explorer on Windows and open the Google site.

Report index.html
Exec "mozilla file://{_REPORT_FILE}"

- Create an HTML report and open it in a Mozilla browser on the local machine. The _REPORT_FILE variable is populated by the Report command and contains full report file path.

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

// List the directory contents (Linux/Unix).
 // For Windows replace the "ls" command with "command.com /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.5 Exit

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

scope=<process|file|procedure|block>
- Controls scope of the exit command. The default value is 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>

- Optional description supported since v2.3. It is only used if the exit scope is not specified or is equal to process. The command then saves the description under the _EXIT_DESC variable which is picked up and displayed by the reporting framework (such as the Enterprise Report Provider).


RETURNS
The command returns the exit code which is specified as its argument.

EXAMPLES
Exit 10

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

Typeline myapplication
Waitfor update extent=40% timeout=20s ontimeout="Exit 2" cumulative=true

- This is a typical usage of the Exit command. It shows a situation when you start a GUI application called myapplication from a terminal window. Let's suppose that the myapplication window has a fixed size equal to at least 40% of the screen size. If the GUI starts properly, the script will continue. The Waitfor command will otherwise wait for 20 seconds and then terminate the test script with an exit code of 2.


3.2.6 Include

DESCRIPTION
 Next | Previous | Top^
Include - Include another script or compiled Java code.

When the argument is a TPR test script in the language described by this document, the command will load ONLY procedures and variables from the script into the execution context and make them available to the calling script. This principle allows to build  libraries with globally used variables and procedures and link them to scripts.

When the argument is a Java resource meaning a JAR or ZIP file or a class path (directory structure containing .class files), the command adds it to the Java class path and makes any compiled Java code it contains available for instantiation. This mechanism was introduced in v2.2 and it is intended to support dynamic loading of compiled Java test scripts which may be subsequently called by the class name through the Run command.

Be aware that dynamic update of the class path affects the whole Java Virtual Machine (JVM) instance. If there are multiple automated testing processes, loading of such a resource makes its classes instantly available to all of them. If the file or path is already present on the class path, the command does nothing and repeated calls of the same Include command cause no harm. Once the resource is loaded, eventual changes in the file system are not synchronized with the JVM. This means that it is not possible to apply changes to the resource code and recompile while Robot is running and it must be restarted to pick up any updates in the included library.

The name of the included file or path can be also specified dynamically through a variable. This eventually allows to pass the library name externally via the '-v' CLI option.

SYNOPSIS
include <file_or_Java_resource>
* Red color indicates obligatory parameters

OPTIONS
file

- A TPR test script file or a Java resource (JAR/ZIP file or a class path) to be included. File name can be either relative (e.g. sayHello.tpr) or absolute (e.g. /root/scripts/sayHello.tpr). T-Plan Robot will check if the file exists and is readable during every script compilation and report an error if not. The file can be also specified via a variable (see examples).

RETURNS
The command always returns 0 (zero). If the specified file is not found, T-Plan Robot reports a syntax error rather than returning a non-zero return value.

EXAMPLES
Include sayHello.tpr

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


Include /root/scripts/sayHello.tpr

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


 Var PROFILE=profile1.tpr
Include {PROFILE}

- Include a script specified by a variable. If you have more scripts with different configurations, you may then include another script from CLI using '-v PROFILE=profile2.tpr'.

Include C:\projects\TestLib\testlib.jar
Run mypackage.MyTestScript

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



3.2.7 Pause

DESCRIPTION
 Next | Previous | Top^
Pause - Pause the script execution. If T-Plan Robot is executing in GUI mode, the Pause button/menu item get selected and user can deselect the button or the menu item to resume the execution. If the script is being executed in CLI mode, a message is printed out into the console and user can press a key to resume the execution.

The Pause command can be used e.g. to pause execution when a runaway behavior is detected. Though the usual way is to exit the script with an error exit code (e.g. 'Exit 1'), some test suites may prefer to send an E-mail to the responsible person, pause the execution and wait for human help.

SYNOPSIS
pause <description>

OPTIONS
description

- Optional description of the reason why the script was paused. This description will be displayed in the report (if defined) and printed out to the console in case of CLI mode execution.

RETURNS
The command always returns 0 (zero).

EXAMPLES
Compareto "application.png"
if ({_EXIT_CODE} > 0) {
    # Cry for help - send a screenshot via E-mail and pause
    Screenshot runaway.png
   Sendmail to="tester@dummyserver.com" from="robot@dummyserver.com" server="mail.dummyserver.com" subject="Runaway behavior detected - see attached picture. Please help!" attach="{_REPORT_DIR}/runaway.png"
    Pause "Runaway behavior detected"
}

- When image comparison fails, send a screenshot by E-mail to the tester and pause the execution.



3.2.8 Run

DESCRIPTION
 Next | Previous | Top^
Run - Execute another script which may be one of:
  1. TPR test script in the format described by this specification (typically a .tpr file). T-Plan Robot Enterprise will process its commands as if they were written in the calling script, which means that all procedures, variables, screenshots and report generators defined by the executed script will remain in the execution repository and can be accessed once the Run command finishes. Exit command with the scope set to file can be used to return from a script executed through Run to the main script.
  2. Java source file (must be a .java file; supported from version 2.2). The class must be a valid T-Plan Robot Enterprise Java test script which extends the DefaultJavaTestScript class or at least implements the JavaTestScript interface. The Run command compiles the source code, instantiates the class and executes its test() method. As this call requires access to Java compiler, T-Plan Robot Enterprise must run on Java Development Kit (JDK) or be configured with a path to the JDK installation }supported since 2.3.3). If the tool runs just on Java Runtime Environment (JRE) and no JDK is available the tool will report an error. Refer to chapter 1 of the Release Notes document for instructions.
  3. Java class name (supported from version 2.2). It must be a fully qualified Java class name (package+class name) corresponding to a valid T-Plan Robot Enterprise Java test script which extends the DefaultJavaTestScript class or at least implements the JavaTestScript interface. The class must have the default (parameterless) constructor. The Run command instantiates the class by name and executes its test() method. As this method doesn't involve compilation of Java code, it is very fast with a minimum performance overhead and it is recommended for production scenarios. The compiled class code must be placed on the T-Plan Robot Enterprise class path in one of the three supported ways:
Version 2.2 also delivers support of optional parameters in form of <name>=<value> pairs specified on the command line after the mandatory file/class argument. These parameters are exposed to the executed script as local variables which are valid only inside the executed script or Java class. In TPR scripts the parameters may be called by name as standard variables. On the side of Java code they may be retrieved through the getContext().getVariable() method or through the set of convenience methods getVariableAsXXX() defined in the ScriptingContext interface.

Run commands can be effectively used to implement generic snippets of code (libraries) or to separate test code of individual test cases. The Java support enhancements delivered in version 2.2 allow to implement a library of parametrized Java routines and call them from TPR scripts. This is an efficient way of how to add custom functionality to the scripting language without having to go through the Plugin mechanism.

SYNOPSIS
run <file_or_class> [<param1>=<value1> ... <paramN>=<valueN>]
* Red color indicates obligatory parameters

OPTIONS
file

- The file can be one of:

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

<param>=<value>

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


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

EXAMPLES
Run sayHello.tpr

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


Run /root/scripts/sayHello.tpr

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


 Run /root/scripts/MyTest.java

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

Run com.testsuite.MyDummyTestScript server="rfb://localhost:5901" pass="welcome"

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


Var SCRIPT_TO_EXECUTE=sayHello.tpr
Run "{SCRIPT_TO_EXECUTE}"

- Execute a script specified by a variable.



3.2.9 String

DESCRIPTION
 Next | Previous | Top^
String - Process or parse text. The command allows to apply a text processing function to the argument text. While basic string "test" operations such as "contains", "startswith", "endswith" or "matches" may be performed in if/else statements through boolean expressions, the String command rather targets more complicated processing of text consisting of a sequence of one or more operations.

If the argument text contains variable calls they will be resolved (replaced with values) before the text is processed. The command populates a set of _STRING prefixed variables as follows:

Variable Name Description
_STRING=<operationResult>
 Result of the performed operation for all operations except for "String split".
If the command uses the "var" parameter to define a custom output variable
the default _STRING variable is not created.
_STRING_COUNT=<stringCount> Number of tokens resulting from the "String split" operation.
_STRING<n>=<token> The n-th token (substring) from the "String split" operation where <n> is
between 1 and _STRING_COUNT. If the command uses the "var" parameter
to define a custom output variable base name the default _STRING<n>
variables are not created.

Result of the operation is by default saved to the _STRING variable or to the custom variable specified through the optional 'var' parameter. If the operation produces multiple values (such as the 'split' operation), each value is saved to a numbered variable such as _STRING1, _STRING2 etc. or to similarly numbered set of variables derived from name specified by the 'var' parameter. Number of values is then stored to the _STRING_COUNT variable.

The command has a basic structure of:

String <operation> "<text>" [<parameters>]

Supported operations in alphabetical order are listed below. Their names are in most cases derived from method names of the java.lang.String Java class.

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

OPTIONS
text

- The text to process.

string

- The string to search for in the text.

start

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

end

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

var

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

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

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

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


String length  "<text>"  [var=<variable_name>]
* Red color indicates obligatory parameters

OPTIONS
var

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

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

EXAMPLES
String length "Demo text" var=len 

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


String matches  "<text>" pattern="<regular_expression>"  [var=<variable_name>]
* Red color indicates obligatory parameters

OPTIONS
pattern

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

var

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

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

EXAMPLES

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

- Open a data file, read it line by line and match each one against the specified regular expression. If the line matches, save the line number to the "result" variable and stop.


String replace  "<text>" string="<text>"  replacement="<text>" [var=<variable_name>]
String replace  "<text>" pattern="<regular_expression>"  replacement="<text>"  [var=<variable_name>]
* Red color indicates obligatory parameters

OPTIONS
replacement

- The new string (replacement).

string

- The old string (to be replaced in the text).

pattern

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

var

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

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

EXAMPLES

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

- Updates the _STRING variable with "sad fat cat" and returns 0 because the string has been updated.

String replace "bad fat cat" pattern="[bf]a[td]" replacement="cat"
- Updates the _STRING variable with "cat cat cat" and returns 0 because the string has been updated.


String split  "<text>" string="<text>"  [var=<variable_name>]
String split  "<text>" pattern="<regular_expression>"  [var=<variable_name>]
* Red color indicates obligatory parameters

OPTIONS
string

- The delimeter (separator) to split by.

pattern

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

var

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

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

EXAMPLES

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

- Split the text by spaces. As a custom variable base name of "s" is specified the command produces a set of three variables s1="bad", s2="fat" and s3="cat". The _STRING_COUNT variable will be set to 3.


String split "bad, fat cat" pattern="[,]* "
- Split the text by spaces which may be optionally preceded by a comma. Similarly to the previous example the command produces a set of three variables _STRING1="bad", _STRING2="fat" and _STRING3="cat". The _STRING_COUNT variable will be set to 3.


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

// List the directory contents (Linux/Unix).
 // For Windows replace the "ls" command with "command.com /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 "String split" command is here used to split the directory listing 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.



String substring  substring "<text>" start=<index>  [end=<index>]  [var=<variable_name>]
String substring  "<text>" end=<index>  [start=<index>]  [var=<variable_name>]
* Red color indicates obligatory parameters

OPTIONS
start

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

end

- End index (a number or a valid numeric expression). The default value is the text length (end of text).

var

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

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

EXAMPLES

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

- Removes the first four characters and sets the "s" variable to "fat cat".

String length "bad fat cat" var="len"
String substring "bad fat cat" start="{len-3}" end="{len-2}"
- Cuts the third last character ("c") into the _STRING variable.


String tostring  "<text>" unicode=<index>  [var=<variable_name>]
* Red color indicates obligatory parameters

OPTIONS
unicode

- One numeric Unicode/ASCII code or a semicolon separated list of codes to be converted into a string. As each code in the list is being parsed through the java.lang.Integer.decode() method, it may be a decimal number, hexadecimal (with leading '0x' or '#', such as '0xF0' or '#F0') or octal. For example, the '@'character may be specified as '64' (decimal), '0xF0', '#F0' (hexadecimal) or '0100' (octal). For the list of character codes see the ASCII and Unicode tables on Wikipedia.

var

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

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

EXAMPLES

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

- Populates the "s" variable with "hello".

String tostring "0xF1" var="s"
Var tomorrow="ma{s}ana"
- Sets the "tomorrow" variable to "mañana".

String trim  "<text>" [var=<variable_name>]
* Red color indicates obligatory parameters

OPTIONS
var

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

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

EXAMPLES

String trim " Hello!  " var="s"

- Sets the "s" variable to "Hello!".


3.2.10 Var

DESCRIPTION
 Next | Previous | Top^
Var - Define a script variable. See the Variables chapter for general description of script variable support.

Variables starting with underscore ('_') are so called predefined variables. They are typically provided by T-Plan Robot or by its commands and contain useful values providing information about the execution context and operation results.  A non-exhaustive table of the most important ones follows.

Who Creates and When Variable Name Description
T-Plan Robot when
a the client receives
a clipboard change from
desktop server
 _SERVER_CLIPBOARD_CONTENT=<text>
 Content of the remote desktop clipboard. Note that ability to transfer
text to the clipboard is subject to client capabilities. This variable is
typically used together with the Waitfor clipboard command.
T-Plan Robot when
a script execution
is started or when a
script is compiled.		 _DATE=<yyyyMMdd> Date of the execution start in the "yyyyMMdd" format.
For example, May 8, 2005 will be defined as "20050508". The format may
be customized in the Language panel of user preferences.
To get the current date see the _CURDATE variable below.
_TIME=<HHmmss> Time of the execution start in the "HHmmss" 24-hrs. format.
For example, 3:10:33 pm will be defined as "151033". The format may be
customized in the Language panel of user preferences. To get the current
time in miliseconds see the _CURTIME variable below. Should you need
formatted version of current time use _CURDATE with a custom format.
_FILE=<file> Absolute path of the executed script, e.g. "/root/test.txt".
_FILENAME=<filename>
 Script file name, e.g. "test.txt".
_REPORT_DIR=<path>
 Target directory for screenshots and reports. The default value
is the user home folder and it is configurable in user preferences
(Language panel). All screenshots and reports
will be saved to this directory unless they are specified via absolute path.
_TEMPLATE_DIR=<path>
 Source directory containing template images for image comparison.
The default value is the user home folder and it is configurable
in user preferences (Language panel). Commands employing image
comparison will search this directory for all templates specified
by relative path.
_SCRIPT_DIR=<path>
 Directory where the currently executed script is located (absolute path).
_WARNING_COUNT=<number>
 Number of warnings which have been generated by the Warning
command during the script execution.
_CURDATE_FORMAT=<format>
 Date/time format for the _CURDATE dynamic variable. It must  be a string
complying with the java.text.SimpleDateFormat specification. For example,
setting the variable to "yyyy" will cause any later use of _CURDATE to
produce "2010" (the current year in 4-digit format). Setting of this
variable to empty string will revert the format to the default value.
_RANDOM_MIN=<integer_number>
_RANDOM_MAX=<integer_number>		 Minimum and maximum values for the random value generator
used for the dynamic variable _RANDOM. Default values are 1 and
100000.
_RGB_X=<x_coordinate>
_RGB_Y=<y_coordinate>		 Coordinates used to retrieve RGB from the desktop image. Users
are advises to set these two variables to the desired coordinates
to retrieve the pixel color through the _RGB dynamic variable.
_INSTALL_DIR=<installation_path>
 Installation directory. It is equal to location of the robot.jar file. The directory
is absolute and does not end with the file separator. Supported since v2.3.
_ENV_<variable_name>=<value>
 Environment variables. These are OS specific variables provided by the
hosting operating system. These variables may not be populated if such an
option is selected in the Scripting->Language panel of the Preferences
window. Supported since v2.3.
T-Plan Robot whenever
the variable is used. As values
of these variables are created
at the time of the variable call,
they are called "dynamic
variables".
 _CURTIME=<time_in_miliseconds>
 Whenever this variable is used, it is dynamically replaced by
the current system time in miliseconds since midnight
of January 1, 1970 UTC. You may use this variable to calculate
how long a command or a block of commands took to execute or
to measure performance of the remote system.
_CURDATE=<formatted_time_and_date>
 Produces a readable current time and/or date. The format may be
specified in script through the _CURDATE_FORMAT variable. If the
variable is not set the format defaults to the value in user configuration
(see the Language panel of user preferences). If neither the preference
is set the format defaults to the default Java one produced by
java.util.Date().toString().
_MOUSE_X=<X_coordinate>
_MOUSE_Y=<Y_coordinate>		 Return current mouse pointer X, Y coordinates. If the tool is not connected
to a desktop or no mouse event has been registered yet since the connection,
the coordinates return [0, 0].
_RANDOM=<random_integer>
 Whenever used the variable produces a random integer number.
The range is by default set to [1, 100000] and may be changed through
the _RANDOM_MIN and _RANDOM_MAX variables (see above).
_RGB=<RGB_color> Whenever used the variable retrieves current color of the desktop
image pixel pointed to by coordinates specified by the _RGB_X and
_RGB_Y variables. This can be used to test whether a location on the
screen contains a particular color or not. Users are advised to set
the _RGB_X and _RGB_Y variables to the target coordinates and then call
the _RGB variable to retrieve the color.

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

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

Var _RGB_X=234 _RGB_Y=128
if ("{_RGB}" == "00ff00") {
   // The pixel is green
}

This mechanism is suitable for a simple exact color matching only. For
more general testing of a screen area for objects of a particular color or
color shade see the Object Search algorithm employed by the Compareto,
Screenshot and 'Waifor match' commands.
T-Plan Robot when
a script execution
is started. Also updated by
Connect and Disconnect
commands.
 _MACHINE=<servername> Desktop server machine name to which T-Plan Robot is connected.
The variable is empty if there is no connection.
_PORT=<portnumber> Desktop server port number. If the connected desktop doesn't
use a TCP/IP connection (such as drivers attached directly to
local displays), the variable is empty.
_PROTOCOL=<protocolname>
 Name of protocol used for desktop connection, for example "rfb" or "java".
_URL=<desktop_url>
 Desktop URL containing protocol, machine (host) name and optionally
port number.
_DESKTOP_WIDTH=<width_in_pixels> Width of the currently connected remote desktop (in pixels).
_DESKTOP_HEIGHT=<width_in_pixels> Height of the currently connected remote desktop (in pixels).
RFB (VNC) Client
when connected or
disconnected
 _DISPLAY=<servername>:[<display#>] Display variable which is useful for display redirection
on Unix/Linux systems. It is in the "server:port" format,
e.g. "mymachine:2" defines a machine called 'mymachine'
running a VNC server on port 5902.
The variable is empty if there is no VNC connection.
Waitfor command
when an update event
complying with
the given criteria occurs
_X=<number_in_pixels>
 The 'x' coordinate of the last update event that met the criteria.
_Y=<number_in_pixels> The 'y' coordinate of the last update event that met the criteria.
_W=<number_in_pixels> The 'width' coordinate of the last update event that met the criteria.
_H=<number_in_pixels> The 'height' coordinate of the last update event that met the criteria.
Waitfor command after
every execution
_TIMEOUT=<true|false> If timeout is defined and reached, the Waitfor command will set
this variable to 'true', otherwise to 'false'.
Report command
whenever a report gets
generated
 _REPORT_FILE=<file> Report file (absolute path), e.g. '/root/report.html'.
_REPORT_FILENAME=<filename> Report file name, e.g. 'report.html'.
Compareto command,
Screenshot
comparisons and
'Waifor match' calls
 _COMPARETO_TEMPLATE=<file>
 Image file (absolute path) used for last image comparison.
_COMPARETO_RESULT=<number>
 Comparison result percentage. It is always a number between 0
and 100. It indicates how much the images matched.
_COMPARETO_PASS_RATE=<number>
 Pass rate percentage used for the last image comparsion. It is
always a number between 0 and 100.
_COMPARETO_TIME_IN_MS=<milliseconds>
 Time in miliseconds spent by the image comparison. If there's a list
of templates, the value represents a summary time of all performed
comparisons.
_COMPARETO_TEMPLATE_INDEX=<number>
 Index of the template in the template list which produced the pass
result. Indexing starts from zero.
_COMPARETO_TEMPLATE_WIDTH=<number>
_COMPARETO_TEMPLATE_HEIGHT=<number>		 On successful comparison the variables contain dimensions of the matching
template image. Supported since 2.0.2.
_COMPARETO_SOURCE_X=<number>
_COMPARETO_SOURCE_Y=<number>
 Source coordinates of the last compared template. These variables
are populated only for templates created with version 2.2 and higher.
See the Image Meta Data chapter for details.
_COMPARETO_CLICK_X=<number>
_COMPARETO_CLICK_Y=<number>		 Click point of the last compared template image. The coordinates by default
point to the center of the component located through the "search" image
comparison algorithm or to the custom relative location.
See the Image Meta Data chapter for details.
User (customizable)
 _COMPARETO_SORT_MODE=<number>

 Desired sort mode to be applied to template images loaded from directories.
See the Image Collections chapter for details.
Compareto command,
Screenshot
comparisons and
'Waifor match' calls
when "search" comparison
method is used
 _SEARCH_MATCH_COUNT=<number>
 Number of matches found through image search. It is always an integer
greater than or equal to zero.
_SEARCH_X=<number> The 'x' coordinate of the first match. If the template image was
not found, the value is -1.
_SEARCH_Y=<number> The 'y' coordinate of the first match. If the template image was
not found, the value is -1.
_SEARCH_X_<n>=<number>
_SEARCH_Y_<n>=<number>
 The 'x' and 'y' coordinates of the n-th match where n is between
1 and value of _SEARCH_MATCH_COUNT.
Compareto command,
Screenshot
comparisons and
'Waifor match' calls
when "object" comparison
method is used		 _OBJECT_COUNT=<number> Number of objects located through the "object" image comparison method.
_OBJECT_X_<n>=<number>
_OBJECT_Y_<n>=<number>
_OBJECT_W_<n>=<number>
_OBJECT_H_<n>=<number>
 The 'x' and 'y' coordinates, width and height of the n-th object
where n is between 1 and value of _OBJECT_COUNT.
Exec command after
every execution		 _EXEC_OUTPUT=<text>
 Standard output of the executed command, i.e. messages which
are printed into the console.
_EXEC_ERROR=<text> Error output of the executed command, i.e. error messages which
are printed into the console.
_EXEC_COMMAND=<command> Last executed OS command, i.e. the Exec argument.
_EXEC_VALUE=<number>
 Integer exit code of the executed OS command.

You may use the Variable Browser window to view the list of variables which are present in the current execution repository.

SYNOPSIS
var <var_name_1>=<value_1> [<var_name_2>=<value_2> ... <var_name_N>=<value_N>]
* Red color indicates obligatory parameters

OPTIONS
var_name

- A name for the variable. The name is case sensitive and must not contain spaces.

value

- Variable value. If the value contains spaces, it must be enclosed in double quotes, e.g. "This is a text containing spaces". If you need to include the double quote character into your variable value, place a leading backslash before it, e.g. "This is a double quote \"". If you need to include a backslash followed by a double quote, use '\\"', e.g. "This is a backslash followed by a double quote - \\"".

RETURNS
The Var command always returns 0 (zero).

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

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

Compareto "search.png" method="search"

 for (i=1; {i}<{_SEARCH_MATCH_COUNT}+1; i={i}+1) {
  # Nested variables compose the variable names of a suffix and an index
   Mouse click to=x:{_SEARCH_X_{i}},y:{_SEARCH_Y_{i}}
}

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


3.2.11 Wait

DESCRIPTION
 Next | Previous | Top^
Wait - Wait for a specified amount of time. Use this command to pause the script execution for a specified period of time.

SYNOPSIS
wait <time>
* Red color indicates obligatory parameters

OPTIONS
time

- Time to wait before proceeding to the next command. It must be a number greater than zero. A plain number is by default interpreted as miliseconds. See syntax of time values for specification of time formats.

RETURNS
The command always returns 0 (zero).

EXAMPLES
Wait 30000
 Wait 30s
Wait 0.5m

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

3.2.12 Waitfor

DESCRIPTION
 Next | Previous | Top^
Waitfor - Pause execution of a script and wait for an RFB event or state of the remote desktop image. Currently supported events are screen update, bell (desktop server emited a beep through printing of the ASCII character 0x07), delivery of text copied on the remote system (desktop server clipboard change) and match/mismatch (waiting for a positive or negative image comparison result).

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

Waitfor Event
 RFB Client ("rfb") Static Image ("file")
"update" (Screen update)
 Yes
 Yes (through detection of the image file changes)
"bell" (Beeps)
 Yes
 No
"clipboard" (Clipboard changes)
 Yes (may require the vncconfig or autocutsel
utility to run on server. See the Release Notes for more.)
 No
"match" (Positive image comparison result)
 Yes
 Yes
"mismatch" (Negative image comparison result) Yes
 Yes

All Waitfor commands populate the following variable:

Variable Name Description
_TIMEOUT=<true|false> If timeout is defined and reached, the Waitfor command will set
this variable to 'true', otherwise to 'false'.

The Waitfor update command populates additional variables:

Variable Name Description
_X=<X-coordinate>
_Y=<Y-coordinate>
_W=<width>
_H=<width>		 The X, Y coordinates and the width and height of the last update
event that met the criteria. These variables are populated just for
Waitfor update.

The Waifor match and mismatch commands maintain result compatibility with the Compareto command and populate two more variable groups:
  1. All the _COMPARETO prefixed variables specified in the Compareto command,
  2. Variables populated by the selected image comparison method.
Though the Waitfor clipboard describes the _SERVER_CLIPBOARD_CONTENT variable it is not created by the Waitfor command and it is being populated by the core framework independently from any commands.

SYNOPSIS

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

event_id

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

COMMON OPTIONS

timeout=<time>

- Timeout specifying how long to wait at a maximum. The value must be either a number of miliseconds or a valid time value. The default value is 15 seconds.

ontimeout=<command>

- A command to be executed when the timeout is reached. It must be one single command. If you need to define a sequence of command to be executed, use a procedure.

onpass=<command>

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

count=<number>

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

wait=<time>

- Time to wait after the Waitfor condition is met. It has the same effect as if the following command was 'Wait <time_in_ms>'. This parameter is ignored if the timeout defined by the timeout parameter is reached. The value must be either a number of miliseconds or a valid time value.


Waitfor bell [<common options>]

SPECIFIC OPTIONS - BELL

None.


Waitfor update [area=[x:<x>][,y:<y>][,w:<width>][,h:<height>]]  [extent=<number>[%]]  [cumulative=<false|true>]  [<common options>]

SPECIFIC OPTIONS - UPDATE

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

- The screen area to wath for updates. This parameter is applicable only to the update event and enables user to define a custom area and watch it for updates. The area coordinates have format of 'x:<x>,y:<y>,w:<width>,h:<height>', where each coordinate can be specified in pixels (e.g. 'x:225') or as a percentage (e.g. 'x:23%'). If any of x, y, width or height is omitted, T-Plan Robot will use the full screen values to determine the missing parameters, i.e. 'x:0, y:0, w:<screen_width>, h:<screen_height>'. You may also define the update area using the status bar Update Coordinates feature.

extent=<number>[%]

- Extent (scope) of the screen update. This parameter is applicable only to the update event and defines how large the screen update must be. The value can be either a number of updated pixels (e.g. 'extent=400') or percentage (e.g. 'extent=22%'). If a custom area is defined by the area parameter, the percentage/pixel value will be computed against this area.

cumulative=<false|true>

- Switches on/off cumulative updates. If your desktop server prefers gradual screen updates and sends many small image fragments instead of a larger expected one, switch this feature on and T-Plan Robot will sumarize all partial updates falling into the defined area. The default value is false.

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


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

SPECIFIC OPTIONS - MATCH AND MISMATCH

template=<image_collection>

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

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

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

interval=<time>

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

passrate=<pass_rate>%

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

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 a name of a third party method enabled through the plugin interface. If omitted the command will use the default one.

methodparams=<custom_params>

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

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

- The rectangular area of the desktop to be limit the comparison to. If you omit this parameter the whole remote desktop will be used. The area coordinates have the format of 'x:<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>).


Waitfor clipboard [<common options>]

SPECIFIC OPTIONS - CLIPBOARD

None.


RETURNS
The command generally returns 0 (zero) when the condition (event) is met. Non-zero value (usually 1) is returned when the timeout is reached. 'Waitfor match' and 'Waitfor mismatch' mimick behavior of the Compareto command and return 0 (zero) when the comparison passes, 1 when it fails and 2 when the template image is not found or cannot be read.

EXAMPLES
Typeline "export MYDOC=`find / -name mydoc.txt`; sleep 1; echo -e '\007\007'"
Waitfor bell count=2
Typeline "gnome-text-editor $MYDOC"

- This is a typical example on how to use the bell event on a Unix/Linux system. Let's suppose that you need to find a file on your hard drive and edit it. The first command will run the search in a terminal window and proceed to the Waitfor command. Once the search finishes, two bell characters are printed using the echo OS command and your machine beeps twice. This will cause the Waitfor command to proceed and run the third command which will open the document in a Gnome text editor.

Please note the 'sleep 1' command in the first line. If your desktop server is very fast and your machine running T-Plan Robot is somewhat slower, it may happen that the document search finishes before T-Plan Robot manages to proceed to the Waitfor command. The 'sleep 1' prevents this problem because the server will wait 1 second before printing the two bell characters.

procedure terminate {
    Screenshot error.jpg
    Report report.html
    Exit {1}
}
Typeline myapplication
Waitfor update extent=40% timeout=20s ontimeout="terminate 2"

- This is a typical usage of the 'Waitfor update' command. It shows a situation when you are starting a GUI application called myapplication from a terminal window. Let's suppose that the application window has a fixed size equal to at least 40% of the screen size. If the GUI starts properly, the script will continue. The Waitfor command will otherwise wait for 20 seconds and then will run the exit procedure with the given exit code.

Waitfor match template=application.png;application2.png passrate=95% interval=5s timeout=5m ontimeout="exit 1"

- Compare the remote desktop image to images application.png and application2.png every 5 seconds until there's at least 95% match with one of them. If this condition is not met within 5 minutes, terminate the script execution using the Exit command and return exit code 1.


Press Ctrl+C
Waitfor clipboard timeout=5s
if ({_EXIT_CODE} == 0) {
  Screenshot copied_text.jpg desc="Received text copied on the remote desktop: {_SERVER_CLIPBOARD_CONTENT}"
}

- Pressing of Ctrl+C on the remote desktop typically copies selected text to the remote system clipboard. Some desktop servers are capable of sending this text to the clients. T-Plan Robot can decode such a message and provide the text into the script in form of the _SERVER_CLIPBOARD_CONTENT variable. The example above shows how to verify reception of the copied text through Waitfor clipboard and how to use it e.g. in description of a screenshot.



3.3 Reporting Commands


3.3.1 Log

DESCRIPTION
 Next | Previous | Top^
Log - Log a message to the script execution log file. For details see the Execution Log help topic.

SYNOPSIS
log "<text>" [level=<logLevel>]
* Red color indicates obligatory parameters

OPTIONS
text

- The log text. As the execution log file is generated in the HTML format it may contain HTML markup.

level=<logLevel>

- Optional log level, one of "SEVERE", "WARNING", "INFO", "CONFIG", "FINE", "FINER" and "FINEST". The default value is "INFO" or the custom value specified in the Log command preferences.

Levels allow to filter the log file by the message priority. The default filter level (also called"minimum level") is "INFO" which means that the log will record only messages of this or higher level. This allows to build scripts with detailed logging with an option to set off part of the logs later on through a simple change of one of the corresponding preference.

RETURNS
The command always returns 0 (zero).

EXAMPLES
Log "Suspicious image search coordinates: _SEARCH_X={_SEARCH_X}, _SEARCH_Y={_SEARCH_Y}" level="WARNING"

- Create a warning log.

3.3.2 Report

DESCRIPTION
 Next | Previous | Top^
Report - Create and start a report provider for the executed script. It is an object which builds a report from the script execution data such as results, screenshots and warnings. Report providers are customizable plugins and their functionality, life cycle and output format are implementation specific. See the Plugin API for more information on how to customize reports. The default provider started by the command is configurable in the Report preferences and defaults to the 'enterprise'.

Enterprise Report Provider
This provider supports both HTML and XML formats. It's code is "enterprise". It copies exactly behavior of the default provider (except for the scope parameter) and it even reuses all of its configuration parameters. The difference is however in the way how the test output is processed to generate the resulting report file. Unlike the default provider, this one also supports the Script, Step and Timer test results and it is tightly integrated with the script execution log.

When the output format is set to XML (an .xml file is specified in the command argument), the provider generates a simple XML file with all test outputs. It's format is specified in the provider's Java API documentation. As XML reports are linked with an XML style sheet (XSL), they may be displayed by web browsers and they provide exactly the same view of the report as the HTML files generated by the default provider. As interpretation of the XML data into an HTML view is on the web browser side, the XML output is fast and efficient. The XML file may be in addition reused for export of test results to third party applications.

The tool provides a mechanism in the user preferences to replace the default XSL file with a custom one. This allows to customize the way how web browser displays the XML data. The provider offers additional configurable options affecting mainly performance and allow to customize the frequency of report generating.

If the output is set to HTML, the provider in fact generates the XML output first and then employs the XSL transformation to produce an HTML file. This operation is inefficient and usually very slow. As the provider in this case creates the same HTML content as the default one, it is recommended to use the default one instead unless there are custom changes applied to the XSL file.

A sample XML report is available online at http://www.t-plan.com/robot/docs/examples/report-enterprise/sample.xml.


Default Report Provider
The default provider is a legacy report generator creating simple HTML reports. It is compatible with the previous VNCRobot 1.x versions and well as T-Plan Robot open source version. Its provider code is "default". It has the following lifecycle:
A sample report is at http://www.t-plan.com/robot/docs/examples/report-simple/sample.html.

The default report provider always processes all images and warnings taken during a script execution. It means that even if you call the Report command at the very end of your script, the HTML report will list all screenshots and warnings including those that were taken before the Report command was executed. The list of images can be currently restricted only depending on the image origin (see the scope parameter below).

HTML reports may also contain a table of results of performed image comparisons. This feature can be configured in the T-Plan Robot Enterprise Preferences window to display all or just failed comparison results executed through the Screenshot commands. Note that image comparisons performed through the Compareto and Waitfor match/mismatch commands are never listed. The rationale is that you have to create a screenshot anyway to provide a functional link in the table. See the sample report at the link listed above for an example.

The default provider also inserts specific values at the end of HTML reports. They are embedded in HTML comments and they are not displayed in browser. They provide information about the report state, length of execution, number of failed image comparisons etc. These values can be parsed by third party applications in order to interpret the report state and result. A list of provided variables with sample values follows:

<!-- version=1.3-20061210 -->
 Indicates which T-Plan Robot Enterprise version and build was used to generate this report.
 
<!-- running=false -->
 Indicates whether execution of the script is running or has already finished. 
<!-- stopped=false -->
 A value of 'true' indicates that execution of the script has been manually stopped by user via Stop button in GUI mode or by Ctrl+C in CLI. 
<!-- paused=false -->
 A value of 'true' indicates that execution of the script has been either manually or programatically (via the Pause command) paused. 
<!-- exitCode=0 -->
 Exit code. Zero indicates success while any other positive number is interpreted as failure. See the Exit command. 
<!-- imageCount=3 -->
 Number of images in the report. 
<!-- failedComparisons=0 -->
 Number of failed image comparisons. 
<!-- warningCount=0 -->
 Number of warnings added by the Warning command.
 
<!-- executionTimeInSec=44 -->
 Time of script execution in seconds.


SYNOPSIS
report <file> [provider=<provider_name>] [desc=<description>] [scope=<scope_id>]
* Red color indicates obligatory parameters

OPTIONS
file

- File name to save the report to. T-Plan Robot Enterprise will then check whether the path and file can be created and report an error if not. File extension is validated against the list of supported formats declared by the provider and a syntax error is raised on mismatch. The "default" provider supports .htm and .html extensions, the "enterprise" one supports .xml, .htm and .html.

File name can be either relative (e.g. report.xml) or absolute (e.g. /root/report/report.xml). If the path doesn't exist, it is usually created (default provider) but this behavior may be provider specific. If you use a relative path, the report file and all associated outputs should be saved to a directory defined by the _REPORT_DIR variable.

provider=<provider_name>

- Report provider name (code). In the current version it may be 'default', 'enterprise' or eventually name of a custom report provider installed through the plugin framework. This parameter is optional and defaults to the configured default provider in the user preferences if omitted. If you migrate among different product versions (especially between the open source and Enterprise ones), you should always check this value in preferences because it may be set to a provider which is supported by one product version and not by the other one.

If the provider is not specified and the preferred default one doesn't support the requested format, the command searches the list of report provider plug ins and tries to find one supporting it. This provides a failover mechanism for those who switch among product versions and/or provider plug ins.This behavior was implemented in 2.0.1.

desc=<description>

- Report description. It will be displayed in the report header. If the default provider is used, the text may contain any HTML tags.

scope=<scope_id>

- The scope parameter provides a way to define which images should be included in the report based on the screenshot creator. This parameter is supported just by the Default Report Provider and it gets ignored by the Enterprise one. There are two acceptable values:

RETURNS
The Report command returns 0 (zero) if the report provider is started and the first report is created and saved successfuly. If any error occurs, i.e. the report file cannot be created, the command returns 1.

EXAMPLES
Report index.html desc="This is my report."

- Create a report generator and start to generate a report. As relative file is provided, the report will be saved to a directory defined by value of the _REPORT_DIR variable. The provided description will be displayed in the report header.


Report index.xml provider=enterprise desc="This is my XML report."

- Create a report generator and start to generate an XML report. As relative file is provided, the report will be saved to a directory defined by value of the _REPORT_DIR variable. The provided description will be displayed in the report header.


Var _REPORT_DIR=/var/apache/htdocs/robot
Report index.html scope=file
Screenshot start_state.jpg desc="Initial state of the {_MACHINE} desktop. Starting execution of the {_FILE} script..."
...

- This is a typical example on how to use the report command. The first command defines the output path for the report file and screenshots which actually resides inside the Apache document root. This is very convenient because users can watch the report online through a web browser. As both report and screenshot commands use relative path for the outputs, everything will be saved to the output directory.



3.3.3 Screenshot

DESCRIPTION
 Next | Previous | Top^
Screenshot - Take a screenshot of the current remote desktop and save it to a file.

The Screenshot command has been closely integrated with the Compareto command. Comparison is performed when a corresponding template image is found in the template directory (see the _TEMPLATE_DIR variable) and at least one of the following conditions is met:
Unless you specify a template image explicitly through the 'template' parameter, the command will search the template directory for a template with matching name and extension PNG, GIF, BMP and JPG (in this order). You can switch this feature off in the Screenshot preferences to force the command to search for templates with exactly the same file name as the screenshot images.

If the command performs image comparison it populates the image comparison specific variables.

SYNOPSIS
screenshot <file> [desc=<description>] [area=[x:<x>][,y:<y>][,w:<width>][,h:<height>]][attach=<list_of_files>] [template=<image_collection>] [passrate=<pass_rate>%] [onpass=<command>] [onfail=<command>] [method=<comparison_method>] [methodparams=<custom_params>]  [cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]]   [drawresults=<true|false>]   [<method_specific_params>]
* Red color indicates obligatory parameters

OPTIONS
file

- File name to save the image to. It MUST have a supported extension, for example "png" or "jpg". Supported image formats are subject to the Java version. Java 1.6 supports at least PNG, JPG, GIF and BMP. File name can be either relative (e.g. img.jpg) or absolute (e.g. /root/report/img.jpg). If the path doesn't exist, it is created. If you use relative path or just a file name, the image will be saved to a directory defined by the _REPORT_DIR variable.

desc=<description>

- Image description. It will be displayed in the report.

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

- This parameter can be used to specify which part (subimage) of the remote desktop will be saved. 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 (e.g. 'x:225') or as a percentage (e.g. 'x:23%'). If any of x, y, width or height is omitted, T-Plan Robot will use the full screen values to determine the missing parameters, i.e. 'x:0, y:0, w:<screen_width>, h:<screen_height>'. You may also define the comparison area using the Screenshot window.

attach=<list_of_files>

- A file or a list of semicolon (';') separated files to be attached to a report. It provides a way to link for example log files and documents to the screenshot entry in the report. The report generator will list the attachments in the screenshot title in the HTML report and creates a hyperlink for each attached file. Please note that you have to copy the files to the target location on your own as T-Plan Robot neither copies the attached files to the report directory nor validates whether they exist there.

This parameter is obsoleted a it maintained to preserve compatibility with the previous versions. It is not supported in the Java Test Script API. 

template=<image_collection>

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

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

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


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

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 a name of a third party method enabled through the plugin interface. If omitted the command will use the default one.

methodparams=<custom_params>

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

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

- The rectangular area of the desktop to be limit the comparison to. If you omit this parameter the whole remote desktop will be used. The area coordinates have the format of 'x:<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>).

onfail=<command>

- A command to be executed when the image comparison fails. It must be one single command. If you need to define a sequence of command to be executed, use a procedure.

onpass=<command>

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

drawresults=<true|false>

- This flag controls whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored.

In the default T-Plan Robot Enterprise configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

method_specific_params

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


RETURNS
The command returns 0 (zero) if the screenshot is successfully saved and eventual image comparison passes. If image comparison takes place and fails, a value of 1 is returned. If the screenshot cannot be saved (e.g. not enough space), the command returns 2.

EXAMPLES
Screenshot image.jpg

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


Screenshot /root/images/image2.png desc="This image shows what happened after I had clicked the Start button."

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


3.3.4 Script

DESCRIPTION
 Next | Previous | Top^
Script - Define start or end of a script (test case). Though the command was introduced as part of the integration with T-Plan Professional, it can be used in a generic way to define the test script structure as is common in the QA industry. Script mappings are recognized by the Enterprise report provider and may be used to map the output XML data (or HTML report) onto QA documentation (such as test case specification).

A script in T-Plan terminology in this case is equal to a test case. Scripts in general consist of test steps which represent a set atomic test instructions describing how to execute the test case. Steps may be specified in T-Plan Robot Enterprise scripts through the Step command.

The command is intended to be used in pairs [Script <id> start , Script <id> end] to define a block of code which executes a test case. Any output objects generated inside such a block (such as screenshots or warnings) are then associated with the script (test case) ID and this relationship is reflected in the test result data. As a script block validity ends automatically with the file end or with declaration of another "Script start" command, declaration of the script end is optional and may be omitted.


SYNOPSIS
script <id> [start|end]  [name=<displayable_name>]
* Red color indicates obligatory parameters

OPTIONS
id

- A unique script ID. It may be a number or text. If the test results are to be exported to a third party test management application, the ID must be an understandable value. Export to T-Plan database (and T-Plan Professional) requires the ID to be a valid script entity number as is described in the Entity Mapping chapter of the T-Plan Robot Enterprise 3.0.1 Integration Reference.

start|end

- Indicates whether the script block starts or ends. It may be also specified as action=[start|end]. If the parameter is omitted, the command defaults to start.

name

- Optional displayable name for the script.

RETURNS
The Script command always returns 0 (zero).

EXAMPLES
Script 1 start name="Display http://www.t-plan.com"
Press Windows+R wait=3s
Typeline "http://www.t-plan.com"
Waitfor match template="tplanlogo.png" method=search timeout=20s
if ({_EXIT_CODE} == 0) {
  Step "Open http://www.t-plan.com in web browser" pass
} else {
  Step "Open http://www.t-plan.com in web browser" fail
  Exit 1
}
Script 1 end

- An example of script number 1 which opens the T-Plan web site in the default web browser on Windows. The script uses image search to verify that the page was displayed successfully. If the T-Plan logo is detected  on the desktop, the script records a passed step result. Otherwise a failed step is recorded and the script exits with code of 1 to indicate failure.



3.3.5 Sendmail

DESCRIPTION
 Next | Previous | Top^
Sendmail - Send an E-mail. The command acts as an SMTP client and sends E-mails with eventual attachments through an SMTP server. Supported authentication schemes are either no security (public mail servers) or plain user/password authentication. The communication is unencrypted (no SSL support at the moment). Optional attachments are sent in the Base64 encoding.

If default values of from, to, server, user and passwd are provided in the Sendmail preferences they may be omitted in the command.

SYNOPSIS
sendmail [from=<sender_address>] [to=<recipient_address>] [server=<server[:port]>] [subject=<subject>] [text=<mail_body>] [attach=<attachments>] [user=<userId>] [passwd=<password>]  [debug=<true|false>]
* Parameters are obligatory unless valid default values are provided through Sendmail preferences 

OPTIONS
from=<sender_address>

- The sender E-mail address, for example john.doe@company.com.

to=<recipient_address>

- The recipient E-mail address, for example jane.doe@company.com.

server=<server[:port]>

- The SMTP server to send the mail message through. If just a host name without a port number is used, the command attempts to connect the server on the standard SMTP port of 25.

subject=<subject>

- The mail subject (title).

text=<mail_body>

- The mail body. If the text starts with "<html>", the content type is set to HTML. Otherwise the content is sent as plain text. To indicate a line break use '\n'. If you need to use '\n' in the normal text, double the backslash character ('\\n').

attach=<attachments>

- List of attachments, i.e. files to attach to the E-mail. File names must be separated by semicolon (';'). On Linux/Unix make sure the file name doesn't contain semicolon because the list would be incorrectly parsed. If an attachment is not found, it is ignored and the mail is sent without it. It is recommended to provide the files with absolute path.

user=<username>

- The user ID to authenticate to the SMTP server with. This option should be used together with the passwd parameter when the SMTP server specified by the server parameter requires plain password authentication.

passwd=<password>

- The password to authenticate to the SMTP server. This option should be used together with the user parameter when the SMTP server specified by the server parameter requires plain password authentication.

debug=<true|false>

- Debug flag. Use debug=true to switch on the JavaMail debugging console output. This is useful if you need to find out why the E-mail feature doesn't work.

RETURNS
The command returns 0 (zero) on success or 1 if the E-mail cannot be sent.

EXAMPLES
Screenshot scr.png
Sendmail to="tester@dummyserver.com" from="robot@dummyserver.com" server="mail.dummyserver.com" subject="Screenshot of the remote desktop" text="Please check the attached screenshot." attach="{_REPORT_DIR}/scr.png"

- Take a screenshot of the current remote desktop and send it by E-mail to user tester@dummyserver.com.


 Sendmail subject="Hello" text="This is a multiline E-mail.\nSecond line.\nThird line."

- Example of a multiline E-mail. This command will only work if you have set correct default values of the 'from','to' and 'server' parameters in the Sendmail command preferences.


3.3.6 Step

DESCRIPTION
 Next | Previous | Top^
Step - Define result of a test step. A step represents one atomic instruction of a test case (script). Steps should be located inside a script block.

SYNOPSIS
step <name> [pass|fail|nt|na]  [instruct=<instructions>]  [expected=<expected_result_desc>]  [actual=<actual_result_desc>]  [notes=<notes>] 
* Red color indicates obligatory parameters

OPTIONS
name

- A displayable step name, for example "Logon", "Open Browser" etc. It doesn't have to be unique.

pass|fail|nt|na

- Step result. It must be one of pass (passed, successful), fail (failed, unsuccessful), nt (not yet tested) or na (not available).

instruct=<instructions>

- Step instructions (optional). It is usually a brief description of what was performed to accomplish the step.

expected=<expected_result_desc>

- Description of the expected step result (optional).

actual=<actual_result_desc>

- Description of the actual step result (optional). It is typically used with failed steps to indicate the difference from the expected result.

notes=<notes>

- Additional step information (optional).

RETURNS
The Step command always returns 0 (zero).

EXAMPLES
Compareto template= "application.png"
if ({_EXIT_CODE} == 0) {
  Step "Start application" pass expected="The application GUI opens."
} else {
  Step "Start application" fail expected="The application GUI opens." actual="The application failed to start."
  Exit 1
}

- A typical example of Step usage. The snippet employs image comparison to test whether the desktop matches the application.png template or not and produces a Step pass or fail result accordingly.


3.3.7 Timer

DESCRIPTION
 Next | Previous | Top^
Timer - Manage timers and timer groups. A timer allows to measure time elapsed by a command, block of commands or a script, usually for performance testing purposes.

A typical task for a timer is to measure time taken by an automated task or a piece of script code. This requires to create a timer and start it before the task begins and stop it in the end of task. Timers are typically used together with the Report command which stores test results including the time data into an XML file:

Report perftesting.xml
Timer t1 start desc="My task #1 duration"
<task code>
Timer t1 stop

If the resulting XML file is viewed in a web browser, it displays a summary of script timers in form of a simple table. For example, the script above will create:

Table of timers
Number Timer Name Description Value
1.
t1 My task #1 duration 25.009 sec (25009ms)

The XML result file can be also reused as a source of reference data. In a typical scenario one would execute the script above to get an XML with base timer data recorded against application which hasn't been optimized. To verify performance improvements in later automated executions modify the script as follows:

Report perftesting2.xml
Timer load="perftesting.xml"

Timer t1 start desc="My task #1 duration"
<task code>
Timer t1 stop

The "Timer load" command parses the input XML file and records the reference data for timers defined by the script (matching is based on timer names). Reference values may be alternatively also defined through the refvalue parameter; this allows to populate the reference data from another source, for example from a MS Excel sheet (see Excel) or a plain text or CSV file (see File). When the reference data is defined, the resulting XML will display actual timers with a comparison to the reference values as follows:

Table of timers
Number Timer Name Description Value Reference Value Change
1.
t1 My task #1 duration 24.984 sec (24984ms) 25.009 sec (25009ms)
0.1%
  

Important timer and timer group features:
Each timer exposes its time value in milliseconds to the script in form of a "_TIMER_<timerName>" variable. In the example above there will be the _TIMER_t1 variable and the script may retrieve the current timer value through a variable call such as "{_TIMER_t1}". If the called variable starts with the reserved prefix of "_TIMER_" but the name after it doesn't correspond to any existing timer name, it returns -1. This value may be used to test existence of a timer.

Though timer variables can be modified through the Var or Eval commands, it has no effect on the timers themselves because their values are stored in an internal data structure. The variable is rather just a read-only copy of the internal value. To set the timer to a particular value use the value parameter. Note that setting of a value of a running timer will stop it and to resume from the specified value the command must contain the "start" action.

For example, to make the t1 timer start from 1 second (1000ms) rather than from zero use:

Timer t1 start desc="My task duration" value="1000"

Another example shows how to create a new timer t2 with the value of timer t1 plus 1 second:

Timer t2 value="{_TIMER_t1}+1000"

As the value parameter also accepts a timer name, to create a plain copy of the t1 timer simply call:

Timer t2 value="t1"

The Timer command accepts either a single object (timer or timer group) or a comma separated list of timers (groups). To start the two timers defined above one may use:

Timer t1,t2 start

Timers may be optionally associated into groups. Grouping allows to organize timers in a logical way and perform bulk operations with them. A group should be understood as a plain list of timers equivalent to a comma separated timer list; it has no status and it doesn't affect the appearance of test results. Groupping and ungrouping is achieved through the group and ungroup parameters which create and update groups. The following example creates two timers t1 and t2, associates them into a group called tgroup and starts/stops both timers using the group name:

Timer t1,t2 group=tgroup
Timer tgroup start
<task code>
Timer tgroup stop

To copy  tgroup into a new group called tgroup2 call:

Timer tgroup group=tgroup2

One timer may be a member of multiple groups. Timers may be freely grouped or ungrouped any time. To remove the t1 timer from both tgroup and tgroup2 use:

Timer t1 ungroup=tgroup,tgroup2

Alternatively to remove the timer from all groups use the ungroup parameter with an empty value:

Timer t1 ungroup=

To cancel a group and remove all timers from it use the following command which should be understood as a request like "take all timers listed in group tgroup and remove them from tgroup".
 
Timer tgroup ungroup=tgroup

When a group name is used in the Timer command argument, it expands into a list of timers and all other operations specified by the command (start, stop, value/description setting, ...) are applied to each timer. The following example will create and group the two timers, set their value to 1 second (1000ms), set their description to "Performance test" and start them:

Timer t1,t2 group=tgroup
Timer tgroup start value=1000 desc="Performance test"

As you may have noticed, a single command may specify one or more operations. They are performed in the following order:
  1. Resolve the argument into a list of timers and create those which do not exist yet
  2. Set the value or any other attributes (such as description),
  3. Ungroup if the ungroup parameter is present,
  4. Group if the group parameter is present,
  5. Load the reference data if the load parameter is present,
  6. Start or stop the timers identifed in the first step if the start or stop parameter is present.
This order allows to fit the example above into a single line of code. In terms of processing order the command should be understood as a request like "create timers t1 and t2, set their value and description, group them into a group called tgroup and start them":

Timer t1,t2 start value=1000 desc="Performance test" group="tgroup"

SYNOPSIS
timer <name(s)> [start|stop]  [desc=<description>]  [value=<time_millis>]  [refvalue=<time_millis>]  [load=<XML_file>]  [group=<name(s)>]  [ungroup=<name(s)]
timer load=<XML_file>
* Red color indicates obligatory parameters

OPTIONS
name(s)

- Timer or group name or a comma separated list of names to apply the command to. A mixture of groups and timers is also allowed. If any of the specified names contains a space, the whole list must be enclosed in double quotes. A unique name (or names) will create a new timer (timers). If the name corresponds to a group previously created by a command call with the group parameter, it is expanded into a list of timers currently present in that group.

start|stop

- Start or stop the specified timer(s) (optional). Starting of an already started timer or stopping of a stopped one has no effect and reports no error.

desc=<description>

- Optional timer description.

value=<time_millis>

- Initial timer value in milliseconds (optional). The value may refer to a name of an existing timer. The default value is zero. Setting of a value of a started timer will stop it and it is necessary to restart it.

refvalue=<time_millis>

- Reference time value in milliseconds. It plays no role during the script execution and it is used exclusively for reporting purposes. When the reference value is specified, the timer entry in resulting XML file created by the Report command will contain the reference value as well as the relative difference (percentage) from the reference data. This functionality allows to track performance changes across testing of two application versions.

load=<XML_file>

- The parameter loads reference data from an XML file previously generated through the Report command. If the file is relative, it is resolved in the same way as the Report file (meaning against the output path specified by the _REPORT_DIR variable). The XML is parsed for timer data and if any of the timer names corresponds to a timer created in the current script, the XML timer value is set as a reference time of the current timer. Reference times as well the difference from the actually measured values are then written into the newly generated XML. See also the refvalue parameter above. Note that loading of reference data from XML has a priority over the refvalue parameter and it will overwrite its settings.

If the load operation is called from a Timer command operating over a set of timers (the first command form as is specified in the Synopsis above), it is applied just to the specified set and all other data from XML are discarded. To load reference data of all timers at once use the second command form of "Timer load=<XML_file>". As this command stores the reference data internally and updates all already existing as well as the to-be-created timers, the global load operation may be called anywhere in the script (not necessarily at the script beginning).

group=<group(s)>

- A group or a comma separated list of group names to associate the timer(s) with. If any of the specified group names contains a space, the whole list must be enclosed in double quotes. A unique name (or names) will create a new group (groups). A group name may not be the same as name of an already existing timer. 

ungroup=<group(s)>

- A group or a comma separated list of group names to remove the timer(s) from. If any of the specified group names contains a space, the whole list must be enclosed in double quotes. If the specified timer(s) is a member of the specified group or groups, it is removed from there.

RETURNS
If the command employs the load parameter to read reference data from an XML file, it returns 0 (zero) when the XML is valid and contains at least one timer value. When the XML does not contain any timer data but the format is correct, the command returns 1 (one). If the file can not be read or is not a valid XML file, the command returns the value of 2 (two).

Timer commands without the load parameter always return 0 (zero).

EXAMPLES
See the text above for examples.


3.3.3 Warning

DESCRIPTION
 Next | Previous | Top^
Warning - Insert a warning into the report. A warning can be associated with a specific screenshot through the image parameter. Such a warning will be displayed below the image description in the report. If there's no associated image, the warning will be displayed in the report as a single component.

When a script is being executed and there's a running report provider (i.e. the script contains a Report command), an execution of a Warning command will trigger refresh of the report. If there's no active report provider, a warning is created in the internal tables but it is not reported in any way.

SYNOPSIS
warning <description> [image=<screenshot_name>]
* Red color indicates obligatory parameters

OPTIONS
description

- Text of the warning to be displayed in the report.

image=<screenshot_name>

- A screenshot to be associated with the warning. The screenshot name should correspond to an image created by the Screenshot command.

RETURNS
The Warning command always returns 0 (zero).

EXAMPLES
Report index.html
Exec "mozilla file://{_REPORT_FILE}"
if ({_EXIT_CODE} > 0) {
  Warning "Mozilla failed to start. Error output: {_EXEC_ERROR}"
}

- Try to open the HTML report in a Mozilla browser using the Exec command and add a warning if it fails.

Screenshot image.jpg template=template1.png onfail="Warning \"The image image.jpg doesn't seem to display what is expected.\" image=image.jpg"

- Take a screenshot and compare it to a template called template1.png. If the comparison fails, add a warning to the image description.




3.4 I/O Commands


3.4.1 Excel

DESCRIPTION
 Next | Previous | Top^
Excel - Read from and/or write to Microsoft Excel 97/2000/XP (.xls) and since v2.3 also MS Excel 2007 XML documents (.xlsx). The command allows to navigate through XLS and XLSX documents, read, write and search for cell values and deal with a subset of Excel supported formats. The command takes advantage of the Apache POI framework and as such it is subject to its limitations.

The command defines this set of actions:
A typical work flow consists of the following logical steps:
  1. Open an existing Excel document ("Excel open") or create a new one ("Excel create"). If the script works with multiple documents at a time, each file must be tagged by an ID and all subsequent Excel commands must reference it. This step populates variables with the file name, path and structure.
  2. Select (open) or create a spread sheet. Opening of an Excel document through "Excel open" automatically selects the first spread sheet in the workbook unless the sheet is explicitly specified by the parameter. Creating of a new document through "Excel create" automatically creates and selects one default spread sheet with the default "Sheet1" name unless another name is explicitly specified. To change the spread sheet selection later on call "Excel select". To create and select a new spread sheet use "Excel create". Each change in spread sheet selection populates a the Sheet variable group describing number of spread sheets available and the name and number of the currently selected one.
  3. To read a cell call "Excel select" or search for a cell value using "Excel find". If the cell is found successfully, its value, type and format are provided in form of script variables. If the cell is contains a formula you may retrieve either its text or the resulting value depending on the "evaluate" parameter. Like sheets, the cell reference is cached and a sequence of commands operating over a single cell doesn't have to specify the coordinates (either row/cell number or reference) in each command instance.
  4. To modify a cell use the "Excel set" command. If the format is not explicitly specified, the command checks for number or boolean values and eventually defaults to string. If the coordinates point to a cell which doesn't exist, it is created.
  5. To close a document and save or discard changes call the "Excel close" command. This step is optional and all documents are closed and eventually saved automatically when the script finishes.
A typical example showing both read and write operations follows. It opens an existing file Excel 2007 file, selects the second sheet and reads a value from the first cell and writes it to the second one for every row.

// Open the Excel file. Exit on any I/O error.
Excel open file="C:\data\test.xlsx"
if ({_EXIT_CODE} > 0) {
  Exit {_EXIT_CODE} desc="{_EXCEL_ERROR}"
}

// Select the second sheet
Excel select sheet=1

// Iterate over all data lines
for (index=1; {index}<{_EXCEL_SHEET_ROWS}+1;index={index}+1) {

  # Read value from the first cell
  Excel select row={index} column="1"

  # Set value of the second cell
  Excel set row={index} column="2" value="{_EXCEL_CELL_VALUE}"
}

The Excel command populates these variables:

Who Creates and When Variable Name Description
Excel open,
Excel create

("File Group")
 _EXCEL_FILE
 Document file path (full/absolute).
_EXCEL_FILENAME
 Document file name.
_EXCEL_OUTFILE Output file path (full/absolute) if it was explicitly specified.
_EXCEL_OUTFILENAME Output file name if it was explicitly specified.
_EXCEL_SHEET_COUNT
 Number of spread sheets available in the document.
Excel open
Excel create
Excel select (sheet)
Excel set sheet=<>
Excel find sheet=<>

("Sheet Group")
 _EXCEL_SHEET_NAME
 Name of the currently selected sheet.
_EXCEL_SHEET_NUMBER
 Number of the currently selected sheet.
_EXCEL_SHEET_ROWS
 Number of rows available in the currently selected sheet.
Excel set
Excel select (cell)
Excel find

("Cell Group")
 		_EXCEL_CELL_COLUMN
 Ordinary column number of the selected/found/modified cell.
_EXCEL_CELL_ROW
 Ordinary row number of the cell.
_EXCEL_CELL_TYPE Cell type; one of [BLANK, BOOLEAN, ERROR, FORMULA, NUMERIC or STRING]
_EXCEL_CELL_VALUE
 Cell value (as a string).
_EXCEL_CELL_REF
 Excel compatible cell reference, for example "A1" or "J10".
All Excel commands
 _EXCEL_ERROR
 Text of the error thrown by the last Excel command execution or compilation.
This variable is being created since v2.3 and allows to track I/O errors resulting
from Excel processing.

The command in general returns 0 on success or one of the following exit codes:

Exit Code Pseudo code
 Description
0
 SUCCESS
 Successful completion.
1
 FAILED_TO_OPEN
 Failed to open the input file. Returned just by "Excel open".
2
 FAILED_TO_SAVE
 Failed to save to the file. Returned just by "Excel close".
3 FAILED_TO_CREATE Failed to create a new document or sheet. Returned just by "Excel create".
4
 SHEET_NOT_FOUND
 The row and/or column parameters do not point to an existing cell. Returned by all cell-reading commands supporting "row" and "column".
5
 CELL_NOT_FOUND Failed to find a cell with the given coordinates or with the specified value ("Excel find").

Syntax and parameters of each action are described in details below.
  
SYNOPSIS

Excel open [file=<input_Excel _file>]  [outfile=<output_Excel_file>]  [id=<identifier>]  [sheet=<sheet_name_or_index>]
* Red color indicates obligatory parameters

OPTIONS
file=<Excel_file>

- The Excel file to open. Relative path is resolved against the script directory (meaning the folder containing the calling script).

outfile=<output_Excel_file>

- Optional output file to save the Excel data to (regardless of whether it has been changed or not). When this parameter is specified, the input file specified by file is opened in read only mode, its data is loaded into the memory and saved to outfile unless the file is closed in the discard mode (Excel close save=false). The input and output files must be of the same format (both must be either XLS or XLSX).

id=<identifier>

- An identifier (name) for the Excel document. This parameter doesn't have to be specified if the script opens/creates just one Excel document at a time. If multiple documents are being opened the identifier identifies the document in the subsequent Excel read/write commands.

sheet=<sheet_name_or_index>

- The spread sheet to select. It may be specified either by its name or ordinary number starting from 1. This parameter is optional and if it is not present, the command selects (opens) the first spread sheet by default.

RETURNS
The open command returns either 0 (SUCCESS) or 1 (FAILED_TO_OPEN). On success it populates variables from the File and Sheet variable group.

EXAMPLES

Excel open file="data.xls"

- Open a MS Excel document located in the same directory as the script in read/write mode.

Excel open file="C:\Data\data.xls" outfile="newdata.xls"

- Open a MS Excel document located in the specified directory in the read only mode. When the document is closed, save the content and eventually all changes into the specified output file in the script directory. If the output file exists it will be overwritten.



Excel create file=<Excel _file>  [id=<identifier>]  [sheet=<sheet_name>]
Excel create sheet=<sheet_name>  [id=<identifier>]
* Red color indicates obligatory parameters

OPTIONS
file=<Excel_file>

- The Excel file to create. Relative path is resolved against the script directory (meaning the folder containing the calling script). If the file exists, it is overwritten.

id=<identifier>

- An identifier (name) for the created document. This parameter doesn't have to be specified if the script opens/creates just one Excel document at a time. If multiple documents are being opened the identifier identifies the document in the subsequent Excel read/write commands.

sheet=<sheet_name>

- Name of the spread sheet to create. If the command is called with the file parameter specified to create a new file, the sheet parameter is optional. If it is not present, the command behaves the same way as MS Excel and creates a default spread sheet called "Sheet1" in the newly created file.

RETURNS
The open command returns either 0 (SUCCESS) or 3 (FAILED_TO_CREATE) on failure, for example when a sheet of the specified name already exists. The command populates variables from the File and Sheet variable groups.

EXAMPLES
Excel create file="C:\Data\log.xls"

- Create a new Excel document in the memory and associate it with the specified file for output. The command will also create a sheet called "Sheet1" and select it.

Excel create file="C:\Data\log.xls" sheet="Data"
- Same as previous example but the sheet will be named "Data".

Excel create sheet="Data"

- Create a new sheet with named "Data" in the currently opened document.



Excel select  [sheet=<sheet_name_or_index>]  [id=<identifier>]
Excel select  [row=<row_number>]  [column=<column_number_or_id>]  [sheet=<sheet_name_or_index>]  [id=<identifier>]
Excel select  [ref=<cell_id>]  [sheet=<sheet_name_or_index>]  [id=<identifier>] 
* Red color indicates obligatory parameters

OPTIONS
row=<row_number>
column=<column_number_or_id>

- Row and column ordinary numbers identifying the cell to select. Numbering starts from 1. The column may be in addition referenced by alphabetical ID used in MS Excel ("A"-"ZZ"). For example, "column=C" is equal to "column=3". The "row" and "column" parameters must be always present together. The parameters are mandatory in the first cell operation to cpecify the "current" cell. The reference is then cached and sequences of commands operating over a single cell do not have repeat the  "column"/"row" or "ref" coordinates.

ref=<cell_id>

- Cell ID compatible with MS Excel referencing, for example "A1" or "J10". It is provided as an alternative way of cell referencing. The parameter should not be used together with the row/column parameter pair.

sheet=<sheet_name_or_index>

- The spread sheet to select (open). It may be specified either by its name or ordinary number starting from 1. If the command is being used just to select a sheet (the first form in the list above), this parameter is mandatory. Other command forms targeting a particular cell do not require it and if it is not present, the command will operate over the last selected sheet.

evaluate=<true|false>

- A flag controlling how FORMULA cells are handled. If it is "true" the cell value will be the calculated formula result. Otherwise the cell value stored under the _EXCEL_CELL_VALUE will contain the formula text. If the targeted cell is not a FORMULA one, this parameter is ignored. The default value is "false".

id=<identifier_or_name>

- The document identifier to apply the operation to. This parameter doesn't have to be specified if the script opens/creates just one Excel document and no ID was specified in the open/create command.

RETURNS
The open command returns either 0 (SUCCESS), 4 (SHEET_NOT_FOUND) or 5 (CELL_NOT_FOUND). The command populates variables from the Sheet and Cell variable groups.

EXAMPLES
Excel select sheet=2

- Select second sheet in the document and store its properties into the Sheet variables..

Excel select sheet="Data"
- Select sheet called "Data" in the document.

Excel select row=2 column=4
- Select cell on the specified position in the current sheet and retrieve its properties into the Cell variables.

Excel select sheet="Results" ref=A5
- Select the "Results" sheet and then select cell on the specified position (fifth row, first column). Both the Sheet and Cell variable groups will be updated with the sheet/cell properties.


Excel find  [value=<value>]  [type=<type>]  [sheet=<sheet_name_or_index>]  [evaluate=<true|false>]  [id=<identifier>]
Excel find  [pattern=<regular_expression>]  [type=<type>]  [sheet=<sheet_name_or_index>]  [evaluate=<true|false>]  [id=<identifier>]
* Red color indicates obligatory parameters

OPTIONS
value=<value>

- String representation of the value to search for. The current sheet will be searched row by row for a cell having the specified value and the first matching one will be selected.

pattern=<regularExpression>

- Search for a cell value which matches a regular expression. The expression must comply with the Java Pattern specification.

type=<type>

- Type of cell to limit the search to. It must be one of [BLANK, BOOLEAN, ERROR, FORMULA, NUMERIC, STRING]. If the parameter is not specified all cell types are searched.

sheet=<sheet_name_or_index>

- The spread sheet to select (open). It may be specified either by its name or ordinary number starting from 1. This parameter is optional and if it is not present the command will operate over the last selected sheet.

evaluate=<true|false>

- Flag controlling how FORMULA cells are handled. If it is "true" the cell value will be the calculated formula result. Otherwise the specified value will be compared to the formula text. The default value is "false".

id=<identifier_or_name>

- The document identifier to search. This parameter doesn't have to be specified if the script opens/creates just one Excel document and no ID was specified in the open/create command.

RETURNS
The open command returns either 0 (SUCCESS), 4 (SHEET_NOT_FOUND) or 5 (CELL_NOT_FOUND). If the cell is located successfully the command populates variables from the Sheet and Cell variable groups.

EXAMPLES
Excel find value="Test data"
if ({_EXIT_CODE} > 0) {
  Warning "The \"Test data\" cell was not found."
  Exit 1
}
Excel select row={_EXCEL_CELL_ROW}+1 column={_EXCEL_CELL_COLUMN}

- Search the current spread sheet for a cell containing the text "Test data". If successful select the cell below the found one. If the search fails, record a warning and exit the script with the exit code of 1.

Excel find value="2" evaluate=true
- Search the current sheet for any numeric cell containing the number of 2 or any text cel containing "2". As the evaluate flag is on, each cell of the FORMULA type will be calculated (evaluated) and compared to the value of 2.

Excel find sheet="Data" pattern="boo.*"
- Select sheet called "Data" in the document and search it for the first value starting with "boo".

Excel find type=FORMULA pattern="SUM\(.*\)"
- Search the current sheet for the first cell of FORMULA type containing the summary formula and retrieve its properties into the Cell variables. As the "evaluate" flag is not specified and defaults to false, the _EXCEL_CELL_VALUE will be populated with the formula text.

Excel find type=FORMULA pattern="SUM\(.*\)" evaluate=true
- Same as the previous example. The _EXCEL_CELL_VALUE will however contain result of the formula, i.e. a number equal to the sum of the cells specified in the formula text.



Excel set  [row=<row_number>]  [column=<column_number_or_id>]  [sheet=<sheet_name_or_index>]  [id=<identifier>]  [type=<type>]  [value=<value>]
Excel set  [ref=<cell_id>]  [sheet=<sheet_name_or_index>]  [id=<identifier>]  [type=<type>]  [value=<value>]
* Red color indicates obligatory parameters

OPTIONS
row=<row_number>
column=<column_number_or_id>

- Row and column ordinary numbers identifying the cell to select. Numbering starts from 1. The column may be in addition referenced by alphabetical ID used in MS Excel ("A"-"ZZ"). For example, "column=C" is equal to "column=3". The "row" and "column" parameters must be always present together. The parameters are mandatory in the first cell operation to cpecify the "current" cell. The reference is then cached and sequences of commands operating over a single cell do not have repeat the  "column"/"row" or "ref" coordinates.

ref=<cell_id>

- The cell ID compatible with MS Excel, for example "A1" or "J10". It is provided as an alternative way of cell referencing. The parameter should not been used together with the row/column parameter pair.

sheet=<sheet_name_or_index>

- The spread sheet to select (open). It may be specified either by its name or ordinary number starting from 1. If the command is being used just to select a sheet (the first command syntax form in the list above), this parameter is mandatory. Other command forms targeting a particular cell do not require it and if it is not present, the command will operate over the last selected sheet.

type=<type>

- Type of cell to set. It must be one of [BLANK, BOOLEAN, ERROR, FORMULA, NUMERIC, STRING]. If the parameter is not specified, the type defaults to STRING.

value=<value>

- Cell value to set. It must be aligned with the cell type. For example when the cell type is NUMERIC, the value should be a valid number. If the "type" parameter is not specified, the command guesses whether it is a number, a boolean value or a string and sets the cell type accordingly. To override this behavior specify the type explicitly.

The value may contain a numeric expression but the type must be explicitly set to NUMERIC to tell the compiler that numeric evaluation is needed. To create and populate a cell of the FORMULA type use the type="FORMULA" parameter and specify the formula with or without the leading equals character as the value. For example, both "SUM(A1:A4)" and "=SUM(A1:A4)" are valid formulas.

id=<identifier_or_name>

- The document identifier to apply the set operation to. This parameter doesn't have to be specified if the script opens/creates just one Excel document and no ID was specified in the open/create command.

RETURNS
The open command returns either 0 (SUCCESS), 4 (SHEET_NOT_FOUND) or 5 (CELL_NOT_FOUND). If the cell is located successfully the command sets the value and/or cell type and populates variables from the Sheet and Cell variable groups.

EXAMPLES
Excel set ref=A5 value="Test data"

- Set value of the A5 cell in the current sheet to "Test data". The cell type will be STRING.

Excel set row=1 column=A value="2" sheet="Results"
- Select the "Results" sheet and set value of the A1 cell to 2. As the value is apparently a numeric one the cell type will be automatically set to NUMERIC.

# Declare the variable as numeric to supress compiler error
 Var _EXCEL_CELL_VALUE=1
Excel set row=1 column=A value="2"
Excel set value={_EXCEL_CELL_VALUE}+1 type=NUMERIC
- Set the A2 cell value to 2 and then increment it to 3. Declaration of the _EXCEL_CELL_VALUE is needed only to supress the compiler error when trying to evaluate the value.

Excel set row=5 column=1 type=FORMULA value="SUM(A1:A4)"
Excel select evaluate=true
- Set value of the cell at A5 to the summary formula of the A1-A4 cells and get the result.


Excel close  [id=<identifier>]  [save=<true|false>]
* Red color indicates obligatory parameters

OPTIONS
id=<identifier_or_name>

- The identifier of the document which is to be closed. This parameter doesn't have to be specified if the script opens/creates just one Excel document and no ID was specified in the open/create command.

save=<true|false>

- True saves the document to the file system, false discards any changes. The default value is "true" and the file will be saved automatically after the script execution finishes provided that there were any changes.

RETURNS
The open command returns either 0 (SUCCESS) or 2 (FAILED_TO_SAVE) on an I/O error. It also clears up all Excel specific variables from the context.

EXAMPLES

Excel open file=test.xls
...
Excel close

- Close the file. If the content has been modified, save the changes to the test.xls file.


Excel open file=test.xls outfile=test2.xls
...
Excel close

- Close the file. The content loaded from test.xls will be written to test2.xls regardless of whether it has been modified or not.

Excel open file=test.xls id="testfile"
...
Excel close id="testfile" save=false

- Close the file and discard any eventual changes. As the "testfile" ID was assigned to the file in "Excel open", it must be specified in the "Excel close" one as well as in any other Excel call between these two commands.


3.4.2 File

DESCRIPTION
 Next | Previous | Top^
File - Read from and/or write to text files. The command allows to open or create plain text files, read/write text, search strings/regular expressions and parse values from individual text lines using either the Comma Separated Values (CSV) format or regular expressions.

Files are by default opened and saved in UTF-8 encoding. The file content is read using the Java character streams line by line and stored into a string buffer in the memory. All subsequent I/O operations are performed on the buffer and the content is written to the file (or output file) only when the file either gets explicitly closed or when the script finishes in a standard way (meaning not through unexpected or abnormal program termination). With regard to the used technology the command is suitable to process smaller files (up to tens of kB) and its performance significantly degrades with large data files.

The command defines this set of actions:
A typical work flow consists of the following logical steps:
  1. Open an existing file ("File open") or create a new one ("File create"). This step populates variables with the file name, path and structure. If the script works with multiple files at a time, each file must be tagged by an ID and all subsequent File commands must reference it.
  2. To read a value from a known position in the file use "File read". If the position is unknown, "File find" may be used to identify position of a text value. If the file contains data in a particular format, parse them through "File parse". This command supports reading of values in the CSV format or parsing of values based on a custom regular expression.
  3. To write to the file use either "File append" or "File insert". The append action adds the text to the end of the file. The insert one allows to insert the text into a particular position in the file.
  4. To close a document and save or discard changes call the "File close" command. This step is optional and all documents are closed and eventually saved automatically when the script finishes.
Navigation through the file and retrieval of parsed text is enabled through variables:

Who Creates, Group Name
 Variable Name Description
File open,
File create

(so called "File Group")
 		_FILE_FILE
 File path (full/absolute).
_FILE_FILENAME
 File name.
_FILE_OUTFILE Output file path (full/absolute) if it was explicitly specified.
_FILE_OUTFILENAME Output file name if it was explicitly specified.
File open
File create
File append
File insert

("Counter Group")
 _FILE_LENGTH File length in characters including the new line ones. Note that it doesn't have to match
the file size because some UTF-8 characters may be encoded in multiple bytes.
_FILE_LINE_COUNT Number of text lines in the file.
File find
File read
File parse
File insert

("Line Group")
 _FILE_LINE_NUMBER
 Number of the currently processed line. Lines are numbered from 1 (one).
_FILE_LINE_LENGTH Length of the current line in characters excluding the new line character.
_FILE_LINE_TEXT Text of the current line (full length without the new line character).
_FILE_LINE_COLUMN Column (character) number on the line. Column numbering starts from 1 (one) which
represents beginning of the line. This variable is populated by the "find" action to indicate
position of the searched text on the line. Other commands either mimick the "column"
parameter or its default value of 1 (one).
File read
 _FILE_READ
 Text read by the "File read"command.
File delete
 _FILE_DELETED
 Text deleted by the "File delete" command.
File parse

("Parse group")
 		_FILE_PARSE_COUNT
 Number of values parsed by "File parse".
_FILE_PARSE_VALUE<N>
 N-th value parsed from the text line where <N> is between 1 and _FILE_PARSE_COUNT.

The command in general returns 0 on success or one of the folowing exit codes:

Exit Code Pseudo code
 Description
0
 SUCCESS
 Successful completion.
1
 FAILED_TO_OPEN
 Failed to open the input file. Returned just by "File open".
2
 FAILED_TO_SAVE
 Failed to save to the file. Returned just by "File close".
3 FAILED_TO_FIND
 Failed to find a value. Returned just by "File find" to indicate failed text search.
4
 INVALID_POSITION
 The line and/or column parameters do not point to an existing position in the file.
Returned by all commands supporting "line" and "column".
 
Syntax and parameters of each action are described in details below.
  
SYNOPSIS


File open [file=<file>]  [outfile=<output_file>]  [id=<identifier>]
File create [file=<file>]  [id=<identifier>]
* Red color indicates obligatory parameters

OPTIONS
file=<ile>

- The file to open or create. Relative path is resolved against the calling script location (meaning the folder containing the calling script).

outfile=<output_file>

- Optional output file. When specified the command creates a copy of the file and applies all changes to it rather than to the source file. Relative path is resolved against the calling script location (meaning the folder containing the calling script). If the parameter is omitted the file is opened in read/write mode. If the file already exists it will be overwritten.

id=<identifier>

- An identifier (name) for the file. This parameter can be omitted if the script opens/creates just one file at a time. If multiple file are being opened, the identifier  is mandatory and identifies the file in the subsequent File commands.

RETURNS
The open command returns either 0 (SUCCESS) or 1 (FAILED_TO_OPEN). The create command always returns 0 because it creates the file just in memory.  If the command exits with 0 it populates variables from the File and Counter variable groups.

EXAMPLES

File open file="data.csv"

- Open a CSV file located in the same directory as the script in read/write mode.

File open file="C:\Data\data.csv" outfile="newdata.csv"

- Open a CSV file located in the specified directory in the read only mode. When the file is closed, save the content and eventually all changes into the specified output file in the script directory. If the output file exists it will be overwritten.

File create file="C:\Data\log.txt"

- Create a new file content buffer in the memory and associate it with the specified file for output.



File append  [text=<text>]  [id=<identifier>]
* Red color indicates obligatory parameters

OPTIONS
text=<text>

- Text to append to the end of the file. It may contain any UTF-8 characters. To indicate a line break use "\n". If you need to use the "\n" sequence in the normal text, double the backslash character ("\\n").

id=<identifier>

- Identifier of the file to append the text to. It must be equal to the ID specified in the File open or create command. The parameter doesn't have to be specified if the script opens/creates just one file and no ID is specified in the open/create command.

RETURNS
The command always returns 0 (success). As it changes file size and eventually number of lines, the command updates variables from the Counter group.

EXAMPLES

File append text="This is one line\nwhile this is another one"

- Append two lines of text , "This is one line" and "while this is another one" to the end of the file.

File append text="screws\\nails"

- Append one line of text, "screws\nails". The back slash character must be in this case doubled because it would be otherwise interpreted as new line character.



File insert  [text=<text>]  [line=<line_number>]  [column=<column_number>]  [id=<identifier>]
* Red color indicates obligatory parameters

OPTIONS
text=<text>

- Text to insert into the file. It may contain any UTF-8 characters. To indicate a line break use "\n". If you need to use the "\n" sequence in the normal text, double the backslash character ("\\n").

line=<line_number>

- The line number to insert the text to. Numbering starts from 1. If the line number is out of the range the command fails with the exit code of 4 (INVALID_POSITION).

column=<column_number>

- The column (character number) to insert the text into. Numbering starts from 1. If not specified the command inserts by default to the line beginning (column=1).  If the column is greater than number of characters on the line the command fails with the exit code of 4 (INVALID_POSITION).

id=<identifier>

- Identifier of the file to insert the text into. It must be equal to the ID specified in the File open or create command.  The parameter doesn't have to be specified if the script opens/creates just one file and no ID is specified in the open/create command.

RETURNS
The command returns 0 (SUCCESS) or 4 (INVALID_POSITION) if the line and column parameters do not point to an existing position in the file. As it changes file size and eventually number of lines, the command updates variables from the Counter group. The command also updates the Line variable group to provide information about the line pointed to by the [line,column] coordinates.

EXAMPLES

File read line=2
File insert text=" and potatoes" line=2 column={_FILE_LINE_LENGTH}+1

- Append " and potatoes" to the end of the second line. The "File read" command is called to get the line length (the _FILE_LINE_LENGTH variable).

File find text="bananas"
File insert text=" and potatoes" line={_FILE_LINE_NUMBER} column={_FILE_LINE_COLUMN}+7

- Search for "bananas" and insert  the text to create "bananas and potatoes". Note that the example doesn't test whether the find command succeeds.


File find  [text=<text>]  [line=<line_number>]  [column=<column_number>]  [direction=<forward|backward>]  [scope=<line|file>]  [id=<identifier>]
* Red color indicates obligatory parameters

OPTIONS
text=<text>

- The text to search for. It may contain any UTF-8 characters. To indicate a line break use "\n". If you need to use the "\n" sequence as normal text, double the backslash character ("\\n").

line=<line_number>

- The line number to start the search from. Numbering starts from 1. If the line number is out of the range the command fails with exit code of 4 (INVALID_POSITION).

column=<column_number>

- The column (character number) to start the search from (to be used together with "line"). Numbering starts from 1. If not specified the command searches by default from the line beginning (column=1).  If the column is greater than number of characters on the line the command fails with exit code of 4 (INVALID_POSITION).

direction=<forward|backward>

- The search mode. The default one is forward and searches from the position specified by [line, column] towards the end of file or line. The backward mode searches in the opposite direction from the given position.

scope=<file|line>

- The search scope. The default one is file and searches the whole file or its part. The line scope allows to search just the specified line or its part and the searched text should not contain the new line character.

id=<identifier>

- Identifier of the file which is to be searched. It must be equal to the ID specified in the File open or create command. The parameter doesn't have to be specified if the script opens/creates just one file and no ID is specified in the open/create command.

RETURNS
The command returns 0 (SUCCESS) if the text is found, 3 (NOT_FOUND) if the text is not found or 4 (INVALID_POSITION) if the line and column parameters do not point to a valid position in the file. If the search succeeds, the Line variable group is updated to provide the target [line,column] coordinates.

EXAMPLES
File find text="bananas"
if ({_EXIT_CODE} == 3) {
  Exit 3
}
File insert text=" and potatoes" line={_FILE_LINE_NUMBER} column={_FILE_LINE_COLUMN}+7

- Search the file forwards for "bananas" and insert  the text to create "bananas and potatoes". If the word is not found the script will be terminated with the exit code of 3.


File read  [line=<line_number>]  [column=<column_number>]  [length=<length_in_chars>]  [id=<identifier>]
* Red color indicates obligatory parameters

OPTIONS
line=<line_number>

- The number of the line to read from. Numbering starts from 1. If the line number is out of the range the command fails with exit code of 4 (INVALID_POSITION).

column=<column_number>

- The column (character number) to read from. Numbering starts from 1. If not specified the command reads from the line beginning (column=1).  If the column is greater than number of characters on the line the command fails with exit code of 4 (INVALID_POSITION).

length=<length_in_chars>

- Optional length specifying how many characters should be read. The range may not exceed the text line bounds. If the length parameter is not specified the command reads to the end of the specified line (excluding the new line character).

id=<identifier>

- Identifier of the file to read from. It must be equal to the ID specified in the File open or create command. The parameter doesn't have to be specified if the script opens/creates just one file and no ID is specified in the open/create command.

RETURNS
The command returns 0 (SUCCESS) if the text is located and read successfully or 4 (INVALID_POSITION) if the line and column parameters do not point to a valid position in the file. If successful the extracted text is stored into the _FILE_READ variable. The command also updates the Line variable group to provide information about the line pointed to by the [line,column] coordinates.

EXAMPLES
File find text="bananas" line=2 scope=line
File read line=2 length={_FILE_LINE_COLUMN}
Type "{_FILE_READ}"

- Find the "bananas" word on the second line, read the text before the word and type it.


File parse  [line=<line_number>]  [delimeter=<delimeter_char>]  [separator=<separator_char>]  [trim=<true|false>]  [id=<identifier>]
File parse  [line=<line_number>]  [pattern=<regular_expression>]  [trim=<true|false>]  [id=<identifier>]
* Red color indicates obligatory parameters

The command by default reads values from the specified line according to the Comma Separated Values (CSV) specification. The command is compatible with rules specified in the Comma-Separated Values article at Wikipedia and supports multi line values. The parsing mechanism may be in addition customized with optional custom text delimeter, value separator. and trimming mode.

When the "pattern" parameter is specified, the command parses the line based on the provided Java-compatible regular expression. This approach takes advantage of the java.lang.String.split() method and it is fundamentally different from the CSV mechanism. For example, to parse individual words separated by a space use regular expression "\s". This mode may not be mixed with CVS parsing and "pattern" can not be specified at the same time as "delimeter" and/or "separator".

The parsed values are made available through a set of numbered variables (_FILE_PARSE_VALUE1, _FILE_PARSE_VALUE2, ...) and a counter (_FILE_PARSE_COUNT) and may be retrieved in the script through a "for" loop with nested variable names (see the examples section). The command also modifies the line variables and sets the line number to the last processed line. This is an important feature allowing to iterate correctly over lines which may contain multiline values. 

OPTIONS
line=<line_number>

- The number of the line to parse. Numbering starts from 1. If the line number is out of the range the command fails with exit code of 4 (INVALID_POSITION).

delimeter=<delimeter_char>

- The character which will serve as text delimeter. If the parameter is not specified it defaults to CSV compatible double quote ( " ).

separator=<separator_char>

- The character which will serve as value separator. If the parameter is not specified it defaults to CSV compatible comma ( , )

pattern=<regular_expression>

- A regular expression expressing the value to separate the values by. This parse mode internally relies on the java.lang.String.split() method. The expression must comply with the Java Pattern specification.

trim=<true|false>

- The value of true trims white spaces from the beginning and end of each parsed value. Be aware that this mode is not CSV compatible and doesn't meet requirements of RFC 4180. The default value is false (do not trim).

id=<identifier>

- Identifier of the file to read & parse from. It must be equal to the ID specified in the File open or create command. The parameter doesn't have to be specified if the script opens/creates just one file and no ID is specified in the open/create command.

RETURNS
The command returns 0 (SUCCESS) if the text is located and read successfully or 4 (INVALID_POSITION) if the line and column parameters do not point to a valid position in the file. On success the command populates the Parse variable group and also updates the Line one with information about the processed line.

EXAMPLES

Let's have a set of data listed as example on Wikipedia:

1997 Ford
 E350
 ac, abs, moon 3000.00
1999
 Chevy
 Venture "Extended Edition"
4900.00
1999
 Chevy Venture "Extended Edition, Very Large"
5000.00
1996
 Jeep
 Grand Cherokee MUST SELL!
air, moon roof, loaded		 4799.00

The corresponding CSV file looks as follows:

1997,Ford,E350,"ac, abs, moon",3000.00
1999,Chevy,"Venture ""Extended Edition""","",4900.00
1999,Chevy,"Venture ""Extended Edition, Very Large""","",5000.00
1996,Jeep,Grand Cherokee,"MUST SELL!
air, moon roof, loaded",4799.00

The following script parses the lines one by one and prints out the individual CSV values (to see the results open a text editor on the connected remote desktop). It also calculates and prints out a sum of all prices located usually in the fifth value on the line. Note that we can not simply iterate over the number of lines in the file because the second last line contains a multiline value.

File open file="data.csv"

# We declare the fifth variable just to supress compiler error in the Eval cmd below
Var sum=0 _FILE_PARSE_VALUE5=0

for (i=1; {i}<{_FILE_LINE_COUNT}; i={i}+1) {
  File parse line={i}
  Typeline "Line #{i}:"
  for (j=1; {j}<{_FILE_PARSE_COUNT}+1; j={j}+1) {
    Typeline " Value #{j}: {_FILE_PARSE_VALUE{j}}"
  }

  # Add the car price from column 5 to the sum
  Eval sum={sum}+{_FILE_PARSE_VALUE5}

  # As the parse command updates the Line var group with number of the last
  # processed line, this will alow us to skip lines with multiline values
  Var i={_FILE_LINE_NUMBER}
}
Typeline "Summary value: ${sum}"

When the script is executed it types the following output on the desktop:
 
Line #1:
  Value #1: 1997
  Value #2: Ford
  Value #3: E350
  Value #4: ac, abs, moon
  Value #5: 3000.00
Line #2:
  Value #1: 1999
  Value #2: Chevy
  Value #3: Venture "Extended Edition"
  Value #4:
  Value #5: 4900.00
Line #3:
  Value #1: 1999
  Value #2: Chevy
  Value #3: Venture "Extended Edition, Very Large"
  Value #4:
  Value #5: 5000.00
Line #4:
  Value #1: 1996
  Value #2: Jeep
  Value #3: Grand Cherokee
  Value #4: MUST SELL!
air, moon roof, loaded
  Value #5: 4799.00
Summary value: $17699

Another example: Let's have a text file with numbers separated by one or more spaces or tabulators:

1  14   23  9   100
117   5  7

To calculate the sum of all numbers into a variable called "count" one would typically use the following script. Note that as the data file is not CSV, it is necessary to use a Java regular expression "\s".

File open file="C:\numbers.txt"
Eval count=0
Var _FILE_PARSE_COUNT=0 _FILE_PARSE_VALUE1=0

for (i=1; {i}<{_FILE_LINE_COUNT}+1; i={i}+1) {
  File parse line={i} pattern="\s"
  for (j=1; {j}<{_FILE_PARSE_COUNT}+1; j={j}+1) {
     Eval count={count}+{_FILE_PARSE_VALUE{j}}
  }
}



File delete  [line=<line_number>]  [column=<column_number>]  [length=<length_in_chars>]  [id=<identifier>]
* Red color indicates obligatory parameters

OPTIONS
line=<line_number>

- The line number to delete. Numbering starts from 1. If the line number is out of the range the command fails with exit code of 4.

column=<column_number>

- The column (character number) to delete the text from. Numbering starts from 1. If not specified the command deletes from beginning of the line (column=1). If the column is greater than number of characters on the line the command fails with exit code of 4.

length=<length_in_chars>

- Optional length specifying how many characters should be deleted. The resulting delete area may exceed the text line bounds and in such a case the delete operation is applied to the terminating new line character and then to the following line or lines. If the length exceeds the the file size, all the content file content after the specified position is deleted. If the length parameter is not specified the command deletes just to the end of the specified line including the new line character.

id=<identifier>

- Identifier of the file to read & parse from. It must be equal to the ID specified in the File open or create command. The parameter doesn't have to be specified if the script opens/creates just one file and no ID is specified in the open/create command.

RETURNS
The command returns 0 (SUCCESS) if the text is located and deleted successfully or 4 (INVALID_POSITION) if the line and column parameters do not point to a valid position in the file. The command saves the deleted text to the _FILE_DELETED variable. As the delete operation changes file size and eventually number of lines, it updates variables from the Counter group as well as the Line one.

EXAMPLES

File delete line="1"

- Delete the first line (including the new line character).


File delete line="2" length={_FILE_LENGTH}

- Delete everything from the second line to the end of file and leave just the first line.

for (i=1; {i}<{_FILE_LINE_COUNT}; i={i}+1) {
  File delete line={i} length=10
}

- Delete first 10 characters on each line.
 

File read line=1
File delete line="1" column={_FILE_LINE_LENGTH}+1 length=1

- Remove the new line character located at the end of the first line and join the first and second line.




File close  [id=<identifier>]  [save=<true|false>]
* Red color indicates obligatory parameters

OPTIONS
save=<true|false>

- True saves the file to the file system, false discards any changes. The default value is "true". The file is saved only if it has been modified by the script and/or if another output file was specified.

id=<identifier>

- Identifier of the file to close. It must be equal to the ID specified in the File open or create command. The parameter doesn't have to be specified if the script opens/creates just one file and no ID is specified in the open/create command.

RETURNS
The open command returns either 0 (SUCCESS) or 2 (FAILED_TO_SAVE) on an I/O error. It also clears up all File specific variables from the context.

EXAMPLES

File open file=test.txt
...
File close

- Close the file. If the content has been modified, save the changes to the test.txt file.


File open file=test.txt outfile=test2.txt
...
File close

- Close the file. The content loaded from test.txt will be written to test2.txt regardless of whether it has been modified or not.

File open file=test.txt id="testfile"
...
File close id="testfile" save=false

- Close the file and discard any eventual changes. As the "testfile" ID was assigned to the file in "File open", it must be specified in the "File close" one as well as in any other File call between these two commands.



4. Image Comparison Capabilities


4.1 Image Comparison Overview

Image comparison methods are algorithms and/or technologies which analyze image of the connected desktop. They are used in test scripts to verify the desktop contents, retrieve artifacts such as GUI components or text and act upon the results. Most methods work with one or more image files ("template images") and/or image folders ("template image collections"). These artifacts are described closer in the Image Collections and Image Meta Data chapters.

Image comparison method plugins are closely integrated with the three following scripting language commands and their Java method counterparts. These are in the comparison method context usually called hosting commands or Java methods:

Command Java Method(s)
 Description
Compareto compareTo() Apply the selected image comparison method to the currently conected desktop once.
Typically used to verify existence of a component or to get its coordinates, to retrieve
text or to verify whether the screen content is expected.
Screenshot screenShot() Save a screenshot of the remote desktop to a file and optionally apply the selected
image comparison method through an internal call of the Compareto command.
Waitfor match/mismatch waitForMatch()
waitForMismatch()
 Pause the execution until ('match') or while ('mismatch') the selected image comparison
method produces the result of "success" (the return code of 0). Typically used to wait
until the expected component or text appears on the screen or disappears from the screen..

Each comparison method is identified by its unique name (also referred to as code), for example "search2" or "object". Besides the standard "passrate" and "cmparea" parameters supported by the command framework each method may declare any number of optional parameters specific for the particular algorithm. These parameters are then visible to the calling command.

As all image comparison methods are internally implemented as plugins, users are free to develop their custom algorithms and integrate them into the scripting language and the Java Test Script API. See the ImageComparisonModule interface for details.

The following examples demonstrate call of the most frequently used "search2" algorithm with all the framework provided parameters of "passrate" and "cmparea" and its own specific parameter of "order":

Compareto                   "buttonOk.png" passrate="70" method="search2" cmparea="x:258,y:114,w:417,h:298" sort="none"
Screenshot "s.jpg" template="buttonOk.png" passrate="70" method="search2" cmparea="x:258,y:114,w:417,h:298" sort="none"
Waitfor    "match" template="buttonOk.png" passrate="70" method="search2" cmparea="x:258,y:114,w:417,h:298" sort="none"

The same example in form of a Java test script:

compareTo(new File[] { new File( "buttonOk.png" ) }, 70.0f, new Rectangle(258, 114, 417, 298), "none" );
screenshot(new File( "s.jpg" ), (String) null , (Rectangle) null , new File[] { new File( "buttonOk.png" ) }, 70.0f, new Rectangle(258, 114, 417, 298), "none" , false);
waitForMatch(new File[] { new File( "buttonOk.png" ) }, 70.0f, (String) null , new Rectangle(258, 114, 417, 298), (String) null , "none" , (String) null);


4.1.1 Image Collections

Image collections typically represent images capturing various visual apperances or possible states of a single graphical object, for example of a button on various environments and/or operating systems. Collections may be employed by the CompareTo, Screenshot and WaitFor match/mismatch scripting language commands or the corresponding Java methods to locate the component on the screen seamlessly on all environments.

T-Plan Robot Enterprise version 2.0 and higher supports image collections through semicolon separated image file lists. For example, to search for an "OK" button represented by two template images buttonOK1.png and buttonOK2.png located in the template folder one would use:

Compareto "buttonOK1.png;buttonOK2.png" method=search

T-Plan Robot Enterprise version 2.2 introduces dynamic image collections represented by folders. This mechanism allows to add, remove and edit template images dynamically without having to update the test script code. Each folder is searched recursively for Java supported images of losless format (PNG, BMP, WBMP, GIF) and the specified image comparison action is performed on the generated image list.

For example, images from the previous example can be moved to a folder called buttonOK and the command can be changed to:

Compareto "buttonOK" method=search

Images retrieved from the folder are by default processed in the natural order returned by the underlying operating system. Version 2.3.3 introduced a new optional mechanism allowing to change this behavior and sort the images before comparison:
  1. To configure the default sort mode see the CompareTo Command panel in the Preferences window. This setting will be used application wide unless the sort mode is overruled by the script as is described in the next bullet.
  2. Scripts may set the sort mode through setting of the _COMPARETO_SORT_MODE variable to the desired sort mode index. The variable acts as a switch and the sort mode is applied by all comparison commands until the variable gets reset or the end of the script is reached. Acceptable values are:
0 - Sort by image file name (ascending)
1 - Sort by image file name (descending)
2 - Sort by the image file last modification date (ascending)
3 - Sort by the image file last modification date (descending)

For example, to process the images from the previous example in the file name descending order (buttonOK2.png first) use:

Var _COMPARETO_SORT_MODE=1
Compareto "buttonOK" method=search

To reset the sort mode to the default one simply set the variable to an empty string:

 Var _COMPARETO_SORT_MODE=

Image collections can be freely combined into file lists consisting of images and image collections. For example, to search for the "OK" button or an "Approve" button represented by the buttonApprove1.png and buttonApprove2.png images one would use:

Compareto "buttonOK;buttonApprove1.png;buttonApprove2.png" method=search

Or, having created a folder called buttonApprove for the two images one could write:

Compareto "buttonOK;buttonApprove" method=search


4.1.2 Image Meta Data

T-Plan Robot Enterprise version 2.2 and higher saves template images to the hard drive together with an additional text file containing image meta data such as the source coordinates and click point. Whenever the image is used for image comparison, the data is loaded and made available to the test script in form of predefined variables.

The meta data file is in the Java .properties format and its name is derived from the image file (typically <imagefile>.<formatextension>.properties). The GUI allows to create the meta data file for an already existing template created with the previous version or  with a third party image editor. Since the source coordinates are however lost, the GUI in this case allows to edit and store only the click point.

Source coordinates store the original coordinates in the desktop image at the time of template creation. They are exposed to the script through the _COMPARETO_SOURCE_X and _COMPARETO_SOURCE_Y variables. These variables are not populated when the meta data file is not available or the data is not populated (templates created prior to v2.2 or with 3rd party tools).

Source coordinates allow to script actions testing whether the object has moved on the screen. A typical piece of code for this action is:

Compareto "buttonOK" method=search
if ("{_COMPARETO_SOURCE_X}" != "{_SEARCH_X}" && "{_COMPARETO_SOURCE_Y}" != "{_SEARCH_Y}") {
    # Object has moved
    ...
}

The Click Point represents the best location for an eventual mouse action such as a click, press, release or drag. The point defaults to the image center but it can be customized to point to any location inside or even outside the template image rectangle. The click point coordinates are internally stored relatively to the template image top left corner.

Usage of the click point makes sense only with the image search. When it locates the object on the screen, it recalculates the click point to absolute coordinates and stores them under the _COMPARETO_CLICK_X and _COMPARETO_CLICK_Y variables. When the meta data file doesn't exist (templates created prior to v2.2), the variables are also available and default to the image center. The following code snippet locates an object and on success clicks on its click point:

Compareto "buttonOK" method=search
if ({_EXIT_CODE} == 0) {
    Mouse click to="x:{_COMPARETO_CLICK_X},y:{_COMPARETO_CLICK_Y}"
}


4.1.3 Image Comparison Recommendations

Reliability of most image comparison methods decreases with factors which produce image differencies on the pixel level. To minimize these impacts consider the following hints:

4.2 Image Search Methods

Image Search Methods search the screen for an object (component) based on template image(s), image collection(s) or object parameters such as the size, color or shape. The method typically returns a list of locations and/or rectangles on the screen where the specified object was detected. This method group is often employed to automate actions such as "find and click a button" or "make sure that a component is visible on the screen".

The Image Search Methods supported by T-Plan Robot Enterprise 3.0.1 are:

  1. The Image Search V2 (code "search2") method searches the screen for components by template images and collections. The algorithm features three search modes (exact, tolerant and fuzzy) and ordering of results by the lowest difference or location.
  2. The Image Search (code "search") method is an older version of the V2 algorithm. It is also capable of searching the screen for components by template images and collections with a limited tolerance to minor image changes.
  3. The Object Search (code "object") method locates objects by a color, size and an optional sample template image. The algorithm is capable of searching of rotated instances of the object and provides a certain robustness against eventual object overlapping. This method is not suitable for the application GUI automation and it rather targets analysis of graphical systems such as GIS outputs, maps, charts and similar.

4.2.1 Image Search V2 ("search2")

DESCRIPTION
 Top^

The Image Search v2 (code "search2", since v3.0) searches the desktop screen for a component or an object represented by one or more template images and/or image collections. It is typically employed for verification of the desktop screen contents ("make sure that an object is visible") or to locate a component for a subsequent mouse or keyboard operation ("find and click or drag", "find and press/type", etc.).

The "search2" algorithm is a new generation of the older Image Search method ("search") one with the following improvements:
  1. Easy to use - The only parameter controlling the tolerance to minor desktop image changes is the standard "passrate" one. Its default value is set to 50% to perform out-of-the-box reliable search for most environments including those considered as difficult to automate at the desktop image level, such as for example Flash applications.
  2. Fast performance - The search operates significantly faster even for low values of the passrate parameter. Also as the algorithm avoids copying of the image pixels and works directly with the desktop buffer it consumes up to 90% less memory than the other similar methods.
  3. Result sorting - The default sorting of the results (matching locations) by the best match ensures that even if the passrate value is too low and the method produces multiple fuzzy matches, the best matching location is always reported in the first place. This allows to work with the first match (which is the most likely the correct one) and ignore the other remotely similar ones.
Coordinates of the resulting match locations are exposed to the calling script in form of a set of _SEARCH_ prefixed variables. This system is compatible with the older "search" method:

Method Created Variable Description
_SEARCH_MATCH_COUNT=<number> Number of matching locations identified by the Object Search.
_SEARCH_X_<n>=<X-coordinate>
_SEARCH_Y_<n>=<Y-coordinate>
 The X,Y coordinates of the n-th match location where "n" is
between 1 and the _SEARCH_MATCH_COUNT value.
_SEARCH_X=<X-coordinate>
_SEARCH_Y=<Y-coordinate>		 The X,Y coordinates of the first match location (synonyms for
_SEARCH_X_1 and _SEARCH_Y_1).

To get the width and height of the match location use the _COMPARETO_TEMPLATE_WIDTH and _COMPARETO_TEMPLATE_HEIGHT variables which are populated by the hosting command or Java method call.

This method is not capable of working with transparent/translucent template images and with the "search" specific parameters of "removebg", "bgcolor", "minalpha" and "tolerance". Should you need this functionality use the "search" method instead.

OPTIONS


The method requires one or more template images and/or image collections specified through the hosting command or Java method call.

In the context of the "search2" method, the parameter of "passrate" specifies the required minimum similarity between the template image and the matching location on the screen. The default value is 50% which ensures a good performance/accuracy ratio in most cases. If you experience too many matches, for example on low contrast environments , set the pass rate to a higher level. To get the maximum performance set the pass rate to 100%.

The "cmparea" parameter is optional and defaults to the full screen when omitted.

The method supports one specific parameter as follows:

sort=<best|none|top|bottom|left|right>
- Result sort mode (optional), one of:

RETURNS

The method makes the calling command (method call)  return 0 (success) if at least one matching location is found for at least one of the input template images. Otherwise it returns the value of 1.

TROUBLESHOOTING

To deal with a failing "search2" comparison:


EXAMPLES

Compareto buttonOk.png  method="search2" passrate="90" sort="bottom"

if ({_EXIT_CODE} > 0) {
  Screenshot failure.png desc="Failed to find the OK button."
  Exit 1 desc="Failed to find the OK button."
} else {
  Mouse click to=x:{_SEARCH_X},y:{_SEARCH_Y}
}

- Search for the bottommost OK button and click it. If the button is not found take an exit screen shot and terminate the script with the exit code of 1.



4.2.2 Image Search ("search")

DESCRIPTION
 Top^

The Image Search (code "search") searches the desktop screen for a component or an object represented by one or more template images and/or image collections. It is typically employed for verification of the desktop screen contents ("make sure that an object is visible") or to locate a component for a subsequent mouse or keyboard operation ("find and click or drag", "find and press/type", etc.).

The method uses a plain pixel comparison with three independent mechanisms of tolerance:
  1. Pixel based tolerance makes the algorithm search for occurrences which have a certain amount of pixels different from the template image. This is achieved through the Pass Rate "passrate" parameter which defines percentage of pixels required to match. If your template image size is for example 10x10 (100 pixels) and you specify the pass rate of 99%, the algorithm will find all matching locations having up to 1 different pixel. Note that the lower pass rate you specify, the lower the performance will be and the longer the search will take.
  2. RGB tolerance has been introduced in v2.2. It is activated by the tolerance parameter which is an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a desktop pixel may differ at a maximum to consider the color be equivalent to the corresponding template pixel. This value allows to deal with images whose pixels are changing slightly, for example as a result of blurring or merging of the image with the background. This behavior has been reported for Flash applications where decorative texts and even some images are not being rendered in a constant way as the application refreshes. Be aware that the higher the tolerance value, the higher the probability of false match detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm compares pixels using exact color match.
  3. Transparency/translucency based tolerance allows to ignore certain pixels of the template image. The image search algorithm by default counts as "passed" all transparent or translucent (partially transparent) pixels having the translucency component Alpha lower than the limit specified by the Minimum Alpha parameter (minalpha). For example, if a template with 100 pixels contains 90 transparent pixels and the minimum alpha is set to 0xFF (forcing to search for fully opaque pixels only), only the remaining 10 non-transparent pixels will be compared against the desktop image.

    Transparency is a powerful method allowing to build image comparison which is robust against background or component color changes. When you for example search for an icon rendered on your remote desktop, marking the background color pixels transparent in the icon template will make sure that the image comparison passes regardless of the remote desktop color changes. The template image may be further on doctored with common image editors to remove insignificant pixels and leave just a skeleton of the searched object. This is often the only possible way to test certain types of applications with unstable object rendering, such as for example Geographic Information Systems (GIS).
T-Plan Robot Enterprise version 2.1 and higher supports automatic background transparency through the removebg and bgcolor parameters. It allows to ignore the template image background without having to edit the image with a third party editor. The algorithm accepts an opaque template image on the input (meaning an image with no transparency) and applies an internal transparency filter to remove all pixels equal to or reasonably similar to the background. The background color defaults to the first template image pixel but it may be also specified explicitly through the bgcolor parameter. Automatic transparency may be comfortably configured through the GUI, in particular with the Template Image Editor and the comparison GUI component described in the CompareTo window.

Transparency may be also introduced into template images using third party image editors. For example, Windows and Linux/Unix users may take advantage of Gimp to set up transparency as follows:
  1. Open the template image with Gimp
  2. Select Layer->Transparency->Color To Alpha
  3. Select the transparent color. It usually works fine if you leave it on the defaults provided by Gimp (white background color).
  4. Save the template image to the file.
  5. Retest with the Template Image Editor. This is necessary because if the image contains just colors which are very close to the background color, Gimp may turn all pixels transparent or translucent which will make the template unusable for image search with the default minalpha value. The Template Image Editor is able to detect such cases and suggest changes to the image search parameters.
Coordinates of the resulting match locations are exposed to the calling script in form of a set of _SEARCH_ prefixed variables:

Method Created Variable Description
_SEARCH_MATCH_COUNT=<number> Number of matching locations identified by the Object Search.
_SEARCH_X_<n>=<X-coordinate>
_SEARCH_Y_<n>=<Y-coordinate>
 The X,Y coordinates of the n-th match location where "n" is
between 1 and the _SEARCH_MATCH_COUNT value.
_SEARCH_X=<X-coordinate>
_SEARCH_Y=<Y-coordinate>		 The X,Y coordinates of the first match location (synonyms for
_SEARCH_X_1 and _SEARCH_Y_1).

To get the width and height of the match location use the _COMPARETO_TEMPLATE_WIDTH and _COMPARETO_TEMPLATE_HEIGHT variables which are populated by the hosting command or Java method call.

Note that the number of match locations is limited by a parameter in the Compareto command preferences and the search will stop when the maximum gets reached.

OPTIONS


The method requires one or more template images and/or image collections specified through the hosting command or Java method call. The parameter of "passrate" specifies in the context of the "search" method the minimum ratio of pixels that must match exactly between the template image and the screen match location. The default value is 100% (no pixel diff tolerated). The "cmparea" parameter is optional and defaults to the full screen when omitted.

Supported specific parameters:

tolerance=<0-255>
- The tolerance parameter controls the RGB tolerance to minor color changes. It must be an integer number between 0 and 255 where 0 stands for no tolerance (exact matching) and 255 meand maximum tolerance. It indicates how much the Red, Green and Blue components of a desktop pixel may differ at a maximum to consider the color be equivalent to the corresponding template pixel. High tolerance values increas probability of false match detections.

This parameter allows to deal with images whose pixels are changing slightly, for example as a result of blurring or merging of the image with the background. This behavior has been reported for Flash applications where decorative texts and even some images are not being rendered in a constant way over the time. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm compares pixels using the exact color match.
removebg=<true|false>
The removebg parameter switches the automatic background transparency on ("true") or off ("false"). The value of "true" applies automatic transparency to ignore the template image background color. If the template image (or template images) already contain transparent or translucent pixels, the background filter is not applied and this parameter as well as the bgcolor one are ignored. The default value is "false" (background filter is off).

bgcolor=<HTMLColor>
The bgcolor parameter is optional and it may define custom background color for the automatic background transparency mode activated through the removebg parameter. It accepts RGB in the HTML-like notation, such as for example "ffffff" for white or "000000" for black. The value must be 6 characters long where each of the R, G, B components are specified in form of 2-digit hexa decimal number (00 to ff). When the bgcolor is not specified the method selects the background color from the very first template image pixel (top left image corner).

minalpha
The minalpha parameter sets the translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing transparent or translucent pixels. The default value of 255 instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Values lower than 255 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit.

The minimum alpha parameter is intended to solve situations where the background color filter makes too many pixels or even all of them transparent or translucent. This leaves the search algorithm comparing just against a small number of opaque pixels which usually leads to unexpected match results. As lowering the alpha limit increases number of comparable pixels, it may be used to improve accuracy of the image search algorithm. Be however aware that comparison of translucent pixels is based on color similarity, it has significalntly slower performance than the classic image search and extremely low values of minimum alpha may produce unexpected match results.

RETURNS

The method makes the calling command (method call) return 0 (success) if at least one matching location is found for at least one of the input template images. Otherwise it returns the value of 1.

TROUBLESHOOTING

To deal with a failing "search" comparison:


EXAMPLES

Compareto buttonOk.png  method="search" tolerance="50"

if ({_EXIT_CODE} > 0) {
  Screenshot failure.png desc="Failed to find the OK button."
  Exit 1 desc="Failed to find the OK button."
} else {
  Mouse click to=x:{_SEARCH_X},y:{_SEARCH_Y}
}

- Search for the OK button and click it. If the button is not found take an exit screen shot and terminate the script with the exit code of 1.


4.2.3 Object Search ("object")

DESCRIPTION
 Top^

The Object Search (code "object") locates objects of a particular color or colors within a certain RGB range. It also allows to filter the object list by an optional template image with detection of eventual object rotation. The method was designed to handle simple image analysis tasks such as "find all red objects on the screen" or "find all black triangles in any level of rotation on the screen".

As the method always locates the largest possible object and it doesn't search recursively for any other ones it may contain, this approach is not suitable for classic GUI components which are often framed, overlayed and merged together. The method however performs very well in testing of schemes, maps and images with low color scenes generated for example by Geographic Information System (GIS) applications or systems producing simple image data. The method can be also employed to check whether an object of a certain color or color range is present on the screen, for example to answer a question like "is there any red message in this particular area?".

The algorithm first scans the image for the first pixel which meets the input color criteria. Then it follows the outer shape of each such an object and stores its bounding rectangle into the context in form of a set of variables:

Method Created Variable Description
_OBJECT_COUNT=<number> Number of objects identified by the Object Search.
_OBJECT_X_<n>=<X-coordinate>
_OBJECT_Y_<n>=<Y-coordinate>
_OBJECT_W_<n>=<width>
_OBJECT_H_<n>=<height>
 The X,Y coordinates and the Width and Height
of the n-th object where "n" is between 1 and the
_OBJECT_COUNT value.

The original shapes (java.awt.Shape instances) that describe the objects more accurately are available just to Java test scripts through the getContext().getObjectSearchShapes() method.

OPTIONS


The method optionally accepts one template image specified through the hosting command or Java method call.

The passrate parameter plays a role only when the "object" method is called with a template image. The image must contain exactly one shape of the specified color (color range) in any level of rotation. The list of objects identified by the the input "color" parameter will be then filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the passrate parameter. If the rotations parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times. If the template image is not specified the method locates all objects matching the specified color and size parameters regardless of the passrate value.

The standard parameter of "cmparea" is optional and defaults to the full screen when omitted.

Supported specific parameters:

color=<HTMLColor>
The color parameter defines the object color in the HTML-style 6-character RGB hexadecimal format (white is '000000', black is 'ffffff'). If the parameter is not specified it defaults to black.

tolerance=<0-255>
The tolerance parameter is an optional integer number between 0 and 255. It is similar to the RGB Tolerance one in the Image Search method. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the color parameter. This parameter effectively allows to specify the that the object color may be in a color range rather than a single color.  It also helps deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. The higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

bridgecolors=<HTMLColor1;HTMLColor2;...HTMLColorN>
The bridgecolors parameter is optional and it may contain a semicolon separated list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. These colors are always compared using the exact match and they do not work with the tolerance parameter.

rotations=<1-360>
The optional rotations parameter makes only sense when a template image is provided. It defines rotation granularity. It basically says how many times to rotate the template object for object filtering purposes. For example, the value of 36 will rotate the shape in 10 degree steps. Obviously, a high number of rotations increases accuracy of recognition of rotated objects but decreases performance. Low rotation values may be compensated through lowering the passrate parameter. This approach is somewhat better in terms of performance but raises the risk of wrong detection of objects similar enough to the template one.

min=w:<width>;h:<height>
Optional minimum size (width and/or height) to filter the resulting objects by. The parameter can specify both the width and height separated by a semicolon (for example "w:100;h:100") or just one of the dimensions ("h:100").

max=w:<width>;h:<height>
Optional maximum size (width and/or height) to filter the resulting objects by. The parameter can specify both the width and height separated by a semicolon (for example "w:100;h:100") or just one of the dimensions ("h:100").

overlapmode=<true|false>
The optional overlapmode flag defines whether the objects on the screen may overlap (conflict). If the parameter value is "true" the method makes an extra effort to look for partially overlapped objects.

draw=<true|false>
The draw parameter is an optional flag which enables highlighting of the located objects on the Robot's desktop view. When the parameter is "true" the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component. This is useful for debugging and demonstration purposes. These drawings are reset (removed) when the script finishes or another Object Search with the parameter of "clear=true" is executed.

clear=<true|false>
The clear parameter allows to clear up all drawings created by the previously called Object Search methods. See the draw parameter for details.

RETURNS

The method makes the calling command (method call) return 0 (success) if at least one object meeting the specified criteria is found. Otherwise it returns the value of 1.

TROUBLESHOOTING

To deal with a failing "object" comparison:


4.3 Text Recognition Methods


4.3.1 Tesseract OCR ("tocr")

DESCRIPTION
 Top^

The Tesseract OCR method (code "tocr") allows to call the external Tesseract OCR engine version 2 or higher to extract text from the remote desktop image. Prior to using this method the user has to install and configure Tesseract on the client system (meaning the system running T-Plan Robot) as is described in the TesseractOCR class documentation.

The integration is based on the Tesseract command line interface (CLI) and the local file system. When executed the method extracts the desktop image or its rectangular part specified through the cmparea parameter. The image is magnified (scaled up) for better accuracy and saved in the 8-bit black & white format to a file in the system temporary path. The method then starts Tesseract through the CLI with the image file as an argument. The engine performes OCR and stores the recognized text into a text file in the temporary path which is then parsed by the method and eventually tested against the text (plain text search), text and distance (tolerant text search) or pattern (regular expression matching) parameters.

The regular expression matching matches the recognized text against the specified java.util.regex.Pattern compliant regular expression. The expression must match the whole text and no searching for a matching substring is performed.

The tolerant (fuzzy) text search is based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is enabled through the "distance" parameter which is an integer number specifying how many characters may be omited or not recognized properly at a maximum to consider the sample text provided in the "text" parameter equivalent. Unlike the regular expressions the tolerant matching always searches the recognized text for any occurence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text.

The method stores the OCR results into a set of _TOCR_ prefixed variables as follows:

Method Created Variable Description
_TOCR_ERROR=<errorText>
 Contains the error text thrown when Tesseract is not installed
or misconfigured. See the Troubleshooting paragraph for more.
_TOCR_TEXT=<text> The recognized text (all lines).
_TOCR_LINE_COUNT=<number> Number of recognized text lines (rows).
_TOCR_LINE<n>=<lineText> Text of the n-th line where <n> is between 1 and _TOCR_LINE_COUNT.
_TOCR_MATCH=<matchingString>
 A fragment of the recognized text that caused the tolerant text search
specified through the text and distance parameters succeed.
_TOCR_MATCH_INDEX=<index>
 Index of the matching text specified through text in the whole recognized
text. Indexing starts with 0 which indicates beginning of the recognized text.

OPTIONS
The method accepts no template images. The parameter of "passrate" is not applicable in the context of Tesseract OCR and it is ignored. The parameter of "cmparea" is optional and defaults to the full screen when omitted.

Supported specific parameters:

language=<3-charLanguageCode>
The language parameter be a valid 3-character language code of a properly installed Tesseract language data file. If the parameter is omitted it defaults to "eng" (English).

scale=<scaleFactor>
The scale parameter defines how many times the desktop image will be magnified before it is passed to Tesseract. Scaling may have an impact on accuracy. See the Troubleshooting paragraph for more.

The scale value can be any float number such as 1.5, 2 or 3. High scale values significantly increase memory requirements and may cause Robot to run out of memory (OutOfMemoryError). The default scale factor is 2.

text=<textToSearchFor>
Optional text to search the recognized text for. The hosting command will then return either 0 when the OCR was performed correctly and the recognized text contains the given string or 1 otherwise. This parameter can not be used together with the pattern one.

distance=<0-[textLength]>
Optional Levenshtein distance used in conjunction with the "text" parameter to perform tolerant text matching. See the method specification for details.

pattern=<regularExpression>
Optional java.util.regex.Pattern compliant regular expression to test the recognized text against. The expression must match the whole text (no searching for a matching substring is performed). This parameter can not be used together with the text one.

RETURNS

The method makes the hosting command return 1 when the OCR throws an error caused by misconfiguration or an I/O error. This applies to situations when the Tesseract is not installed at all,or the configured command template doesn't point to the Tesseract binary or when the optional language parameter specified by the calling script doesn't match a properly installed Tesseract language data file. Text of the error is made available through the _TOCR_ERROR variable. Testing of existence of this variable is a way to detect core OCR errors in test scripts.

The return code otherwise depends on the input parameters. If the method is called to perform just OCR with no result testing it always returns 0 even if no text was recognized. If the method is called with the parameters of "text" or "pattern" it returns 0 if the recognized text matches the given string/regular expression or 1 otherwise.

TROUBLESHOOTING

To test whether the Tesseract OCR is correctly installed and configured simply run a "tocr" recognition through the "Compare" button. It will display any error thrown by Tesseract. The most common errors are:
As Tesseract's recognition capabilities are limited to most common fonts and languages T-Plan doesn't guarantee any accuracy and/or compatibility with a particular test environment. The Tesseract engine can be eventually "trained" for the particular font or language settings. The steps are described in Tesseract's documentation.

The accuracy can be controled on the Robot side only through two parameters:
  1. Limiting the recognition to a particular screen area through the cmparea parameter significantly improves the accuracy. When the recognition is performed on the whole desktop screen, it seems to distract the engine which often finds text even where there's not any. This leads to unexpected results with many errors.
  2. As the engine seems to have problems recognizing a standalone string consisting of 1-2 characters, use it for longer texts only (3+ characters).
  3. Higher values of the "scope" parameter such as 2.5 or 3 may slightly improve the accuracy, for example when the font is very small.

EXAMPLES

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}}"
}
- Recognize text in the specified desktop area and type 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
}
- Exit the script when the recognized text doesn't match the 'Application' or 'application' word.


Compareto method="tocr" cmparea="x:33,y:2,w:200,h:22" pattern=".*[aA]pplication.*"
if ({_EXIT_CODE} > 0) {
  Exit 1
}
- The previous example modified to exit the script when the recognized text doesn't contain 'Application' or 'application'.


Compareto method="tocr" cmparea="x:33,y:2,w:200,h:22" text="apple" distance="2"

- Recognize text on the screen and verifies whether it is like and/or it contains a string like 'apple':

When the text is matched, the index of the match location in the text is stored to the _TOCR_MATCH_INDEX variable. The index starts from 0 which represents the text beginning. The matching substring is further on saved under the _TOCR_MATCH variable. For example, the example above with the recognized text of 'There are Appls' will create the variables as _TOCR_MATCH=Appls and _TOCR_MATCH_INDEX=10.


4.3.2 Image Based Text Recognition ("text")

DESCRIPTION
 Top^
The Image Based Text Recognition (code "text", since v3.0) allows to recognize text and its coordinates on the screen based on a collection of presaved characters. Compared to OCR:
Character image collections can be comfortably created and maintained in the Character Capture Wizard. See its help page for details.

Similar to the "tocr" method, the recognized text can ve verified in three ways:
  1. The "text" parameter alone activates plain text search for the specified string and makes the calling command return 0 (success) when found and 1 (fail) when not found.
  2. A combination of the "text" and "distance" parameters performs tolerant (fuzzy) text search. The "distance" parameter is the Levenshtein distance which is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is enabled through the "distance" parameter which is an integer number specifying how many characters may be omited or not recognized properly at a maximum to consider the sample text provided in the "text" parameter equivalent. Unlike the regular expressions the tolerant matching always searches the recognized text for any occurence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text.
  3. The regular expression matching matches the recognized text against the specified java.util.regex.Pattern compliant regular expression. The expression must match the whole text and no searching for a matching substring is performed.
The method stores the OCR results into a set of _TEXT prefixed variables as follows:

Variable Name Description
_TEXT_ERR=<error_text> Error message. It gets populated only if the method fails to perform text
recognition, for example when there is no desktop connection or when
the specified character image collection doesn't exist or can not be read.
_TEXT=<text>
 The recognized text (full multiline format). The variable is created always
when the method gets executed successfully (meaning that it doesn't fail
for a missing desktop connection or invalid character image collection).
_TEXT_X=<number>
_TEXT_Y=<number>
_TEXT_WIDTH=<number>
_TEXT_HEIGHT=<number>
 The X, Y coordinates and the width and height of the recognized text.
_TEXT_LINE_COUNT=<number> Number of recognized text lines.
_TEXT_LINE<n>=<text> The n-th text line where <n> is the line number between 1 and
_TEXT_LINE_COUNT.
_TEXT_LINE_X_<n>=<number>
_TEXT_LINE_Y_<n>=<number>
_TEXT_LINE_WIDTH_<n>=<number>
_TEXT_LINE_HEIGHT_<n>=<number>
 The X, Y coordinates and the width and height of the n-th text line
where <n> is the line number between 1 and _TEXT_LINE_COUNT.
_TEXT_MATCH=<text>
 The part of recognized text that matches the "text" parameter (plain text
search) or a combination of "text" and "distance" (tolerant text search).
_TEXT_MATCH_INDEX=<number>
 Position (index) of the matching text referred to by _TEXT_MATCH. Indexing
starts from 0 which corresponds to the beginning of the recognized text.
_TEXT_MATCH_X=<number>
_TEXT_MATCH_Y=<number>
_TEXT_MATCH_WIDTH=<number>
_TEXT_MATCH_HEIGHT=<number>		 The X, Y coordinates and the width and height of the matching text
referred to by the _TEXT_MATCH variable.


OPTIONS

The method requires one character image collection on the input. The "passrate" parameter in the context of the "text" method defines tolerance to minor differences in rendering of the characters. As this tolerance is currently experimental and works only for a few larger fonts. it is recommended to keep the pass rate at 100%.

The "cmparea" standard parameter can be used to limit the text recognition to a particular rectangular area of the screen. It defaults to the full screen if not specified.

Supported specific parameters:

text=<textToSearchFor>
Optional text to search the recognized text for. The hosting command will then return either 0 when the recognition was performed correctly and the recognized text contains the given string or 1 otherwise. This parameter can not be used together with the pattern one.

distance=<0-[textLength]>
Optional Levenshtein distance used in conjunction with the "text" parameter to perform tolerant text matching. See the method specification for details.

pattern=<regularExpression>
Optional java.util.regex.Pattern compliant regular expression to test the recognized text against. The expression must match the whole text (no searching for a matching substring is performed). This parameter can not be used together with the text one.

RETURNS

When none of the "text", "distance" and "pattern" parameters is used the calling command returns 0 (success) to indicate a successful execution even when no text gets actually recognized. If the text matching parameters are used the calling command will return either success (0) or fail (non-zero value) depending on whether the recognized text matches or not.

TROUBLESHOOTING

To deal with a failing "text" comparison:

EXAMPLES

Var _TEXT_LINE_COUNT=0
Compareto "C:\MyAutomation\chars"   method="text" cmparea="x:33,y:2,w:200,h:22"
for (i=1; {i}<{_TEXT_LINE_COUNT}+1; i={i}+1) {
   Typeline "{_TEXT_LINE{i}}"
}
- Recognize text in the specified desktop area and type it onto the desktop.


Compareto "C:\MyAutomation\chars"   method="text" cmparea="x:33,y:2,w:200,h:22" pattern="[aA]pplication"
if ({_EXIT_CODE} > 0) {
  Exit 1
}
- Exit the script when the recognized text doesn't match the 'Application' or 'application' word.

Compareto "C:\MyAutomation\chars"   method="text" cmparea="x:33,y:2,w:200,h:22" pattern=".*[aA]pplication.*"
if ({_EXIT_CODE} > 0) {
  Exit 1
}
- The previous example modified to exit the script when the recognized text doesn't contain 'Application' or 'application'.

Compareto "C:\MyAutomation\chars"   method="text" cmparea="x:33,y:2,w:200,h:22" text="apple" distance="2"

- Recognize text on the screen and verifies whether it is like and/or it contains a string like 'apple':

When the text is successfully matched, the index of the match location in the text is stored to the _TEXT_MATCH_INDEX variable and its X, Y coordinates and width/height to _TEXT_MATCH_X, _TEXT_MATCH_Y, _TEXT_MATCH_WIDTH and _TEXT_MATCH_HEIGHT. The matching substring is further on saved under the _TOCR_TEXT variable. For example, the example above with the recognized text of 'There are Appls' will create the variables as _TEXT_MATCH=Appls and _TEXT_MATCH_INDEX=10.

4.4 Other Methods

4.4.1 Histogram Based Comparison ("default")

DESCRIPTION
 Top^
The Histogram Based Comparison Method (code "default") was historically the first method provided by T-Plan Robot in 2005. It was designed for a quick check of the desktop screen against one or more full screen template image(s). Though it has been obsoleted by better verification means such as the "search2" and "search" methods it may be still used in special cases.

The method is based on a simple histogram comparison. An image histogram is in simple words a list of colors located in the image together with number of pixels of each color. The method first calculates histograms both of the remote desktop and template images and compares them. Result of the image comparison is then calculated as a number of matching pixels divided by the total number of image pixels.

The following example illustrates how the method works. Let us have two simple 120x100 images (12000 pixels each):



Image 1
120x100





Image 2
120x100
Color Image 1
 Image 2 Matching Pixels
White
 9000px
 6000px
 6000px
Red 3000px
 6000px
 3000px
Sum of matching pixels:
 9000px
The comparison result is in this case 9000px/12000px, which is 0.75, or better 75%. This corresponds to what a human would say when comparing the images visually - they are different just in one quarter.

Though this is a very primitive algorithm it is sufficient where you need to verify whether the desktop displays correct application provided that the application and desktop background colors differ. The algorithm is also quite robust in terms of window location changes which don't affect the full screen color histogram.

Be aware that the default method is designed to compare two images of the same size. If your template image has different size than the remote desktop, both images will be internally cropped to the size of their intersection. As this may lead to unpredictable results it is not recommended to use the default method together with a custom comparison area (the "cmparea" parameter).

OPTIONS

The method requires one or more template images and/or image collections specified through the hosting command or Java method call. The parameter of "passrate" defines in the context of the "default" method the lowest acceptable result of comparison of the template image and the screen histograms (see the example in the method description). It defaults to 95%. The "cmparea" is optional and defaults to the full screen when omitted.

No other method-specific parameters are supported.

RETURNS
The method makes the calling command (method call)  return 0 (success) if the produced comparison result is greater than or equal to the specified pass rate. Otherwise it returns the value of 1.

TROUBLESHOOTING
As the "default" method does not use any method-specific parameters, the only means of dealing with a failing histogram comparison is decreasing of the "passrate" parameter. To see the actual comparison result after a histogram comparison look for the _COMPARE_RESULT variable in the variable viewer.

Besides the general Image Comparison Recommendations consider the following reliability factors:


EXAMPLES

Compareto netscape1.png;netscape1.png  method="default" passrate="90"

if ({_EXIT_CODE} > 0) {
  Exit 1
}

- - Compare the desktop screen to the netscape1.png and netscape1.png images with the pass rate of 90% and terminate the script with the exit code of 1 if neither of them matches the screen.