com.tplan.robot.scripting

Class AbstractJavaTestScript

java.lang.Object

com.tplan.robot.scripting.AbstractJavaTestScript

All Implemented Interfaces:

JavaTestScript, TestWrapper

Direct Known Subclasses:

DefaultJavaTestScript

public abstract class AbstractJavaTestScript
extends Object
implements TestWrapper, JavaTestScript

Base class for the default Java test script. It defines infrastructure needed to reach the scripting language command handlers.

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

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

Constructors

Constructor and Description
AbstractJavaTestScript()

Method Summary

Modifier and Type	Method and Description
int	callByName(String command, String... parameters) Generic method allowing to call a command by name.
ScriptingContext	getContext() Get context associated with this test script.
StyledDocument	getDocument() Get the document associated with this wrapper.
int	getLineNumber(ScriptingContext ctx) Get number of the currently executed command line.
String	getOutputDir() Get the output path.It is the directory where the script will store any file outputs such as screen shots, logs and reports.
TestWrapper	getParentWrapper() Get the parent wrapper.
File	getScriptFile() Get the script file.
ScriptManager	getScriptManager() Get script manager associated with this test script and its interpret.
String	getTemplateDir() Get the template path.
String	getTestSource()
Object	getVariable(String name) Convenience method to get a context variable value.
Boolean	getVariableAsBoolean(String name) Convenience method to get a context variable value and convert it to a Boolean.
Color	getVariableAsColor(String name) Convenience method to get a context variable value and convert it to a Color.
Float	getVariableAsFloat(String name) Convenience method to get a context variable value and convert it to Float number.
Integer	getVariableAsInt(String name) Convenience method to get a context variable value and convert it to Integer number.
Point	getVariableAsPoint(String name) Convenience method to get a context variable value and convert it to a Point.
Rectangle	getVariableAsRectangle(String name) Convenience method to get a context variable value and convert it to a Rectangle.
String	getVariableAsString(String name) Convenience method to get a context variable value and convert it to String.
int	getWrapperType()
void	importVariables() This method is intended to support conversion of TPR test scripts into Java.
boolean	isDebug() Indicate whether the debug mode is on.
boolean	isPaused() Find out whether execution of the script is paused.
void	mouseEvent(MouseEvent event) Allows to send low level mouse event (a MouseEvent instance) to the underlying remote desktop client.
void	resume() Resume execution (set the pause indicator to false).
int	runScriptCommand(String commandName, List params, Map values) Generic method to execute a scripting language command.
void	setContext(ScriptingContext context) Set the context.
void	setDebug(boolean debug) Set the debug mode flag.
void	setDocument(StyledDocument document) Set the document associated with this wrapper.
void	setInterpret(TestScriptInterpret interpret) Set the test script interpret.
void	setOutputDir(String dir) Set the output path.
void	setTemplateDir(String dir) Set the template path.
void	setTestSource(String testSource)
void	setVariable(String name, Object value) Convenience method to set a context variable value from the test script body (from inside the JavaTestScript.test() method).
String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.tplan.robot.scripting.JavaTestScript

test

Constructor Detail

AbstractJavaTestScript

public AbstractJavaTestScript()

Method Detail

resume

public void resume()

Resume execution (set the pause indicator to false).

isPaused

public boolean isPaused()

Find out whether execution of the script is paused.

Returns:

true if paused, false if not.

mouseEvent

public void mouseEvent(MouseEvent event)
                throws IOException

Allows to send low level mouse event (a MouseEvent instance) to the underlying remote desktop client. It should be only used to implement a script behavior where the standard mouse methods supported by the scripting API do not suffice. When there is no client, the method does nothing.

Parameters:

event - a mouse event.

Throws:

IOException - on an I/O error or when the client is not connected.

runScriptCommand

public final int runScriptCommand(String commandName,
                                  List params,
                                  Map values)
                           throws IllegalArgumentException,
                                  IOException,
                                  StopRequestException

Generic method to execute a scripting language command.

Parameters:

