com.tplan.robot.scripting
Class DefaultJavaTestScript

java.lang.Object
  com.tplan.robot.scripting.AbstractJavaTestScript
      com.tplan.robot.scripting.DefaultJavaTestScript

All Implemented Interfaces:

JavaTestScript, TestWrapper

public class DefaultJavaTestScript
extends AbstractJavaTestScript

Default Java test script. Users wishing to write Java test scripts are recommended to extend this class and override the test() method with their own sequence of automated testing command calls. See the Developing Java Test Scripts document for an introduction and overview of the T-Plan Robot Enterprise Java Test Script Framework.

Let's have a simple test script which types "Hello world" on the remote desktop. Let's suppose that there's already connection to a desktop and all we have to do is to type the text. The script in the TPR language would then look as follows:

 Type "Hello word"
 

The same script in Java based on this class:

 import com.tplan.robot.scripting.DefaultJavaTestScript;
 import com.tplan.robot.scripting.JavaTestScript;
 import java.io.IOException;

 public class MyTest extends DefaultJavaTestScript {

    public void test() {
       try {
          type("Hello world");
       } catch (IOException ex) {
          ex.printStackTrace();
       }
    }
 }
 

To execute the script either:

• Start the T-Plan Robot Enterprise GUI, open the .java file through File->Open Test Script and select the Execute too bar button or menu item (manual execution),
• Specify the script through the -r/--run CLI switch (automated execution). To execute in CLI mode without GUI specify the -n switch as well.

T-Plan Robot Enterprise in fact supports execution of Java test scripts the same way as the TPR language ones. The tool is able to compile the Java code (.java) into byte code (.class) internally and execute it on the fly provided that you run a Java Development Kit (JDK). If you run T-Plan Robot Enterprise through a Java Runtime Environment (JRE), the tool will report an error because JRE is a limited version of Java and does not include the necessary Java Compiler binary javac.

A Java test script may be controlled the same way as the TPR test scripts - it may be executed, paused or stopped from the GUI or CLI. The only limitation is that the pause or stop requests get noticed and applied only inside the methods provided by this class. Though the GUI even provides some limited support of Java test script development, such as simple Java editor and reporting of javac compilation errors, it is recommended to use an IDE such as NetBeans or Eclipse to develop Java classes. This tool is not designed to support editing of complex Java projects.

Java test scripts may be also executed as standalone processes through their own main() method. As test scripts are executed as threads, one simple Java program can create and start any number of test instances. This allows to run multiple automated testing tasks simultaneously or even to use the tool for load testing through simulation of multiple users accessing the tested service or application.

Our "Hello world" example enhanced with the main() method would look as follows:

 import com.tplan.robot.*;
 import com.tplan.robot.scripting.DefaultJavaTestScript;
 import com.tplan.robot.scripting.JavaTestScript;
 import java.io.IOException;

 public class MyTest extends DefaultJavaTestScript {

    public void test() {
       try {
          type("Hello world");
       } catch (IOException ex) {
          ex.printStackTrace();
       }
    }

    public static void main(String args[]) {
       MyTest test = new MyTest();
       ApplicationSupport robot = new ApplicationSupport();
       AutomatedRunnable t = robot.createAutomatedRunnable(test, "javatest", args, System.out, false);
       new Thread(t).start();
    }
 }
 

The point is to let the ApplicationSupport class to create a test runnable (AutomatedRunnable) from an instance of our Java test class. As the resulting object implements the Runnable interface, it is possible to execute it through a Thread. Another important feature to notice is that the createAutomatedRunnable() method accepts a String array of input arguments. This makes it possible to customize any single test script runnable with any command line options specified in the T-Plan Robot Enterprise CLI Options document.

If you for some reason can not extend this class but you need to access its methods, you may create an instance and call its methods instead. Your class however must implement at least the JavaTestScript interface which is the bare minimum for a test script to be able to execute through the T-Plan Robot Enterprise framework. You must also make sure that the JavaTestScript.setContext(com.tplan.robot.scripting.ScriptingContext) and JavaTestScript.setInterpret(com.tplan.robot.scripting.interpret.TestScriptInterpret) methods get called correctly on this class instance. An example follows:

 import com.tplan.robot.scripting.*;
 import com.tplan.robot.scripting.interpret.TestScriptInterpret;
 import java.io.IOException;

 public class MyCustomTest implements JavaTestScript {
    ScriptingContext context;
    TestScriptInterpret interpret;

    public void setContext(ScriptingContext context) {
       this.context = context;
    }

    public void setInterpret(TestScriptInterpret interpret) {
       this.interpret = interpret;
    }

    public void test() {
       try {
          DefaultJavaTestScript defaultScript = new DefaultJavaTestScript();
          defaultScript.setContext(context);
          defaultScript.type("Hello world");
       } catch (IOException ex) {
          ex.printStackTrace();
       }
    }
 }
 

This way may be also efficiently used to create libraries of test tasks or routines similar to the functionality provided by the Run and Include commands.

Since version 2.2 Java test scripts may be easily called from regular ones. The Include command is capable of putting the JAR files or class paths with compiled Java code onto the Robot's Java class path in a dynamic way. The Run command was enhanced to support instantiation of such Java test scripts by class name. The Run command is also able to accept a set of parameters on the command line and pass them to the Java code.

For example, a call of a Java test script class test.DummyTest from the C:\tests\MyTests.jar JAR file with parameters of 'count' and 'wait' equal to '2' and '500' would look as follows:

Include C:\tests\MyTests.jar
Run testscript.MyJavaTestScript count=2 wait=500

As the parameters are stored by the Run command into the table of local variables, the Java test script may retrieve them inside their test() method through the context methods such as the getContext().getVariable(<parameterName>) one. To get the 'wait' parameter value from our example as int one would call getContext().getVariableAsInt("wait").

The list of parameters is by default not validated in any way. Java test scripts may optionally declare the parameters they support through implementing the ExtendedParamsObject interface (except the setParameters() method which is not used in this case). As the mechanism of parameter declaration takes advantage of the framework created originally for user preferences, the terminology might be misleading, especially in case of the ExtendedParamsObject.getVisualParameters() method where each parameter must be encapsulated in a Preference instance. The Preference object requires by default the configuration key (in our case the parameter name), the value type (INT, FLOAT, STRING, ...), label (short description) and description. The object allows to define various value restrictions and dependencies, for example minimum and maximum values for numeric parameters etc. See the Preference class documentation for a complete list.

If the parameters are declared properly the GUI will support the following features. To read more about the discussed GUI components see the Script Editor help topic in the GUI Reference document collection.

• The script editor will check the parameters against the list declared by the ExtendedParamsObject.getParameters() method during script compilation and report a syntax error if an unknown parameter is specified.
• If a parameter is an enumerated type (meaning its value must be one of the predefined values) and this is properly declared through the ExtendedParamsObject.getParameterValues(java.lang.String) method, the editor will check if the parameter value is one of the expected ones and reports a syntax error if not.
• If the parameter properties are further described by a Preference wrapper returned by the ExtendedParamsObject.getVisualParameters() method, the editor will check whether the parameter meets the specified type and any type of declared limitations (numeric limit, mandatory, ...).
• The Command Wizard activated through Ctrl+Enter in the editor will provide the list of the declared parameters and eventually their values (for enumerated types).
• A right mouse click onto the Run command in the editor opens up a context menu containing the Edit parameters menu item. When selected it opens a simple dialog allowing to edit all the declared parameters.

As is already indicated by the examples above, this class contains methods which provide almost the same functionality as elements of the T-Plan Robot Enterprise TPR language defined by the T-Plan Robot Enterprise Scripting Language Specification. The following table summarizes compatibility of this Java class with the specification and the existing limitations. Use this table as a reference of how to implement the same functionality both in the scripting language and Java as well as which limitations apply to conversion of TPR test scripts into Java.

