T-Plan Robot Enterprise 4.0.1
Build No. 4.0.1-20141118.1

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, (C) 2009-2014 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.
 javax.swing.text.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.
 java.lang.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.
 java.lang.String getTypeDescription()
          Get the test script interpret type description.
 java.net.URI getURI()
          Get test script source code URI.
 boolean hasSource()
          Find out if the interpret has access to the source code.
 boolean isEditable(java.lang.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()
          Find out if the executable is currently executing or paused.
 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()
          Find out if the executable is executing and paused.
 boolean isStop()
          Find out if the executable was stopped.
 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(java.lang.Object source, boolean pause, java.lang.String reason)
          Request to pause the executing object.
 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(java.lang.Object source, boolean stop, boolean isManual, java.lang.String manualStopJustification)
          Request to stop the script execution.
 void setURI(java.net.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

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

java.lang.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(java.lang.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

java.net.URI getURI()
Get test script source code URI.

Returns:
test script source code URI

setURI

void setURI(java.net.URI uri,
            boolean load)
            throws java.io.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:
java.io.IOException - if the load parameter is true and loading of test script fails.

reload

void reload()
            throws java.io.IOException
Reload the content from the URI set through the setURI(java.net.URI, boolean) method.

Throws:
java.io.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 java.lang.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:
java.lang.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 java.lang.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:
java.lang.IllegalStateException - if the method gets called even though the isPartialExecutionAllowed() method returns false to indicate that this mode is not supported.

getDocument

javax.swing.text.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()
Description copied from interface: ScriptedExecutable
Find out if the executable is currently executing or paused.

Specified by:
isExecuting in interface ScriptedExecutable
Returns:
true if executing, false if not.

isPartiallyExecuting

boolean isPartiallyExecuting()

isStop

boolean isStop()
Description copied from interface: ScriptedExecutable
Find out if the executable was stopped.

Specified by:
isStop in interface ScriptedExecutable
Returns:
true if the executable was stopped.

isManualStop

boolean isManualStop()

setStop

void setStop(java.lang.Object source,
             boolean stop,
             boolean isManual,
             java.lang.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()
Description copied from interface: ScriptedExecutable
Find out if the executable is executing and paused.

Specified by:
isPause in interface ScriptedExecutable
Returns:
true if the executable is paused.

setPause

void setPause(java.lang.Object source,
              boolean pause,
              java.lang.String reason)
Description copied from interface: ScriptedExecutable
Request to pause the executing object.

Specified by:
setPause in interface ScriptedExecutable
Parameters:
source - source of the request (for tracking purposes).
pause - true to request pause, false to reset the pause flag.
reason - optional pause justification.

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.

T-Plan Robot Enterprise 4.0.1
Build No. 4.0.1-20141118.1