Utils

Utilities Plugin For T-Plan Robot Enterprise

1. Overview

The Utilities plugin provides various utility commands to be used in test scripts. Should you have any questions or suggestions contact the T-Plan support. For the list of other plugins provided by T-Plan go here.

2. Plugin installation

The plugin requires T-Plan Robot 6.0 or higher. To install the plugin download it from the following location:

Version 0.6: https://downloads.t-plan.com/releases/robot/plugins/utils_v0.6.zip

For version differences see the Change Log.

OPTION 1:

Unzip the file and copy the utils.jar file to the plugins/ directory under the Robot installation directory. This will make Robot load the classes on the start up. Make sure to remove any older versions of the plugin.
Start or restart Robot. The test scripts will be exposed to Robot. When you create a Run command in your TPR script the property window will list the plugin scripts.

OPTION 2:

Unzip the file to a location on your hard drive.
If you plan on using the plugin in the TPR scripts put the following command to the beginning of each test script:

Include "<location>/utils.jar"

If you plan on using the plugin in Java test scripts put the utils.jar file onto the Java class path.

To uninstall the plugin simply delete the file and remove the Include references.

3. Usage

Version 0.5 contains these Java test scripts:

Script Name	Description
com.tplan.utils.StopSchedule	Stop the calling script and/or the workitem it executes within.
com.tplan.utils.GetDate	Process a date and save it under a custom format.
com.tplan.utils.Terminal	Print out a message to the terminal (command prompt).
com.tplan.utils.FileControl	Execute commands from a text file populated by another process.
com.tplan.utils.PopUpWindow	Display a pop up window.
com.tplan.utils.CompareTexts	Compare two texts line by line.
com.tplan.utils.GetJsonValue	Extract value of an attribute from a JSON document.

The plugin scripts are to be called from TPR test scripts using the Run command. The commands may be easily created using the Command Wizard tool. To edit an existing Run command right click it and select Properties in the context menu.

3.1 StopSchedule Script

DESCRIPTION

The com.tplan.utils.StopSchedule command stops the calling script using an internal call of the Exit command. If the script executes within a workitem (former "schedule") it also stops the workitem. This will have the same effect as if the user clicks the Stop button while the workitem is being executed. If the script is being executed alone (not within a workitem) the command behaves the same way as the Exit one.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.utils.StopSchedule [code=<number>] [desc=<description>]

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.utils.StopSchedule" [, "code", "<number>"] [, "desc", "<description>"] );

* Red color indicates obligatory parameters

OPTIONS

code=<number>

- The numeric exit code to be passed to the Exit command (optional). The value of 0 (zero) indicates that the script passed while any other value makes it fail. When it is omitted the value defaults to 0 (pass).
desc=<description>

- The description to be passed to the Exit command (optional). If the exit code is other than zero it will appear in the script report as a description of the failure.

RETURNS

The command always returns 0 (zero).

EXAMPLES

- Terminate the script and the workitem because a component was not found on the screen:

Run "com.tplan.utils.StopSchedule" code="1" desc="Terminated because component A did not appear on the screen."

3.2 GetDate Script

DESCRIPTION

The com.tplan.utils.GetDate script allows to load a date or use the current one, modify it (add or subtract time) and save the result to a variable. It performs four steps:

Read the date specified through the date parameter. The informat parameter should be used to specify the input date format. If the date is not specified the script will use the current date.
Add or subtract the time specified through the add parameter.
Format the date using the pattern specified in the outformat parameter or the default one.
Write the formatted date to the script variable of name specified by the var parameter or to the default one.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.utils.GetDate [date=<date>] [informat=<pattern>] [add=<time_value>] [outformat=<pattern>] [var=<variable_name>]

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.utils.GetDate" [, "date", "<date>"] [, "informat", "<pattern>"] [, "add", "<time_value>"] [, "outformat", "<pattern>"] [, "var", "<variable_name>"] );

* Red color indicates obligatory parameters

OPTIONS

date=<date>

- The input date, for example '22-04-16' or '22 April 2016'.

informat=<pattern>

- A java.text.SimpleDateFormat compliant date pattern specifying the input date format. The patterns for the above examples are 'dd-MM-yy' and 'dd MMMM yyyy'. If the format is not specified it will default to the one defined for the _DATE variable in the Preferences->Language panel or to the system default one if not set.

add=<time>

- The time to add or subtract from the date. It must be a positive or negative integer number followed by one of the time modifiers of 's' (second), 'm' (minute), 'h' (hour), 'd' (day), 'M' (month) or 'y' (year). For example the value of '-7d' will move the date by one week to the past. A plain number value without a modifier will be interpreted as milliseconds.

