Test Script Services Reference

prevnext

Utility Class


Use the utility methods to perform actions common to many test scripts.


Applicability

Commonly used with TestManager and QualityArchitect.


Summary

The following table lists the utility methods. They are static methods of class TSSUtility.

Method Description
applicationPid() Gets the process ID of an application.
applicationStart() Starts an application.
applicationWait() Waits for an application to terminate.
delay() Delays the specified number of milliseconds.
errorDetail() Retrieves error information about a failure.
getComputerConfiguration
AttributeList()
Gets the list of computer configuration attributes and their values.
getComputerConfiguration
AttributeValue()
Gets the value of a computer configuration attribute.
getPath() Gets a pathname.
getScriptOption() Gets the value of a script playback option.
getTestCaseConfiguration
Attribute()
Gets the value of a test case configuration attribute.
getTestCaseConfiguration
AttributeList()
Gets the list of test case configuration attributes and their values.
getTestCaseConfigurationName() Gets the name of the configuration (if any) associated with the current test case.
getTestCaseName() Gets the name of the test case in use.
getTestToolOption() Gets a test case tool option.
javaApplicationStart() Starts a Java application.
negExp() Gets the next negative exponentially distributed random number with the specified mean.
rand() Gets the next random number.
seedRand() Seeds the random number generator.
stdErrPrint() Prints a message to the virtual tester's error file.
stdOutPrint() Prints a message to the virtual tester's output file.
uniform() Gets the next uniformly distributed random number in the specified range.
uniqueString() Returns a unique text string.


TSSUtility.applicationPid()

Gets the process ID of an application.


Syntax

int applicationPid(int appHandle)

Element Description
appHandle The ID of the application whose PID you want to get. Returned by applicationStart() or javaApplicationStart().


Return Value

On success, this method returns the system process ID of the specified application. On failure, it throws an exception: call TSSException.getErrorCode() in a catch block .


Comments

This method works for applications started by applicationStart() or javaApplicationStart().

A successful invocation does not imply that the application whose PID is returned is still alive nor guarantee that the application is still running under this PID.


Example

This example returns the PID of application myApp.

int myAppHandle = TSSUtility.applicationStart("myApp", "d:\myDir" ,0);
int myAppPID = TSSUtility.applicationPid (myAppHandle);

See Also

applicationStart(), applicationWait(), javaApplicationStart()

TSSUtility.applicationStart()

Starts an application.


Syntax

int applicationStart(String appHandle, String workingDir, int 
flags)
int applicationStart(String appHandle)

Element Description
appHandle The pathname of the application to be started, which can include options and arguments. The file suffix can be omitted.
workingDir The directory in which to start the application. The current directory if not specified.
flags Reserved for future use. Specify as 0.


Return Value

On success, this method returns a handle for the started application. On failure, it throws an exception: call TSSException.getErrorCode() in a catch block.


Comments


Example

This example starts application myApp.

int myAppHandle = TSSUtility.applicationStart("myApp", "d:\myDir" ,0);

See Also

applicationPid(), applicationWait(), javaApplicationStart()

TSSUtility.applicationWait()

Waits for an application to terminate.


Syntax

int applicationWait(int app, TSSInteger exitStatus, int 
timeout)
int applicationWait(int app)

Element Description
app The application that you are waiting for. Returned by applicationStart() or javaApplicationStart().
exitStatus OUTPUT. If not null, the exit status of app. See TSSInteger for the implementation of this argument's type.
timeout The number of milliseconds to wait for app to terminate or 0 to return immediately.


Return Value

On success, this method returns TSS_OK.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

This method works for applications started by applicationStart() or javaApplicationStart().

If app is still running at the time this call returns, exitStatus contains NULL. If app has terminated at the time of return, exitStatus contains its termination code.


Example

This example waits 600 milliseconds for application myApp to terminate.

TSSInteger termStatus;
int myAppHandle = TSSUtility.applicationStart("myApp");
int retval = TSSUtility.applicationWait(myAppHandle, termStatus, 600);

See Also

applicationPid(), applicationStart(), javaApplicationStart()

TSSUtility.delay()

Delays script execution for the specified number of milliseconds.


Syntax

void delay (int msecs)

Element Description
msecs The number of milliseconds to delay script execution.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

The delay is scaled as indicated by the contents of the EVAR_Delay_dly_scale environment variable. The accuracy of the time delayed is subject to operating system limitations.