Spec Command/Element	Supported By Java	Comments
Code comments	Yes	Java supports code comments similar to the scripting language ones.
Labels	No	Labels define places in the script code to jump to. As Java doesn't support a "goto" command, labels are not supported. A workaround is to use Java language elements to implement conditional execution blocks, such as methods, if/else and switch statements.
Time values	Yes	Time values are supported as arguments of methods corresponding to the scripting commands. Examples are "1s" (one second) or 5m (5 minutes
Procedures	Yes	Procedures correspond with Java void methods.
Numeric expressions	Yes	Numeric expressions specified by the TPR language are fully supported in Java.
Boolean expressions	Yes	Boolean expressions specified by the TPR language are fully supported in Java.
If/else statement	Yes	If/else statement specified by the TPR language is fully supported in Java.
For statement	Yes	For statement specified by the TPR language is supported in Java, just the for statement iterating over a set of enumerated values must be implemented indirectly with the help of a String array or Java Collections.
Local variables	Yes	Java supports the same concept of local variables as the TPR language. Global variables may be implemented in Java either as class member variables or stored to the variable list in the context through the ScriptingContext.setVariable(String, Object) method.
Return values	Yes	Java methods return exit values of the scripting language commands.
Connect command	Yes	Provided through the set of connect() methods.
Disconnect command	Yes	Provided through the disconnect() method.
Press command	Yes	Provided through the set of press() methods.
Type and Typeline commands	Yes	Provided through the set of type() and typeLine() methods.
Mouse command	Yes	Provided through the set of mouseEvent(), mouseMove(), mouseClick(), mouseRightClick(), mouseDoubleClick(), mouseDrag(), mouseRightDrag(), mouseWheelUp() and mouseWheelDown() methods.
Var and Eval commands	Yes (indirectly)	There is no direct method corresponding to the Var/Eval commands. Script variables populated by the commands or the automated testing framework (so called predefined or implicit variables) can be accessed through the context methods ScriptingContext.getVariable(String) and ScriptingContext.setVariable(String, Object). Other user variables may be implemented either as Java local or member variables or through the context as well. Dynamically populated variables are present in the context but they will return just dummy values populated at the time of context creation. To get the desired variable value use appropriate Java code as follows: To get the current time in milliseconds (variable _CURTIME) use System.currentTimeMillis(). To get the formatted current time and date (variable _CURDATE) use new java.util.Date().toString(). If you want to apply the format specified in the user preferences, load it through String format = UserConfiguration.getInstance().getString("scripting.curdateFormat") and format the Date object through new java.text.SimpleDateFormat(format).format(new Date()). To get a random number (variable _RANDOM) use java.util.Random. To get RGB of a pixel on the desktop use ((BufferedImage) getContext().getClient().getImage()).getRGB(x,y). This will yield the RGB value as integer which may be used in constructor of java.awt.Color. Should you want to convert the color to the HTML-style format, call getContext().getParser().colorToString(Color). To get the current mouse coordinates (variables _MOUSE_X and _MOUSE_Y) call getContext().getClient().getLastMouseEvent().getPoint(). Don't forget to test whether the client is not null and connected and whether the mouse event is not null. Be aware that when the client connects to a desktop it doesn't know the initial mouse pointer location. To start tracking of the last mouse event you have to perform at least one mouse() call Variables passed through the -v/--variable CLI option may be accessed through the getContext().getCommandLineVariables() method. The overriding mechanism known from TPR test script is not applied in case of Java test scripts which are free to decide whether to use or ignore the CLI value.
Run and Include commands	Yes	Version 2.3 and newer supports direct calls of .tpr scripts through the run(java.lang.String) and include(java.lang.String) methods. These have the same functionality as the corresponding Run and Include commands. Procedures imported through the include() method can be called (executed) through callProcedure(java.lang.String, java.lang.String[]). The run() method is also capable of running Java source code files (*.java); the tool must however run on a JDK to have access to the Java compiler. The method may also instantiate and run a Java test script specified by a fully qualified class name. For example, a call like run("mypackage.MyTestScript") will make an attempt to instantiate the mypackage.MyTestScript class and execute its test() method provided that the class is available on the class path (or has been put onto the class path through a include([JAR_file_or_class_path]) method call) and it implements at least the JavaTestScript interface Versions prior to 2.3 provide no direct method corresponding to the Run/Include commands. It is not possible to execute a script in the TPR format directly from a Java test script (only as a separate independent automated process created through the mechanism described in theAutomatedRunnable interface). In cases where Java is used as an exclusive automation language and no mixing of Java and TPR scripts is needed it is recommended to use capabilities of the Java language to create libraries with test script routines. The Include command corresponds to instantiation of another Java class and accessing its methods and member variables. The Run command is equivalent to calling of test() method of another Java test script instance.
Pause command	Yes	Provided through the set of pause() methods.
Exit command	Yes (indirectly)	To exit a script execution (scope=process) use the System.exit(int) method. Other exit scopes such as procedure, block and file must be implemented indirectly using Java language capabilities.
Log command	Yes	Provided through the log(java.lang.String, java.util.logging.Level) method.
Wait command	Yes	Provided through the wait(java.lang.String) method.
WaitFor command	Yes	Provided through the waitForBell(), waitForUpdate(), waitForMatch(), waitForMismatch() and waitForClipboard() methods.
CompareTo command	Yes	Provided through the compareTo() methods.
Exec command	Yes	Provided through the exec() methods.
Screenshot command	Yes	Provided through the screenshot() methods.
Report command	Yes (partially)	Provided through the report() methods. There's however one limitation. Though the scope parameter is among the method arguments, it is present just for the sake of backward compatibility and should be considered as obsolete. Its value will be ignored and the method will always execute with the scope fixed to all (include all outputs created by the test scripts in the report).
Warning command	Yes	Provided through the warning() methods.
Sendmail command	Yes	Provided through the sendMail() methods.
Script command	Yes	Provided through the script() and similar methods.
Step command	Yes	Provided through the step() methods.
File command	No	Users are advised to take advantage of standard Java I/O APIs to implement plain text file input/output. To parse CSV it is possible to use the FileCommand.parseCSV(java.lang.CharSequence, int, char, char, boolean, boolean, int[]) method or employ any public CSV parsing Java library.
Excel command	Yes	Provided through the excelOpen(java.io.File, java.io.File, java.lang.String, java.lang.String) and other excel-prefixed methods.
Timer command	Yes	Provided through the timer(java.lang.String, java.lang.String, long, long, java.lang.String, java.lang.String, java.io.File) method and other timer-prefixed methods.

Methods representing commands of the TPR scripting language share the following design principles:

• Methods have generally the same names as their corresponding commands. There are a few reasonable exceptions, for example the Mouse command is for better clarity represented by methods called mouseMove, mouseClick, mouseDrag etc. Such methods usually represent a combination of a command and one or more its parameters (for example, the mouseDoubleClick method represent a "Mouse click button=left count=2" command).
• To omit a method argument set its value to null (for objects) or to a negative number (for int, long, float or double arguments). This makes the command behave as if the parameter was not specified and rely on the default value. For example, methods performing image search such as compareTo() automatically look for 100% match if the passRate argument is set to -1f.
• Each method returns an integer value equal to the command return value described in the specification. A value of 0 (zero) usually indicates success while values other than zero indicate either an error or a negative test result.
• An IOException is thrown only on when an unrecognized or unexpected error happens in the communication between the desktop client and server. Don't be surprised that some methods, for example connect(), rather return an error code than throw an IOException in standard situations, such as failure to connect to the server because it is down, authentication failure etc.
• All methods may throw an IllegalArgumentException when one or more argument values are invalid and/or if the corresponding command requires connection to a desktop and the tool is in disconnected state. As this execption is unchecked, it is not explicitly declared as thrown by the method.

Most methods of this class are annotated. The goal is to provide information allowing to map these methods and their arguments onto commands and parameters of the TPR scripting language. This data is retrieved through Java Reflection API by the AdvancedConverter which provides conversion of TPR test scripts into Java classes. Should you want to extend both the TPR language and the Java test script class with a new command/method, you have to annotate the method in a similar way to make the command calls convertible to Java code.

T-Plan Robot Enterprise, (C) 2009-2013 T-Plan Limited. All rights reserved.

Nested Class Summary

static interface	DefaultJavaTestScript.Command
static interface	DefaultJavaTestScript.Param

Field Summary

Fields inherited from interface com.tplan.robot.scripting.TestWrapper

WRAPPER_TYPE_BLOCK, WRAPPER_TYPE_INCLUDE, WRAPPER_TYPE_JAVA, WRAPPER_TYPE_PROCEDURE, WRAPPER_TYPE_RUN, WRAPPER_TYPE_SCRIPT, WRAPPER_TYPE_UNKNOWN

Constructor Summary

DefaultJavaTestScript()

Method Summary

int	callProcedure(String procedureName, String... args) Call a stored procedure which was previously imported from a .tpr script through the call of run(java.lang.String) or include(java.lang.String).
int	compareTo(File[] templates) Compare the current remote desktop image to one or more template images using the default histogram based image comparison (code "default") and default numeric pass rate (95% unless the user modified the value in user preferences).
int	compareTo(File[] templates, float passRate) Compare the current remote desktop image to one or more template images using the default histogram based image comparison (code "default") and numeric pass rate.
int	compareTo(File[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha) Search the current remote desktop image for one or more template images using the "search" image comparison module (method), numeric pass rate and an optional comparison rectangle.
int	compareTo(File[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance) Search the current remote desktop image for one or more template images using the "search" image comparison module (method), numeric pass rate and an optional comparison rectangle.
int	compareTo(File[] templates, float passRate, Rectangle cmpArea, String sort) Search the current remote desktop image for one or more template images using the "search2" image comparison module (method), numeric pass rate and an optional comparison rectangle.
int	compareTo(File[] templates, float passRate, Rectangle cmpArea, String text, int distance, String pattern) Recognize the text on the screen by a character image collection using the Image Based Text Recognition comparison method.
int	compareTo(File[] template, String method) Compare the current remote desktop image to one or more template images using the specified image comparison module and default numeric pass rate (100% for "search", 95% for "default" unless the user modified these values in user preferences).
int	compareTo(File[] templates, String method, float passRate) Compare the current remote desktop image to one or more template images using the specified image comparison module instance and numeric pass rate.
int	compareTo(File[] templates, String method, float passRate, Integer rgbTolerance) Compare the current remote desktop image to one or more template images using the specified image comparison module instance and numeric pass rate.
int	compareTo(File[] templates, String method, float passRate, Rectangle cmpArea) Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
int	compareTo(File[] templates, String method, float passRate, Rectangle cmpArea, Integer rgbTolerance) Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
int	compareTo(File[] templates, String method, String methodParams, float passRate, Rectangle cmpArea) Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
int	compareTo(File template, Float passRate, Rectangle cmpArea, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear) Analyze the current remote desktop image using the Object Search Method.
int	compareTo(Image[] templates, ImageComparisonModule module, float passRate, Rectangle cmpArea) Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
int	compareTo(Image[] templates, ImageComparisonModule module, float passRate, Rectangle cmpArea, Boolean removeBg, Color bgColor, Integer minAlpha) Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
int	compareTo(Image[] templates, ImageComparisonModule module, float passRate, Rectangle cmpArea, Boolean removeBg, Color bgColor, Integer minAlpha, Integer rgbTolerance) Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
int	compareTo(Image[] templates, ImageComparisonModule module, float passRate, Rectangle cmpArea, Integer rgbTolerance) Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
int	compareTo(Image template, Float passRate, Rectangle cmpArea, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear) Analyze the current remote desktop image using the Object Search Method.
int	compareTo(Rectangle cmpArea, String language) Perform Optical Character Recognition (OCR) using the Tesseract engine.
int	compareTo(Rectangle cmpArea, String language, float scale, String text, int distance, String pattern) Perform Optical Character Recognition (OCR) using the Tesseract engine.
int	compareTo(Rectangle cmpArea, String language, String text, String pattern) Perform Optical Character Recognition (OCR) using the Tesseract engine.
int	connect(String host) Connect to a server which requires no authentication (for example a Java client or an RFB/VNC server which is configured this way).
int	connect(String host, boolean force) Connect to a server which requires no authentication (for example a Java client or an RFB/VNC server which is configured this way).
int	connect(String host, String password) Connect to a server which may or may not require a password.
int	connect(String host, String user, String password, boolean force) Connect to a server using the specified user and password.
int	connect(String host, String user, String password, Map<String,Object> params, boolean force) Connect to a desktop.
int	connect(String host, String user, String password, String params, String paramSeparator, boolean force) Connect to a desktop.
int	disconnect() Disconnect from a desktop.
int	excelClose(String id, boolean save) Close and eventually save the specified Excel document.
int	excelCreate(File outputFile, String sheetName, String id) Create a new Microsoft Excel document for reading and writing.
int	excelCreate(OutputStream outputStream, String sheetName, String id) Create a Microsoft Excel document and associate it with an output stream.
int	excelCreate(String sheetName, String id) Create and select a new sheet in the current or specified Excel document.
int	excelFind(Object value, String type, boolean evaluate, Object sheet, String id) Search the specified sheet for a cell of the given type and/or value.
int	excelFind(String pattern, boolean evaluate, String type, Object sheet, String id) Search the specified sheet for a cell whose value (and optionally also type) matches the given regular expression.
int	excelOpen(File inputFile, File outputFile, String sheet, String id) Open a Microsoft Excel file for reading and writing.
int	excelOpen(File inputFile, String id) Open a Microsoft Excel file for reading and writing and select automatically the first sheet.
int	excelOpen(InputStream inputStream, OutputStream outputStream, String sheet, String id) Open a Microsoft Excel file.
int	excelSelect(int row, String column, boolean evaluate, String id) Select a cell from the current sheet and retrieve its coordinates (row/column, reference), type and value to the context variables of _EXCEL_CELL_ROW, _EXCEL_CELL_COLUMN, _EXCEL_CELL_REF, _EXCEL_CELL_TYPE and _EXCEL_CELL_VALUE.
int	excelSelect(int row, String column, String sheet, boolean evaluate, String id) Select a cell and retrieve its value and type to the context variables.
int	excelSelect(String ref, boolean evaluate, String id) Select a cell from the current sheet and retrieve its value and type to the context variables.
int	excelSelect(String sheet, String id) Select (open) a sheet.
int	excelSelect(String ref, String sheet, boolean evaluate, String id) Select a cell and retrieve its value and type to the context variables.
int	excelSet(int row, String column, Object value, Object sheet, String type, String id) Set value and/or type of the specified cell.
int	excelSet(int row, String column, Object value, String id) Set value of the specified cell in the currently selected sheet.
int	excelSet(int row, String column, Object value, String type, String id) Set value and/or type of the specified cell in the currently selected sheet.
int	excelSet(Object value, String id) Set value of the currently selected (previously used) cell in the currently selected sheet.
int	excelSet(String ref, Object value, Object sheet, String type, String id) Set value and/or type of the specified cell.
int	excelSet(String ref, Object value, String id) Set value of the specified cell in the currently selected sheet.
int	excelSet(String ref, Object value, String type, String id) Set value and/or type of the specified cell in the currently selected sheet.
int	exec(String command) Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command without any further options.
int	exec(String command, boolean nowait) Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command without any further options.
int	exec(String command, OutputStream out) Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command once (count=1) with no waiting period specified (wait=null).
int	exec(String command, OutputStream out, boolean nowait, int count, String wait) Execute a command of the local operating system.
int	exec(String command, OutputStream out, int count, String wait) Execute a command of the local operating system.
int	exec(String command, String wait) Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command once (count=1) with no output stream (out=null) and no waiting period (wait=null).
int	exec(String command, Writer out) Convenience method employing the exec(java.lang.String, java.io.Writer, int, java.lang.String) method to execute a command once (count=1) with no waiting period specified (wait=null).
int	exec(String command, Writer out, boolean nowait, int count, String wait) Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method with the command output redirected to a Writer rather than to an OutputStream.
int	exec(String command, Writer out, int count, String wait) Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method with the command output redirected to a Writer rather than to an OutputStream.
int	execBrowser(String url) A convenience method to open a web browser on the local operating system.
int	exit(Integer exitCode) Exit the test script.
int	exit(Integer exitCode, String description) Exit the test script.
int	fileAppend(String text, String id) Append text to the end of the text file.
int	fileClose(String id, boolean save) Close and eventually save the specified text/CSV file.
int	fileCreate(File outputFile, String id) Create a new text or CSV file for reading and writing.
int	fileCreate(OutputStream outputStream, String id) Create a text or CSV file and associate it with an output stream.
int	fileDelete(int line, int column, int length, String id) Delete the text specified by the line/column numbers and length..
int	fileFind(String text, int line, int column, String direction, String scope, String id) Find the first position of the specified text in the file..
int	fileInsert(String text, int line, int column, String id) Insert text to the position specified by the line and column parameters.
int	fileOpen(File inputFile, File outputFile, String id) Open a text or CSV file for reading and writing.
int	fileOpen(InputStream inputStream, OutputStream outputStream, String id) Open a text or CSV file.
int	fileParse(int line, String id) Parse the specified CSV line into values using the rules defined by the RFC 4180.
int	fileParse(int line, String pattern, boolean trim, String id) Parse the specified line into values by the given java.util.regex.Pattern compatible regular expression.
int	fileParse(int line, String separator, String delimeter, boolean trim, String id) Parse the specified line into values by the given separator and delimeter.
int	fileRead(int line, int column, int length, String id) Read text of a single line from the position specified by line, column and length parameters.
int	getExitCode() Return result of the last executed command (method).
TestWrapper	getRootWrapper()
UserConfiguration	getUserConfiguration() Convenience method for quick access to the user configuration.
int	include(String file) Include a TPR test script (.tpr).
boolean	isPass() Return result of the last executed command (method).
int	log(String message, Level level) Log a message to the script execution log.
int	mouseClick(int x, int y) Perform a single left mouse click on the currently connected desktop.
int	mouseClick(int x, int y, int count) Perform left mouse click(s) on the currently connected desktop.
int	mouseClick(int x, int y, int count, String wait) Perform left mouse click(s) on the currently connected desktop.
int	mouseClick(Point to) Perform a single left mouse click on the currently connected desktop.
int	mouseClick(Point to, int count) Perform left mouse click(s) on the currently connected desktop.
int	mouseClick(Point to, int modifiers, int button, int count, String wait) Perform left mouse click(s) on the currently connected desktop.
int	mouseClick(Point to, int count, String wait) Perform left mouse click(s) on the currently connected desktop.
int	mouseClick(Point to, String wait) Perform a single left mouse click on the currently connected desktop.
int	mouseDoubleClick(int x, int y) Perform a double left mouse click on the currently connected desktop.
int	mouseDoubleClick(int x, int y, String wait) Perform a double left mouse click on the currently connected desktop.
int	mouseDoubleClick(Point to) Perform a double left mouse click on the current desktop client.
int	mouseDoubleClick(Point to, String wait) Perform a double left mouse click on the current desktop client.
int	mouseDrag(Point from, Point to, int modifiers, int button, String wait) Perform a left button mouse drag on the currently connected desktop.
int	mouseEvent(String action, int modifiers, int button, Point from, Point to, int count, String wait) Perform a generic mouse action on the currently connected desktop.
int	mouseMove(int x, int y) Perform a mouse move on the currently connected desktop.
int	mouseMove(int x, int y, int modifiers, String wait) Perform a mouse move on the currently connected desktop with optional modifier key(s) pressed.
int	mouseMove(int x, int y, String wait) Perform a mouse move on the currently connected desktop.
int	mouseMove(Point to) Perform a mouse move on the currently connected desktop.
int	mouseMove(Point to, int modifiers, String wait) Perform a mouse move on the currently connected desktop with optional modifier key(s) pressed.
int	mouseMove(Point to, String wait) Perform a mouse move on the currently connected desktop.
int	mouseRightClick(int x, int y) Perform a single right mouse click on the currently connected desktop.
int	mouseRightClick(int x, int y, int count) Perform right mouse click(s) on the currently connected desktop.
int	mouseRightClick(int x, int y, int count, String wait) Perform right mouse click(s) on the currently connected desktop.
int	mouseRightClick(Point to) Perform a single right mouse click on the currently connected desktop.
int	mouseRightClick(Point to, int count) Perform right mouse click(s) on the currently connected desktop.
int	mouseRightClick(Point to, int modifiers, int count, String wait) Perform right mouse click(s) on the currently connected desktop.
int	mouseRightClick(Point to, int count, String wait) Perform right mouse click(s) on the currently connected desktop.
int	mouseRightDrag(Point from, Point to, int modifiers, String wait) Perform a right button mouse drag on the currently connected desktop.
int	mouseWheelDown(int x, int y, int modifiers, int count, String wait) Scroll down the mouse wheel on the current desktop.
int	mouseWheelDown(Point to, int modifiers, int count, String wait) Scroll down the mouse wheel on the current desktop.
int	mouseWheelUp(int x, int y, int modifiers, int count, String wait) Scroll up the mouse wheel on the current desktop.
int	mouseWheelUp(Point to, int modifiers, int count, String wait) Scroll up the mouse wheel on the current desktop.
int	pause() Pause execution of the test script until the user manually resumes it.
int	pause(String reason) Pause execution of the test script until the user manually resumes it with an optional description for report providers.
int	press(char c, int location, int count, String wait) Press a character with optional modifiers on the current desktop once or more times.
int	press(char c, int location, int count, String delay, String wait) Press a character with optional modifiers on the current desktop once or more times.
int	press(String key) Press a key with optional modifiers on the current desktop.
int	press(String key, int location) Press a key with optional modifiers on the current desktop.
int	press(String key, int location, int count, Boolean release, String delay, String wait) Press a key with optional modifiers on the current desktop once or more times.
int	press(String key, int location, int count, String wait) Press a key with optional modifiers on the current desktop once or more times.
int	press(String key, int location, int count, String delay, String wait) Press a key with optional modifiers on the current desktop once or more times.
int	press(String key, int location, String wait) Press a key with optional modifiers on the current desktop.
int	press(String key, String wait) Press a key with optional modifiers on the current desktop.
int	press(String key, String wait, int count) Press a key with optional modifiers on the current desktop once or more times.
int	report(File out) Start the default report provider to generate a report on test script execution.
int	report(File out, String description) Start the default report provider to generate a report on test script execution.
int	report(File out, String provider, String description) Start the specified report provider to generate a report on test script execution.
int	report(File out, String provider, String description, String scope) Start the specified report provider to generate a report on test script execution.
int	run(String script) Execute a TPR test script (.tpr) or a source Java file (.java) or instantiate & execute a Java test script specified by a fully qualified class name (with package).
int	run(String script, Object... parameters) Execute a test script with optional parameters.
int	screenshot(File file) Take a screen shot of the remote desktop and save it to a file.
int	screenshot(File file, Rectangle area) Take a screen shot of the remote desktop or its part and save it to a file.
int	screenshot(File file, String description) Take a screen shot of the remote desktop and save it to a file.
int	screenshot(File file, String description, Rectangle area) Take a screen shot of the remote desktop or its part and save it to a file.
int	screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, boolean drawResults) Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s).
int	screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, boolean drawResults) Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s).
int	screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, boolean drawResults, boolean drawDiff) Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s).
int	screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, String sort, boolean drawResults) Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison with the given template(s) using the Enterprise Image Search v2 method (code "search2").
int	screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, String sort, boolean drawResults, boolean drawDiff) Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison with the given template(s) using the Enterprise Image Search v2 method (code "search2").
int	screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, String text, int distance, String pattern, boolean drawResults) Take a screen shot of the remote desktop or its part, save it to a file and call the Image Based Text Recognition comparison method to recognize text from the desktop image or its part.
int	screenshot(File file, String description, Rectangle area, File[] templates, String method, float passRate) Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
int	screenshot(File file, String description, Rectangle area, File[] templates, String method, float passRate, Integer rgbTolerance) Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
int	screenshot(File file, String description, Rectangle area, File[] templates, String method, float passRate, Rectangle cmpArea) Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
int	screenshot(File file, String description, Rectangle area, File[] templates, String method, String methodParams, float passRate, Rectangle cmpArea) Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
int	screenshot(File file, String description, Rectangle area, File[] templates, String method, String methodParams, float passRate, Rectangle cmpArea, boolean drawResults) Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
int	screenshot(File file, String description, Rectangle area, File[] templates, String method, String methodParams, float passRate, Rectangle cmpArea, boolean drawResults, boolean drawDiff) Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
int	screenshot(File file, String description, Rectangle area, File[] templates, String method, String methodParams, float passRate, Rectangle cmpArea, Integer rgbTolerance, boolean drawResults) Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
int	screenshot(File file, String description, Rectangle area, File[] templates, String method, String methodParams, float passRate, Rectangle cmpArea, Integer rgbTolerance, boolean drawResults, boolean drawDiff) Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
int	screenshot(File file, String description, Rectangle area, File template, float passRate, Rectangle cmpArea, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear) Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison using the Object Search method.
int	screenshot(File file, String description, Rectangle area, Image[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, boolean drawResults) Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s).
int	screenshot(File file, String description, Rectangle area, Image[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, boolean drawResults) Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s).
int	screenshot(File file, String description, Rectangle area, Image[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, boolean drawResults, boolean drawDiff) Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s).
int	screenshot(File file, String description, Rectangle area, Image[] templates, String method, String methodParams, float passRate, Rectangle cmpArea) Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
int	screenshot(File file, String description, Rectangle area, Image[] templates, String method, String methodParams, float passRate, Rectangle cmpArea, boolean drawResults) Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
int	screenshot(File file, String description, Rectangle area, Image[] templates, String method, String methodParams, float passRate, Rectangle cmpArea, boolean drawResults, boolean drawDiff) Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
int	screenshot(File file, String description, Rectangle area, Rectangle cmpArea, String language, float scale, String text, int distance, String pattern) Take a screen shot of the remote desktop or its part, save it to a file and perform Tesseract OCR to recognize text from the desktop image or its part.
int	screenshot(File file, String description, Rectangle area, Rectangle cmpArea, String language, String text, String pattern) Take a screen shot of the remote desktop or its part, save it to a file and perform Tesseract OCR to recognize text from the desktop image or its part.
int	script(String number, boolean isEnd, String name) Define start or end of a script (test case).
int	scriptEnd(String number) Define end of a script (test case).
int	scriptEnd(String number, String name) Define end of a script (test case).
int	scriptStart(String number) Define start of a script (test case).
int	scriptStart(String number, String name) Define start of a script (test case).
int	sendMail(String subject, String text) Send an E-mail of the specified subject and text to one or more recipients through an SMTP server which requires no authentication.
int	sendMail(String subject, String text, File[] attachments) Send an E-mail of the specified subject, text and optional file attachments to one or more recipients through an SMTP server which requires no authentication.
int	sendMail(String password, String subject, String text) Send an E-mail of the specified subject and text to one or more recipients through an SMTP server.
int	sendMail(String password, String subject, String text, File[] attachments, boolean debug) Send an E-mail of the specified subject, text and optional file attachments to one or more recipients through an SMTP server.
int	sendMail(String server, String user, String password, String from, String to, String subject, String text, File[] attachments, boolean debug) Send an E-mail of the specified subject, text and optional file attachments to one or more recipients through an SMTP server.
void	setOutputDir(String dir) Set the output path.
void	setTemplateDir(String dir) Set the template path.
int	step(String name, String result, String instructions, String expected, String actual, String notes) Define result of a particular test step.
int	stepFail(String name, String instructions) Define a failed (unsuccessful) test step.
int	stepFailed(String name, String instructions, String expected, String actual, String notes) Define a failed (unsuccessful) test step.
int	stepNotAvailable(String name, String instructions, String expected, String actual, String notes) Define a test step whose result is not available.
int	stepNotTested(String name, String instructions, String expected, String actual, String notes) Define a test step which was not (yet) tested.
int	stepPassed(String name, String instructions) Define a passed (successful) test step.
int	stepPassed(String name, String instructions, String expected, String actual, String notes) Define a passed (successful) test step.
int	stringIndexOf(String text, String string) The method provides access to functionality of the String indexof command.
int	stringIndexOf(String text, String string, int start, int end, String variableName) The method provides access to functionality of the String indexof command.
int	stringIndexOf(String text, String string, String variableName) The method provides access to functionality of the String indexof command.
int	stringLength(String text) The method provides access to functionality of the String length command.
int	stringLength(String text, String variableName) The method provides access to functionality of the String length command.
int	stringMatches(String text, String pattern) The method provides access to functionality of the String matches command.
int	stringMatches(String text, String pattern, String variableName) The method provides access to functionality of the String matches command.
int	stringReplace(String text, String string, String replacement) The method provides access to functionality of the String replace command.
int	stringReplace(String text, String string, String replacement, String variableName) The method provides access to functionality of the String replace command.
int	stringReplacePattern(String text, String pattern, String replacement) The method provides access to functionality of the String replace command.
int	stringReplacePattern(String text, String pattern, String replacement, String variableName) The method provides access to functionality of the String replace command.
int	stringSplit(String text, String delimeter) The method provides access to functionality of the String split command.
int	stringSplit(String text, String delimeter, String variableName) The method provides access to functionality of the String split command.
int	stringSplitByPattern(String text, String pattern) The method provides access to functionality of the String split command.
int	stringSplitByPattern(String text, String pattern, String variableName) The method provides access to functionality of the String split command.
int	stringSubstring(String text, Integer start, Integer end) The method provides access to functionality of the String substring command.
int	stringSubstring(String text, Integer start, Integer end, String variableName) The method provides access to functionality of the String substring command.
int	stringToString(String codeList) The method provides access to functionality of the String tostring command.
int	stringToString(String codeList, String variableName) The method provides access to functionality of the String tostring command.
int	stringTrim(String text, String variableName) The method provides access to functionality of the String trim command.
void	test() Empty test method implementing the JavaTestScript interface.
int	timer(String names, String description) Create and/or configure timer(s).
int	timer(String names, String description, long value, long referenceValue) Create and/or configure timer(s).
int	timer(String names, String description, long value, long referenceValue, String group, String ungroup, File referenceFile) Create and/or configure timer(s) and/or timer groups.
int	timerGroup(String names, String group) Associate timer(s) with a timer group or groups.
int	timerLoad(File referenceFile) The method loads Timer reference data from an XML file previously generated through the Report command (see also report(java.io.File)).
int	timerStart(String names) Start timer(s).
int	timerStart(String names, String description, long value, long referenceValue, String group, String ungroup) Create and/or configure timer(s) and/or timer groups and start it (them).
int	timerStop(String names) Stop timer(s) and/or timer groups.
int	timerStop(String names, String description, long value, long referenceValue, String group, String ungroup) Stop timer(s) and/or timer groups.
int	timerUngroup(String names, String ungroup) Remove timer(s) from a timer group or groups.
int	type(String text) Type a text on the current desktop.
int	type(String text, int count, int location, String wait) Type a text on the current desktop.
int	type(String text, int count, String wait) Type a text on the current desktop.
int	type(String text, String wait) Type a text on the current desktop.
int	typeLine(String text) Type a text and press an Enter key on the current desktop.
int	typeLine(String text, int count, int location, String wait) Type a text and press an Enter key on the current desktop once or more times.
int	typeLine(String text, int count, String wait) Type a text and press an Enter key on the current desktop once or more times.
int	typeLine(String text, String wait) Type a text and press an Enter key on the current desktop.
int	wait(String time) Postpone execution of the test script for the specified time period.
int	waitForBell(int count, String timeout, String wait) Wait until the remote desktop emits one or more beeps (bells).
int	waitForBell(String timeout) Wait until the remote desktop beeps (rings a bell).
int	waitForBell(String timeout, String wait) Wait until the remote desktop beeps (rings a bell).
int	waitForClipboard(String timeout)
int	waitForClipboard(String timeout, String wait)
int	waitForMatch(File[] templates) Pause the script indefinitely until the default image comparison method produces a positive result for at least one of the template.
int	waitForMatch(File[] templates, float passRate, Rectangle cmpArea, String interval, String timeout, String text, int distance, String pattern, String wait) Pause the script until the text recognized through the Image Based Text Recognition comparison method contains a string or matches a regular expression or until the time out limit is reached.
int	waitForMatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, String wait) Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
int	waitForMatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, String wait) Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
int	waitForMatch(File[] templates, float passRate, String method, Rectangle cmpArea, String timeout, String wait)
int	waitForMatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, String sort, String wait) Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
int	waitForMatch(File[] templates, float passRate, String method, String timeout)
int	waitForMatch(File[] templates, float passRate, String interval, String method, String methodParams, Rectangle cmpArea, String timeout, String wait) Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
int	waitForMatch(File[] templates, String timeout)
int	waitForMatch(File[] templates, String method, String timeout)
int	waitForMatch(File template, float passRate, String interval, Rectangle cmpArea, String timeout, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, String wait) Pause the script until the current remote desktop contains at least one object located by the Object Search image comparison method.
int	waitForMatch(Image[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, String wait) Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
int	waitForMatch(Image[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, String wait) Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
int	waitForMatch(Image[] templates, float passRate, String interval, String method, String methodParams, Rectangle cmpArea, String timeout, String wait) Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
int	waitForMatch(Image template, float passRate, String interval, Rectangle cmpArea, String timeout, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, String wait) Pause the script until the current remote desktop contains at least one object located by the Object Search image comparison method.
int	waitForMatch(String interval, Rectangle cmpArea, String timeout, String language, float scale, String text, int distance, String pattern, String wait) Pause the script until the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached.
int	waitForMatch(String interval, Rectangle cmpArea, String timeout, String language, String text, String pattern, String wait) Pause the script until the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached.
int	waitForMismatch(File[] templates) Wait as long as at least one of the specified template images matches the screen.
int	waitForMismatch(File[] templates, float passRate, Rectangle cmpArea, String interval, String timeout, String text, int distance, String pattern, String wait) Pause the script as long as the text recognized through the Image Based Text Recognition comparison method contains a string or matches a regular expression or until the time out limit is reached.
int	waitForMismatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, String wait) Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached.
int	waitForMismatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, String wait) Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached.
int	waitForMismatch(File[] templates, float passRate, String method, Rectangle cmpArea, String timeout, String wait)
int	waitForMismatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, String sort, String wait) Pause the script as long as the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
int	waitForMismatch(File[] templates, float passRate, String method, String timeout)
int	waitForMismatch(File[] templates, float passRate, String interval, String method, String methodParams, Rectangle cmpArea, String timeout, String wait) Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached.
int	waitForMismatch(File[] templates, String timeout)
int	waitForMismatch(File[] templates, String method, String timeout)
int	waitForMismatch(File template, float passRate, String interval, Rectangle cmpArea, String timeout, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, String wait) Pause the script as long as the current remote desktop contains at least one object located by the Object Search image comparison method.
int	waitForMismatch(Image[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, String wait) Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached.
int	waitForMismatch(Image[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, String wait) Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached.
int	waitForMismatch(Image[] templates, float passRate, String interval, String method, String methodParams, Rectangle cmpArea, String timeout, String wait) Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached.
int	waitForMismatch(Image template, float passRate, String interval, Rectangle cmpArea, String timeout, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, String wait) Pause the script as long as the current remote desktop contains at least one object located by the Object Search image comparison method.
int	waitForMismatch(String interval, Rectangle cmpArea, String timeout, String language, float scale, String text, int distance, String pattern, String wait) Pause the script as long as the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached.
int	waitForMismatch(String interval, Rectangle cmpArea, String timeout, String language, String text, String pattern, String wait) Pause the script as long as the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached.
int	waitForUpdate(Rectangle area, String extent, boolean cumulative, String timeout, String wait) Wait until the remote desktop refreshes the screen or its particular area.
int	waitForUpdate(Rectangle area, String extent, String timeout) Wait until the remote desktop refreshes the screen or its particular area.
int	waitForUpdate(Rectangle area, String extent, String timeout, String wait) Wait until the remote desktop refreshes the screen or its particular area.
int	waitForUpdate(String extent, String timeout) Wait until the remote desktop refreshes the whole screen.
int	warning(String text) Add a warning to be picked up by a report provider.
int	warning(String text, File image) Add a warning to be picked up by a report provider.

Methods inherited from class com.tplan.robot.scripting.AbstractJavaTestScript

callByName, getContext, getDocument, getLineNumber, getLineNumber, getOutputDir, getParentWrapper, getScriptFile, getScriptManager, getTemplateDir, getTestSource, getVariable, getVariableAsBoolean, getVariableAsColor, getVariableAsFloat, getVariableAsInt, getVariableAsPoint, getVariableAsRectangle, getVariableAsString, getWrapperType, importVariables, isDebug, isPaused, mouseEvent, resume, runScriptCommand, setContext, setDebug, setDocument, setInterpret, setTestSource, setVariable, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DefaultJavaTestScript

public DefaultJavaTestScript()

Method Detail

test

public void test()

Empty test method implementing the JavaTestScript interface. Override this method with your own test code to create a Java test script.

getRootWrapper

public TestWrapper getRootWrapper()

connect

public int connect(String host,
                   String user,
                   String password,
                   Map<String,Object> params,
                   boolean force)
            throws IOException

Connect to a desktop. This method has the same functionality as the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) one save that it allows to specify custom parameters through a map of objects. This is useful for programmatic connections to a desktop whose client requires a custom parameter which has other than String value.

Parameters:

host - host connection URI. It can not be null. See the method description for information about its format.

user - user name for plain text password authentication. It may be null for servers which do not require this authentication scheme.

password - password for plain text password authentication. It may be null for servers which do not require this authentication scheme.

params - custom client parameters in form of a map with [param_name, param_value] pairs. Note that this is a generic mechanism to allow future plugins of clients which use custom ways of authentication and login parameters. The two built in RFB and Java clients do not support at the moment any custom parameters.

force - true will force reconnection even if the tool is already connected to the same server. A value of false will cause the method to check whether a connection to the specified server already exists and connect only in case it is not so. Default value is false.

Returns:

command exit code as is specified in the Connect specification.

Throws:

IOException - if an I/O error happens during client-server communication.

connect

public int connect(String host,
                   String user,
                   String password,
                   String params,
                   String paramSeparator,
                   boolean force)
            throws IOException

Connect to a desktop. The method provides access to functionality of the Connect scripting language command. The host argument must be a valid URL in form of <protocol>://<host_or_IP>[:<port>] where the protocol must be equal to one of the installed client plugin codes. If port is not explicitly specified, it defaults to the default protocol-specific port provided by the RemoteDesktopClient.getDefaultPort() method. For more information on host string format see documentation of particular desktop clients.

If protocol is omitted in the URL, the host defaults to the RFB (VNC) protocol to provide backward compatibility with VNCRobot 1.x. Port number is in this case considered to be a display number rather than real port. To get a real port take the display number and add it to 5900 which is the default RFB port. 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. To specify the same address in the standard URL form one has to list the real port specifically and the equivalent URL is "rfb://localhost:5901".

The connect method supports by default just servers with either none or plain user/password authentication. Both user and password parameters may be also passed through CLI or programmatically among parameters of the ApplicationSupport.createAutomatedRunnable(com.tplan.robot.scripting.JavaTestScript, java.lang.String, java.lang.String[], java.io.PrintStream, boolean) method. Clients which use custom authentication schemes must use a different ways of passing custom connection parameters to the script, such as script variables (specified from CLI using -v/--variable and available during script execution through getContext().getVariable()). An alternative way is to use the framework of user preferences together with the -o/--option CLI switch.

As the connection mechanism was enhanced with connection pooling since version 2.2, the method may but doesn't necessarily have to create a new client and go through the connection sequence depending on whether the pooling mode is on and there's a free already connected client available. Read more about connection pooling in the RemoteDesktopClientFactory class.

Note that the method doesn't throw any exception on standard situations, such as failures to connect or authenticate. These cases are reported through the return value which should be checked by the script. If a value other than zero is returned to report failure, the connect exception may be obtained through the ScriptingContext.getConnectError() method. The IOException declared by this method is thrown only on unrecognized I/O errors which may happen during the initialization of the connection, for example an intermittent network failure.

Examples:

• connect("localhost", null, null, false) will attempt to connect to the RFB (VNC) server running on the default port 5900 of the local system. As no password is provided, the server is expected to require no authentication.
  
• connect("rfb://localhost:5901", null, "welcome", false) will attempt to connect to the RFB (VNC) server running on the port 5901 of the local system. This is a typical setup on Linux/Unix where the default port of 5900 is occupied by the system X-server. The host string can be in this case also specified as "localhost:1" or "localhost::5901". As a password is provided, the client will use it to authenticate if the server requests it. User name may be null because RFB requires just a password.
  
• connect("java://192.168.1.1:1099", null, null, false) will connect to the display of the host with IP address 192.168.1.1 through the Java native client using RMI. The host machine must have Java installed and it must be executing T-Plan Robot Enterprise in the Java server mode. See the Java client documentation for more.
  
• connect("java://localhost", null, null, false) will connect to the local system display (meaning the very same desktop you see on your screen or other display device) through the Java native client.
  
• connect("rdp://192.168.1.1:1234", "Administrator", "welcome", true) will connect to an RDP server running on port 1234 of the system with IP address 192.168.1.1. If T-Plan Robot Enterprise is already connected to the given system, the connection is terminated and the application reconnects because the force is set to true. The server is expected to require a user name and plain password authentication. Note that this example is just illustrative because RDP is not yet directly supoported..
  

Parameters:

host - host connection URI. It can not be null. See the method description for information about its format.

user - user name for plain text password authentication. It may be null for servers which do not require this authentication scheme.

password - password for plain text password authentication. It may be null for servers which do not require this authentication scheme.

params - custom client parameters. Through the client framework supports by default just URI (protocol+host+port), user name and password parameters, this parameter allows to pass any custom parameter to a custom client. The list may contain any number of parameter name and value pairs separated by comma (',') or a custom separator specified by the paramSeparator argument. For example, to specify two parameters PARAM_A=value_A and PARAM_B=valueB the argument should look like "PARAM_A,valueA,PARAM_B,valueB". Note that this is a generic mechanism to allow future plugins of clients which use custom ways of authentication and login parameters. The two built in RFB and Java clients do not support at the moment any custom parameters.

paramSeparator - optional separator for the list of parameter names and values specified by the params argument. If it is null, it defaults to comma (",").

force - true will force reconnection even if the tool is already connected to the same server. A value of false will cause the method to check whether a connection to the specified server already exists and connect only in case it is not so. Default value is false.

Returns:

command exit code as is specified in the Connect specification.

Throws:

IOException - if an I/O error happens during client-server communication.

connect

public int connect(String host,
                   String user,
                   String password,
                   boolean force)
            throws IOException

Connect to a server using the specified user and password. As this is just a convenience method calling the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) one, see its documentation for a complete description of the method behavior.

