Test Script Services Reference |
Use the utility commands to perform actions common to many test scripts.
The following table lists the utility commands.
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.
Gets the process ID of an application.
pid
= `tsscmdApplicationPid
appHandle`
appHandle
The ID of the application whose PID you want to get. Returned by
ApplicationStart
or JavaApplicationStart
.
On success, this command returns the system process ID of the specified application. It exits with one of the following values :
This command 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.
This example returns the PID of application myApp
.
myAppHandle = `tsscmd ApplicationStartmyApp` myAppPID = `tsscmd
ApplicationPid
myAppHandle`
ApplicationStart, ApplicationWait,JavaApplicationStart
handle
= `tsscmdApplicationStart
[-workdirworkingDir
]
appHandle
`
On success, this command returns a handle for the started application. It exits with one of the following values:
This example starts application myApp
.
myAppHandle = `tsscmd ApplicationStart
myApp`
ApplicationPid, ApplicationWait,JavaApplicationStart
Waits for an application to terminate.
tsscmdApplicationWait
[-timeoutmsec
]app
This command exits with one of the following results:
app
was not found. It may have terminated before this call or app
may be an invalid handle.
This command works for applications started by ApplicationStart or JavaApplicationStart.
This example waits 600 milliseconds for application myApp
to terminate.
myAppHandle = `tsscmd ApplicationStartmyApp` tsscmd
ApplicationWait
-timeout 600 myAppHandle
ApplicationPid, ApplicationStart,JavaApplicationStart
Delays script execution for the specified number of milliseconds.
tsscmdDelay
msecs
msecs
The number of milliseconds to delay script execution.
This command exits with one of the following results:
The delay is scaled as indicated by the contents of the Delay_dly_scale
environment variable. The accuracy of the time delayed is subject to operating system limitations.
This example delays execution for 10 milliseconds.
tsscmd Delay
10
Retrieves error information about a failure.
errorText
=`tsscmdErrorDetail
`
This command returns 0 if the previous command succeeded. If the previous command failed, ErrorDetail returns one of the error codes listed below and corresponding errorText
.
This example opens a datapool and, if there is an error, displays the associated error message text.
dpid = `tsscmdDatapoolOpen
custdata` errorText = `tsscmdErrorDetail
`
Gets the list of computer configuration attributes and their values.
config
= `tsscmdGetComputerConfigurationAttributeList
[-single]`
This command exits with one of the following results:
You create and maintain computer configuration attributes from TestManager. This command returns the current settings.
The computer configuration attribute list can be obtained in either of two formats:
-single
option, two result lines are returned for each row with the configuration name appearing on the first and its value on the second.
-single
option, all rows are returned on one result line containing all pairs in the form name=value
.
This example returns the current computer configuration attribute list.
config = `tsscmd GetComputerConfigurationAttributeList
`
GetComputerConfigurationAttributeValue
Gets the value of computer configuration attribute.
value
= `tsscmdGetComputerConfigurationAttributeValue
name
`
name
The
name
of the computer configuration attribute whose value is to be returned.
On success, this command returns a handle for the started application. It exits with one of the following values.
This example returns the value of the configuration attribute Operating System
.
OSVal = `tsscmd GetComputerConfigurationAttributeValue
"Operating
System"`
GetComputerConfigurationAttributeList
Gets the root path of a test asset.
value
= `tsscmdGetPath
pathKey
`
pathKey
Specifies one of these values:
On success, this command returns the root of the currently executing test script or of the files attached to the log. On failure, it returns nothing: call ErrorDetail
for information.
The root path returned by this command 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 C
ontext
.
This example returns the root path of the source from which the currently executing test script was selected.
scriptPath = `tsscmd GetPath
SOURCE_PATH`
Gets the value of a test script playback option.
optVal
=`tsscmdGetScriptOption
optionName
`
optionName
The name of the script option whose value is returned.
On success, this command returns the value of the specified script option, or NULL if the value specified is not used by the execution adapter. The command exits with one of the following results:
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.
The Command Line adapter supports these options: _TM_CMDLINE_WORKING_DIR
, _TM_CMDLINE_LEFT_PARAM_DELIM
, _TM_CMDLINE_RIGHT_PARAM_DELIM
, _TM_CMDLINE_ESCAPE_CHAR
, _TM_SHELLCMD_ARGS
, _TM_PASSWORD
, _TM_USERNAME
, _TM_PROJECT_PATH
, _TM_PROJECT_NAME
. These options have initial values that can be changed from TestManager.
This example gets the current working directory.
optVal = `tssscmd GetScriptOption
_TM_CMDLINE_WORKING_DIR`
Gets the value of the specified test case configuration attribute.
config
= `tsscmdGetTestCaseConfigurationAttribute
[-single]name
`
name
Specifies the name of the configuration attribute to be returned.
On success, this command returns the value of the specified test case configuration attribute. It exits with one of the following results:
You create and maintain test case configuration attributes from TestManager. This command returns the value of the specified attribute for the current test case.
The test case configuration attribute value can be obtained in either of two formats:
-single
option, three result lines are returned for each row with the configuration name
appearing on the first, the operator
on the second, and the configuration value
on the third.
-single
option, each row is returned on one result line containing a name operator value
triplet.
This example returns the value of the configuration attribute Operating System
.
OSVal = `tsscmd GetTestCaseConfigurationAttribute "
Operating System"`
GetTestCaseConfigurationAttributeList
Gets the list of test case configuration attributes and their values.
config
= `tsscmdGetTestCaseConfigurationAttributeList
[-single]`
This command exits with one of the following results:
You create and maintain test case configuration attributes from TestManager. This command returns the current settings for the current test case.
The test case configuration attribute value can be obtained in either of two formats:
-single
option, three result lines are returned for each row with the configuration name
appearing on the first, the operator
on the second, and the configuration value
on the third.
-single
option, each row is returned on one result line containing a name operator value
triplet.
This example returns the current test case configuration attribute list.
config = `tsscmd GetTestCaseConfigurationAttributeList
`
GetTestCaseConfigurationAttribute
Gets the name of the configuration (if any) associated with the current test case.
config
=`tsscmdGetTestCaseConfigurationName
`
On success, this command returns the name of the configuration associated with the test case in use. The command exits with one of the following results:
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.
tcConfig = `tsscmd GetTestCaseConfigurationName
`
Gets the name of the test case in use.
testcase=`tsscmd GetTestCaseName
`
On success, this command returns the name of the current test case. The command exits with one of the following results:
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
.
tcName = `tsscmd GetTestCaseName
`
Gets the value of a test tool execution option.
optVal
=`tsscmdGetTestToolOption
optionName
`
optionName
The name of the test tool execution option whose value is returned.
On success, this command returns the value of the specified test tool execution option. On failure, it returns nothing: call ErrorDetail for information.
If you develop adapters for a new test script type that support options, you can use this command to get the value of a specified option.
This example returns the value of an option called persist
.
optval = `tsscmd GetTestToolOption
"persist"`
handle
= `tsscmdJavaApplicationStart
[-workdirworkingDir
] [-classpathclassPath
][-jvm
JVM
][-jvmoptions
JVMOptions
]
app
`
On success, this command returns a handle for the started application. It exits with one of the following values.
This example starts application myJavaApp
.
myAppHandle = `tsscmd JavaApplicationStart
myApp`
ApplicationPid, A
pplicationStart, ApplicationWait
Gets the next negative exponentially distributed random number with the specified mean.
nnext
=`tsscmdNegExp
mean
`
mean
The mean value for the distribution.
This command returns the next negative exponentially distributed random number with the specified mean, or -1 if there is an error. The command exits with one of the following results:
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.
tsscmd SeedRand 10
next = `tsscmd NegExp
10`
Rand, SeedRand, Uniform
next=`tsscmd Rand
`
This command returns the next random number in the range 0 to 32767, or -1 if there is an error. The command exits with one of the following results:
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.
next = `tsscmd Rand
`
SeedRand, NegExp, Uniform
Seeds the random number generator.
tsscmdSeedRand
seed
This command exits with one of the following results:
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:
tsscmd SeedRand
10
Rand, NegExp, Uniform
Prints a message to the virtual tester's error file.
tsscmdePrint
message
This command exits with one of the following results:
This example prints to the error file the message Login failed. The quotes are optional.
tsscmd ePrint
"Login failed"
Prints a message to the virtual tester's output file.
tsscmdmessage
This command exits with one of the following results:
This example prints the message Login successful. The quotes are optional.
tsscmd Print
"Login successful"
Gets the next uniformly distributed random number.
unext
=`tsscmdUniform
low
high
`
low
The low end of the range.
high
The high end of the range.
This command returns the next uniformly distributed random number in the specified range, or -1 if there is an error. The command exits with one of the following results:
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.
If the error return value -1 is a legitimate value for the specified range, then TSSErrorDetail exits with value 0.
This example gets the next uniformly distributed random number between -10 and 10.
next = `tsscmd Uniform
-10 10`
Rand, SeedRand, NegExp
str
=`tsscmdUniqueString
`
On success, this command 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 command to construct the name for a unique asset, such as a test script source file.
This example returns a unique text string.
str = `tsscmd UniqueString
`
The Command Line Interface to Rational Test Script Services | Rational Software Corporation |
Copyright (c) 2003, Rational Software Corporation | http://www.rational.com support@rational.com info@rational.com |