T-Plan Robot Enterprise Plugin Home

11 December 2017

Utilities Plugin For T-Plan Robot Enterprise

1. Overview

2. Plugin installation

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

• Version 0.5: http://www.t-plan.ltd.uk/releases/robot/plugins/utils_v0.5.zip

OPTION 1:

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.

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

1. Unzip the file to a location on your hard drive.
2. 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"

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

3. Usage

Script Name	Description
com.tplan.utils.StopSchedule	Stop the calling script and the schedule 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.

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

OPTIONS
code=<number>

- 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

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

3.2 GetDate Script

1. 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.
2. Add or subtract the time specified through the add parameter.
3. Format the date using the pattern specified in the outformat parameter or the default one. 
4. Write the formatted date to the script variable of name specified by the var parameter or to the default one.
   

OPTIONS
date=<date>

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

outformat=<pattern>

- 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

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

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

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



3.3 Terminal Script

OPTIONS
text=<text>

- 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

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

3.4 FileControl Script

1. It enters an infinite loop and checks the specified input file periodically.
   
2. 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.
   
3. After the code block gets executed the script creates the receipt file to indicate that it's ready to consume another block of code.
   
4. 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.

OPTIONS
input=<input_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)
  

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

- 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

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

2. Start the script and leave it running.
3. 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"

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

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

OPTIONS
text=<text>

- The window title (optional).

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

- 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

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

3.6 CompareTexts Script

OPTIONS
text1=<text>

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

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

- 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

// 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}"

4. Change Log

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.