com.tplan.robot.scripting.interpret
Interface TestScriptInterpret

All Superinterfaces:

ScriptTypeProvider

All Known Implementing Classes:

AbstractTestScriptInterpret, JavaTestScriptInterpret, PlainTextInterpret, ProprietaryTestScriptInterpret

public interface TestScriptInterpret
extends ScriptTypeProvider

Generic test script interface. It describes methods of a test script written in a particular language.

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

Field Summary

static int	TYPE_JAVA
static int	TYPE_PROPRIETARY
static int	TYPE_UNKNOWN

Method Summary

boolean	compile(ScriptingContext customContext) Compile source code of the test script.
void	destroy() Clean up method.
int	execute(ScriptingContext customContext) Execute the test script.
ScriptingContext	getCompilationContext() Get context from the last compilation.
StyledDocument	getDocument() Get the styled document holding source code of the test script.
ScriptingContext	getExecutionContext() Get context from the last execution.
long	getFileLastModified() Get the last modification time (in millis) of the file that the interpret owns.
ScriptManager	getScriptManager() Get the script manager associated with this test interpret instance.
String[]	getSupportedFileExtensions() Get typical file extensions that should be handled by a particular implementation of a test script.
int	getType() Get the test script type.
String	getTypeDescription() Get the test script interpret type description.
URI	getURI() Get test script source code URI.
boolean	hasSource() Find out if the interpret has access to the source code.
boolean	isEditable(String extension) Find out if a test script file of the given extension is a text one (source code) and can be edited in the script editor.
boolean	isExecuting()
boolean	isManualStop()
boolean	isModified() Find out if the script is modified or not.
boolean	isPartialExecutionAllowed() Indicate whether it is possible to execute just a part of the test script.
boolean	isPartialExecutionAllowed(int start, int end, int[] outRange) Indicate whether it is possible to execute the specified part of the test script.
boolean	isPartiallyExecuting()
boolean	isPause()
boolean	isStop()
boolean	isSupportedTestScript()
void	reload() Reload the content from the URI set through the setURI(java.net.URI, boolean) method.
void	resetSelection() Reset selection for partial execution purposes.
void	setFileLastModified(long time) Set the last modification time (in millis) of the file that the interpret owns.
void	setModified(boolean modified) Indicate that the test script has been modified.
void	setPause(Object source, boolean pause, String reason)
void	setScriptManager(ScriptManager sm) Set the script manager associated with this test script interpret.
void	setScriptOwner(ScriptOwner owner)
void	setSelection(int startOffset, int endOffset) Set the start and end offset for partial execution of a test script.
void	setStop(Object source, boolean stop, boolean isManual, String manualStopJustification) Request to stop the script execution.
void	setURI(URI uri, boolean load) Set the test script URI.

Field Detail

TYPE_UNKNOWN

static final int TYPE_UNKNOWN

See Also:

Constant Field Values

TYPE_PROPRIETARY

static final int TYPE_PROPRIETARY

See Also:

Constant Field Values

TYPE_JAVA

static final int TYPE_JAVA

See Also:

Constant Field Values

Method Detail

getType

int getType()

Get the test script type. Reserved values are 0 (unknown language), 1 (test script in the T-Plan Robot Enterprise proprietary scripting language) and 2 (Java test scripts).

Specified by:

getType in interface ScriptTypeProvider

Returns:

test script type.

getTypeDescription

String getTypeDescription()

Get the test script interpret type description. This string is typically displayed to the user when a new script is being created through the GUI and the user has to select which test script type is to be created.

Returns:

test script type description such as "TPR test script", "Java test script" etc.

getSupportedFileExtensions

String[] getSupportedFileExtensions()

Get typical file extensions that should be handled by a particular implementation of a test script. Test script interpret factory (TestScriptInterpretFactory) takes advantage of this method to create interpret instances for particular test script files.

Returns:

