![]() |
T-Plan Robot Enterprise
3.0.1 Doc
Collection |
20/07/12 |
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.
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:
# This is a
comment
// This is also a comment
goto
command supported by
other programming languages). See the --fromlabel
and --tolabel
T-Plan Robot Enterprise
CLI
options for more label info.identificator=value
' or 'identificator="value with
spaces"
' are considered to be one single token and they are
further parsed into identificator/value pairs. This is a text containing spaces
This
',
'is
', 'a
', 'text
', 'containing
',
'spaces
'.This "is a text" containing
spaces
This
',
'is
a
text
', 'containing
',
'spaces
'.This text contains "double quote (\")"
This
',
'text
', 'contains
', 'double quote (")
'Var SAMPLE_VAR_1="value with spaces" SAMPLE_VAR_2=no_spaces
"NO_VAR=not_a_variable"
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.
wait
/timeout
/delay
parameters of other commands support the following syntax:"1"
is parsed as 1 milisecond,"1s"
is 1 second,"1m"
is 1 minute,"1h"
is 1 hour,"1d"
is one day.'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. Wait
"1.5d"
Press
Ctrl+C wait=5s
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}"
_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}}
}
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). 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}"
-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. procedure
<procedure_name> {
command1
command2
...
commandN
}
procedure
"Perform action A" {
...
}
...
"
Perform action A"
'{'
must be on the same line
as the
procedure header. '}'
must be alone on a single line. <procedure_name>
parameter1
"parameter2 with spaces" .... parameterN
# 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
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
}
take_screenshot image3 tiff
DisconnectFallback
will be
called when connection to the VNC server crashes either in the init
phase (inside the Connect command) or any time
later on, for example when the server is terminated (killed) or a
network error is experienced. A call of the Disconnect
command will not start
the
procedure because it is an expected connection termination. If a
Connect is called in the fallback procedure body, it will not call the
procedure again on failure to prevent infinite connection looping. If
the connection crash is detected in the normal operation phase during
script execution, the procedure gets called right after the currently
executing command finishes. Be aware that the procedure may not be used
in such a case for a safe recovery (meaning reconnection and resuming
of the script) because the scope of data transferred to the server
correctly is not known. This is a problem when the crash happens for
example in the middle of text typing where it is not possible to
determine how many characters were typed successfully before the
connection failure.ComparisonFailureFallback
gets executed every time a CompareTo or Waitfor match/mismatch fails and no explicit
fail action is specified through the onfail
or ontimeout
parameter. The first procedure argument which may be retrieved inside
the procedure body as "{1}" will always contain the numeric exit code
of the calling comparison command. This is typically "1" when the
object is not found or "2" when one or more of the template images are
not found or can not be read.
procedure
DisconnectFallback {
Exit
3
}
procedure ComparisonFailureFallback {
Screenshot
comparison_failure.png
Exit
{1}
}
// Script body
Connect
localhost:1 password=welcome
Compareto
button.png
method=search
// ...
'1.25'
.'5s'
(five seconds) are not
accepted except the cases where the time modifier is at the very end of
the expression. Examples: Wait
5+5s
Wait 5s+5s
'('
and ')'
'+'
'-'
'-'
(negative numbers)'*'
'/'
# 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"
'
Eval
HOUR_IN_MS=1*60*60*1000
'.
if/else
and for
. The following operators are supported:
'('
and ')'
'>'
and lower than '<'
.
These
two
operators
require
numeric
arguments.'=='
and not equal to '!='
.
Arguments are first converted to numbers and compared. If at least one
of the argument is not a number, a plain string comparison is
performed.
Examples:'yes == no'
will be false'yes != no'
will be true'1.0 == 1'
will be true because both
arguments can be converted to a number and the numeric values are equal.'&&'
and '||'
-
logical "and" and "or". These operators require boolean arguments, i.e.
other expressions. Example:'1 > 0 || yes != no'
will be true
because one of the two expressions is true'1 > 0 && yes != no'
will
be
false because one expression is false'exists <variableName>'
tests
existence of a variable. Example:'exists _REPORT_FILE'
will be true if
the script creates a report through the Report command'contains'
tests whether the first string
argument contains the other one (case sensitive). Example:'"{_MACHINE}" contains "sourceforge"'
will
be
true
if
the
connected
VNC
server
name
contains
'sourceforge'
'startswith'
tests whether the first
string argument starts with the other one (case sensitive). Example:'"{_DISPLAY}" startswith "localhost"'
will
be
true
if
the
connected
VNC
desktop
name
starts
with
'localhost',
for
example
'localhost:1'.'endswith'
tests whether the first string
argument ends with the other one (case sensitive). Example:'"{_DISPLAY}" endswith ":3"'
will be
true if the connected VNC server runs on port 5903 (which is typically
indicated by the ':3' display number in the desktop name).'matches'
compares the first string
argument to a java.util.regex.Pattern
compliant regular expression. Example:'"{_DATE}" matches "201008[12][1-5]"'
will be true
if the current date is between 11 and 15 or between 21 and 25 August
2010 .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
}
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>
}
'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. # 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.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. for
statement executes as long as
the specified boolean expression results true: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 Valuesfor
<variable name> in
<list of space separated values> {
<commands>
}
Type
"I speak "
for language in English Spanish "Brazilian Portuguese" {
if ("{language}" == "Brazilian
Portuguese") {
Type
"{language}."
} else {
Type
"{language}, "
}
}
Type
"I speak "
Var VALUES=
"English Spanish \"Brazilian Portuguese\""
for language in {VALUES} {
if ("{language}" == "Brazilian
Portuguese") {
Type
"{language}."
} else {
Type
"{language}, "
}
}
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"
}
_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.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"
}
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."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. java
{
<import clauses>
<Java code>
} endjava
Java Code Block |
Resulting Java Test
Script Class |
|
java { |
|
import com.tplan.robot.scripting.*; |
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.4 I/O Commands
DESCRIPTION |
Next | Previous | Top^ |
DisconnectFallback
fallback
procedure for information on how to set up a central point of
failure for server connections.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):
As T-Plan
Robot provides an interface allowing to plug in other clients, there
might be more protocols supported by additional plugins.
If port is not
explicitly specified, it defaults to the protocol-specific well known port.
For example, RFB/VNC server runs by default on port 5900, Java RMI
starts by on port 1099 and RDP (Windows Terminal Services)
default to 3389. If you want to connect to a VNC running on Linux/Unix,
you typically have to specify the port of 5901 or higher because the
default RFB port is occupied by the X-Windows server.
If protocol is omitted in the URL, the
script defaults to the RFB (VNC) protocol to provide backward compatibility with VNCRobot 1.x.
The
port
number
is
in
this
case
treated
as
the
display
number which is equal to the port number minus 5900.
Direct port can be in this mode specified through double colon. For
example both "localhost:1"
and "localhost::5901"
refer to the same local VNC server running on port 5901. The same
address in the standard URL form is "rfb://localhost:5901"
.
password=<password>
onpass=<command>
onfail=<command>
params=<param_name_and_value_pairs>
paramseparator
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.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>
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.
DESCRIPTION |
Next | Previous | Top^ |
RETURNS
The command returns 0 (zero) on success or 1 when it fails to
disconnect.
EXAMPLES
Disconnect
- Disconnect from
the currently connected desktop.
DESCRIPTION |
Next | Previous | Top^ |
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
event_id
move"
,
a
mouse
pointer
move
from
the
optional
destination
to
the
target
point,"click"
, one or more clicks at the target point
using the specified mouse button,"press"
, a mouse button press (without release),"release"
, a mouse button release (logically
requires a preceding press
event),"drag"
, mouse drag from the optional destination
to the target point using the specified mouse button,"swipe"
, a mouse drag with adjusted timing for
devices with a touch display (such as Android devices),"wheelup"
, one or more mouse wheel rotation steps
upwards (wheel rotating away from user), "wheeldown"
, one or more mouse wheel rotation
steps downwards (wheel rotating towards user). btn
- This
parameter is used to identify
the mouse button to click, press, release or drag with. Allowed values
are "left"
, "middle"
and "right"
.
modifiers
to=[x:<x>][,y:<y>]
move"
they
define where to move the mouse pointer (target point)."click"
, "press"
, "release"
, "wheelup"
or "wheeldown"
the mouse pointer
will be first moved to this location and then the associated action is
performed. "drag"
or "swipe"
the mouse pointer will be
dragged from its actual position (or from the position specified by the
from
option) to this target location. The coordinates
have format of 'x:<x>,y:<y>
', where each
coordinate can be specified in pixels (e.g. 'x:225
') or as
a percentage (e.g. 'x:23%'
). If x or y is omitted, the
current mouse pointer location will be used to determine the missing
coordinate.
from=[x:<x>][,y:<y>]
drag"
or "swipe"
the
mouse
pointer
will
be
dragged
from
this
position
to
the
coordinates
specified
by
the to option. "click"
, "press"
, "release"
, "wheelup"
or "wheeldown"
, this parameter will be ignored. 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
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
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
DESCRIPTION |
Next | Previous | Top^ |
SYNOPSIS
press [<modifier_1>+...+<modifier_N>+]<key | modifier> [location=<standard|numpad|left|right>]
[release=<true|false>]
[count=<number>]
[wait=<time>]
OPTIONS
key
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 ',' ).
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.
DESCRIPTION |
Next | Previous | Top^ |
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.
DESCRIPTION |
Top^ |
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.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.
DESCRIPTION |
Next | Previous | Top^ |
_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. |
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. |
Fallback
fallback procedure.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>
onfail=<command>
method=<comparison_method>
methodparams=<custom_params>
cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]
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
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}}
}
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}}"
}
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"
Compareto circle.png
method="object"
color="00FF00"
tolerance="100"
passrate="80%"
draw="true"
rotations="30"
DESCRIPTION |
Next | Previous | Top^ |
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"
DESCRIPTION |
Next | Previous
| Top^ |
'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.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"
'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.list.bat
file:@echo off
dir %1 > %1\dir.txt
Exec
"\"{_SCRIPT_DIR}\list.bat\" \"C:\Program Files\" "
_EXEC_
prefixed variables
as follows:OPTIONS
command
- The OS command to be executed on the local system. See the command description for OS specific details.
count=<number>
onpass=<command>
if/else
construction
based
on the Exec
command return value. onfail=<command>
if/else
construction
based
on the Exec
command return value.outfile=<file_name>
outfile="{_SCRIPT_DIR}\out.txt"
.wait=<time>
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
}
}
DESCRIPTION |
Next | Previous | Top^ |
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.
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. 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.procedure
value exits from the innermost procedure.
If
no procedure is executed, the Exit command is ignored.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>
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.
DESCRIPTION |
Next | Previous | Top^ |
'-v'
CLI option.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}
'-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.
DESCRIPTION |
Next | Previous | Top^ |
'Exit 1'
), some test suites may
prefer to send an
E-mail to the responsible person, pause the execution and wait for
human
help.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.
DESCRIPTION |
Next | Previous | Top^ |
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.<java-home>\lib\ext
(Windows) or <java-home>/lib/ext
(Linux/Unix) of
the Java installation used to execute Robot. This will make the code
available to any instance of Java started from this installation (and
thus to all Robot instances as well).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.OPTIONS
file
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.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.
DESCRIPTION |
Next | Previous | Top^ |
_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. |
String
indexof "<text>"
string=<text> [start=<index>] [end=<index>]
[var=<variable_name>]
* Red color indicates obligatory
parameters
OPTIONS
text
string
start
end
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.
OPTIONS
var
- Optional name of
the variable to store the resulting text length to. If this parameter
is not specified the result will be stored to the default _STRING
variable.
RETURNS
The 'String length'
command always returns 0 (zero) and stores the argument text length
(number of characters) to the _STRING variable or a custom variable
specified by the 'var'
parameter.
EXAMPLES
String length "Demo text"
var=
len
- Stores the length
of "Demo text" (9) into the "len" variable.
OPTIONS
pattern
- A java.util.regex.Pattern compliant regular expression. The regular expression of "." matches by default any character except for the line terminator. This behavior may be changed through the command preferences.
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
}
}
OPTIONS
replacement
string
pattern
- A java.util.regex.Pattern compliant regular expression representing the strings to be replaced. The regular expression of "." matches by default any character except for the line terminator. This behavior may be changed through the command preferences.
var
- Optional name of
the variable to store the resulting new text to. If this parameter
is not specified the result will be stored to the default _STRING
variable.
RETURNS
The 'String replace' command
returns
0
(zero)
if
at
least
one
replacement
has
been
performed
or
1
when
no
replacement
has
been
done
and
the
resulting
text
equals
to
the
original
one.
The
new
text
is
stored
to
the _STRING variable or a custom variable specified by the
'var' parameter regardles of
whether it has been changed or not.
EXAMPLES
String replace "bad fat
cat"
string=
"b" replacement
=
"s"
String replace
"bad fat cat"
pattern=
"[bf]a[td]" replacement
=
"cat"
OPTIONS
string
pattern
- A java.util.regex.Pattern compliant regular expression to split by. The regular expression of "." matches by default any character except for the line terminator. This behavior may be changed through the command preferences.
var
- Optional base
name of
the variables to store the resulting strings to. If this parameter
is not specified the result will be stored to the default numbered
_STRING<number>
variables.
RETURNS
The 'String split' command
always
returns
0
(zero).
Each
parsed
value
is
saved
to
a
numbered
variable
such
as
_STRING1,
_STRING2
etc.
or
to
similarly
numbered
set
of
variables
derived
from
name
specified
by
the
'var'
parameter. Number of values is then stored to the _STRING_COUNT
variable.
EXAMPLES
String split
"bad fat cat"
string=
" " var
=
"s"
String
split
"bad, fat cat"
pattern=
"[,]* "
//
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
}
}
OPTIONS
start
end
var
- Optional base
name of
the variables to store the resulting substring to. If this parameter
is not specified the result will be stored to the default _STRING
variable.
RETURNS
The 'String substring' command
returns
0
(zero)
when
the
start
and
end
indices
refer
to
valid
positions
in
the
text.
If
the
start
position
is
invalid
(meaning
it
is
less
than
zero
or
equal
to
or
larger
than the text length), the command
sets the start index to 0 and returns 1. Otherwise if the end position
is invalid (meaning it is less than the start position or larger than
the text length), the command sets the end index to the default value
of text length and returns 2. Regardless of the returned value the
_STRING variable (or the custom one passed through the 'var' parameter) is always
populated with a new substring between the start and end positions.
EXAMPLES
String substring
"bad fat cat" start
="4" var="s"
String
length
"bad fat cat"
var="len"
String
substring
"bad fat cat"
start="{len-3}" end="{len-2}"
OPTIONS
unicode
var
- Optional base
name of
the variables to store the resulting string to. If this parameter
is not specified the result will be stored to the default _STRING
variable.
RETURNS
The 'String tostring' command
returns
0
(zero)
on
success
and
1
when
one
or
more
codes
do
not
correspond
to
valid
ASCII/Unicode
characters.
The
command
on
success
populates
the
_STRING
variable
(or
the
custom
one
passed
through
the 'var'
parameter) with the converted
string.
EXAMPLES
String tostring
"104;101;101;108;111" var="s"
String
tostring
"0xF1" var="s"
Var
tomorrow="ma{s}ana"
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"
DESCRIPTION |
Next | Previous | Top^ |
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") { 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}}
}
search.png
and
clicking onto
each of the occurencies.
DESCRIPTION |
Next | Previous | Top^ |
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.
DESCRIPTION |
Next | Previous | Top^ |
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'. |
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. |
_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.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'
.
_SERVER_CLIPBOARD_CONTENT
variable (see also the Var command).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>
passrate=<pass_rate>%
"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>
methodparams=<custom_params>
cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]
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.
DESCRIPTION |
Next | Previous | Top^ |
OPTIONS
text
- The log text. As the execution log file is generated in the HTML format it may contain HTML markup.
level=<logLevel>
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.
DESCRIPTION |
Next | Previous | Top^ |
Report
preferences
and defaults to the 'enterprise'
. "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..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.default"
. It has the
following
lifecycle: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).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.
<!-- 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. |
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>
desc=<description>
scope=<scope_id>
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:all
- This value is the default one. All images
taken
during the script execution will be included in the report.file
- Include only those images that were taken
within the current script and in procedures called by this script.
Other
screenshots created by the master script (i.e. a super script calling
this script) and by the scripts executed using the Run
command will be excluded. This approach is suitable when you
execute
a number of smaller scripts using one superscript and you prefer to
have
a couple of shorter reports instead of a large one.
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.
DESCRIPTION |
Next | Previous | Top^ |
'template'
, 'passrate'
,'onpass'
,'onfail'
.'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.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>
area=[x:<x>][,y:<y>][,w:<width>][,h:<height>]
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>
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=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>
methodparams=<custom_params>
cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]
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>
onpass=<command>
drawresults=<true|false>
method_specific_params
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.
DESCRIPTION |
Next | Previous | Top^ |
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
name
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.
DESCRIPTION |
Next | Previous | Top^ |
from,
to, server, user and passwd are provided in the Sendmail
preferences they may be omitted in the command.OPTIONS
from=<sender_address>
to=<recipient_address>
server=<server[:port]>
subject=<subject>
text=<mail_body>
attach=<attachments>
user=<username>
passwd=<password>
parameter when
the SMTP server specified by the server parameter requires plain
password authentication. debug=<true|false>
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.
DESCRIPTION |
Next | Previous | Top^ |
OPTIONS
name
pass|fail|nt|na
instruct=<instructions>
expected=<expected_result_desc>
actual=<actual_result_desc>
notes=<notes>
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.
DESCRIPTION |
Next | Previous | Top^ |
Report perftesting.xml
Timer
t1
start desc="My
task #1 duration"
<task
code>
Timer
t1
stop
Number | Timer Name | Description | Value |
|
t1 | My task #1 duration | 25.009 sec (25009ms) |
Report perftesting2.xml
Timer load="perftesting.xml"
Timer
t1
start desc="My
task #1 duration"
<task
code>
Timer
t1
stop
Number | Timer Name | Description | Value | Reference Value | Change |
|
t1 | My task #1 duration | 24.984 sec (24984ms) | 25.009 sec (25009ms) |
|
_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.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.Timer
t1
start desc="My
task duration"
value
="1000"
Timer
t2
value="{_TIMER_t1}+1000"
Timer
t2
value="t1"
Timer
t1,t2
start
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
Timer
t1
ungroup=tgroup,tgroup2
Timer
t1
ungroup=
Timer
tgroup
ungroup
=tgroup
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:
Timer
t1,t2 start
value=1000 desc="Performance test"
group="tgroup"
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
desc=<description>
value=<time_millis>
refvalue=<time_millis>
load=<XML_file>
group=<group(s)>
ungroup=<group(s)>
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.
DESCRIPTION |
Next | Previous | Top^ |
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.OPTIONS
description
- Text of the warning to be displayed in the report.
image=<screenshot_name>
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.
DESCRIPTION |
Next | Previous | Top^ |
// 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}"
}
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"). |
OPTIONS
file=<Excel_file>
outfile=<output_Excel_file>
id=<identifier>
sheet=<sheet_name_or_index>
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.
OPTIONS
file=<Excel_file>
id=<identifier>
sheet=<sheet_name>
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"
Excel
create file="C:\Data\log.xls" sheet="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>
ref=<cell_id>
sheet=<sheet_name_or_index>
evaluate=<true|false>
id=<identifier_or_name>
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
Excel
select sheet="Data"
Excel
select row=2 column=4
Excel
select sheet="Results" ref=A5
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>
pattern=<regularExpression>
type=<type>
sheet=<sheet_name_or_index>
evaluate=<true|false>
id=<identifier_or_name>
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}
Excel
find value="2" evaluate=true
Excel
find sheet="Data" pattern="boo.*"
Excel
find type=FORMULA pattern="SUM\(.*\)"
Excel
find type=FORMULA pattern="SUM\(.*\)"
evaluate=true
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>
ref=<cell_id>
sheet=<sheet_name_or_index>
type=<type>
value=<value>
id=<identifier_or_name>
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"
Excel
set row=1 column=A value="2"
sheet="Results"
#
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
Excel
set row=5 column=1 type=FORMULA
value="SUM(A1:A4)"
Excel
select evaluate=true
Excel close [id=<identifier>]
[save=<true|false>]
* Red color indicates obligatory
parameters
OPTIONS
id=<identifier_or_name>
save=<true|false>
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.
DESCRIPTION |
Next | Previous | Top^ |
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". |
OPTIONS
file=<ile>
outfile=<output_file>
id=<identifier>
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>
id=<identifier>
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>
line=<line_number>
column=<column_number>
id=<identifier>
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>
line=<line_number>
column=<column_number>
direction=<forward|backward>
scope=<file|line>
id=<identifier>
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>
column=<column_number>
length=<length_in_chars>
id=<identifier>
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>
delimeter=<delimeter_char>
separator=<separator_char>
pattern=<regular_expression>
trim=<true|false>
id=<identifier>
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}"
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>
column=<column_number>
length=<length_in_chars>
id=<identifier>
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.
OPTIONS
save=<true|false>
id=<identifier>
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.
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.
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);
buttonOK1.png
and buttonOK2.png
located in the template folder
one would
use:Compareto
"buttonOK1.png;buttonOK2.png"
method=search
buttonOK
and the command can be changed to:Compareto
"buttonOK" method=search
buttonOK2.png
first) use:Var _COMPARETO_SORT_MODE=1
Compareto
"buttonOK" method=search
Var _COMPARETO_SORT_MODE=
buttonApprove1.png
and buttonApprove2.png
images one would use:Compareto
"buttonOK;buttonApprove1.png;
buttonApprove2.png
" method=search
buttonApprove
for the
two
images one could write:Compareto
"buttonOK;buttonApprove
" method=search
Compareto
"buttonOK" method=search
if
(
"{_COMPARETO_SOURCE_X}" != "{_SEARCH_X}" &&
"{_COMPARETO_SOURCE_Y}" != "{_SEARCH_Y}
") {
# Object has
moved
...
}
Compareto
"buttonOK" method=search
if (
{_EXIT_CODE} == 0
) {
Mouse
click to="x:{_COMPARETO_CLICK_X},y:{_
COMPARETO_CLICK
_Y}"
}
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:
DESCRIPTION |
Top^ |
_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). |
OPTIONS
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.
DESCRIPTION |
Top^ |
_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). |
OPTIONS
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.
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
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. |
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._TOCR_ERROR
variable. Testing of existence of
this variable is a way to detect core
OCR errors in test scripts.
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}}"
}
Compareto method="tocr" cmparea="x:33,y:2,w:200,h:22"
pattern="[aA]pplication"
if ({_EXIT_CODE} > 0) {
Exit 1
}
Compareto method="tocr" cmparea="x:33,y:2,w:200,h:22"
pattern=".*[aA]pplication.*"
if ({_EXIT_CODE} > 0) {
Exit 1
}
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
.
DESCRIPTION |
Top^ |
java.util.regex.Pattern
compliant regular expression. The expression must match the whole text and no searching for a
matching substring is performed.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. |
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.
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}}"
}
Compareto
"C:\MyAutomation\chars"
method=
"text"
cmparea="x:33,y:2,w:200,h:22"
pattern="[aA]pplication"
if ({_EXIT_CODE} > 0) {
Exit 1
}
Compareto
"C:\MyAutomation\chars"
method=
"text"
cmparea="x:33,y:2,w:200,h:22"
pattern=".*[aA]pplication.*"
if ({_EXIT_CODE} > 0) {
Exit 1
}
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
.
DESCRIPTION |
Top^ |
Image 1 120x100 |
Image 2 120x100 |
|
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.
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.