Example

This example delays execution for 10 milliseconds.

TSSUtility.delay(10);

TSSUtility.errorDetail()

Retrieves error information about a failure.


Syntax

int errorDetail(StringBuffer errorText)

Element Description
errorText OUTPUT. Returned explanatory error message about the previous TSS call, or an empty string ("") if the previous TSS call did not fail.


Return Value

This method returns TSS_OK if the previous call succeeded. If the previous call failed, TSSUtility.errorDetail() returns one of the error codes listed below and corresponding errorText.


Comments

This method is called internally by Java methods, which throw TSSException on error. Get the error code by calling TSSException.getErrorCode(). You can use TSSUtility.errorDetail(), but there is no need to do so. For implementation details, see TSSException.


Example

This example opens a datapool and, if there is an error, displays the associated error message text.

TSSDatapool dp = new TSSDatapool();
dp.open ("custdata");
StringBuffer errorText;
boolean fetchRet = dp.fetch();
if (fetchRet==false)
	 // fetch failed, get detail
	 int errorRet = TSSUtility.errorDetail (errorText);
	 System.out.print (errorText);

TSSUtility.getComputerConfigurationAttributeList()

Gets the list of computer configuration attributes and their values.


Syntax

TSSNamedValue[] getComputerConfigurationAttributeList ()

Return Value

On success, this method returns an array of computer configuration attribute names and their values. It exits with one of the following results:


Comments

You create and maintain computer configuration attributes from TestManager. This call returns the current settings.

See TSSNamedValue for the implementation of the return value's data type.

Example

This example returns the current computer configuration attribute list.

TSSNamedValue [] nvLst = 
TSSUtility.getComputerConfigurationAttributeList();
if (nvLst.length == 0) {
// if length is 0 we need to check for error
	 StringBuffer errStr = new StringBuffer();
	 int errCod = TSSUtility.errorDetail(errStr);
	 if (errCod == TSS_OK) {
	 	 System.out.println("zero attributes returned");
	 	 }
	 	 else {
	 	 System.err.print("error: string=");
	 	 System.err.print(errStr);
	 	 System.err.print(" code=");
	 	 System.err.println(errCod);
	 	 }
}
else {
// if length > 0 then print the first TSSNamedValue\qs members
	 System.out.println(nvLst[1].name);
	 System.out.println(nvLst[1].value);
}

See Also

getComputerConfigurationAttributeValue()


TSSUtility.getComputerConfigurationAttributeValue()

Gets the value of computer configuration attribute.


Syntax

String getComputerConfigurationAttributeValue (String name)

Element Description
name The name of the computer configuration attribute whose value is to be returned.


Return Value

On success, this method returns a handle for the started application. On failure, it throws an exception: call TSSException.getErrorCode() in a catch block.


Example

This example returns the value of the configuration attribute Operating System.

String OSVal = TSSUtility.getComputerConfigurationAttributeValue 
("Operating System");

See Also

getComputerConfigurationAttributeList()


TSSUtility.getPath()

Gets the root path of a test asset.


Syntax

String getPath (Long pathKey)

Element Description
pathKey Specifies one of these values:
  • TSS_SOURCE_PATH to get the root path of the test script source from which the currently executing test script was selected. On an agent, this is the root of the destination to which files are copied from the local computer.

  • TSS_ATTACHED_LOG_FILE_PATH to get the root of files attached to the log.


Return Value

On success, this method returns the root of the currently executing test script or of the files attached to the log. On failure, it throws an exception: call TSSException.getErrorCode() in a catch block.


Comments

The root path returned by this method might be the exact location where an asset is stored, but it need not be. For example, in the fully-qualified pathname C:\Datastore\TestScripts, C: might be the root path and Datastore\TestScripts a pathname relative to the root path.

For test scripts run from TestManager, the returned root path is a value in shared memory for the current virtual tester at the time of the call. For test scripts run stand-alone (outside TestManager), the returned root path is a value set by context().


Example

This example returns the root path of the source from which the currently executing test script was selected.

String scriptPath = TSSUtility.getPath (TSS_SOURCE_PATH);

See Also

context(), uniqueString()


TSSUtility.getScriptOption()

Gets the value of a test script playback option.


Syntax

String getScriptOption(String optionName)

Element Description
optionName The name of the script option whose value is returned.


Return Value

On success, this method returns the value of the specified script option, or NULL if the value specified is not used by the execution adapter.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

