sir.mts
Interface TestScriptGenerator

All Known Implementing Classes:

BourneShellScriptGenerator, CShellScriptGenerator, XMLGenerator

public interface TestScriptGenerator

A test script generator is responsible for receiving the stream of test implementation commands parsed from a STImpL file and producing the corresponding implementation script in a particular target language.

Version:

05/01/2006

Author:

Alex Kinneer

Method Summary

int	addComment(java.lang.String comment) Adds a comment to the generated script.
int	addExternalFinishScript(java.lang.String scriptName, java.util.List params) Adds a script invocation to be executed after invocation of the test case.
int	addExternalSetupScript(java.lang.String scriptName, java.util.List params) Adds a script invocation to be executed prior to invocation of the test case.
int	addInlineFinishScript(java.lang.String scriptName, java.util.Map params) Inlines a script to executed after invocation of the test case.
int	addInlineSetupScript(java.lang.String scriptName, java.util.Map params) Inlines a script to executed prior to invocation of the test case.
int	addInputFile(java.lang.String file) Adds a file redirection to the standard input stream of the current test case.
int	addMoveFile(java.lang.String srcFile, java.lang.String desetFile) Adds a command to move an output file to another location after execution of the test case.
int	addOutputFile(java.lang.String file) Adds a redirection to file of the standard output and error streams of the current test case.
int	addParameter(java.lang.String param) Adds a command line parameter to the current test case.
int	addTestDriver(java.lang.String testDriver) Adds a test driver to be used to invoke the test case.
void	addVariableAssign(java.lang.String var, java.lang.String val, boolean unsetFirst) Inserts a statement in the script to assign a value to a named variable.
void	addVerbatim(java.lang.String text) Copies text verbatim to the generated script.
int	endScript() Indicates the end of the script.
int	endTest() Indicates the end of the current test implementation specification.
java.lang.String	getEscapedQuote() Gets the escape sequence to generate a single quote character (").
void	newTest(int testID) Indicates the start of a new test implementation specification.
int	setRunInBackground(boolean flagged) Instructs the script generator to cause the test case to be executed as a background job.
void	startScript() Indicates the start of a new script.

Method Detail

startScript

void startScript()
                 throws ScriptGenException

Indicates the start of a new script.

This is most useful for inserting content at the start of the script.

Throws:

ScriptGenException - If the script generator fails to generate content associated with this event.

endScript

int endScript()
              throws ScriptGenException

Indicates the end of the script.

This is most useful for inserting content at the end of the script.

Returns:

The number of test cases in the generated script.

Throws:

ScriptGenException - If the script generator fails to generate content associated with this event.

addVerbatim

void addVerbatim(java.lang.String text)
                 throws ScriptGenException

Copies text verbatim to the generated script.

Note: There is currently no STImpL syntax associated with this event, and it is not called by the parser. It is reserved for future use.

Parameters:

text - Text to be copied unchanged to the generated script.

Throws:

ScriptGenException - If the script generator fails to copy the specified text to the script.

addVariableAssign

void addVariableAssign(java.lang.String var,
                       java.lang.String val,
                       boolean unsetFirst)
                       throws ScriptGenException

Inserts a statement in the script to assign a value to a named variable.

Variables are considered to exist in the global scope. Thus all test cases subsequent to a variable assignment should have access to the variable value.

Parameters:

var - Name of the variable to be assigned.

val - Value to be assigned to the variable.

unsetFirst - boolean Flag indicating whether a statement to explicitly unset the specified variable should be inserted before the assignment statement, if such a capability exists in the target language.

Throws:

ScriptGenException - If the script generator is unable to insert a variable assignment statement.

newTest

void newTest(int testID)
             throws ScriptGenException

Indicates the start of a new test implementation specification.

Parameters:

testID - The test number of this test in the script.

Throws:

ScriptGenException - If the script generator is unable to generate a new test.

endTest

int endTest()
            throws ScriptGenException

Indicates the end of the current test implementation specification.

Returns:

The number of tests added to the script so far.

Throws:

ScriptGenException - If the script generator fails to generate content associated with this event.

addParameter

int addParameter(java.lang.String param)
                 throws ScriptGenException

Adds a command line parameter to the current test case.

Parameters:

param - Command line parameter string to be added to the invocation command for the current test case.

Returns:

The number of STImpL test specification commands received so far for the current test case.

Throws:

ScriptGenException - If the script generator is unable to add the parameter string to the test case invocation.

addInputFile

int addInputFile(java.lang.String file)
                 throws ScriptGenException

Adds a file redirection to the standard input stream of the current test case.

Parameters:

file - Name of the file that should be redirected to the test case on the standard input stream.

Returns:

The number of STImpL test specification commands received so far for the current test case.

Throws:

ScriptGenException - If the script generator is unable to add the input file redirection to the test case invocation.

addOutputFile

int addOutputFile(java.lang.String file)
                  throws ScriptGenException

Adds a redirection to file of the standard output and error streams of the current test case.

Parameters:

file - Name of the file to which the standard output and error streams of the test case should be redirected.

Returns:

The number of STImpL test specification commands received so far for the current test case.

Throws:

ScriptGenException - If the script generator is unable to add the output redirection to the test case invocation.

addMoveFile

int addMoveFile(java.lang.String srcFile,
                java.lang.String desetFile)
                throws ScriptGenException

Adds a command to move an output file to another location after execution of the test case.

Parameters:

srcFile - Name of the output file to be moved.

desetFile - Path and file name to which the output file should be moved.

Returns:

The number of STImpL test specification commands received so far for the current test case.

Throws:

ScriptGenException - If the script generator is unable to add a command to move the specified output file.

addExternalSetupScript

int addExternalSetupScript(java.lang.String scriptName,
                           java.util.List params)
                           throws ScriptGenException

Adds a script invocation to be executed prior to invocation of the test case.

By historical convention, script invocations should be added in the order received (that is, the order in which they are requested by calls to this method), and should be inserted before any inlined startup scripts.

Parameters:

scriptName - Name of the script to be invoked prior to the test case.

params - List of parameters to be passed to the invoked script.

Returns:

The number of STImpL test specification commands received so far for the current test case.

Throws:

ScriptGenException - If the script generator is unable to add the invocation of a startup script.

addInlineSetupScript

int addInlineSetupScript(java.lang.String scriptName,
                         java.util.Map params)
                         throws ScriptGenException

Inlines a script to executed prior to invocation of the test case.

By historical convention, scripts should be inlined in the order received (that is, the order in which they are requested by calls to this method), and they should always appear after the invocations of non-inlined startup scripts.

The parameters argument can be used to request that the script generator insert appropriate variable assignment statements at the head of the inlined script to simulate parameters. Note however that these variables are not cleared at the end of the inlined script, and thus they may remain in scope and available to subsequent test cases. This may be useful for maintaining state in the script.

Parameters:

scriptName - Name of the script to be inlined into the generated script prior to execution of the test case.

params - Map A Map<String,String> that contains pairings of variable names to values that should be assigned to those variables at the beginning of the script, simulating parameters to the script.

Returns:

The number of STImpL test specification commands received so far for the current test case.

Throws:

ScriptGenException - If the script generator is unable to inline the requested startup script.

addExternalFinishScript

int addExternalFinishScript(java.lang.String scriptName,
                            java.util.List params)
                            throws ScriptGenException

Adds a script invocation to be executed after invocation of the test case.

By historical convention, script invocations should be added in the order received (that is, the order in which they are requested by calls to this method), and should be inserted after any inlined finishing scripts.

Parameters:

scriptName - Name of the script to be invoked after the test case.

params - List of parameters to be passed to the invoked script.

Returns:

The number of STImpL test specification commands received so far for the current test case.

Throws:

ScriptGenException - If the script generator is unable to add the invocation of a finishing script.

addInlineFinishScript

int addInlineFinishScript(java.lang.String scriptName,
                          java.util.Map params)
                          throws ScriptGenException

Inlines a script to executed after invocation of the test case.

By historical convention, scripts should be inlined in the order received (that is, the order in which they are requested by calls to this method), and they should always appear before the invocations of non-inlined finishing scripts.

The parameters argument can be used to request that the script generator insert appropriate variable assignment statements at the head of the inlined script to simulate parameters. Note however that these variables are not cleared at the end of the inlined script, and thus they may remain in scope and available to subsequent test cases. This may be useful for maintaining state in the script.

Parameters:

scriptName - Name of the script to be inlined into the generated script after execution of the test case.

params - Map A Map<String,String> that contains pairings of variable names to values that should be assigned to those variables at the beginning of the script, simulating parameters to the script.

Returns:

The number of STImpL test specification commands received so far for the current test case.

Throws:

ScriptGenException - If the script generator is unable to inline the requested finishing script.

addComment

int addComment(java.lang.String comment)
               throws ScriptGenException

Adds a comment to the generated script.

Comment text is supplied verbatim, including unmodified whitespace.

Parameters:

comment - Comment text to be added.

Returns:

The number of STImpL test specification commands received so far for the current test case.

Throws:

ScriptGenException - If the script generator is unable to add the comment text.

addTestDriver

int addTestDriver(java.lang.String testDriver)
                  throws ScriptGenException

Adds a test driver to be used to invoke the test case.

Parameters:

testDriver - Name of the test driver program to be used to invoke the program under test.

Returns:

The number of STImpL test specification commands received so far for the current test case.

Throws:

ScriptGenException - If the script generator is unable to insert the use of a test driver to invoke the test case.

setRunInBackground

int setRunInBackground(boolean flagged)
                       throws ScriptGenException

Instructs the script generator to cause the test case to be executed as a background job.

Parameters:

flagged - true if the test case should be run in the background, false if it should be run as a normal process.

Returns:

The number of STImpL test specification commands received so far for the current test case.

Throws:

ScriptGenException - If the script generator cannot cause the test case to be executed as a background job.

getEscapedQuote

java.lang.String getEscapedQuote()

Gets the escape sequence to generate a single quote character (").

Returns:

The escape sequence required to safely produce a quote character in the target script language.