outformat=<pattern>

- A java.text.SimpleDateFormat compliant date pattern specifying the output date format. The patterns for the above examples are 'dd-MM-yy' and 'dd MMMM yyyy'. If the format is not specified it will default to the one defined for the _DATE variable in the Preferences->Language panel or to the system default one if not set.

var=<variable_name>

- Name of the variable to save the date to. If the variable name is not set it will use the default one of _GDATE.

RETURNS

The command always returns 0 (zero). A syntax error is thrown on invalid arguments which results in script termination.

EXAMPLES

- Store yesterday's day number to variable 'Y':

Run "com.tplan.utils.GetDate" add="-1d" var="Y" outformat="d"

- Read the specified date of '22-03-2016' and save it to variable MYDATE in a custom format of '23/03/16':

Run "com.tplan.utils.GetDate" date="22-03-2016" informat="dd-MM-yyyy" outformat="dd/MM/yy" var="MYDATE"

- Save the current date plus one month in the default format to the 'D' variable:

Run "com.tplan.utils.GetDate" add="1M" var="D"

3.3 Terminal Script

DESCRIPTION

The com.tplan.utils.Terminal script prints out a message to the terminal (command prompt). This will make the text visible in the process output as well as in the Robot's application log (Help->Log Viewer).

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.utils.Terminal text="<text>" [err=<true|false>]

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.utils.Terminal", "text", "<text>" [, "err", "true|false"] );

* Red color indicates obligatory parameters

OPTIONS

text=<text>

- The text to print out. New line characters must be specified as '\n'. For example, to print out two lines use "First line\nSecond line\n".

err=<true|false>