Parameters:

host - host connection URI. It can not be null. See the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) method description for information about its format.

user - user name for plain text password authentication. It may be null for servers which do not require this authentication scheme.

password - password for plain text password authentication. It may be null for servers which do not require this authentication scheme.

force - true will force reconnection even if the tool is already connected to the same server. A value of false will cause the method to check whether a connection to the specified server already exists and connect only in case it is not so. Default value is false.

Returns:

command exit code as is specified in the Connect specification.

Throws:

IOException - if an I/O error happens during client-server communication.

connect

public int connect(String host,
                   String password)
            throws IOException

Connect to a server which may or may not require a password. This is typical for RFB (VNC) servers which support none or just password (without user name) authentication schemes. If the connection already exists, do not reconnect (force=false).

As this is just a convenience method calling the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) one, see its documentation for a complete description of the method behavior.

Parameters:

host - host connection URI. It can not be null. See the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) method description for information about its format.

password - password for plain text password authentication. It may be null for servers which do not require this authentication scheme.

Returns:

command exit code as is specified in the Connect specification.

Throws:

IOException - if an I/O error happens during client-server communication.

connect

public int connect(String host,
                   boolean force)
            throws IOException

Connect to a server which requires no authentication (for example a Java client or an RFB/VNC server which is configured this way).

