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

ApplicationPid(appHandle As Long) As Integer

Element Description
appHandle The ID of the application whose PID you want to get. Returned by ApplicationStart.


Return Value

On success, this method returns the system process ID of the specified application. On failure, it returns 0: call ErrorDetail for information.


Comments

This method works for applications started by ApplicationStart.

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.

Dim MyAppHandle As Long
Dim MyAppPID As Integer
Dim util As New TSSUtility
myAppHandle = util.ApplicationStart ("myApp", "d:\myDir", 0)
myAppPID = util.ApplicationPid (myAppHandle)

See Also

ApplicationStart, ApplicationWait

TSSUtility.ApplicationStart

Starts an application.


Syntax

ApplicationStart(appHandle As String, [workingDir As String], 
[flags As Long]) As Long

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 returns 0: call ErrorDetailfor information.


Comments


Example

This example starts application myApp.

Dim myAppHandle As Long
Dim util As New TSSUtility
Long myAppHandle = util.ApplicationStart ("myApp", "d:\myDir", 0)

See Also

ApplicationPid, ApplicationWait

TSSUtility.ApplicationWait

Waits for an application to terminate.


Syntax

ApplicationWait(app As Long, [exitStatus As Integer], [timeout 
As Integer ])

Element Description
app The application that you are waiting for. Returned by ApplicationStart.
exitStatus OUTPUT. If not NULL, the exit status of app.
timeout The number of milliseconds to wait for app to terminate or 0 to return immediately.


Error Codes

This method may generate one of the followingerror codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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.

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.

Dim myAppHandle As Long
Dim termStatus As Integer
Dim util As New TSSUtility
myAppHandle = util.ApplicationStart ("myApp")
util.ApplicationWait (myAppHandle, termStatus, 600)

See Also

ApplicationPid, ApplicationStart

TSSUtility.Delay

Delays script execution for the specified number of milliseconds.


Syntax

Delay (msecs As Long)

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


Error Codes

This method may generate one of the followingerror codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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.

Dim util As New TSSUtility
util.Delay(10)

TSSUtility.ErrorDetail

Retrieves error information about a failure.


Syntax

ErrorDetail (errorText As String) As Long

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.


Error Codes

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.

If you handle one of these errors and do not log it, TestManager is not aware of the error 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 opens a datapool and, if there is an error, displays the associated error message text.

Dim fetchRet As Boolean
Dim errorText As String
Dim dp As New TSSDatapool
Dim utility As New TSSUtility
dp.Open "custdata"
fetchRet = dp.Fetch
if (fetchRet = False) Then
	 utility.ErrorDetail(errorText)
	 MsgBox "Datapool fetch failed:", &errorText
EndIf

TSSUtility.GetComputerConfigurationAttributeList

Gets the list of computer configuration attributes and their values.


Syntax

GetComputerConfigurationAttributeList () As Variant

Return Value

On success, this method returns an array of computer configuration attribute names and their values.


Error Codes

This method may generate one of the following error codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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 computer configuration attributes from TestManager. This call returns the current settings.

The returned Variant is an array of name/value pairs.


Example

This example returns the current computer configuration attribute list.

Dim config As Variant
Dim util As New TSSUtility
config = util.GetComputerConfigurationAttributeList()

See Also

GetComputerConfigurationAttributeValue


TSSUtility.GetComputerConfigurationAttributeValue

Gets the value of computer configuration attribute.


Syntax

GetComputerConfigurationAttributeValue (name As String) As 
String

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 returns NULL: call ErrorDetailfor information.


Example

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

Dim OSVal As String
Dim util As New TSSUtility
OSVal = util.GetComputerConfigurationAttributeValue "Operating System"

See Also

GetComputerConfigurationAttributeList


TSSUtility.GetPath

Gets the root path of a test asset.


Syntax

GetPath (pathKey As Long) As String

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 returns NULL: call ErrorDetailfor information.


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.

Dim scriptPath As String
Dim util As New TSSUtility
scriptPath = util.GetPath TSS_SOURCE_PATH

See Also

Context, UniqueString


TSSUtility.GetScriptOption

Gets the value of a test script playback option.


Syntax

GetScriptOption(optionName As String) As String

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.


Error Codes

This method may generate one of the followingerror codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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.