- If the parameter is omitted or is set to 'false' the text will be printed out to the standard output (Java's System.out). The value of 'true' will use the error output.

RETURNS

The command always returns 0 (zero).

EXAMPLES

Print out two lines to the standard output:

Run "com.tplan.utils.Terminal" text="First line\nSecond line\n"

3.4 FileControl Script

DESCRIPTION

The com.tplan.utils.FileControl script allows to drive the automation from another process through a shared file (the "input file"). It is intended to enable a simple integration with 3rd party frameworks. The mechanism follows the producer-consumer scenario where a 3rd party process (the "driving process") produces blocks of TPR code or Java test scripts ("code blocks") and feeds them to the running Robot instance for immediate execution. The script has the following life cycle:

It enters an infinite loop and checks the specified input file periodically.
When the file gets created or changed the script creates a file copy and executes it through a call of the Run command. If the file has the .java extension it must be a valid Java test script. Files with any other extension are treated as TPR scripts.
After the code block gets executed the script creates the receipt file to indicate that it's ready to consume another block of code.
The above process repeats until the script is terminated through one of the following exit mechanisms:
- The script is stopped by the user, for example through the Stop button in the Robot's GUI.
- The executed code throws a syntax error.
- The script fails to create or write to the receipt file, for example for insufficient file permissions or when the file is locked (used by another process).
- The executed code terminates the script, for example through a call of the Exit command or on a Click or Drag failure. This typically terminates the FileControl script as well as the parent script which started it.
- The "quit" command gets written into the file. This will terminate the FileControl script only and the parent script is allowed to continue.

Implementation details:

The last file modification time is used to detect changes in the input file.
The file is not checked for changes while the code is being executed. The driving process is recommended to use the receipt file for synchronization. In a typical scenario the process deletes the receipt file, writes the code into the input one and waits for the receipt file to get created before processing the next block of code.
When a change is detected the file gets locked by the FileControl script for a short period to enable safe copying of its contents. The driving process must be able to cope with file I/O errors thrown on an attempt to access the file while it is locked. Processes that can't handle I/O errors safely are recommended to either wait for the receipt file or give the FileControl script enough time to process the file. For example, if the checking interval is set to the default one of 250 ms it is reasonable to believe that the change gets detected and the input file copied within a second or two since the moment the code was written to the file.
Development and debugging on environments where the driving process resides on the same machine as the Robot instance and the automation relies on the Local Desktop connection has its limitations because the script will pause on any external mouse move. The workaround is to call "Connect java://localhost" at the beginning of each block of code and close the connection through Disconnect at the end of it. To make the connection fast consider enabling of the stored keyboard maps.
Since all code from the input file is executed within a single session it has read/write access to all global variables defined by the parent script. Variables created inside a code block are created as local ones and they are not visible from the parent script or another code block.

See the Examples paragraph for an example session.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.utils.FileControl input="<input_file>" [receipt="<receipt_file>"] [interval="<milliseconds>"] [verbose="<true|false>"]

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.utils.FileControl", "input", "<input_file>" [, "receipt", "<receipt_file>"] [, "interval", "<milliseconds>"] [, "verbose", "true|false"] );

* Red color indicates obligatory parameters

OPTIONS

input=<input_file>

- The file used to feed the TPR commands or Java code into Robot.

receipt=<receipt_file>

- Optional file to write the receipt to every time the injected code completes execution. If the file does not exist it gets created. To detect the execution completion the driving process is recommended to either watch the file modification stamp or delete the file prior to writing to the input file and then check for its existence. The receipt file will contain RFC 4180 compliant CSV data (Comma Separated Values) with a short summary of important resources:

The first line always contains the three values of

exit,<exitCode>,<processExited>

where "<exitCode>" is the numeric exit code (return value) of the executed code and "<processExited>" indicates whether the automation has terminated. If the value is "true" the script is still running and ready to process code. If the value is "false" the script is not running any more because it was terminated through one of the exit mechanisms described above.

The second line always contains the full path to the HTML execution log file as:

log,<logFile>

Be aware that for performance reasons the log file gets created only after the script gets terminated. This means that the file doesn't exists while the script is alive and the field rather indicates where it will be created.

If the script records results to a report using the Report command the third line will contain its path as "report,<reportFile>"
Further lines vary depending on the executed commands (the order is preserved):
- Any call of Screenshot will insert its path as "screenshot,<screenshotFile>"
- Any call of Step will insert a line of "step,<stepName>,<result>" where <result> is one of the recognized step result words (pass, fail, nt, na)

interval=<milliseconds>

- The file check interval in milliseconds (optional). The default value is 250 ms.

verbose=<true|false>

- Optional log level flag. The value of 'true' will log all the executed code to the execution log. Use for debugging purposes only. Long operation in verbose mode may increase the memory consumption.

RETURNS

The command always returns 0 (zero).

EXAMPLES

To understand functionality of the FileControl script perform the following steps:

Open Robot and create a new TPR script with the following content (adjust the file paths to your local environment)
Include "C:\Users\John\MyAutomation\utils.jar"
Report "results.xml"
Run "com.tplan.utils.FileControl" input="C:\Users\John\MyAutomation\control.tpr" receipt="C:\Users\John\MyAutomation\receipt.csv" verbose="true"
Screenshot "finalscreen.png"
Start the script and leave it running.
Open (create) the input file in a text editor (Notepad, Jedit, ...). Type the following line and save it:
Step "Example step #1" pass
Wait "5s"
Observe the Robot's GUI. The execution log viewer will log the received code. The status bar at the bottom will display the timeout count down to indicate that the 5-second wait operation is in progress. Once finished read the receipt file. It will contain something like:
exit,0,true
log,C:\Users\John\MyAutomation\reports\Script1.tpr_1473159479894.a42cc\log.html
report,C:\Users\John\MyAutomation\reports\Script1.tpr_1473159479894.a42cc\results.xml
step,Example step #1,pass
Go back to the text editor. Replace the contents with either "Exit 1" or "Quit", save the file and observe the behavior in the Robot's GUI. The script will terminate. If you review the receipt file the last value of the first line will be "false" to indicate that the script is no longer alive. The difference between Exit and Quit is as follows:

- Quit will terminate just the the FileControl script and return the control to the parent one. If you check the resulting report it will contain the "finalscreen.png" screen shot.
- Exit will terminate the parent script. The Screenshot command in the code above will not be executed.

3.5 PopUpWindow Script

DESCRIPTION

The com.tplan.utils.PopUpWindow script displays a pop up window on the local desktop. It may be used for demonstration purposes or for interactive scripts (let the user choose among options).

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.utils.PopUpWindow [text="<text>"] [title="<title>"] [buttons="<button_list>"] [timeout=<time>]

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.utils.PopUpWindow" [, "text", "<text>"] [, "title", "<title>"] [, "buttons", "<button_list>"] [, "timeout", "<time>"] );

* Red color indicates obligatory parameters

OPTIONS

text=<text>

- The message to display (optional). It may be either plain text or HTML code which must start with "<html><body>".

title=<title>

- The window title (optional).

buttons=<button_list>

- Semicolon (;) separated list of button labels (optional). For example, the value of "OK;Cancel" will display a window with two buttons of "OK" and "Cancel". The button that the user selects will be saved to the _POPUP_BUTTON script variable. If the window times out the first button will be used. If the parameter is omitted the window will contain just the default "OK" button.

timeout=<true|false>

- Optional timeout to close the window unless the user closes it through one of the buttons. It must be a valid time value. To set it off omit the parameter or provide the value of 0.

RETURNS

The command always returns 0 (zero).

EXAMPLES

Display a message of "Hello!" in header font and close it after 10 seconds:

Run "com.tplan.utils.PopUpWindow" text="<html><body><h1>Hello!</h></body></html>" timeout="10s"

3.6 CompareTexts Script

DESCRIPTION

The com.tplan.utils.CompareTexts compares two multiline texts line by line and detects missing lines. Lines may be compared using exact or fuzzy text matching. Differences in the line order are ignored.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.utils.CompareTexts [text1="<text>"] [text2="<text>"] [distance="<number>"] [template="<templateText>"]

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.utils.CompareTexts", "text1", "<text>", "text2", "<text>" [, "distance", "<number>"] [, "template", "<templateText>"] );

* Red color indicates obligatory parameters

OPTIONS

text1=<text>

- One text (mandatory)

text2=<text>

- Another text to be compared to the first one (mandatory)

distance=<button_list>

- Distance for fuzzy matching (optional). If the parameter is not specified it defaults to 0 and the script applies exact text matching. Values greater than 0 allow for fuzzy text matching through the Levenshtein distance. It roughly expresses how many characters may be different or omitted to consider two lines still matching.

template=<templateText>

- Line difference template used for the comparison summary stored to the _TEXTDIFF variable (optional). It may be customized for reporting purposes. The default template is:

Item "{0}" is present in the {1} text only

where {0} will be replaced with the line text and {1} with the word of "first" or "second".

RETURNS

The command returns the number of mismatching text lines or 0 (zero) if the texts contain the same lines. The number of mismatching lines is also stored to the _TEXTDIFF_COUNT variable.

EXAMPLES

- A typical usage is to compare two texts retrieved from the screen using OCR:

// Recognize texts in the first screen area
Compareto method= "tocr" cmparea="x:4,y:71,w:119,h:53"

// Save the resulting multiline text to a variable
Var TEXT1= "{_TOCR_TEXT}"

// Recognize text in another area
Compareto method= "tocr" cmparea="x:6,y:225,w:119,h:80"

// Compare the texts. For results see the _TEXTDIFF prefixed variables.
Run "com.tplan.utils.CompareTexts" distance="3" text1="{TEXT1}" text2="{_TOCR_TEXT}"

3.6 GetJsonValue Script

DESCRIPTION

The com.tplan.utils.GetJsonValue parses a JSON document and extracts value of an attribute.

SYNOPSIS (TPR SCRIPTS)

Run com.tplan.utils.GetJsonValue [json="<JSON_document>"] [name="<attribute_name>"] [parent="<parent_attribute_name>"] [var="<var_name>"]

SYNOPSIS (JAVA SCRIPTS)

run("com.tplan.utils.GetJsonValue", "json", "<JSON_document>", "name", "<attribute_name>" [, "parent", "<parent_attribute_name>"] [, "var", "<var_name>"] );

* Red color indicates obligatory parameters

OPTIONS

json=<JSON_document>

- The JSON document (mandatory).

name=<attribute_name>

- Name of the attribute (mandatory)

parent=<parent_attribute_name>

- Optional name of the parent attribute. This allows to restrict the lookup to a certain object in the document. The parent may be both direct or indirect (parent of the parent etc).

var=<var_name>

- Name of the variable to store the attribute value to. If the parameter is omitted the result will be stored to the default _JSON_VALUE variable.

RETURNS

The command returns 0 on success, 1 if the lookup fails or 2 on an internal error.

EXAMPLES

- This example extracts the value of "date" to the "mydate" variable and prints it out.

// Save the resulting multiline text to a variable
Var JSON="{\"status\":{\"id\":240000778,\"date\":\"2024-05-08\"}}"
Run "com.tplan.utils.GetJsonValue" json="{JSON}" name="date" var="mydate" Log "The date is: {mydate}"

4. Change Log

Version 0.6 released on 8 May 2024

GetJsonValue scripts introduced.

Version 0.5 released on 11 December 2017

CompareTexts scripts introduced.

Version 0.4 released on 8 September 2016

FileControl and PopUpWindow scripts introduced.

Version 0.3 released on 11 April 2016

Terminal script introduced.

Version 0.2 released on 24 March 2016

GetDate script introduced.

Version 0.1 released on 9 March 2015

First public release with the StopSchedule script.

Contents:

1. Overview

2. Plugin installation

3. Usage

3.1 StopSchedule Script

DESCRIPTION

3.2 GetDate Script

DESCRIPTION

3.3 Terminal Script

DESCRIPTION

3.4 FileControl Script

DESCRIPTION

3.5 PopUpWindow Script

DESCRIPTION

3.6 CompareTexts Script

DESCRIPTION

3.6 GetJsonValue Script

DESCRIPTION

4. Change Log