As this is just a convenience method calling the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) one, see its documentation for a complete description of the method behavior.

Parameters:

host - host connection URI. It can not be null. See the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) method description for information about its format.

force - true will force reconnection even if the tool is already connected to the same server. A value of false will cause the method to check whether a connection to the specified server already exists and connect only in case it is not so. Default value is false.

Returns:

command exit code as is specified in the Connect specification.

Throws:

IOException - if an I/O error happens during client-server communication.

connect

public int connect(String host)
            throws IOException

Connect to a server which requires no authentication (for example a Java client or an RFB/VNC server which is configured this way). If the connection already exists, do not reconnect (force=false).

As this is just a convenience method calling the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) one, see its documentation for a complete description of the method behavior.

Parameters:

host - host connection URI. It can not be null. See the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) method description for information about its format.

Returns:

command exit code as is specified in the Connect specification.

Throws:

IOException - if an I/O error happens during client-server communication.

disconnect

public int disconnect()
               throws IOException

Disconnect from a desktop. The method provides access to functionality of the Disconnect scripting language command. If there's a connection to a desktop, it gets closed through RemoteDesktopClient.close(). If the tool is not connected to any desktop the method does nothing.

Returns:

command exit code as is specified in the Disconnect specification.

Throws:

IOException - if an I/O error happens during the connection shutdown.

mouseEvent

public int mouseEvent(String action,
                      int modifiers,
                      int button,
                      Point from,
                      Point to,
                      int count,
                      String wait)
               throws IOException

Perform a generic mouse action on the currently connected desktop. The method provides access to functionality of the Mouse scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

action - mouse action string as is defined in the Mouse command specification. Supported values are move, click, drag, press, release, wheelup and wheeldown. The action codes are not case sensitive.

modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK

button - mouse button ID as specified in MouseEvent. Supported values are MouseEvent.BUTTON1 (left button), MouseEvent.BUTTON2 (middle button) and MouseEvent.BUTTON3 (right button). If any other value is used, the argument defaults to the left button. This argument applies only to mouse events which involve buttons, such as mouse click, press, release and drag.

from - start point of a mouse move or drag event. If the argument is null, it defaults to the current desktop mouse pointer position. The value is ignored by other actions.

to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.

count - how many times to repeat the event. It applies only to mouse clicks and wheel events and it is ignored by other ones. Default value is 1 (one). Delays among multiple clicks are defined by a value in the Mouse command user preferences.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication or if no desktop is connected.

mouseMove

public int mouseMove(Point to,
                     String wait)
              throws IOException

Perform a mouse move on the currently connected desktop. The method provides access to functionality of the Mouse move scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseMove

public int mouseMove(Point to,
                     int modifiers,
                     String wait)
              throws IOException

Perform a mouse move on the currently connected desktop with optional modifier key(s) pressed. The method provides access to functionality of the Mouse move scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.

modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseMove

public int mouseMove(Point to)
              throws IOException

Perform a mouse move on the currently connected desktop. The method provides access to functionality of the Mouse move scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseMove

public int mouseMove(int x,
                     int y,
                     String wait)
              throws IOException

Perform a mouse move on the currently connected desktop. The method provides access to functionality of the Mouse move scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

x - X-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseMove

public int mouseMove(int x,
                     int y,
                     int modifiers,
                     String wait)
              throws IOException

Perform a mouse move on the currently connected desktop with optional modifier key(s) pressed. The method provides access to functionality of the Mouse move scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

x - X-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseMove

public int mouseMove(int x,
                     int y)
              throws IOException

Perform a mouse move on the currently connected desktop. The method provides access to functionality of the Mouse move scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

x - X-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(Point to,
                      int modifiers,
                      int button,
                      int count,
                      String wait)
               throws IOException

Perform left mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.

modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK

button - mouse button ID as specified in MouseEvent. Supported values are MouseEvent.BUTTON1 (left button), MouseEvent.BUTTON2 (middle button) and MouseEvent.BUTTON3 (right button). If any other value is used, the argument defaults to the left button. This argument applies only to mouse events which involve buttons, such as mouse click, press, release and drag.

count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(Point to,
                      int count,
                      String wait)
               throws IOException

Perform left mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

The method was introduced in the 3.0 release to allow the script recorder to produce shorter and better readable code.

Parameters:

to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.

count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

Since:

3.0

mouseClick

public int mouseClick(Point to,
                      int count)
               throws IOException

Perform left mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.

count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(Point to,
                      String wait)
               throws IOException

Perform a single left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(Point to)
               throws IOException

Perform a single left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(int x,
                      int y,
                      int count,
                      String wait)
               throws IOException

Perform left mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

x - X-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(int x,
                      int y,
                      int count)
               throws IOException

Perform left mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

x - X-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(int x,
                      int y)
               throws IOException

Perform a single left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

x - X-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(Point to,
                           int modifiers,
                           int count,
                           String wait)
                    throws IOException

Perform right mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.

modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK

count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(Point to,
                           int count,
                           String wait)
                    throws IOException

Perform right mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.

count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(Point to,
                           int count)
                    throws IOException

Perform right mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.

count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(Point to)
                    throws IOException

Perform a single right mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(int x,
                           int y,
                           int count,
                           String wait)
                    throws IOException

Perform right mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

x - X-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(int x,
                           int y,
                           int count)
                    throws IOException

Perform right mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

x - X-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(int x,
                           int y)
                    throws IOException

Perform a single right mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

x - X-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseDoubleClick

public int mouseDoubleClick(Point to,
                            String wait)
                     throws IOException

Perform a double left mouse click on the current desktop client. The method provides access to functionality of the Mouse click button=left count=2 scripting language command.

Perform a double left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left count=2 scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseDoubleClick

public int mouseDoubleClick(Point to)
                     throws IOException

Perform a double left mouse click on the current desktop client. The method provides access to functionality of the Mouse click button=left count=2 scripting language command.

Perform a double left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left count=2 scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseDoubleClick

public int mouseDoubleClick(int x,
                            int y,
                            String wait)
                     throws IOException

Perform a double left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left count=2 scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

x - X-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseDoubleClick

public int mouseDoubleClick(int x,
                            int y)
                     throws IOException

Perform a double left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left count=2 scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

x - X-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseDrag

public int mouseDrag(Point from,
                     Point to,
                     int modifiers,
                     int button,
                     String wait)
              throws IOException

Perform a left button mouse drag on the currently connected desktop. The method provides access to functionality of the Mouse drag button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK

button - mouse button ID as specified in MouseEvent. Supported values are MouseEvent.BUTTON1 (left button), MouseEvent.BUTTON2 (middle button) and MouseEvent.BUTTON3 (right button). If any other value is used, the argument defaults to the left button. This argument applies only to mouse events which involve buttons, such as mouse click, press, release and drag.

from - start point of the drag. If the argument is null, it defaults to the current desktop mouse pointer position. The value is ignored by other actions.

to - target drag point (drop location). If the argument is null, it defaults to the current desktop mouse pointer position.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseRightDrag

public int mouseRightDrag(Point from,
                          Point to,
                          int modifiers,
                          String wait)
                   throws IOException

Perform a right button mouse drag on the currently connected desktop. The method provides access to functionality of the Mouse drag btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK

from - start point of the drag. If the argument is null, it defaults to the current desktop mouse pointer position. The value is ignored by other actions.

to - target drag point (drop location). If the argument is null, it defaults to the current desktop mouse pointer position.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseWheelUp

public int mouseWheelUp(Point to,
                        int modifiers,
                        int count,
                        String wait)
                 throws IOException

Scroll up the mouse wheel on the current desktop. The method provides access to functionality of the Mouse wheelup scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK

to - location to move the mouse pointer to before performing the wheel scroll. If the argument is null, it defaults to the current desktop mouse pointer position.

count - how many wheel steps to scroll up. Default value is 1 (one mouse wheel step). Delays among multiple steps are defined by a value in the Mouse command user preferences.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseWheelUp

public int mouseWheelUp(int x,
                        int y,
                        int modifiers,
                        int count,
                        String wait)
                 throws IOException

Scroll up the mouse wheel on the current desktop. The method provides access to functionality of the Mouse wheelup scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK

x - X-coordinate of the mouse pointer to move to before scrolling the wheel. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of the mouse pointer to move to before scrolling the wheel. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

count - how many wheel steps to scroll up. Default value is 1 (one mouse wheel step). Delays among multiple steps are defined by a value in the Mouse command user preferences.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseWheelDown

public int mouseWheelDown(Point to,
                          int modifiers,
                          int count,
                          String wait)
                   throws IOException

Scroll down the mouse wheel on the current desktop. The method provides access to functionality of the Mouse wheeldown scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK

to - location to move the mouse pointer to before performing the wheel scroll. If the argument is null, it defaults to the current desktop mouse pointer position.

count - how many wheel steps to scroll up. Default value is 1 (one mouse wheel step). Delays among multiple steps are defined by a value in the Mouse command user preferences.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

mouseWheelDown

public int mouseWheelDown(int x,
                          int y,
                          int modifiers,
                          int count,
                          String wait)
                   throws IOException

Scroll down the mouse wheel on the current desktop. The method provides access to functionality of the Mouse wheeldown scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK

x - X-coordinate of the mouse pointer to move to before scrolling the wheel. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.

y - Y-coordinate of the mouse pointer to move to before scrolling the wheel. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.

count - how many wheel steps to scroll up. Default value is 1 (one mouse wheel step). Delays among multiple steps are defined by a value in the Mouse command user preferences.

wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Mouse specification.

Throws:

IOException - if an I/O error happens during client-server communication.

type

public int type(String text,
                int count,
                int location,
                String wait)
         throws IOException

Type a text on the current desktop. The method provides access to functionality of the Type scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.

count - how many times to repeat typing of the text. Default value is 1 (type the text once). Delays among multiple typings are defined by a value in the Type command user preferences.

location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method 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.

wait - how long to wait after the text is typed to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Type specification.

Throws:

IOException - if an I/O error happens during client-server communication.

type

public int type(String text,
                int count,
                String wait)
         throws IOException

Type a text on the current desktop. The method provides access to functionality of the Type scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.

count - how many times to repeat typing of the text. Default value is 1 (type the text once). Delays among multiple typings are defined by a value in the Type command user preferences.

wait - how long to wait after the text is typed to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Type specification.

Throws:

IOException - if an I/O error happens during client-server communication.

type

public int type(String text,
                String wait)
         throws IOException

Type a text on the current desktop. The method provides access to functionality of the Type scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.

wait - how long to wait after the text is typed to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Type specification.

Throws:

IOException - if an I/O error happens during client-server communication.

type

public int type(String text)
         throws IOException

Type a text on the current desktop. The method provides access to functionality of the Type scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.

Returns:

command exit code as is specified in the Type specification.

Throws:

IOException - if an I/O error happens during client-server communication.

typeLine

public int typeLine(String text,
                    int count,
                    int location,
                    String wait)
             throws IOException

Type a text and press an Enter key on the current desktop once or more times. It is equivalent to a Type command followed by a Press Enter. The method provides access to functionality of the Typeline scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.

count - how many times to repeat typing of the text. Default value is 1 (type the text once). Delays among multiple typings are defined by a value in the Type command user preferences.

location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method 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.

wait - how long to wait after the text is typed to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Typeline specification.

Throws:

IOException - if an I/O error happens during client-server communication.

typeLine

public int typeLine(String text,
                    int count,
                    String wait)
             throws IOException

Type a text and press an Enter key on the current desktop once or more times. It is equivalent to a Type command followed by a Press Enter. The method provides access to functionality of the Typeline scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.

count - how many times to repeat typing of the text. Default value is 1 (type the text once). Delays among multiple typings are defined by a value in the Type command user preferences.

wait - how long to wait after the text is typed to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Typeline specification.

Throws:

IOException - if an I/O error happens during client-server communication.

typeLine

public int typeLine(String text,
                    String wait)
             throws IOException

Type a text and press an Enter key on the current desktop. It is equivalent to a Type command followed by a Press Enter. The method provides access to functionality of the Typeline scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.

wait - how long to wait after the text is typed to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Typeline specification.

Throws:

IOException - if an I/O error happens during client-server communication.

typeLine

public int typeLine(String text)
             throws IOException

Type a text and press an Enter key on the current desktop. It is equivalent to a Type command followed by a Press Enter. The method provides access to functionality of the Typeline scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:

text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.

Returns:

command exit code as is specified in the Typeline specification.

Throws:

IOException - if an I/O error happens during client-server communication.

press

public int press(String key,
                 int location,
                 int count,
                 Boolean release,
                 String delay,
                 String wait)
          throws IOException

Press a key with optional modifiers on the current desktop once or more times. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers 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 this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. 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.

Parameters:

key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.

location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method 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.

count - how many times to repeat the key press. Default value is 1 (press the key once). Delays among multiple press actions are defined by a value in the Press Command user preferences.

release - if this argument is null the method performs the standard key press-release sequence automating typing of a key on the keyboard. When the argument is populated the command performs just a key press (release=false) or a key release (release=true). This allows to automate long key presses and/or composed press and mouse events. If you use this parameter make sure that each key press is paired with a later key release.

delay - how long to wait between the key press and release. This value is by default loaded from the Press command configuration. This parameter allows to customize it for a single command call. It is handy for example on mobile devices where certain functionality gets activated through a longer key press. Value of this parameter must be a valid time value specified by the Time Values chapter of the language specification. Use null to apply the default value.

wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Press specification.

Throws:

IOException - if an I/O error happens during client-server communication.

press

public int press(String key,
                 int location,
                 int count,
                 String delay,
                 String wait)
          throws IOException

Press a key with optional modifiers on the current desktop once or more times. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers 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 this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. 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.

Parameters:

