com.tplan.robot.scripting.interpret

Interface TestScriptInterpret

All Superinterfaces:

ScriptedExecutable

All Known Implementing Classes:

AbstractTestScriptInterpret, PlainTextInterpret

public interface TestScriptInterpret
extends ScriptedExecutable

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

T-Plan Robot Enterprise supports two languages, TPR and Java. The necessary minimum to add support of a new scripting language you must implement this interface together with the Plugin one. The recommended way is to extend the AbstractTestScriptInterpret class and implement optional interfaces to enable GUI support:

Optional test script interpret interfaces

Interface	Description
EditorFriendlyInterpret	Method required to enable GUI tools such as context menus, break points, styled documents with syntax highlighting etc.
OptimizedInterpret	Allows to skip lengthy compilation and use cached results if the script code hasn't changed.
ScriptViewFriendlyInterpret	Enables to display the script in alternative views such as a graph or a tree.
RefactoringCapable	Enables refactoring of resources in the script. For example, if a component image gets moved or renamed the interpret must update all commands that reference it.
FallbackSupport	Support of fall back tasks. It allows the interpret to perform something after the script finishes executing, such as for example a clean up or a user defined custom task.
Configurable ConfigurationChangeListener	Allows the command to store user preferences and get notified of their changes.

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

Field Summary

Fields

Modifier and Type	Field and Description
static int	TYPE_JAVA
static int	TYPE_PROPRIETARY
static int	TYPE_UNKNOWN

Method Summary

Modifier and Type	Method and Description
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.
String	getUID() Get the test script unique Id (UID).
URI	getURI() Get test script source code URI.
boolean	hasSource() Find out if the interpret has access to the source code.
boolean	isDestroyed() Test out whether the interpret has been destroyed by a call of destroy().
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).
boolean	isExecuting() Find out whether the test script is currently executing.
boolean	isManualStop() Indicates whether the script execution was stopped manually by the user.
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() Indicates whether the interpret is currently executing a subset of code.
boolean	isPause() Indicates whether the script is currently paused/suspended.
boolean	isRunning() Find out if the script is currently running, i.e.
boolean	isStop() Indicates whether the execution was stopped.
boolean	isSupportedTestScript() Test whether the interpret is a supported script, i.e.
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) Pause or resume the executing script.
void	setScriptManager(ScriptManager sm) Set the script manager associated with this test script interpret.
void	setScriptOwner(ScriptOwner owner) Set the script owner, typically the GUI editor.
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).

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

Parameters:

extension - the file extension.

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 - a script manager.

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

Find out whether the test script is currently executing.

Specified by:

isExecuting in interface ScriptedExecutable

Returns:

true if executing.

Since:

4.4.3

isRunning

boolean isRunning()

Find out if the script is currently running, i.e. either executing (see isExecuting() or it is in the post-execution phase involving posting of final events, result creating and cleaning up.

Returns:

true if the script has been started and hasn't finished yet.

isPartiallyExecuting

boolean isPartiallyExecuting()

Indicates whether the interpret is currently executing a subset of code. For example, the TPR interpret can execute just a block of code highlighted in the editor.

Returns:

true if executing part of the code or false otherwise.

isStop

boolean isStop()

Indicates whether the execution was stopped.

Specified by:

isStop in interface ScriptedExecutable

Returns:

true if stopped.

isManualStop

boolean isManualStop()

Indicates whether the script execution was stopped manually by the user.

Returns:

true if the user stopped the script or false otherwise.

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.

Specified by:

setStop in interface ScriptedExecutable

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

Indicates whether the script is currently paused/suspended.

Specified by:

isPause in interface ScriptedExecutable

Returns:

true if paused.

setPause

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

Pause or resume the executing script.

Specified by:

setPause in interface ScriptedExecutable

Parameters:

source - the object requesting the pause (for tracking purposes only)

pause - true to pause, false to resume

reason - optional string describing why or how the script was paused or resumed.

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.

isDestroyed

boolean isDestroyed()

Test out whether the interpret has been destroyed by a call of destroy().

Returns:

true if destroyed or false otherwise.

Since:

4.4.4

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

Test whether the interpret is a supported script, i.e. whether it is executable. This flag enables multiple GUI features. There may be interprets which return false to disable these features. For example, if you open a .txt file in the Robot script editor it gets encapsulated in a dummy plain text interpret which disables all scripting functionality through this and other flags.

Returns:

true if the interpret supports automation.

setScriptOwner

void setScriptOwner(ScriptOwner owner)

Set the script owner, typically the GUI editor.

Parameters:

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

getUID

String getUID()

Get the test script unique Id (UID).

Returns:

the test script UID.

Since:

4.4.4