Dim optVal As Variant
Dim util As New TSSUtility
optVal = util.GetScriptOption "repeat_count"

TSSUtility.GetTestCaseConfigurationAttribute

Gets the value of the specified test case configuration attribute.


Syntax

GetTestCaseConfigurationAttribute (name As String) As Variant

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.


Error Codes

This method may generate one of the following error codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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 value of the specified attribute for the current test case.

The returned Variant is an array of name/operator/value triplets.


Example

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

Dim OSVal As Variant
Dim util As New TSSUtility
OSVal = util.GetTestCaseConfigurationAttribute "Operating System"

See Also

GetTestCaseConfigurationAttributeList


TSSUtility.GetTestCaseConfigurationAttributeList

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


Syntax

GetTestCaseConfigurationAttributeList () As Variant

Return Value

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


Error Codes

This method may generate one of the followingerror codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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.

The returned Variant is an array of name/operator/value triplets.


Example

This example returns the current test case configuration attribute list.

Dim config As Variant
Dim util As New TSSUtility
config = util.GetTestCaseConfigurationAttributeList()

See Also

GetTestCaseConfigurationAttribute


TSSUtility.GetTestCaseConfigurationName

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


Syntax

GetTestCaseConfigurationName() As String

Error Codes

This method may generate one of the followingerror codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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.

Dim tcConfig As String
Dim util As New TSSUtility
tcConfig = util.GetTestCaseConfigurationName

TSSUtility.GetTestCaseName

Gets the name of the test case in use.


Syntax

GetTestCaseName() As String

Return Value

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


Error Codes

This method may generate one of the followingerror codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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.

Dim tcName As String
Dim util As New TSSUtility
tcName = util.GetTestCaseName

TSSUtility.GetTestToolOption

Gets the value of a test tool execution option.


Syntax

GetTestToolOption(optionName As String) As String

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.

Dim optval As String
Dim util As New TSSUtility
optval = util.GetTestToolOption "persist"

On success, this method returns a handle for the started application. On failure, it returns NULL: call ErrorDetailfor information.


TSSUtility.NegExp

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


Syntax

NegExp (mean As Long) As Long 

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.


Error Codes

This method may generate one of the followingerror codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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.

Dim next As Long
Dim util As New TSSUtility
util.SeedRand 10
next = util.NegExp(10)

See Also

Rand, SeedRand, Uniform

TSSUtility.Rand

Gets the next random number.


Syntax

Rand() As Long 

Return Value

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


Error Codes

This method may generate one of the followingerror codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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.

Dim next as Long
Dim util As New TSSUtility
next = util.Rand()

See Also

SeedRand, NegExp, Uniform

TSSUtility.SeedRand

Seeds the random number generator.


Syntax

SeedRand (seed As Long)

Element Description
seed The base integer.


Error Codes

This method may generate one of the followingerror codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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:

Dim util As New TSSUtility
util.SeedRand(10)

See Also

Rand, NegExp, Uniform

TSSUtility.StdErrPrint

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


Syntax

StdErrPrint (message As String)

Element Description
message The string to print.


Error Codes

This method may generate one of the followingerror codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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.

Dim util As TSSUtility
util.StdErrPrint "Login failed"

See Also

TSSUtility.StdErrPrint


TSSUtility.StdOutPrint

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


Syntax

StdOutPrint (message As String)

Element Description
message The string to print.


Error Codes

This method may generate one of the followingerror codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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.

Dim util As TSSUtility
util.StdOutPrint "Login successful"

See Also

TSSUtility.StdErrPrint


TSSUtility.Uniform

Gets the next uniformly distributed random number.


Syntax

Uniform (low As Long, high As Long) As Long

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.


Error Codes

This method may generate one of the followingerror codes:

If you handle one of these errors and do not log it, TestManager is not aware of the error 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.

Dim next As Long
Dim util As New TSSUtility
util.Uniform -10 10

See Also

Rand, SeedRand, NegExp

TSSUtility.UniqueString

Returns a unique text string.


Syntax

UniqueString() As String


Return Value

On success, this method returns a string guaranteed to be unique in the current test script or suite run. On failure, it returns NULL: call ErrorDetailfor information.


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.

Dim str As String
Dim util As New TSSUtility
str = util.UniqueString()

prevnext


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