key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.

location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method 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.

count - how many times to repeat the key press. Default value is 1 (press the key once). Delays among multiple press actions are defined by a value in the Press Command user preferences.

delay - how long to wait between the key press and release. This value is by default loaded from the Press command configuration. This parameter allows to customize it for a single command call. It is handy for example on mobile devices where certain functionality gets activated through a longer key press. Value of this parameter must be a valid time value specified by the Time Values chapter of the language specification. Use null to apply the default value.

wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Press specification.

Throws:

IOException - if an I/O error happens during client-server communication.

press

public int press(String key,
                 int location,
                 int count,
                 String wait)
          throws IOException

Press a key with optional modifiers on the current desktop once or more times. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers 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 this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. 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.

Parameters:

key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.

location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method 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.

count - how many times to repeat the key press. Default value is 1 (press the key once). Delays among multiple press actions are defined by a value in the Press Command user preferences.

wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Press specification.

Throws:

IOException - if an I/O error happens during client-server communication.

press

public int press(String key,
                 String wait,
                 int count)
          throws IOException

Press a key with optional modifiers on the current desktop once or more times. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers 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 this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. 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.

Parameters:

key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.

count - how many times to repeat the key press. Default value is 1 (press the key once). Delays among multiple press actions are defined by a value in the Press Command user preferences.

wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Press specification.

Throws:

IOException - if an I/O error happens during client-server communication.

press

public int press(char c,
                 int location,
                 int count,
                 String delay,
                 String wait)
          throws IOException

Press a character with optional modifiers on the current desktop once or more times. The method provides access to functionality of the Press scripting language command.

Transferable characters and key combinations are further on subject to limitations applied by the desktop client. 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.

Parameters:

c - a character to press. This method doesn't support modifiers.

location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method 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.

count - how many times to repeat the character press. Default value is 1 (press the key once). Delays among multiple press actions are defined by a value in the Press Command user preferences.

delay - how long to wait between the key press and release. This value is by default loaded from the Press command configuration. This parameter allows to customize it for a single command call. It is handy for example on mobile devices where certain functionality gets activated through a longer key press. Value of this parameter must be a valid time value specified by the Time Values chapter of the language specification. Use null to apply the default value.

wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Press specification.

Throws:

IOException - if an I/O error happens during client-server communication.

press

public int press(char c,
                 int location,
                 int count,
                 String wait)
          throws IOException

Press a character with optional modifiers on the current desktop once or more times. The method provides access to functionality of the Press scripting language command.

Transferable characters and key combinations are further on subject to limitations applied by the desktop client. 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.

Parameters:

c - a character to press. This method doesn't support modifiers.

location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method 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.

count - how many times to repeat the character press. Default value is 1 (press the key once). Delays among multiple press actions are defined by a value in the Press Command user preferences.

wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Press specification.

Throws:

IOException - if an I/O error happens during client-server communication.

press

public int press(String key,
                 int location,
                 String wait)
          throws IOException

Press a key with optional modifiers on the current desktop. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers 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 this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. 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.

Parameters:

key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.

location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method 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.

wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Press specification.

Throws:

IOException - if an I/O error happens during client-server communication.

press

public int press(String key,
                 int location)
          throws IOException

Press a key with optional modifiers on the current desktop. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers 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 this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. 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.

Parameters:

key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.

location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method 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.

Returns:

command exit code as is specified in the Press specification.

Throws:

IOException - if an I/O error happens during client-server communication.

press

public int press(String key,
                 String wait)
          throws IOException

Press a key with optional modifiers on the current desktop. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers 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 this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. 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.

Parameters:

key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.

wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Press specification.

Throws:

IOException - if an I/O error happens during client-server communication.

press

public int press(String key)
          throws IOException

Press a key with optional modifiers on the current desktop. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers 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 this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. 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.

Parameters:

key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.

Returns:

command exit code as is specified in the Press specification.

Throws:

IOException - if an I/O error happens during client-server communication.

wait

public int wait(String time)

Postpone execution of the test script for the specified time period. The method provides access to functionality of the Wait scripting language command.

Parameters:

time - how long to wait. The argument must be in format specified by the Time Values chapter of the language specification. If the argument is null or zero, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Wait specification.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      Image[] templates,
                      float passRate,
                      Rectangle cmpArea,
                      boolean removeBg,
                      String bgColor,
                      Integer minAlpha,
                      Integer rgbTolerance,
                      boolean drawResults,
                      boolean drawDiff)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

removeBg -

set on/off filtering of background color from the template image. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

Since:

3.3.1

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      Image[] templates,
                      float passRate,
                      Rectangle cmpArea,
                      boolean removeBg,
                      String bgColor,
                      Integer minAlpha,
                      Integer rgbTolerance,
                      boolean drawResults)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

removeBg -

set on/off filtering of background color from the template image. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      Image[] templates,
                      float passRate,
                      Rectangle cmpArea,
                      boolean removeBg,
                      String bgColor,
                      Integer minAlpha,
                      boolean drawResults)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

removeBg -

set on/off filtering of background color from the template image. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      Image[] templates,
                      String method,
                      String methodParams,
                      float passRate,
                      Rectangle cmpArea,
                      boolean drawResults,
                      boolean drawDiff)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

Since:

3.3.1

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      Image[] templates,
                      String method,
                      String methodParams,
                      float passRate,
                      Rectangle cmpArea,
                      boolean drawResults)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      Image[] templates,
                      String method,
                      String methodParams,
                      float passRate,
                      Rectangle cmpArea)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      String method,
                      String methodParams,
                      float passRate,
                      Rectangle cmpArea,
                      Integer rgbTolerance,
                      boolean drawResults,
                      boolean drawDiff)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

Since:

3.3.1

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      String method,
                      String methodParams,
                      float passRate,
                      Rectangle cmpArea,
                      Integer rgbTolerance,
                      boolean drawResults)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      float passRate,
                      Rectangle cmpArea,
                      String sort,
                      boolean drawResults,
                      boolean drawDiff)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison with the given template(s) using the Enterprise Image Search v2 method (code "search2"). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:

• "best" - Put the best matching location first (default mode).
• "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
• "top" - Sort locations from the top to the bottom (topmost first).
• "bottom" - Sort locations from the bottom to the top (bottommost first).
• "left" - Sort locations from the left to the right (leftmost first).
• "right" - Sort locations from the right to the left (rightmost first).

When the argument is null the sort mode defaults to the "best" one.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). The "search2" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

Since:

3.3.1

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      float passRate,
                      Rectangle cmpArea,
                      String sort,
                      boolean drawResults)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison with the given template(s) using the Enterprise Image Search v2 method (code "search2"). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:

• "best" - Put the best matching location first (default mode).
• "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
• "top" - Sort locations from the top to the bottom (topmost first).
• "bottom" - Sort locations from the bottom to the top (bottommost first).
• "left" - Sort locations from the left to the right (leftmost first).
• "right" - Sort locations from the right to the left (rightmost first).

When the argument is null the sort mode defaults to the "best" one.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). The "search2" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      Rectangle cmpArea,
                      String language,
                      String text,
                      String pattern)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform Tesseract OCR to recognize text from the desktop image or its part. The method provides access to functionality of the Screenshot scripting language command combined with image comparison method fixed to "tocr" and support of its specific parameters. See also the TesseractOCR class documentation for details on how to install and configure Tesseract.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files.

text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      Rectangle cmpArea,
                      String language,
                      float scale,
                      String text,
                      int distance,
                      String pattern)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform Tesseract OCR to recognize text from the desktop image or its part. The method provides access to functionality of the Screenshot scripting language command combined with image comparison method fixed to "tocr" and support of its specific parameters. See also the TesseractOCR class documentation for details on how to install and configure Tesseract.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the OCR will be performed on the full desktop image.

language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files. If the parameter is null, it will default to the English one ("eng").

scale - magnification factor. The method magnifies (enlarges) the image by the given factor to improve OCR accuracy. If this parameter is set to a value below 0, it defaults to the value configured in the Tesseract OCR Plugin preferences (the factory setting is 2 meaning that the image shall be enlarged to 200% of its original size).

text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer 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 exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence 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. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      float passRate,
                      Rectangle cmpArea,
                      String text,
                      int distance,
                      String pattern,
                      boolean drawResults)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and call the Image Based Text Recognition comparison method to recognize text from the desktop image or its part. The method provides access to functionality of the Screenshot scripting language command combined with image comparison method fixed to "text" and support of its specific parameters.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

The resulting text from the method is stored in form of individual text lines to _TEXT_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TEXT_LINE_COUNT variable and can be retrieved using the getVariableAsInt("_TEXT_LINE_COUNT") method. The whole text including the new line characters as well as the map of text elements and their coordinates can be obtained directly from the context through the getContext().getRecognizedText(java.awt.Rectangle) and getContext().getRecognizedTextElements() methods.

If the method throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TEXT_ERROR variable.

Parameters:

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the recognition will be performed on the full desktop image.

text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the recognized text the method returns 0 to indicate success. Otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer 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 exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence 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. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the recognized text matches the regular expression, the method returns 0 to indicate success or 1 otherwise. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

Returns:

the exit code as is specified in the Image Based Text Recognition specification. When none of the "text", "distance" and "pattern" parameters is specified the method returns 0 (success) to indicate a successful execution even when no text gets actually recognized. If the text matching parameters are used the method will return either success (0) or fail (non-zero value) depending on whether the recognized text matches or not.

Throws:

IOException - on an I/O error (can't read an image file and/or can't get image of the remote desktop).

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      String method,
                      String methodParams,
                      float passRate,
                      Rectangle cmpArea,
                      boolean drawResults,
                      boolean drawDiff)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

Since:

3.3.1

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      String method,
                      String methodParams,
                      float passRate,
                      Rectangle cmpArea,
                      boolean drawResults)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      float passRate,
                      Rectangle cmpArea,
                      boolean removeBg,
                      String bgColor,
                      Integer minAlpha,
                      Integer rgbTolerance,
                      boolean drawResults,
                      boolean drawDiff)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

removeBg -

set on/off filtering of background color from the template image. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

Since:

3.3.1

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      float passRate,
                      Rectangle cmpArea,
                      boolean removeBg,
                      String bgColor,
                      Integer minAlpha,
                      Integer rgbTolerance,
                      boolean drawResults)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

removeBg -

set on/off filtering of background color from the template image. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      float passRate,
                      Rectangle cmpArea,
                      boolean removeBg,
                      String bgColor,
                      Integer minAlpha,
                      boolean drawResults)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

removeBg -

set on/off filtering of background color from the template image. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      String method,
                      String methodParams,
                      float passRate,
                      Rectangle cmpArea)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File template,
                      float passRate,
                      Rectangle cmpArea,
                      Color color,
                      Color[] bridgeColors,
                      Integer rgbTolerance,
                      Integer rotations,
                      Boolean draw,
                      Boolean clear)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison using the Object Search method. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

The method further on analyzes the current remote desktop image using the Object Search Method. It searches the desktop image or its rectangular part for objects of a particular color or colors within the tolerated RGB variance. 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 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. Than it follows the outer shape of each such an object until the shape gets closed. The objects are internally stored as a list of java.awt.Shape instances in the context and may be retrieved through the through the ScriptingContext.getObjectSearchShapes() convenience method. Besides the raw shape data the method also stores bounding rectangle of each object into the context in form of four variables _OBJECT_X_[n], _OBJECT_Y_[n], _OBJECT_W_[n] and _OBJECT_H_[n] which represent the top left corner [x,y] coordinates, width and height. The [n] expression is the object ordinary number starting from 1. The number of objects available is stored under the _OBJECT_COUNT variable. These variables are the only data exposed to the standard scripting language.

Parameters:

template - an optional template image to filter the list of objects by (a File instance). It must contain just one shape of the specified color and/or tolerance in any level of rotation. When it is provided, the list of objects will be filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the 'passrate' parameter. If the 'rotations' parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times.

If the template image is not specified, the algorithm locates all objects matching the color parameters regardless of their size or shape.

passRate - pass rate as percentage between 0 and 100. The pass rate makes sense only when the template is not null and specifies the percentage of acceptable pixel variance from the template image.

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

color - defines the object color.

bridgeColors - is optional list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. Colors in this list are always compared using the exact RGB match and they do not work with the rgbTolerance parameter.

rgbTolerance - RGB tolerance value. It must be an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the 'color' parameter. This value allows to deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. Be however aware that the higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

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

clear - optional boolean flag dealing with result highlighting in the GUI. The clear parameter allows to clear up all drawings created by the previously called object searches. The drawings are also automatically reset when the script finishes.

draw - optional boolean flag dealing with result highlighting in the GUI. When the draw parameter is 'true', the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component.

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      String method,
                      float passRate,
                      Rectangle cmpArea)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      String method,
                      float passRate)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area,
                      File[] templates,
                      String method,
                      float passRate,
                      Integer rgbTolerance)
               throws IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

templates - list of template images to compare the remote desktop image to.

method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.

passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description,
                      Rectangle area)
               throws IOException

Take a screen shot of the remote desktop or its part and save it to a file. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      String description)
               throws IOException

Take a screen shot of the remote desktop and save it to a file. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file,
                      Rectangle area)
               throws IOException

Take a screen shot of the remote desktop or its part and save it to a file. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

screenshot

public int screenshot(File file)
               throws IOException

Take a screen shot of the remote desktop and save it to a file. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:

file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.

Returns:

command exit code as is specified in the Screenshot specification.

Throws:

IOException - when an I/O error occurs.

sendMail

public int sendMail(String server,
                    String user,
                    String password,
                    String from,
                    String to,
                    String subject,
                    String text,
                    File[] attachments,
                    boolean debug)
             throws IOException

Send an E-mail of the specified subject, text and optional file attachments to one or more recipients through an SMTP server. The method provides access to functionality of the Sendmail scripting language command.

The method and the underlying command handler take advantage of the Java Mail API. It is provided as a separate library, typically in form of a file called mail.jar together with its dependency Java Activation Framework (activation.jar). Should you experience any ClassNotFoundException problems, check whether these two libraries are correctly included in your Java class path.

As some of the arguments such as server name and port, sender and recipient addresses and SMTP user name are often static for a particular user, it is possible to define their default values in the user preferences. These arguments may be then omitted (meaning specified as null) in the sendmail method calls. Note that all this data gets saved to a plain text configuration file in the user home directory and it shouldn't contain anything considered sensitive. For this reason there's no configuration parameter for SMTP password which must be specified in each method call (provided that the SMTP server requires authentication).

Parameters:

server - address and eventually port of the SMTP server. The host may be specified both by a name or numeric IP address, with an optional port number specified after a colon (for example, "mysmtp.mydomain.com:1234"). If no port is specified, the method defaults to the well known SMTP port of 25.

user - optional user name for authentication to the SMTP server.

password - optional password for authentication to the SMTP server.

from - sender address, for example "john.doe@mydomain.com". The method itself doesn't validate the address. If it is however invalid, the underlying JavaMail API may refuse it.

to - one or more recipient address(es) separated by comma.

subject - E-mail subject. It should be just plain text without any new line characters.

text - message body. To insert a new line character use "\n". For example, a text of "test\ntest" will resolve in two lines containing word "test". If the text starts with "" (not case sensitive), the content type is set to "text/html". Otherwise the mail body is sent as plain text ("text/plain").

attachments - optional file attachments.

debug - true switches on verbose mode provided by the JavaMail API framework. The method then prints out detailed messages of the SMTP server connection, authentication and message transfer. Use this mode to debug why the command fails.

Returns:

command exit code as is specified in the Sendmail specification.

Throws:

IOException - when an I/O error occurs.

sendMail

public int sendMail(String password,
                    String subject,
                    String text,
                    File[] attachments,
                    boolean debug)
             throws IOException

Send an E-mail of the specified subject, text and optional file attachments to one or more recipients through an SMTP server. The method provides access to functionality of the Sendmail scripting language command. The method works correctly only if there are valid default values of the SMTP server, port and user, sender and recipient address(es) in the user preferences. If any of these values is missing, the method throws an IllegalArgumentException.

As this is just a convenience method calling the sendMail(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.io.File[], boolean) one, see its documentation for a complete description.

Parameters:

password - optional password for authentication to the SMTP server.

subject - E-mail subject. It should be just plain text without any new line characters.

text - message body. To insert a new line character use "\n". For example, a text of "test\ntest" will resolve in two lines containing word "test". If the text starts with "" (not case sensitive), the content type is set to "text/html". Otherwise the mail body is sent as plain text ("text/plain").