TestManager users can set the values of test script playback options. These may be options specifically supported by a Test Script Execution Adapter (TSEA), or arbitrarily named user-defined options. The common way to use test script options in a test script is to query an option's value with this call and branch according to its returned value.


Example

This example gets the current value of a hypothetical script option named repeat_count.

String optVal = TSSUtility.getScriptOption("repeat_count");

TSSUtility.getTestCaseConfigurationAttribute()

Gets the value of the specified test case configuration attribute.


Syntax

TSSTestCaseConfigurationAttribute 
getTestCaseConfigurationAttribute (String name)

Element Description
name Specifies the name of the configuration attribute to be returned.


Return Value

On success, this method returns the value of the specified test case configuration attribute. It exits with one of the following results:


Comments

You create and maintain test case configuration attributes from TestManager. This call returns the value of the specified attribute for the current test case.

See TSSTestCaseConfigurationAttribute for the implementation of the return value's data type.

Example

This example returns the value of the configuration attribute Operating System.

TSSTestCaseConfigurationAttribute OSVal = 
TSSUtility.getTestCaseConfigurationAttribute ("Operating System");

See Also

getTestCaseConfigurationAttributeList()


TSSUtility.getTestCaseConfigurationAttributeList()

Gets the list of test case configuration attributes and their values.


Syntax

TSSTestCaseConfigurationAttribute 
getTestCaseConfigurationAttributeList ()

Return Value

On success, this method returns an array of test case configuration attribute names, base values, and operators.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

You create and maintain test case configuration attributes from TestManager. This call returns the current settings for the current test case.

See TSSTestCaseConfigurationAttribute for the implementation of the return value's 
data type.

Example

This example returns the current test case configuration attribute list.

TSSTestCaseConfigurationAttribute [] nvLst = 
TSSUtility.getTestCaseConfigurationAttributeList();
if (nvLst.length == 0) {
// if length is 0 we need to check for error
	 StringBuffer errStr = new StringBuffer();
	 int errCod = TSSUtility.errorDetail(errStr);
	 if (errCod == TSS_OK) {
	 	 System.out.println("zero attributes returned");
	 	 }
	 	 else {
	 	 System.err.print("error: string=");
	 	 System.err.print(errStr);
	 	 System.err.print(" code=");
	 	 System.err.println(errCod);
	 	 }
}
else {
// if length > 0 then print the first TSSNamedValue\qs members
	 System.out.println(nvLst[1].name);
System.out.println(nvLst[1].op);
	 System.out.println(nvLst[1].value);
}

See Also

getTestCaseConfigurationAttribute()


TSSUtility.getTestCaseConfigurationName()

Gets the name of the configuration (if any) associated with the current test case.


Syntax

String getTestCaseConfigurationName (void)

Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

A test case specifies the pass criteria for something that needs to be tested. A configured test case is one that TestManager can execute and resolve as pass or fail.


Example

This example retrieves the name of a test case configuration.

String tcConfig = TSSUtility.getTestCaseConfigurationName();

TSSUtility.getTestCaseName()

Gets the name of the test case in use.


Syntax

String getTestCaseName()

Return Value

On success, this method returns the name of the current test case.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

Created from TestManager, a test case specifies the pass criteria for something that needs to be tested.


Example

This example stores the name of the test case in use in tcName.

String tcName = TSSUtility.getTestCaseName();

TSSUtility.getTestToolOption()

Gets the value of a test tool execution option.


Syntax

String getTestToolOption(String optionName)

Element Description
optionName The name of the test tool execution option whose value is returned.


Return Value

On success, this method returns the value of the specified test tool execution option. On failure, it returns NULL: call errorDetail() for information.


Comments

If you develop adapters for a new test script type that support options, you can use this call to get the value of a specified option.


Example

This example returns the value of an option called persist.

String optval = TSSUtility.getTestToolOption ("persist");

TSSUtility.javaApplicationStart()

Starts a Java application.


Syntax

int javaApplicationStart(String app, String workingDir, String 
classPath, String JVM, String JVMOptions)
int javaApplicationStart(String app, String classPath)
int javaApplicationStart(String app)

Element Description
app The pathname of the application to be started, which can include options and arguments. The file suffix can be omitted.
workingDir The directory in which to start the application.
classPath The Java classpath. The specified value replaces the current classpath.
JVM The pathname of Java Virtual Machine. If not specified, java.exe is used on Windows machines and java on UNIX agent platforms.
JVMOptions Any valid JVM options may be specified.


