Test Script Services Reference |
Use the utility methods to perform actions common to many test scripts.
Commonly used with TestManager and QualityArchitect.
The following table lists the utility methods. They are methods of class TSSUtility
.
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.
Gets the process ID of an application.
ApplicationPid
(appHandle
As Long) As Integer
appHandle
The ID of the application whose PID you want to get. Returned by
ApplicationStart
.
On success, this method returns the system process ID of the specified application. On failure, it returns 0: call ErrorDetail
for information.
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.
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)
ApplicationStart, ApplicationWait
ApplicationStart
(appHandle
As String, [workingDir
As String], [flags
As Long]) As Long
On success, this method returns a handle for the started application. On failure, it returns 0: call ErrorDetail
for information.
This example starts application myApp
.
Dim myAppHandle As Long
Dim util As New TSSUtility
Long myAppHandle = util.ApplicationStart
("myApp", "d:\myDir", 0)
ApplicationPid, ApplicationWait
Waits for an application to terminate.
ApplicationWait
(app
As Long, [exitStatus
As Integer], [timeout
As Integer ])
This method may generate one of the followingerror codes:
TSS_FAIL
. The application was still running when the time-out expired.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_SYSERROR
. The system returned an error: call ErrorDetail for information.
TSS_NOTFOUND
. The process indicated by app
was not found. It may have terminated before this call or app
may be an invalid handle.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
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.
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)
ApplicationPid, ApplicationStart
Delays script execution for the specified number of milliseconds.
Delay
(msecs
As Long)
msecs
The number of milliseconds to delay script execution.
This method may generate one of the followingerror codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
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.
This example delays execution for 10 milliseconds.
Dim util As New TSSUtility
util.Delay
(10)
Retrieves error information about a failure.
ErrorDetail
(errorText
As String) As Long
errorText
OUTPUT. Returned explanatory error message about the previous TSS call, or an empty string ("") if the previous TSS call did not fail.
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
.
ERROR_INVALID_PARM
. A required argument is missing or invalid.
ERROR_NO_ERROR_MESSAGE
. An attempt was made to fetch a nonexistent message.
ERROR_OUT_OF_MEMORY
. An attempt to allocate dynamic memory failed.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
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
Gets the list of computer configuration attributes and their values.
GetComputerConfigurationAttributeList
() As Variant
On success, this method returns an array of computer configuration attribute names and their values.
This method may generate one of the following error codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
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.
This example returns the current computer configuration attribute list.
Dim config As Variant
Dim util As New TSSUtility
config = util.GetComputerConfigurationAttributeList()
GetComputerConfigurationAttributeValue
Gets the value of computer configuration attribute.
GetComputerConfigurationAttributeValue
(name
As String) As String
name
The
name
of the computer configuration attribute whose value is to be returned.
On success, this method returns a handle for the started application. On failure, it returns NULL: call ErrorDetail
for information.
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"
GetComputerConfigurationAttributeList
Gets the root path of a test asset.
GetPath
(pathKey
As Long) As String
pathKey
Specifies one of these values:
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 ErrorDetail
for information.
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
.
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
Gets the value of a test script playback option.
GetScriptOption
(optionName
As String) As String
optionName
The name of the script option whose value is returned.
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.
This method may generate one of the followingerror codes:
ERROR_CONVERT_BSTR
. An encountered string cannot be converted.
ERROR_INVALID_PARM
. A required argument is missing or invalid.
ERROR_OUT_OF_MEMORY
. An attempt to allocate dynamic memory failed.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
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.
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"
Gets the value of the specified test case configuration attribute.
GetTestCaseConfigurationAttribute
(name
As String) As Variant
name
Specifies the name of the configuration attribute to be returned.
On success, this method returns the value of the specified test case configuration attribute.
This method may generate one of the following error codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
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.
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"
GetTestCaseConfigurationAttributeList
Gets the list of test case configuration attributes and their values.
GetTestCaseConfigurationAttributeList
() As Variant
On success, this method returns an array of test case configuration attribute names, base values, and operators.
This method may generate one of the followingerror codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
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.
This example returns the current test case configuration attribute list.
Dim config As Variant
Dim util As New TSSUtility
config = util.GetTestCaseConfigurationAttributeList()
GetTestCaseConfigurationAttribute
Gets the name of the configuration (if any) associated with the current test case.
GetTestCaseConfigurationName() As String
This method may generate one of the followingerror codes:
ERROR_CREATE_SAVE_ARRAY
. An attempt to create or destroy a SAFEARRAY
failed (which is likely a system rather than a script error).
ERROR_OUT_OF_MEMORY
. An attempt to allocate dynamic memory failed.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
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.
This example retrieves the name of a test case configuration.
Dim tcConfig As String
Dim util As New TSSUtility
tcConfig = util.GetTestCaseConfigurationName
Gets the name of the test case in use.
GetTestCaseName
() As String
On success, this method returns the name of the current test case.
This method may generate one of the followingerror codes:
ERROR_OUT_OF_MEMORY
. An attempt to allocate dynamic memory failed.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
Created from TestManager, a test case specifies the pass criteria for something that needs to be tested.
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
Gets the value of a test tool execution option.
GetTestToolOption
(optionName
As String) As String
optionName
The name of the test tool execution option whose value is returned.
On success, this method returns the value of the specified test tool execution option. On failure, it returns NULL: call ErrorDetail
for information.
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.
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 ErrorDetail
for information.
Gets the next negative exponentially distributed random number with the specified mean.
NegExp
(mean
As Long) As Long
mean
The mean value for the distribution.
This method returns the next negative exponentially distributed random number with the specified mean.
This method may generate one of the followingerror codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
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.
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)
Rand, SeedRand, Uniform
Rand
() As Long
This method returns the next random number in the range 0 to 32767.
This method may generate one of the followingerror codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
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.
This example gets the next random number.
Dim next as Long
Dim util As New TSSUtility
next = util.Rand
()
SeedRand, NegExp, Uniform
Seeds the random number generator.
SeedRand
(seed
As Long)
This method may generate one of the followingerror codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
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.
This example seeds the random number generator with the number 10:
Dim util As New TSSUtility
util.SeedRand
(10)
Rand, NegExp, Uniform
Prints a message to the virtual tester's error file.
StdErrPrint
(message
As String)
This method may generate one of the followingerror codes:
ERROR_CONVERT_BSTR
. An encountered string cannot be converted.
ERROR_INVALID_PARM
. A required argument is missing or invalid.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
This example prints to the error file the message Login failed.
Dim util As TSSUtility
util.StdErrPrint
"Login failed"
Prints a message to the virtual tester's output file.
StdOutPrint
(message
As String)
This method may generate one of the followingerror codes:
ERROR_CONVERT_BSTR
. An encountered string cannot be converted.
ERROR_INVALID_PARM
. A required argument is missing or invalid.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
This example prints the message Login successful.
Dim util As TSSUtility
util.StdOutPrint
"Login successful"
Gets the next uniformly distributed random number.
Uniform
(low
As Long,high
As Long) As Long
low
The low end of the range.
high
The high end of the range.
This method returns the next uniformly distributed random number in the specified range, or -1 if there is an error.
This method may generate one of the followingerror codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
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.
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
Rand, SeedRand, NegExp
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 ErrorDetail
for information.
You can use this call to construct the name for a unique asset, such as a test script source file.
This example returns a unique text string.
Dim str As String
Dim util As New TSSUtility
str = util.UniqueString
()
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 |