attachments - optional file attachments.

debug - true switches on verbose mode provided by the JavaMail API framework. The method then prints out detailed messages of the SMTP server connection, authentication and message transfer. Use this mode to debug why the command fails.

Returns:

command exit code as is specified in the Sendmail specification.

Throws:

IOException - when an I/O error occurs.

sendMail

public int sendMail(String password,
                    String subject,
                    String text)
             throws IOException

Send an E-mail of the specified subject and text to one or more recipients through an SMTP server. The method provides access to functionality of the Sendmail scripting language command. The method works correctly only if there are valid default values of the SMTP server, port and user, sender and recipient address(es) in the user preferences. If any of these values is missing, the method throws an IllegalArgumentException.

As this is just a convenience method calling the sendMail(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.io.File[], boolean) one, see its documentation for a complete description.

Parameters:

password - optional password for authentication to the SMTP server.

subject - E-mail subject. It should be just plain text without any new line characters.

text - message body. To insert a new line character use "\n". For example, a text of "test\ntest" will resolve in two lines containing word "test". If the text starts with "" (not case sensitive), the content type is set to "text/html". Otherwise the mail body is sent as plain text ("text/plain").

Returns:

command exit code as is specified in the Sendmail specification.

Throws:

IOException - when an I/O error occurs.

sendMail

public int sendMail(String subject,
                    String text,
                    File[] attachments)
             throws IOException

Send an E-mail of the specified subject, text and optional file attachments to one or more recipients through an SMTP server which requires no authentication. The method provides access to functionality of the Sendmail scripting language command. It works correctly only if there are valid default values of the SMTP server, port and user, sender and recipient address(es) in the user preferences. If any of these values is missing, the method throws an IllegalArgumentException.

As this is just a convenience method calling the sendMail(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.io.File[], boolean) one, see its documentation for a complete description.

Parameters:

subject - E-mail subject. It should be just plain text without any new line characters.

text - message body. To insert a new line character use "\n". For example, a text of "test\ntest" will resolve in two lines containing word "test". If the text starts with "" (not case sensitive), the content type is set to "text/html". Otherwise the mail body is sent as plain text ("text/plain").

attachments - optional file attachments.

Returns:

command exit code as is specified in the Sendmail specification.

Throws:

IOException - when an I/O error occurs.

sendMail

public int sendMail(String subject,
                    String text)
             throws IOException

Send an E-mail of the specified subject and text to one or more recipients through an SMTP server which requires no authentication. The method provides access to functionality of the Sendmail scripting language command. It works correctly only if there are valid default values of the SMTP server, port and user, sender and recipient address(es) in the user preferences. If any of these values is missing, the method throws an IllegalArgumentException.

As this is just a convenience method calling the sendMail(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.io.File[], boolean) one, see its documentation for a complete description.

Parameters:

subject - E-mail subject. It should be just plain text without any new line characters.

text - message body. To insert a new line character use "\n". For example, a text of "test\ntest" will resolve in two lines containing word "test". If the text starts with "" (not case sensitive), the content type is set to "text/html". Otherwise the mail body is sent as plain text ("text/plain").

Returns:

command exit code as is specified in the Sendmail specification.

Throws:

IOException - when an I/O error occurs.

exec

public int exec(String command,
                OutputStream out,
                int count,
                String wait)
         throws IOException

Execute a command of the local operating system. The method provides access to functionality of the Exec scripting language command.

Parameters:

command - a command to be executed. On most systems the commands have a few limitations, such as no redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.

out - an output stream to write the command output to. If the argument is null, the output is thrown away.

count - how many times to execute the command. Default value is 1;

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Exec specification.

Throws:

IOException - if an I/O error happens during client-server communication.

exec

public int exec(String command,
                OutputStream out,
                boolean nowait,
                int count,
                String wait)
         throws IOException

Execute a command of the local operating system. The method provides access to functionality of the Exec scripting language command.

Parameters:

command - a command to be executed. On most systems the commands have a few limitations, such as no redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.

out - an output stream to write the command output to. If the argument is null, the output is thrown away.

count - how many times to execute the command. Default value is 1;

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

nowait - a flag specifying whether method should make the test script wait until the OS command finishes. The default value is false which makes it wait. When the value is set to true the method does not wait for the result and the test script continues immediately after the process is started. The _EXEC_OUTPUT and _EXEC_ERROR variables are not populated because the output is not known when the method returns the control to the calling script. The _EXEC_ERROR variable may be created if the underlying OS fails to start the specified command and reports it immediately to Robot.

Returns:

command exit code as is specified in the Exec specification.

Throws:

IOException - if an I/O error happens during client-server communication.

Since:

3.4

exec

public int exec(String command,
                OutputStream out)
         throws IOException

Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command once (count=1) with no waiting period specified (wait=null).

Parameters:

command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.

out - an output stream to write the command output to. If the argument is null, the output is thrown away.

Returns:

command exit code as is specified in the Exec specification.

Throws:

IOException - if an I/O error happens during client-server communication.

exec

public int exec(String command,
                Writer out,
                int count,
                String wait)
         throws IOException

Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method with the command output redirected to a Writer rather than to an OutputStream.

Parameters:

command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.

out - a writer to write the command console output to. If the argument is null, the output is thrown away.

count - how many times to execute the command. Default value is 1;

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Exec specification.

Throws:

IOException - if an I/O error happens during client-server communication.

exec

public int exec(String command,
                Writer out,
                boolean nowait,
                int count,
                String wait)
         throws IOException

Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method with the command output redirected to a Writer rather than to an OutputStream.

Parameters:

command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.

out - a writer to write the command console output to. If the argument is null, the output is thrown away.

count - how many times to execute the command. Default value is 1;

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

nowait - a flag specifying whether method should make the test script wait until the OS command finishes. The default value is false which makes it wait. When the value is set to true the method does not wait for the result and the test script continues immediately after the process is started. The _EXEC_OUTPUT and _EXEC_ERROR variables are not populated because the output is not known when the method returns the control to the calling script. The _EXEC_ERROR variable may be created if the underlying OS fails to start the specified command and reports it immediately to Robot.

Returns:

command exit code as is specified in the Exec specification.

Throws:

IOException - if an I/O error happens during client-server communication.

Since:

3.4

exec

public int exec(String command,
                Writer out)
         throws IOException

Convenience method employing the exec(java.lang.String, java.io.Writer, int, java.lang.String) method to execute a command once (count=1) with no waiting period specified (wait=null).

Parameters:

command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.

out - a writer to write the command console output to. If the argument is null, the output is thrown away.

Returns:

command exit code as is specified in the Exec specification.

Throws:

IOException - if an I/O error happens during client-server communication.

exec

public int exec(String command,
                String wait)
         throws IOException

Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command once (count=1) with no output stream (out=null) and no waiting period (wait=null).

Parameters:

command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.

Returns:

command exit code as is specified in the Exec specification.

Throws:

IOException - if an I/O error happens during client-server communication.

exec

public int exec(String command,
                boolean nowait)
         throws IOException

Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command without any further options.

Parameters:

command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.

nowait - a flag specifying whether method should make the test script wait until the OS command finishes. The default value is false which makes it wait. When the value is set to true the method does not wait for the result and the test script continues immediately after the process is started. The _EXEC_OUTPUT and _EXEC_ERROR variables are not populated because the output is not known when the method returns the control to the calling script. The _EXEC_ERROR variable may be created if the underlying OS fails to start the specified command and reports it immediately to Robot.

Returns:

command exit code as is specified in the Exec specification.

Throws:

IOException - if an I/O error happens during client-server communication.

Since:

3.4

exec

public int exec(String command)
         throws IOException

Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command without any further options.

Parameters:

command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.

Returns:

command exit code as is specified in the Exec specification.

Throws:

IOException - if an I/O error happens during client-server communication.

execBrowser

public int execBrowser(String url)

A convenience method to open a web browser on the local operating system. The method makes several attempts to locate and most often used browsers and starts the first one found. The code is optimized to open the default system browser on Windows, Mac OS and Ubuntu. On other systems the method tries to run typical start comands of the most common web browsers according to a hardcoded list and finishes when one of the commands reports success or the list is exhausted.

Note that the method does not use any facilities provided by the Exec command and its behavior can not be modified by any settings applicable to Exec.

Parameters:

url - a document URL to open.

Returns:

0 (zero) on success. Any other value indicates that the method failed to open the browser.

report

public int report(File out,
                  String provider,
                  String description,
                  String scope)
           throws IOException

Start the specified report provider to generate a report on test script execution. The method provides access to functionality of the Report scripting language command.

Report providers are independent threads which typically register with the script manager to receive script execution events. Their role is usually to create and maintain a report with the outputs, such as remote desktop screenshots, image comparison results, warnings and execution logs. The report format is completely up to the particular provider implementation. As the report provider interface ReportProvider is exposed through the plugin framework, anyone may write a custom provider and plug it into the tool.

Note that report scope is obsolete and will be removed in the future. It is provided here only for backward compatibility with test scripts prior to v2.0.

Parameters:

out - a file to save the report to.

provider - a report provider code. It must be a valid code returned by the Plugin.getCode() method of one of the installed report provider plugins or null to use the default report provider (configurable through preferences). T-Plan Robot Enterprise provides by default just one simple HTML report provider with the "default" code.

description - report description.

scope - report scope as is defined in the Report command specification.

Returns:

command exit code as is specified in the Report specification.

Throws:

IOException - if an I/O error happens during client-server communication.

report

public int report(File out,
                  String provider,
                  String description)
           throws IOException

Start the specified report provider to generate a report on test script execution. The method provides access to functionality of the Report scripting language command.

Report providers are independent threads which typically register with the script manager to receive script execution events. Their role is usually to create and maintain a report with the outputs, such as remote desktop screenshots, image comparison results, warnings and execution logs. The report format is completely up to the particular provider implementation. As the report provider interface ReportProvider is exposed through the plugin framework, anyone may write a custom provider and plug it into the tool.

Parameters:

out - a file to save the report to.

provider - a report provider code. It must be a valid code returned by the Plugin.getCode() method of one of the installed report provider plugins or null to use the default report provider (configurable through preferences). T-Plan Robot Enterprise provides by default just one simple HTML report provider with the "default" code.

description - report description.

Returns:

command exit code as is specified in the Report specification.

Throws:

IOException - if an I/O error happens during client-server communication.

report

public int report(File out,
                  String description)
           throws IOException

Start the default report provider to generate a report on test script execution. The method provides access to functionality of the Report scripting language command.

Report providers are independent threads which typically register with the script manager to receive script execution events. Their role is usually to create and maintain a report with the outputs, such as remote desktop screenshots, image comparison results, warnings and execution logs. The report format is completely up to the particular provider implementation. As the report provider interface ReportProvider is exposed through the plugin framework, anyone may write a custom provider and plug it into the tool.

One of the installed report providers is always set as the default one. Unless user changes the default provider in preferences, this method starts the only built-in HTML report provider with the "default" code.

Parameters:

out - a file to save the report to.

description - report description.

Returns:

command exit code as is specified in the Report specification.

Throws:

IOException - if an I/O error happens during client-server communication.

report

public int report(File out)
           throws IOException

Start the default report provider to generate a report on test script execution. The method provides access to functionality of the Report scripting language command.

Report providers are independent threads which typically register with the script manager to receive script execution events. Their role is usually to create and maintain a report with the outputs, such as remote desktop screenshots, image comparison results, warnings and execution logs. The report format is completely up to the particular provider implementation. As the report provider interface ReportProvider is exposed through the plugin framework, anyone may write a custom provider and plug it into the tool.

One of the installed report providers is always set as the default one. Unless user changes the default provider in preferences, this method starts the only built-in HTML report provider with the "default" code.

Parameters:

out - a file to save the report to.

Returns:

command exit code as is specified in the Report specification.

Throws:

IOException - if an I/O error happens during client-server communication.

compareTo

public int compareTo(Image[] templates,
                     ImageComparisonModule module,
                     float passRate,
                     Rectangle cmpArea,
                     Boolean removeBg,
                     Color bgColor,
                     Integer minAlpha,
                     Integer rgbTolerance)
              throws IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with the full set of supported parameters and template images in form of java.awt.Image array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

templates - list of template images (Image instances).

module - image comparison method (module). It may be created through its code (either "default", "search" or third party image comparison plugin code) through the ImageComparisonModuleFactory.getInstance().getModule(code) method.

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(Image template,
                     Float passRate,
                     Rectangle cmpArea,
                     Color color,
                     Color[] bridgeColors,
                     Integer rgbTolerance,
                     Integer rotations,
                     Boolean draw,
                     Boolean clear)
              throws IOException

Analyze the current remote desktop image using the Object Search Method. The method provides access to functionality of the Compareto scripting language command fixed to the "object" comparison module with an optional template image in form of java.awt.Image.

The Object Search module searches the desktop image or its rectangular part for objects of a particular color or colors within the tolerated RGB variance. 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 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. Than it follows the outer shape of each such an object until the shape gets closed. The objects are internally stored as a list of java.awt.Shape instances in the context and may be retrieved through the through the ScriptingContext.getObjectSearchShapes() convenience method. Besides the raw shape data the method also stores bounding rectangle of each object into the context in form of four variables _OBJECT_X_[n], _OBJECT_Y_[n], _OBJECT_W_[n] and _OBJECT_H_[n] which represent the top left corner [x,y] coordinates, width and height. The [n] expression is the object ordinary number starting from 1. The number of objects available is stored under the _OBJECT_COUNT variable. These variables are the only data exposed to the standard scripting language.

Parameters:

template - an optional template image to filter the list of objects by (an Image instance).It must contain just one shape of the specified color and/or tolerance in any level of rotation. When it is provided, the list of objects will be filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the 'passrate' parameter. If the 'rotations' parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times.

If the template image is not specified, the algorithm locates all objects matching the color parameters regardless of their size or shape.

passRate - pass rate as percentage between 0 and 100. The pass rate makes sense only when the template is not null and specifies the percentage of acceptable pixel variance from the template image.

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

color - defines the object color.

bridgeColors - is optional list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. Colors in this list are always compared using the exact RGB match and they do not work with the rgbTolerance parameter.

rgbTolerance - RGB tolerance value. It must be an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the 'color' parameter. This value allows to deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. Be however aware that the higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

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

clear - optional boolean flag dealing with result highlighting in the GUI. The clear parameter allows to clear up all drawings created by the previously called object searches. The drawings are also automatically reset when the script finishes.

draw - optional boolean flag dealing with result highlighting in the GUI. When the draw parameter is 'true', the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component.

Returns:

The method returns 0 when there's at least one object meeting the criteria or 1 otherwise.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File template,
                     Float passRate,
                     Rectangle cmpArea,
                     Color color,
                     Color[] bridgeColors,
                     Integer rgbTolerance,
                     Integer rotations,
                     Boolean draw,
                     Boolean clear)
              throws IOException

Analyze the current remote desktop image using the Object Search Method. The method provides access to functionality of the Compareto scripting language command fixed to the "object" comparison module with an optional template image in form of java.io.File.

The Object Search module searches the desktop image or its rectangular part for objects of a particular color or colors within the tolerated RGB variance. 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 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. Than it follows the outer shape of each such an object until the shape gets closed. The objects are internally stored as a list of java.awt.Shape instances in the context and may be retrieved through the through the ScriptingContext.getObjectSearchShapes() convenience method. Besides the raw shape data the method also stores bounding rectangle of each object into the context in form of four variables _OBJECT_X_[n], _OBJECT_Y_[n], _OBJECT_W_[n] and _OBJECT_H_[n] which represent the top left corner [x,y] coordinates, width and height. The [n] expression is the object ordinary number starting from 1. The number of objects available is stored under the _OBJECT_COUNT variable. These variables are the only data exposed to the standard scripting language.

Parameters:

template - an optional template image to filter the list of objects by (an Image instance).It must contain just one shape of the specified color and/or tolerance in any level of rotation. When it is provided, the list of objects will be filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the 'passrate' parameter. If the 'rotations' parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times.

If the template image is not specified, the algorithm locates all objects matching the color parameters regardless of their size or shape.

passRate - pass rate as percentage between 0 and 100. The pass rate makes sense only when the template is not null and specifies the percentage of acceptable pixel variance from the template image.

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

color - defines the object color.

bridgeColors - is optional list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. Colors in this list are always compared using the exact RGB match and they do not work with the rgbTolerance parameter.