list of specific file extensions which should be handled by this interpret. For example, a Java interpret would return new String[] { "java" }. If the method returns null, it means that there is no specific extension for the script type handled by this class. The latter case applies for example for the proprietary test script format which may be saved with any extension.

isEditable

boolean isEditable(String extension)

Find out if a test script file of the given extension is a text one (source code) and can be edited in the script editor. This method allows to prevent users from opening of binary test scripts, such as for example Java byte code (.class).

Returns:

true if the script is a text one and can be edited or false otherwise.

getURI

URI getURI()

Get test script source code URI.

Returns:

test script source code URI

setURI

void setURI(URI uri,
            boolean load)
            throws IOException

Set the test script URI. If the load argument is true, the interpret should load content from the URI to the document. A value of false is usually used in "Save As" operations where the URI changes for the current document content. Saving of the file is however not performed by this method.

Parameters:

uri - test script URI.

load - whether to open the URI in the current document (see getDocument()).

Throws:

IOException - if the load parameter is true and loading of test script fails.

reload

void reload()
            throws IOException

Reload the content from the URI set through the setURI(java.net.URI, boolean) method.

Throws:

IOException - on an I/O error.

getFileLastModified

long getFileLastModified()

Get the last modification time (in millis) of the file that the interpret owns. This is typically used to check whether someone else has updated the file.

Returns:

last time of saving of the script to the file.

setFileLastModified

void setFileLastModified(long time)

Set the last modification time (in millis) of the file that the interpret owns.

Parameters:

time - last time of saving of the script to the file.

setScriptManager

void setScriptManager(ScriptManager sm)

Set the script manager associated with this test script interpret.

Parameters:

sm -

getScriptManager

ScriptManager getScriptManager()

Get the script manager associated with this test interpret instance.

Returns:

script manager associated with this test interpret

compile

boolean compile(ScriptingContext customContext)
                throws InterpretErrorException

Compile source code of the test script. If the script is in a scripting language, the method should check the code syntax. If the script is in a compilable language (for example Java test scripts), the method should compile the code and make it ready for execution.

Parameters:

customContext - customized context for this validation. If the argument is null, the interpret is supposed to obtain a preinitialized context instance from the script manager through ScriptManager.createDefaultContext().

Returns:

true if the script compiled fine, false if there were errors. Compilation errors are to be saved as a list of SyntaxErrorException instances to the compilation context. The interpret is also supposed to fire appropriate compilation script events through the associated script manager. The context should be made available after compilation through the getCompilationContext() method.

Throws:

InterpretErrorException - should be thrown on an internal error or illegal interpret state. The exception message gets typically displayed or otherwise reported to the user.

execute

int execute(ScriptingContext customContext)
            throws InterpretErrorException

Execute the test script. // TODO: document particular events

Parameters:

customContext - customized context for this execution. If the argument is null, the interpret is supposed to obtain a preinitialized context instance from the script manager through ScriptManager.createDefaultContext(). The context should be made available after execution through the getExecutionContext() method.

Returns:

execution result (exit code).

Throws:

InterpretErrorException - should be thrown on an internal error or illegal interpret state. The exception message gets typically displayed or otherwise reported to the user.

getExecutionContext

ScriptingContext getExecutionContext()

Get context from the last execution. If the script hasn't been executed through execute(ScriptingContext), the method should return null.

Returns:

context from the last execution.

getCompilationContext

ScriptingContext getCompilationContext()

Get context from the last compilation. If the script hasn't been compiled through compile(ScriptingContext), the method should return null.

Returns:

context from the last compilation.

isPartialExecutionAllowed

boolean isPartialExecutionAllowed()

Indicate whether it is possible to execute just a part of the test script. This is typically possible with scripting languages, such as the proprietary T-Plan Robot Enterprise one, where user can select part of the code in the editor and execute it. It is on the other hand not possible with test scripts written in Java.