Return Value

On success, this method returns a handle for the started application. On failure, it throws an exception: call TSSException.getErrorCode() in a catch block.


Example

This example starts application myJavaApp.

int myAppHandle = TSSUtility.javaApplicationStart("myJavaApp");

See Also

applicationPid(), applicationStart(), applicationWait()

TSSUtility.negExp()

Gets the next negative exponentially distributed random number with the specified mean.


Syntax

int negExp(int mean)

Element Description
mean The mean value for the distribution.


Return Value

This method returns the next negative exponentially distributed random number with the specified mean.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

The behavior of the random number generator routines is affected by the settings of the Seed and Seed Flags options in a TestManager suite. By default, TestManager sets unique seeds for each virtual tester, so that each has a different random number sequence.


Example

This example seeds the generator and gets a random number with a mean of 10.

TSSUtility.seedRand (10)
int next = TSSUtility.negExp(10);

See Also

rand(), seedRand(), uniform()

TSSUtility.rand()

Gets the next random number.


Syntax

int rand()

Return Value

This method returns the next random number in the range 0 to 32767.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

The behavior of the random number generator routines is affected by the settings of the Seed and Seed Flags options in a TestManager suite. By default, TestManager sets unique seeds for each virtual tester, so that each has a different random number sequence.


Example

This example gets the next random number.

int next = TSSUtility.rand();

See Also

seedRand(), negExp(), uniform()

TSSUtility.seedRand()

Seeds the random number generator.


Syntax

void SeedRand(int seed)

Element Description
seed The base integer.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

The behavior of the random number generator routines is affected by the settings of the Seed and Seed Flags options in a TestManager suite. By default, TestManager sets unique seeds for each virtual tester, so that each has a different random number sequence.

seedRand() uses the argument seed as a seed for a new sequence of random numbers to be returned by subsequent calls to the rand() routine. If seedRand() is then called with the same seed value, the sequence of random numbers is repeated. If rand() is called before any calls are made to seedRand(), the same sequence is generated as when seedRand() is first called with a seed value of 1.


Example

This example seeds the random number generator with the number 10:

TSSUtility.seedRand(10);

See Also

rand(), negExp(), uniform()

TSSUtility.stdErrPrint()

Prints a message to the virtual tester's error file.


Syntax

void stdErrPrint(String message)

Element Description
message The string to print.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and dos not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Example

This example prints to the error file the message Login failed.

TSSUtility.stdErrPrint("Login failed");

See Also

TSSUtility.stdErrPrint()


TSSUtility.stdOutPrint()

Prints a message to the virtual tester's output file.


Syntax

void stdOutPrint(String message)

Element Description
message The string to print.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Example

This example prints the message Login successful.

TSSUtility.stdOutPrint("Login successful");

See Also

TSSUtility.stdErrPrint()


TSSUtility.uniform()

Gets the next uniformly distributed random number.


Syntax

int uniform(int low, int high)

Element Description
low The low end of the range.
high The high end of the range.


Return Value

This method returns the next uniformly distributed random number in the specified range, or -1 if there is an error.


Exceptions

This method may throw an exception with one of the following values:

If you handle one of these exceptions and do not log it, TestManager is not aware of the exception and does not log a Fail result for it. The script continues to run, and TestManager could log a Pass result for the script.


Comments

The behavior of the random number generator routines is affected by the settings of the Seed and Seed Flags options in a TestManager suite. By default, TestManager sets unique seeds for each virtual tester, so that each has a different random number sequence.


Example

This example gets the next uniformly distributed random number between -10 and 10.

int next = TSSUtility.uniform(-10,10);

See Also

rand(), seedRand(), negExp()

TSSUtility.uniqueString()

Returns a unique text string.


Syntax

String uniqueString(void)


Return Value

On success, this method returns a string guaranteed to be unique in the current test script or suite run. On failure, it throws an exception: call TSSException.getErrorCode() in a catch block.


Comments

You can use this call to construct the name for a unique asset, such as a test script source file.


Example

This example returns a unique text string.

String str = TSSUtility.uniqueString();

prevnext


Rational Test Script Services for Java Rational Software Corporation
Copyright (c) 2003, Rational Software Corporation http://www.rational.com
support@rational.com
info@rational.com