rgbTolerance - RGB tolerance value. It must be an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the 'color' parameter. This value allows to deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. Be however aware that the higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

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

clear - optional boolean flag dealing with result highlighting in the GUI. The clear parameter allows to clear up all drawings created by the previously called object searches. The drawings are also automatically reset when the script finishes.

draw - optional boolean flag dealing with result highlighting in the GUI. When the draw parameter is 'true', the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component.

Returns:

The method returns 0 when there's at least one object meeting the criteria or 1 otherwise.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(Image[] templates,
                     ImageComparisonModule module,
                     float passRate,
                     Rectangle cmpArea,
                     Boolean removeBg,
                     Color bgColor,
                     Integer minAlpha)
              throws IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with the full set of supported parameters and template images in form of java.awt.Image array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

templates - list of template images (Image instances).

module - image comparison method (module). It may be created through its code (either "default", "search" or third party image comparison plugin code) through the ImageComparisonModuleFactory.getInstance().getModule(code) method.

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(Image[] templates,
                     ImageComparisonModule module,
                     float passRate,
                     Rectangle cmpArea,
                     Integer rgbTolerance)
              throws IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with the full set of supported parameters except the imagse search specific ones and template images in form of java.awt.Image array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

templates - list of template images (Image instances).

module - image comparison method (module). It may be created through its code (either "default", "search" or third party image comparison plugin code) through the ImageComparisonModuleFactory.getInstance().getModule(code) method.

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(Image[] templates,
                     ImageComparisonModule module,
                     float passRate,
                     Rectangle cmpArea)
              throws IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with the full set of supported parameters except the imagse search specific ones and template images in form of java.awt.Image array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

templates - list of template images (Image instances).

module - image comparison method (module). It may be created through its code (either "default", "search" or third party image comparison plugin code) through the ImageComparisonModuleFactory.getInstance().getModule(code) method.

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File[] templates,
                     float passRate,
                     Rectangle cmpArea,
                     boolean removeBg,
                     String bgColor,
                     Integer minAlpha,
                     Integer rgbTolerance)
              throws IOException

Search the current remote desktop image for one or more template images using the "search" image comparison module (method), numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array and with the set of arguments enhanced with optional image search specific parameters dealing with background filtering and RGB tolerance.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

templates - list of template images (Image instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

rgbTolerance - RGB tolerance value. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File[] templates,
                     float passRate,
                     Rectangle cmpArea,
                     boolean removeBg,
                     String bgColor,
                     Integer minAlpha)
              throws IOException

Search the current remote desktop image for one or more template images using the "search" image comparison module (method), numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array and with the set of arguments enhanced with image search specific parameters dealing with background filtering.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

templates - list of template images (Image instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File[] templates,
                     float passRate,
                     Rectangle cmpArea,
                     String sort)
              throws IOException

Search the current remote desktop image for one or more template images using the "search2" image comparison module (method), numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

The "search2" method stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

templates - list of template images (File instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:

• "best" - Put the best matching location first (default mode).
• "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
• "top" - Sort locations from the top to the bottom (topmost first).
• "bottom" - Sort locations from the bottom to the top (bottommost first).
• "left" - Sort locations from the left to the right (leftmost first).
• "right" - Sort locations from the right to the left (rightmost first).

When the argument is null the sort mode defaults to the "best" one.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(Rectangle cmpArea,
                     String language,
                     String text,
                     String pattern)
              throws IOException

Perform Optical Character Recognition (OCR) using the Tesseract engine. The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "tocr" and support of its specific parameters. See also the TesseractOCR class documentation for details on how to install and configure Tesseract.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

Parameters:

cmpArea - comparison area (sub rectangle) in the desktop image to apply the comparison to. If it is null the full image will be processed.

language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files.

text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(Rectangle cmpArea,
                     String language)
              throws IOException

Perform Optical Character Recognition (OCR) using the Tesseract engine. The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "tocr" and support of its specific parameters. See also the TesseractOCR class documentation for details on how to install and configure Tesseract.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

Parameters:

cmpArea - comparison area (sub rectangle) in the desktop image to apply the comparison to. If it is null the full image will be processed.

language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(Rectangle cmpArea,
                     String language,
                     float scale,
                     String text,
                     int distance,
                     String pattern)
              throws IOException

Perform Optical Character Recognition (OCR) using the Tesseract engine. The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "tocr" and support of its specific parameters. See also the TesseractOCR class documentation for details on how to install and configure Tesseract.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

Parameters:

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the OCR will be performed on the full desktop image.

language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files. If the parameter is null, it will default to the English one ("eng").

scale - magnification factor. The method magnifies (enlarges) the image by the given factor to improve OCR accuracy. If this parameter is set to a value below 0, it defaults to the value configured in the Tesseract OCR Plugin preferences (the factory setting is 2 meaning that the image shall be enlarged to 200% of its original size).

text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer 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 exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence 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. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File[] templates,
                     String method,
                     String methodParams,
                     float passRate,
                     Rectangle cmpArea)
              throws IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

templates - list of template images (Image instances).

method - image comparison method code. It may be either "default" (histogram based comparison), "search" (tolerant image search) or eventually code of a custom image comparison algorithm added to the tool in form of a plug in.

methodParams - use null for both the "default" and "search" methods. This is a legacy parameter intended to let custom plugins to receive specific parameters from a script.

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).

cmpArea - comparison area (sub rectangle) in the desktop image to apply the comparison to. If it is null the full image will be processed.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File[] templates,
                     String method,
                     float passRate,
                     Rectangle cmpArea)
              throws IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

templates - list of template images (Image instances).

method - image comparison method code. It may be either "default" (histogram based comparison), "search" (tolerant image search) or eventually code of a custom image comparison algorithm added to the tool in form of a plug in.

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).

cmpArea - comparison area (sub rectangle) in the desktop image to apply the comparison to. If it is null the full image will be processed.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File[] templates,
                     String method,
                     float passRate,
                     Rectangle cmpArea,
                     Integer rgbTolerance)
              throws IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

templates - list of template images (Image instances).

method - image comparison method code. It may be either "default" (histogram based comparison), "search" (tolerant image search) or eventually code of a custom image comparison algorithm added to the tool in form of a plug in.

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).

cmpArea - comparison area (sub rectangle) in the desktop image to apply the comparison to. If it is null the full image will be processed.

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File[] templates,
                     String method,
                     float passRate)
              throws IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance and numeric pass rate. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

templates - list of template images (Image instances).

method - image comparison method code. It may be either "default" (histogram based comparison), "search" (tolerant image search) or eventually code of a custom image comparison algorithm added to the tool in form of a plug in.

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File[] templates,
                     String method,
                     float passRate,
                     Integer rgbTolerance)
              throws IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance and numeric pass rate. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

templates - list of template images (Image instances).

method - image comparison method code. It may be either "default" (histogram based comparison), "search" (tolerant image search) or eventually code of a custom image comparison algorithm added to the tool in form of a plug in.

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File[] templates,
                     float passRate)
              throws IOException

Compare the current remote desktop image to one or more template images using the default histogram based image comparison (code "default") and numeric pass rate. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "default" method stores at least the index and size of the matching template as well as the resulting rate expressing similarity of the two compared images. These values are made available as predefined variables with the _COMPARETO prefix (see the Var command specification for a full list). To retrieve them use the ScriptingContext.getVariable(java.lang.String) method such as:

   // Get the matching template index in input array
   Integer index = (Integer)getContext().getVariable("_COMPARETO_TEMPLATE_INDEX");

   // Resulting pass rate may be accessed directly from context
   Number resultingRate = getContext().getComparisonResult();
 

Parameters:

templates - list of template images (Image instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File[] templates,
                     float passRate,
                     Rectangle cmpArea,
                     String text,
                     int distance,
                     String pattern)
              throws IOException

Recognize the text on the screen by a character image collection using the Image Based Text Recognition comparison method. The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "text" and support of its specific parameters.

The resulting text from the method is stored in form of individual text lines to _TEXT_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TEXT_LINE_COUNT variable and can be retrieved using the getVariableAsInt("_TEXT_LINE_COUNT") method. The whole text including the new line characters as well as the map of text elements and their coordinates can be obtained directly from the context through the getContext().getRecognizedText(java.awt.Rectangle) and getContext().getRecognizedTextElements() methods.

If the method throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TEXT_ERROR variable.

Parameters:

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the recognition will be performed on the full desktop image.

text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the recognized text the method returns 0 to indicate success. Otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer 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 exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence 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. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the recognized text matches the regular expression, the method returns 0 to indicate success or 1 otherwise. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

Returns:

the exit code as is specified in the Image Based Text Recognition specification. When none of the "text", "distance" and "pattern" parameters is specified the method returns 0 (success) to indicate a successful execution even when no text gets actually recognized. If the text matching parameters are used the method will return either success (0) or fail (non-zero value) depending on whether the recognized text matches or not.

Throws:

IOException - on an I/O error (can't read an image file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File[] template,
                     String method)
              throws IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module and default numeric pass rate (100% for "search", 95% for "default" unless the user modified these values in user preferences). The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:

template - list of template images (Image instances).

method - image comparison method code. It may be either "default" (histogram based comparison), "search" (tolerant image search) or eventually code of a custom image comparison algorithm added to the tool in form of a plug in.

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(File[] templates)
              throws IOException

Compare the current remote desktop image to one or more template images using the default histogram based image comparison (code "default") and default numeric pass rate (95% unless the user modified the value in user preferences). The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "default" method stores at least the index and size of the matching template as well as the resulting rate expressing similarity of the two compared images. These values are made available as predefined variables with the _COMPARETO prefix (see the Var command specification for a full list). To retrieve them use the ScriptingContext.getVariable(java.lang.String) method such as:

   // Get the matching template index in input array
   Integer index = (Integer)getContext().getVariable("_COMPARETO_TEMPLATE_INDEX");

   // Resulting pass rate may be accessed directly from context
   Number resultingRate = getContext().getComparisonResult();
 

Parameters:

templates - list of template images (Image instances).

Returns:

command exit code as is specified in the Compareto specification.

Throws:

IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

pause

public int pause(String reason)
          throws IOException

Pause execution of the test script until the user manually resumes it with an optional description for report providers. The method provides access to functionality of the Pause scripting language command.

The pausing functionality should not be confused with the Wait command and its corresponding Java method wait(java.lang.String). While the Wait command takes the time specified to complete and delays the script execution this way, the Pause one sets the pause flag of the test script interpret and lets the scripting framework handle it.

When the method gets called, it fires an internal event (ScriptEvent.SCRIPT_EXECUTION_PAUSED) to all registered listeners. The GUI (if present) typically updates status of the associated controls ("pause" menu item and tool bar button) and highlights the pause command line in the script editor. If the script is being executed in CLI mode, the tool prints out a pause warning message into the console. In both cases the user has to resume the script execution manually either through deselection of the GUI controls or a key press in CLI. To resume programmatically call the TestScriptInterpret.setPause(java.lang.Object, boolean, java.lang.String) method with the pause argument set to false. This functionality is however not visible to the TPR test scripts.

Parameters:

reason - an optional description of why the script was paused. It may be picked up by report providers to display it in the report.

Returns:

command exit code as is specified in the Pause specification.

Throws:

IOException - if an I/O error happens during client-server communication.

pause

public int pause()
          throws IOException

Pause execution of the test script until the user manually resumes it. The method provides access to functionality of the Pause scripting language command.

The pausing functionality should not be confused with the Wait command and its corresponding Java method wait(java.lang.String). While the Wait command takes the time specified to complete and delays the script execution this way, the Pause one sets the pause flag of the test script interpret and lets the scripting framework handle it.

When the method gets called, it fires an internal event (ScriptEvent.SCRIPT_EXECUTION_PAUSED) to all registered listeners. The GUI (if present) typically updates status of the associated controls ("pause" menu item and tool bar button) and highlights the pause command line in the script editor. If the script is being executed in CLI mode, the tool prints out a pause warning message into the console. In both cases the user has to resume the script execution manually either through deselection of the GUI controls or a key press in CLI. To resume programmatically call the TestScriptInterpret.setPause(java.lang.Object, boolean, java.lang.String) method with the pause argument set to false. This functionality is however not visible to the TPR test scripts.

Returns:

command exit code as is specified in the Pause specification.

Throws:

IOException - if an I/O error happens during client-server communication.

exit

public int exit(Integer exitCode,
                String description)
         throws IOException

Exit the test script. The argument exit code will be recorded into the results stored to the report file created through a call of one of the methods. The code of 0 is interpreted as "success" while any other value indicates a failure of some type. If the script is executed as a standalone process (typically through the -r CLI option) the exit code is also returned to the underlying operating system.

Parameters:

exitCode - numeric exit code to be returned to the underlying operating system.

description - optional description which will be saved to the test results in form of a variable and it will be displayed in the report.

Returns:

exit code.

Throws:

IOException

exit

public int exit(Integer exitCode)
         throws IOException

Exit the test script. The argument exit code will be recorded into the results stored to the report file created through a call of one of the methods. The code of 0 is interpreted as "success" while any other value indicates a failure of some type. If the script is executed as a standalone process (typically through the -r CLI option) the exit code is also returned to the underlying operating system.

Parameters:

exitCode - numeric exit code to be returned to the underlying operating system.

Returns:

exit code.

Throws:

IOException

warning

public int warning(String text,
                   File image)

Add a warning to be picked up by a report provider. The method provides access to functionality of the Warning scripting language command.

Like the screenshot() method, each call of this method inserts a data structure (OutputObject instance) with the warning text, date and optional associated screen shot to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

text - warning text.

image - optional screen shot file name to associate with this warning. The point is to give the report provider a hint to display the warning close to the previously taken screenshot so that a human may review the reported problem in the image. This argument should correspond to file name argument of a previously executed screenshot() method.

Returns:

command exit code as is specified in the Warning specification.

warning

public int warning(String text)
            throws IOException

Add a warning to be picked up by a report provider. The method provides access to functionality of the Warning scripting language command.

Like the screenshot() method, each call of this method inserts a data structure (OutputObject instance) with the warning text, date and optional associated screen shot to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:

text - warning text.

Returns:

command exit code as is specified in the Warning specification.

Throws:

IOException - the exception is declared but never thrown because the command doesn't deal with the I/O.

waitForBell

public int waitForBell(int count,
                       String timeout,
                       String wait)
                throws IOException

Wait until the remote desktop emits one or more beeps (bells). It provides access to functionality of the WaitFor bell scripting language command.

Parameters:

count - number of expected beeps.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the beep(s) is/are received as expected).

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

Returns:

command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the beeps are received as expected. The value of 1 is returned when the timeout is reached.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForBell

public int waitForBell(String timeout,
                       String wait)
                throws IOException

Wait until the remote desktop beeps (rings a bell). It provides access to functionality of the WaitFor bell scripting language command.

Parameters:

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the beep(s) is/are received as expected).

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

Returns:

command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the beeps are received as expected. The value of 1 is returned when the timeout is reached.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForBell

public int waitForBell(String timeout)
                throws IOException

Wait until the remote desktop beeps (rings a bell). It provides access to functionality of the WaitFor bell scripting language command.

Parameters:

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the beep(s) is/are received as expected).

Returns:

command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the beeps are received as expected. The value of 1 is returned when the timeout is reached.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForUpdate

public int waitForUpdate(Rectangle area,
                         String extent,
                         boolean cumulative,
                         String timeout,
                         String wait)
                  throws IOException

Wait until the remote desktop refreshes the screen or its particular area. This can be used for a simple script control, for example when an application window is expected to open on the desktop. The method provides access to functionality of the WaitFor update scripting language command.

Parameters:

area - the screen area to be watched for update (use null for the full desktop screen).

extent - percentage of the area pixels that are required to refresh. For example if the area is set to a rectangle of 100 pixels (10x10) and the extent is 90% the command will succeed and resume the script once at least 90 pixels of the area get updated.

cumulative - the value of false requires the whole area or its part to refresh at once. This mode works well only with some VNC servers mainly on non-Windows OSes. The value of true will collate minor updates and resume once the union of the updated rectangles meets the specified area and extent restrictions.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the screen refreshes as expected).

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

Returns:

command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the screen refreshes as expected. The value of 1 is returned when the timeout is reached.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForUpdate

public int waitForUpdate(Rectangle area,
                         String extent,
                         String timeout,
                         String wait)
                  throws IOException