Interprets returning true should expect the calls of the setSelection(int, int) method. Interprets which do not support this feature and return false should throw an exception when the method is called.

Returns:

true if partial execution is supported or false otherwise.

isPartialExecutionAllowed

boolean isPartialExecutionAllowed(int start,
                                  int end,
                                  int[] outRange)

Indicate whether it is possible to execute the specified part of the test script.

Parameters:

start - selection start offset

end - selection end offset

outRange - this is an optional output array (length >= 2) where the interpret may specify the start and end elements that will be executed for the given selection specified by [start, end]. These

Returns:

true if partial execution is supported or false otherwise.

Since:

3.0.2

setSelection

void setSelection(int startOffset,
                  int endOffset)
                  throws IllegalStateException

Set the start and end offset for partial execution of a test script. The offsets refer to positions in the document returned by the getDocument() method. Interprets which do not support partial executions (i.e. their isPartialExecutionAllowed() method returns false) should throw an IllegalStateException exception if this method gets called.

Parameters:

startOffset - start offset indicating position in the test script document to start the execution from.

endOffset - end offset in the test script where execution should be finished.

Throws:

IllegalStateException - if the method gets called even though the isPartialExecutionAllowed() method returns false to indicate that this mode is not supported.

resetSelection

void resetSelection()
                    throws IllegalStateException

Reset selection for partial execution purposes. Interprets which do not support partial executions (i.e. their isPartialExecutionAllowed() method returns false) should throw an IllegalStateException exception if this method gets called.

Throws:

IllegalStateException - if the method gets called even though the isPartialExecutionAllowed() method returns false to indicate that this mode is not supported.

getDocument

StyledDocument getDocument()

Get the styled document holding source code of the test script. The reason we hold it in a document instance is easy access to document elements. The method should never return null.

Returns:

document holding source code of the test script or ready to be used as a container for test code.

isExecuting

boolean isExecuting()

isPartiallyExecuting

boolean isPartiallyExecuting()

isStop

boolean isStop()

isManualStop

boolean isManualStop()

setStop

void setStop(Object source,
             boolean stop,
             boolean isManual,
             String manualStopJustification)

Request to stop the script execution. The method is not supposed to stop the automated task immediately. It is rather expected to set an internal "stop" flag. The interpret should periodically test the flag, for example between individual command calls, and stop the execution as soon as possible.

The method should not fire a stop event through the ScriptListener interface. It should be rather fired when the execution is really stopped, not when the request is made.

Parameters:

source - request source.

stop - true stops (false doesn't really make sense).

isManual - this is additional flag allowing to specify whether the stop is manual, i.e. requested by the user either through GUI controls or by pressing Ctrl+C in CLI. This information is saved to the context for the benefit of report providers and doesn't affect the way the stop action is carried out.

manualStopJustification - optional string describing why or how the script was stopped. It is used just for reporting purposes.

isPause

boolean isPause()

setPause

void setPause(Object source,
              boolean pause,
              String reason)

destroy

void destroy()

Clean up method. A call of this method indicates that the interpret will not be used any more. Interprets are expected to perform an internal cleanup on a call of this method and get removed from listener lists and caches.

setModified

void setModified(boolean modified)

Indicate that the test script has been modified. Though the interpret owns the document and it gets notified when it gets updated, the method is used by the GUI to notify the interpret that the script has been saved to a file and thus should be handled as unchanged.

Parameters:

modified - true sets the script status to modified, false to unmodified.

isModified

boolean isModified()

Find out if the script is modified or not.

Returns:

true if the test script code has been modified or false otherwise.

isSupportedTestScript

boolean isSupportedTestScript()

setScriptOwner

void setScriptOwner(ScriptOwner owner)

hasSource

boolean hasSource()

Find out if the interpret has access to the source code. This can be used to determine whether it can be opened in the script editor or not. For example, a Java test script interpret may contain just the test class instance and not the source code.

Returns:

true if the interpret has access to the source code, false if not.