commandName - command name. If the command is not known (there's no command handler registered for the name in the map maintained by the script managers) the method throws an IllegalArgumentException.

params - command parameters in the correct order (if applicable).

values - map of parameters and their values.

Returns:

exit value returned by the executed command.

Throws:

IllegalArgumentException - on unknown command name.

IOException - when the exception is thrown by the command handler. This in general applies just to commands which participate in the client-server communication. Other command declare the exception but never throw it.

StopRequestException - when a request to stop execution of the script has been registered.

callByName

public int callByName(String command,
                      String... parameters)
               throws IOException

Generic method allowing to call a command by name. It is mainly intended to provide a nicer (and shorter) interface to command calls than the similar legacy method of runScriptCommand(java.lang.String, java.util.List, java.util.Map) which required coding of multiple lines to create the necessary parameter list and map.

The method may be also used to call commands delivered by third party subjects and integrated with the tool through the plugin interface. See the CommandHandler and AbstractCommandHandler classes for more details on this mechanism.

Last but not least this method allows to conversion of scripting language code where the command name is specified by a variable.

The method allows to search the command by name in the internal command table and execute it with parameters passed in through the parameters array. Each element of the parameter array must contain either a valid argument or a "parameter=value" pair exactly as it is specified in the legacy scripting language. If the parameter value in a "parameter=value" pair contains a space, it must be properly enclosed with double quotes. For example, to call an equivalent of the command

Screenshot desktop.jpg desc="My desktop"

use this method call:

runCommand("screenshot", "desktop.jpg", "desc=\"My desktop\"");

Parameters:

command - command name according to the language specification and/or returned by the CommandHandler.getCommandNames() method. It is not case sensitive.

parameters - array of arguments and/or parameters in form of "parameter=value" pairs.

Returns:

exit code of the command handler.

Throws:

IOException - on I/O error (applies only to commands which communicate with the desktop client and/or work with local files and/or communicate with other network services (such as SendMail).

Since:

2.4

importVariables

public void importVariables()

This method is intended to support conversion of TPR test scripts into Java. Its implementation in this class is empty and doesn't do anything. To ensure that the converted Java code works the same way as the original script, this method is created and populated with all operations performed on global variables. When the script is included by another script, this method is then called to define the expose all global variables to the calling script.

getContext

public ScriptingContext getContext()

Get context associated with this test script. The context instance is created and set by the test framework before every execution and/or compilation.

Returns:

a context instance or null if the script has been neither compiled nor executed yet.

setContext

public void setContext(ScriptingContext context)

Set the context. This method is employed by the test framework and should not be used programatically.

Specified by:

setContext in interface JavaTestScript

Parameters:

context - a context instance.

isDebug

public boolean isDebug()

Indicate whether the debug mode is on.

Returns:

true if the debug mode is on, false otherwise.

setDebug

public void setDebug(boolean debug)

Set the debug mode flag. If it is on (debug=true), the script prints out debug messages to the console. As the script prints out scripting language commands resulting from the Java API method calls, it may be used as a very approximate conversion of Java test script to a proprietary language one.

Parameters:

debug - the debug to set

getTestSource

public String getTestSource()

Specified by:

getTestSource in interface TestWrapper

getWrapperType

public int getWrapperType()

Specified by:

getWrapperType in interface TestWrapper

getLineNumber

public int getLineNumber(ScriptingContext ctx)

Get number of the currently executed command line.

Specified by:

getLineNumber in interface TestWrapper

Parameters:

ctx - context instance.

Returns:

executed command line number.

getParentWrapper

public TestWrapper getParentWrapper()

Get the parent wrapper. As this test script is always handled as a top level test wrapper, it has no parent and the method always returns null.

Specified by:

getParentWrapper in interface TestWrapper

Returns:

parent test wrapper (always null in this implementation).

getScriptFile

public File getScriptFile()

Get the script file.

Specified by:

getScriptFile in interface TestWrapper

Returns:

script file.

setTestSource

public void setTestSource(String testSource)

Parameters:

testSource - the testSource to set

getDocument

public StyledDocument getDocument()

Get the document associated with this wrapper.

Specified by:

getDocument in interface TestWrapper

Returns:

a StyledDocument instance. Never returns null.

setDocument

public void setDocument(StyledDocument document)

Set the document associated with this wrapper.

Specified by:

setDocument in interface TestWrapper

Parameters:

document - a new document for this wrapper.

toString

public String toString()

Overrides:

toString in class Object

getScriptManager

public ScriptManager getScriptManager()

Get script manager associated with this test script and its interpret.

Returns:

the scriptManager

setInterpret

public void setInterpret(TestScriptInterpret interpret)

Set the test script interpret.

Specified by:

setInterpret in interface JavaTestScript

Parameters:

interpret - interpret instance able to handle Java source code.

getVariable

public Object getVariable(String name)

Convenience method to get a context variable value. It is equivalent to a call like getContext().getVariable().

Parameters:

name - variable name.

Returns:

variable value or null if the variable doesn't exist in the context.

getVariableAsString

public String getVariableAsString(String name)

Convenience method to get a context variable value and convert it to String.

Parameters:

name - variable name.

Returns:

variable value as a String or null if the variable doesn't exist in the context.

getVariableAsFloat

public Float getVariableAsFloat(String name)

Convenience method to get a context variable value and convert it to Float number. It is roughly equivalent to a call like Float.parseFloat(getContext().getVariable().toString)). As the method doesn't catch any exceptions, it may throw a NumberFormatException if the variable is not a number.

Parameters:

name - variable name.

Returns:

variable value as a Float or null if the variable doesn't exist in the context.

getVariableAsInt

public Integer getVariableAsInt(String name)

Convenience method to get a context variable value and convert it to Integer number. As the method doesn't catch any exceptions, it may throw a NumberFormatException if the variable is not a number.

Parameters:

name - variable name.

Returns:

variable value as an Integer or null if the variable doesn't exist in the context.

getVariableAsBoolean

public Boolean getVariableAsBoolean(String name)

Convenience method to get a context variable value and convert it to a Boolean. The method has the same functionality as ScriptingContext.getVariableAsBoolean(java.lang.String). As the method relies on the Boolean.parseBoolean(java.lang.String) method it returns false when the value is not a valid boolean instead of throwing any exception.

Parameters:

name - variable name.

Returns:

variable value as a Boolean or null if the variable doesn't exist in the context.

Since:

3.2

getVariableAsPoint

public Point getVariableAsPoint(String name)

Convenience method to get a context variable value and convert it to a Point. The method has the same functionality as ScriptingContext.getVariableAsPoint(java.lang.String).

Parameters:

name - variable name.

Returns:

variable value as a Point or null if the variable doesn't exist in the context.

Throws:

IllegalArgumentException - if the variable value is not a point.

Since:

3.2

getVariableAsRectangle

public Rectangle getVariableAsRectangle(String name)

Convenience method to get a context variable value and convert it to a Rectangle. The method has the same functionality as ScriptingContext.getVariableAsRectangle(java.lang.String).

Parameters:

name - variable name.

Returns:

variable value as a Rectangle or null if the variable doesn't exist in the context.

Throws:

IllegalArgumentException - if the variable value is not a rectangle.

Since:

3.2

getVariableAsColor

public Color getVariableAsColor(String name)

Convenience method to get a context variable value and convert it to a Color. The method has the same functionality as ScriptingContext.getVariableAsColor(java.lang.String).

Parameters:

name - variable name.

Returns:

variable value as a Color or null if the variable doesn't exist in the context.

Throws:

IllegalArgumentException - if the variable value is not a valid color.

Since:

3.2

setTemplateDir

public void setTemplateDir(String dir)

Set the template path. It is the directory which contains component images and image collections used for recognition of objects on the desktop through image comparison. This is just a convenience method which calls the ScriptingContext.setTemplateDir(java.io.File) method of the associated script context.

Parameters:

dir - a directory.

Throws:

NullPointerException - when the method is called before the script execution from outside of the JavaTestScript.test() method (when no context has been associated with the test script).

setOutputDir

public void setOutputDir(String dir)

Set the output path. It is the directory where the script will store any file outputs such as screen shots, logs and reports. This is just a convenience method which calls the ScriptingContext.setOutputDir(java.io.File) method of the associated script context.

Parameters:

dir - a directory.

Throws:

NullPointerException - when the method is called before the script execution from outside of the JavaTestScript.test() method (when no context has been associated with the test script).

getTemplateDir

public String getTemplateDir()

Get the template path. It is the directory which contains component images and image collections used for recognition of objects on the desktop through image comparison. This is just a convenience method which calls the ScriptingContext.getTemplateDir() method of the associated script context.

Returns:

the template directory (absolute path).

Throws:

NullPointerException - when the method is called before the script execution from outside of the JavaTestScript.test() method (when no context has been associated with the test script).

Since:

3.0

getOutputDir

public String getOutputDir()

Get the output path.It is the directory where the script will store any file outputs such as screen shots, logs and reports. This is just a convenience method which calls the ScriptingContext.getOutputDir() method of the associated script context.

Returns:

the output path (absolute).

Throws:

NullPointerException - when the method is called before the script execution from outside of the JavaTestScript.test() method (when no context has been associated with the test script).

setVariable

public void setVariable(String name,
                        Object value)

Convenience method to set a context variable value from the test script body (from inside the JavaTestScript.test() method). The method just calls the ScriptingContext.setVariable(java.lang.String, java.lang.Object) on the test script context (getContext().

Parameters:

name - variable name.

value - the variable value.

Throws:

NullPointerException - when the method is called before the script execution from outside of the JavaTestScript.test() method (when no context has been associated with the test script).

Since:

3.0