Wait until the remote desktop refreshes the screen or its particular area. This can be used for a simple script control, for example when an application window is expected to open on the desktop. As this method defaults to the non-cumulative mode it may not work properly with servers which prefer to send a series of minor update events instead of a large one. Use the waitForUpdate(java.awt.Rectangle, java.lang.String, boolean, java.lang.String, java.lang.String) method with the cumulative parameter set to true on such environments. The method provides access to functionality of the WaitFor update scripting language command.

Parameters:

area - the screen area to be watched for update (use null for the full desktop screen).

extent - percentage of the area pixels that are required to refresh. For example if the area is set to a rectangle of 100 pixels (10x10) and the extent is 90% the command will succeed and resume the script once at least 90 pixels of the area get updated.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the screen refreshes as expected).

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

Returns:

command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the screen refreshes as expected. The value of 1 is returned when the timeout is reached.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForUpdate

public int waitForUpdate(Rectangle area,
                         String extent,
                         String timeout)
                  throws IOException

Wait until the remote desktop refreshes the screen or its particular area. This can be used for a simple script control, for example when an application window is expected to open on the desktop. As this method defaults to the non-cumulative mode it may not work properly with servers which prefer to send a series of minor update events instead of a large one. Use the waitForUpdate(java.awt.Rectangle, java.lang.String, boolean, java.lang.String, java.lang.String) method with the cumulative parameter set to true on such environments. The method provides access to functionality of the WaitFor update scripting language command.

Parameters:

area - the screen area to be watched for update (use null for the full desktop screen).

extent - percentage of the area pixels that are required to refresh. For example if the area is set to a rectangle of 100 pixels (10x10) and the extent is 90% the command will succeed and resume the script once at least 90 pixels of the area get updated.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the screen refreshes as expected).

Returns:

command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the screen refreshes as expected. The value of 1 is returned when the timeout is reached.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForUpdate

public int waitForUpdate(String extent,
                         String timeout)
                  throws IOException

Wait until the remote desktop refreshes the whole screen. This can be used for a simple script control, for example when an application window is expected to open on the desktop. As this method defaults to the non-cumulative mode it may not work properly with servers which prefer to send a series of minor update events instead of a large one. Use the waitForUpdate(java.awt.Rectangle, java.lang.String, boolean, java.lang.String, java.lang.String) method with the cumulative parameter set to true on such environments. The method provides access to functionality of the WaitFor update scripting language command.

Parameters:

extent - percentage of the screen pixels that are required to refresh. For example if the extent is 90% the command will succeed and resume the script once at least 90% of the screen pixels get updated.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the screen refreshes as expected).

Returns:

command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the screen refreshes as expected. The value of 1 is returned when the timeout is reached.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(Image[] templates,
                        float passRate,
                        String interval,
                        Rectangle cmpArea,
                        String timeout,
                        boolean removeBg,
                        String bgColor,
                        Integer minAlpha,
                        String wait)
                 throws IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Image[], com.tplan.robot.imagecomparison.ImageComparisonModule, float, java.awt.Rectangle, java.lang.Boolean, java.awt.Color, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.awt.Image array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor and minalpha.

Parameters:

templates - list of template images (Image instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.

removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

Returns:

command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(Image[] templates,
                        float passRate,
                        String interval,
                        Rectangle cmpArea,
                        String timeout,
                        boolean removeBg,
                        String bgColor,
                        Integer minAlpha,
                        Integer rgbTolerance,
                        String wait)
                 throws IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Image[], com.tplan.robot.imagecomparison.ImageComparisonModule, float, java.awt.Rectangle, java.lang.Boolean, java.awt.Color, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.awt.Image array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor, minalpha and tolerance.

Parameters:

templates - list of template images (Image instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.

removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:

command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(String interval,
                        Rectangle cmpArea,
                        String timeout,
                        String language,
                        String text,
                        String pattern,
                        String wait)
                 throws IOException

Pause the script until the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Rectangle, java.lang.String, java.lang.String, java.lang.String) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

See the TesseractOCR class documentation for details on how to install and configure Tesseract.

Parameters:

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files.

text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

Returns:

command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(File[] templates,
                        float passRate,
                        Rectangle cmpArea,
                        String interval,
                        String timeout,
                        String text,
                        int distance,
                        String pattern,
                        String wait)
                 throws IOException

Pause the script until the text recognized through the Image Based Text Recognition comparison method contains a string or matches a regular expression or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, java.lang.String, int, java.lang.String) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

Recognize the text on the screen by a character image collection using . The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "text" and support of its specific parameters.

The resulting text from the method is stored in form of individual text lines to _TEXT_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TEXT_LINE_COUNT variable and can be retrieved using the getVariableAsInt("_TEXT_LINE_COUNT") method. The whole text including the new line characters as well as the map of text elements and their coordinates can be obtained directly from the context through the getContext().getRecognizedText(java.awt.Rectangle) and getContext().getRecognizedTextElements() methods.

If the method throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TEXT_ERROR variable.

Parameters:

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the recognition will be performed on the full desktop image.

text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the recognized text the method returns 0 to indicate success. Otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer 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 exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence 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. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the recognized text matches the regular expression, the method returns 0 to indicate success or 1 otherwise. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

Returns:

the exit code as is specified in the Image Based Text Recognition specification. When none of the "text", "distance" and "pattern" parameters is specified the method returns 0 (success) to indicate a successful execution even when no text gets actually recognized. If the text matching parameters are used the method will return either success (0) or fail (non-zero value) depending on whether the recognized text matches or not.

Throws:

IOException - on an I/O error (can't read an image file and/or can't get image of the remote desktop).

waitForMatch

public int waitForMatch(String interval,
                        Rectangle cmpArea,
                        String timeout,
                        String language,
                        float scale,
                        String text,
                        int distance,
                        String pattern,
                        String wait)
                 throws IOException

Pause the script until the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Rectangle, java.lang.String, java.lang.String, java.lang.String) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

See the TesseractOCR class documentation for details on how to install and configure Tesseract.

Parameters:

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the OCR will be performed on the full desktop image.

language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files. If the parameter is null, it will default to the English one ("eng").

scale - magnification factor. The method magnifies (enlarges) the image by the given factor to improve OCR accuracy. If this parameter is set to a value below 0, it defaults to the value configured in the Tesseract OCR Plugin preferences (the factory setting is 2 meaning that the image shall be enlarged to 200% of its original size).

text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer 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 exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence 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. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.

Returns:

command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the OCR was performed successfully. If either the 'pattern' or 'text' are specified, the method returns 0 when the recognized text matches the given text/regular expression or 1 otherwise..

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(Image[] templates,
                        float passRate,
                        String interval,
                        String method,
                        String methodParams,
                        Rectangle cmpArea,
                        String timeout,
                        String wait)
                 throws IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Image[], com.tplan.robot.imagecomparison.ImageComparisonModule, float, java.awt.Rectangle) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.awt.Image array and allows to select the image comparison method ("search" for image search, "default" for histogram based comparison or eventually any other code of third party algorithm installed as a plug in).

Parameters:

templates - list of template images (Image instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

method - use "search" for image search, "default" for histogram based comparison or eventually any other code of third party algorithm installed as a plug in.

methodParams - use null for both the "default" and "search" methods. This is a legacy parameter intended to let custom plugins to receive specific parameters from a script.

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

Returns:

command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(File[] templates,
                        float passRate,
                        String interval,
                        Rectangle cmpArea,
                        String timeout,
                        boolean removeBg,
                        String bgColor,
                        Integer minAlpha,
                        Integer rgbTolerance,
                        String wait)
                 throws IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, boolean, java.lang.String, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.io.File array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor and minalpha.

Parameters:

templates - list of template images (Image instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.

removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:

command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(File[] templates,
                        float passRate,
                        String interval,
                        Rectangle cmpArea,
                        String timeout,
                        String sort,
                        String wait)
                 throws IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, boolean, java.lang.String, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.io.File array. It is also hard coded to the Enterprise Image Search v2 algorithm (code "search2") and it supports its specific parameter of order.

Parameters:

templates - list of template images (Image instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.

sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:

• "best" - Put the best matching location first (default mode).
• "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
• "top" - Sort locations from the top to the bottom (topmost first).
• "bottom" - Sort locations from the bottom to the top (bottommost first).
• "left" - Sort locations from the left to the right (leftmost first).
• "right" - Sort locations from the right to the left (rightmost first).

When the argument is null the sort mode defaults to the "best" one.

Returns:

command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(File[] templates,
                        float passRate,
                        String interval,
                        Rectangle cmpArea,
                        String timeout,
                        boolean removeBg,
                        String bgColor,
                        Integer minAlpha,
                        String wait)
                 throws IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, boolean, java.lang.String, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.io.File array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor and minalpha.

Parameters:

templates - list of template images (Image instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.

removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

Returns:

command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(File[] templates,
                        float passRate,
                        String interval,
                        String method,
                        String methodParams,
                        Rectangle cmpArea,
                        String timeout,
                        String wait)
                 throws IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.io.File array and allows to select the image comparison method ("search" for image search, "default" for histogram based comparison or eventually any other code of third party algorithm installed as a plug in).

Parameters:

templates - list of template images (Image instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

method - use "search" for image search, "default" for histogram based comparison or eventually any other code of third party algorithm installed as a plug in.

methodParams - use null for both the "default" and "search" methods. This is a legacy parameter intended to let custom plugins to receive specific parameters from a script.

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

Returns:

command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(File template,
                        float passRate,
                        String interval,
                        Rectangle cmpArea,
                        String timeout,
                        Color color,
                        Color[] bridgeColors,
                        Integer rgbTolerance,
                        Integer rotations,
                        Boolean draw,
                        Boolean clear,
                        String wait)
                 throws IOException

Pause the script until the current remote desktop contains at least one object located by the Object Search image comparison method. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File, java.lang.Float, java.awt.Rectangle, java.awt.Color, java.awt.Color[], java.lang.Integer, java.lang.Integer, java.lang.Boolean, java.lang.Boolean) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

The Object Search module searches the desktop image or its rectangular part for objects of a particular color or colors within the tolerated RGB variance. 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 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. Than it follows the outer shape of each such an object until the shape gets closed. The objects are internally stored as a list of java.awt.Shape instances in the context and may be retrieved through the through the ScriptingContext.getObjectSearchShapes() convenience method. Besides the raw shape data the method also stores bounding rectangle of each object into the context in form of four variables _OBJECT_X_[n], _OBJECT_Y_[n], _OBJECT_W_[n] and _OBJECT_H_[n] which represent the top left corner [x,y] coordinates, width and height. The [n] expression is the object ordinary number starting from 1. The number of objects available is stored under the _OBJECT_COUNT variable. These variables are the only data exposed to the standard scripting language.

Parameters:

template - an optional template image to filter the list of objects by (a File instance). It must contain just one shape of the specified color and/or tolerance in any level of rotation. When it is provided, the list of objects will be filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the 'passrate' parameter. If the 'rotations' parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times. If the template image is not specified, the algorithm locates all objects matching the color parameters regardless of their size or shape.

passRate - pass rate as percentage between 0 and 100. The pass rate makes sense only when the template is not null and specifies the percentage of acceptable pixel variance from the template image.

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

color - defines the object color.

bridgeColors - is optional list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. Colors in this list are always compared using the exact RGB match and they do not work with the rgbTolerance parameter.

rgbTolerance - RGB tolerance value. It must be an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the 'color' parameter. This value allows to deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. Be however aware that the higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

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

clear - optional boolean flag dealing with result highlighting in the GUI. The clear parameter allows to clear up all drawings created by the previously called object searches. The drawings are also automatically reset when the script finishes.

draw - optional boolean flag dealing with result highlighting in the GUI. When the draw parameter is 'true', the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component.

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

Returns:

command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(Image template,
                        float passRate,
                        String interval,
                        Rectangle cmpArea,
                        String timeout,
                        Color color,
                        Color[] bridgeColors,
                        Integer rgbTolerance,
                        Integer rotations,
                        Boolean draw,
                        Boolean clear,
                        String wait)
                 throws IOException

Pause the script until the current remote desktop contains at least one object located by the Object Search image comparison method. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Image, java.lang.Float, java.awt.Rectangle, java.awt.Color, java.awt.Color[], java.lang.Integer, java.lang.Integer, java.lang.Boolean, java.lang.Boolean) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

The Object Search module searches the desktop image or its rectangular part for objects of a particular color or colors within the tolerated RGB variance. 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 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. Than it follows the outer shape of each such an object until the shape gets closed. The objects are internally stored as a list of java.awt.Shape instances in the context and may be retrieved through the through the ScriptingContext.getObjectSearchShapes() convenience method. Besides the raw shape data the method also stores bounding rectangle of each object into the context in form of four variables _OBJECT_X_[n], _OBJECT_Y_[n], _OBJECT_W_[n] and _OBJECT_H_[n] which represent the top left corner [x,y] coordinates, width and height. The [n] expression is the object ordinary number starting from 1. The number of objects available is stored under the _OBJECT_COUNT variable. These variables are the only data exposed to the standard scripting language.

Parameters:

template - an optional template image to filter the list of objects by (an Image instance). It must contain just one shape of the specified color and/or tolerance in any level of rotation. When it is provided, the list of objects will be filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the 'passrate' parameter. If the 'rotations' parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times. If the template image is not specified, the algorithm locates all objects matching the color parameters regardless of their size or shape.

passRate - pass rate as percentage between 0 and 100. The pass rate makes sense only when the template is not null and specifies the percentage of acceptable pixel variance from the template image.

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

color - defines the object color.

bridgeColors - is optional list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. Colors in this list are always compared using the exact RGB match and they do not work with the rgbTolerance parameter.

rgbTolerance - RGB tolerance value. It must be an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the 'color' parameter. This value allows to deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. Be however aware that the higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

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

clear - optional boolean flag dealing with result highlighting in the GUI. The clear parameter allows to clear up all drawings created by the previously called object searches. The drawings are also automatically reset when the script finishes.

draw - optional boolean flag dealing with result highlighting in the GUI. When the draw parameter is 'true', the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component.

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

Returns:

command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(File[] templates,
                        float passRate,
                        String method,
                        Rectangle cmpArea,
                        String timeout,
                        String wait)
                 throws IOException

Throws:

IOException

waitForMatch

public int waitForMatch(File[] templates,
                        float passRate,
                        String method,
                        String timeout)
                 throws IOException

Throws:

IOException

waitForMatch

public int waitForMatch(File[] templates,
                        String method,
                        String timeout)
                 throws IOException

Throws:

IOException

waitForMatch

public int waitForMatch(File[] templates,
                        String timeout)
                 throws IOException

Throws:

IOException

waitForMatch

public int waitForMatch(File[] templates)
                 throws IOException

Pause the script indefinitely until the default image comparison method produces a positive result for at least one of the template. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one save that it performs image comparison repeatedly at scheduled intervals until either a match is achieved.

This particular method deals with template images in form of java.io.File array and sticks to the "default" for histogram based comparison with the default pass rate of 95%.

Parameters:

templates - list of template images (File instances).

Returns:

command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(Image[] templates,
                           float passRate,
                           String interval,
                           Rectangle cmpArea,
                           String timeout,
                           boolean removeBg,
                           String bgColor,
                           Integer minAlpha,
                           Integer rgbTolerance,
                           String wait)
                    throws IOException

Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached. In plain words the method allows to wait until the desktop changes enough to produce a mismatch with the specified template image or images. It provides access to functionality of the WaitFor mismatch scripting language command. The method behaves like the compareTo(java.awt.Image[], com.tplan.robot.imagecomparison.ImageComparisonModule, float, java.awt.Rectangle, java.lang.Boolean, java.awt.Color, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch or timeout is achieved.

This particular method deals with template images in form of java.awt.Image array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor and minalpha.

Parameters:

templates - list of template images (Image instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (negative image comparison result) is met.

removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).

minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.

rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).

Returns:

command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a negative result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes (fails for mismatch), 1 when it fails (passes for mismatch and 2 when one or more template images are not found or cannot be read.

Throws:

IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(File[] templates,
                           float passRate,
                           String interval,
                           Rectangle cmpArea,
                           String timeout,
                           String sort,
                           String wait)
                    throws IOException

Pause the script as long as the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, boolean, java.lang.String, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.io.File array. It is also hard coded to the Enterprise Image Search v2 algorithm (code "search2") and it supports its specific parameter of order.

Parameters:

templates - list of template images (Image instances).

passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.

interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).

cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.

timeout - maximum time to pause for.