Test Script Services |
Use the utility functions to perform actions common to many test scripts.
The following table lists the utility functions.
TSSApplicationPid()
Gets the process ID of an application.
TSSApplicationStart()
Starts an application.
TSSApplicationWait()
Waits for an application to terminate.
TSSDelay()
Delays the specified number of milliseconds.
TSSErrorDetail()
Retrieves error information about a failure.
TSSGetComputerConfiguration
AttributeList() Gets the list of computer configuration attributes and their values.
TSSGetComputerConfiguration
AttributeValue() Gets the value of a computer configuration attribute.
TSSGetPath()
Gets a pathname.
TSSGetScriptOption()
Gets the value of a script playback option.
TSSGetTestCaseConfiguration
Attribute() Gets the value of a test case configuration attribute.
TSSGetTestCaseConfiguration
AttributeList() Gets the list of test case configuration attributes and their values.
TSSGetTestCaseConfigurationName()
Gets the name of the configuration (if any) associated with the current test case.
TSSGetTestCaseName()
Gets the name of the test case in use.
TSSGetTestToolOption()
Gets a test case tool option.
TSSJavaApplicationStart()
Starts a Java application.
TSSNegExp()
Gets the next negative exponentially distributed random number with the specified mean.
TSSRand()
Gets the next random number.
TSSSeedRand()
Seeds the random number generator.
TSSStdErrPrint()
Prints a message to the virtual tester's error file.
TSSStdOutPrint()
Prints a message to the virtual tester's output file.
TSSUniform()
Gets the next uniformly distributed random number in the specified range.
TSSUniqueString()
Returns a unique text string.
Gets the process ID of an application.
s32TSSApplicationPid
(TSSAppHandleappHandle
)
appHandle
The ID of the application whose PID you want to get. Returned by
TSSApplicationStart()
or TSSJavaApplicationStart()
.
On success, this function returns the system process ID of the specified application. On failure, it returns 0: call TSSErrorDetail() for information.
This function works for applications started by TSSApplicationStart() or TSSJavaApplicationStart().
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
.
TSSAppHandle myAppHandle =TSSApplicationStart
("myAPP", "d:\myDir", 0); s32 myAppPID =TSSApplicationPid
(myAppHandle);
TSS
ApplicationStart(), TSSApplicationWait(),TSS
JavaApplicationStart()
TSSAppHandleTSSApplicationStart
(char *appHandle
, char *workingDir
, u32flags
)
On success, this function returns a handle for the started application. On failure, it returns 0: call TSSErrorDetail()for information.
TSSAppHandle
is defined as: typedef void *TSSAPPHandle
.
This example starts application myApp
.
TSSAppHandle myAppHandle = TSSApplicationStart
("myAPP", "d:\myDir",
0);
TSS
ApplicationPid(), TSSApplicationWait(),TSS
JavaApplicationStart()
Waits for an application to terminate.
s32TSSApplicationWait
(TSSAppHandleapp
, s32 *exitStatus
, s32timeout
)
This function exits with one of the following results:
TSS_OK.
Success.
TSS_FAIL
. The application was still running when the time-out expired.
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_SYSERROR
. The system returned an error: call TSSErrorDetail() 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.
This function works for applications started by TSSApplicationStart() or TSSJavaApplicationStart().
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.
s32 termStatus; TSSAppHandle myAppHandle =TSSApplicationStart
("myAPP", "d:\myDir", 0); s32 retval =TSSApplicationWait
(myAppHandle, termStatus, 600);
TSS
ApplicationPid(), TSSApplicationStart(),TSS
JavaApplicationStart()
Delays script execution for the specified number of milliseconds.
s32TSSDelay
(s32msecs
)
msecs
The number of milliseconds to delay script execution.
This function exits with one of the following results:
TSS_OK.
Success.
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
s32 retVal = TSSDelay
(10);
Retrieves error information about a failure.
s32TSSErrorDetail
(char *errorText
, s32 *len
)
errorText
OUTPUT. Returned explanatory error message about the previous TSS call, or an empty string ("") if the previous TSS call did not fail.
len
The length of string
errorText
.
This function returns TSS_OK
if the previous call succeeded. If the previous call failed, TSSErrorDetail() returns one of the error codes listed below and corresponding errorText
.
TSS_OK.
Success.
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
If the message is too long to fit in errorText
, it is truncated to len
and len
is updated to the message length.
This example opens a datapool and, if there is an error, displays the associated error message text.
char message[256];
s32 dpid, ecode, msglen = 256;
dpid = TSSDatapoolOpen ("custdata",0,0,NULL);
if (dpid < 0)
{
/* open failed, report error */
ecode = TSSErrorDetail
(message, &msglen);
fprintf(stderr, "TSSDatapoolOpen failed. code: %d, message: %s\n",
ecode, message);
}
Gets the list of computer configuration attributes and their values.
s32TSSGetComputerConfigurationAttributeList
(NamedValue[] **config
, s32*count
)
config
OUTPUT. An array containing configuration name/value pairs, where
config[n].name
is the attribute name and config[n].value
is its value.
count
OUTPUT. The number of rows in the
config
array.
On success, this function returns an array of computer configuration attribute names and their values. It exits with one of the following results:
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
You create and maintain computer configuration attributes from TestManager. This call returns the current settings.
The pointer to config
is valid until the next call of this function. The NamedValue
data type is defined as follows:
typedef struct { char *Name; char *Value; } NamedValue;
This example returns the current computer configuration attribute list.
s32 npairs;
NamedValue *config;
s32 retVal = TSSGetComputerConfigurationAttributeList
(&config,
&npairs);
TSSGetComputerConfigurationAttributeValue()
Gets the value of computer configuration attribute.
char *TSSGetComputerConfigurationAttributeValue
(char*name
)
name
The
name
of the computer configuration attribute whose value is to be returned.
On success, this function returns a handle for the started application. On failure, it returns NULL: call TSSErrorDetail()for information.
This example returns the value of the configuration attribute Operating System
.
char *OSVal = TSSGetComputerConfigurationAttributeValue
("Operating
System");
TSSGetComputerConfigurationAttributeList()
Gets the root path of a test asset.
char *TSSGetPath
(u32pathKey
)
pathKey
Specifies one of these values:
On success, this function returns the root of the currently executing test script or of the files attached to the log. On failure, it returns NULL: call TSSErrorDetail()for information.
The root path returned by this function 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 TSSContext()
.
This example returns the root path of the source from which the currently executing test script was selected.
char *scriptPath = TSSGetPath
(TSS_SOURCE_PATH);
TSSContext()
, TSSUniqueString()
Gets the value of a test script playback option.
char *TSSGetScriptOption
(char *optionName
)
optionName
The name of the script option whose value is returned.
On success, this function returns the value of the specified script option, or NULL if the value specified is not used by the execution adapter. The function exits with one of the following results:
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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. For implementation details about test script options and instructions on how to set options from TestManager, see Using Test Script Options.
This example gets the current value of a hypothetical script option named repeat_count
. The returned pointer to optVal
is valid until the next TSSGetScriptOption()
call.
char *optVal;
if (optVal = TSSGetScriptOption
("repeat_count"))
printf("The value of repeat_count is %s\n", repeat_count);
SessionSetOption(), TaskSetOption()
Gets the value of the specified test case configuration attribute.
s32 *TSSGetTestCaseConfigurationAttribute
(char*name
, TestCaseConfigurationAttribute *config
)
name
Specifies the name of the configuration attribute to be returned.
config
OUTPUT. The returned test case configuration value.
On success, this function returns the value of the specified test case configuration attribute. It exits with one of the following results:
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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 TestCaseConfigurationAttribute
data type is defined as follows:
typedef struct { char *name; char *operator char *value; } TestCaseConfigurationAttribute;
This example returns the value of the configuration attribute Operating System
.
TestCaseConfigurationAttribute OSVal =
TSSGetTestCaseConfigurationAttribute
("Operating System");
TSS
GetTestCaseConfigurationAttributeList()
Gets the list of test case configuration attributes and their values.
s32 *TSSGetTestCaseConfigurationAttributeList
(TestCaseConfigurationAttribute **config,
s32*count
)
On success, this function returns an array of test case configuration attribute names, base values, and operators. It exits with one of the following results:
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
You create and maintain test case configuration attributes from TestManager. This call returns the current settings for the current test case.
The TestCaseConfigurationAttribute
data type is defined as follows:
typedef struct { char *name; char *operator char *value; } TestCaseConfigurationAttribute;
This example returns the current test case configuration attribute list.
s32 nrows;
TestCaseConfigurationAttribute *config;
s32 retVal = TSSGetTestCaseConfigurationAttributeList
(&config,
&nrows);
TSS
GetTestCaseConfigurationAttribute()
Gets the name of the configuration (if any) associated with the current test case.
char *TSSGetTestCaseConfigurationName
(void)
On success, this function returns the name of the configuration associated with the test case in use. The function exits with one of the following results:
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
char *tcConfig = TSSGetTestCaseConfigurationName
();
Gets the name of the test case in use.
char *TSSGetTestCaseName
(void)
On success, this function returns the name of the current test case. The function exits with one of the following results:
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
Created from TestManager, a test case specifies the pass criteria for something that needs to be tested.
The returned pointer to testcase
is valid until the next TSSTestCaseName()
call.
This example stores the name of the test case in use in tcName
.
char *tcName;
if (tcName = TSSGetTestCaseName
())
printf("The test case is %s\n, tcName");
Gets the value of a test tool execution option.
char *TSSGetTestToolOption
(char *optionName
)
optionName
The name of the test tool execution option whose value is returned.
On success, this function returns the value of the specified test tool execution option. On failure, it returns NULL: call TSSErrorDetail() 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
.
char *optval = TSSGetTestToolOption
("persist");
TSSAppHandleTSSJavaApplicationStart
(char *app
, char *workingDir
, char *classPath
, char *JVM
, char *JVMOptions
)
On success, this function returns a handle for the started application. On failure, it returns NULL: call TSSErrorDetail()for information.
TSSAppHandle is defined as: typedef void *TSSAPPHandle
.
This example starts application myJavaApp
.
TSSAppHandle myAppHandle = TSSJavaApplicationStart
("myJavaAPP", "",
"", "", "");
TSS
ApplicationPid(),TSSA
pplicationStart(), TSSApplicationWait()
Gets the next negative exponentially distributed random number with the specified mean.
s32TSSNegExp
(s32mean
)
mean
The mean value for the distribution.
This function returns the next negative exponentially distributed random number with the specified mean, or -1 if there is an error. The function exits with one of the following results:
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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 mean, then TSSErrorDetail() returns TSS_OK
.
This example seeds the generator and gets a random number with a mean of 10.
s32 retVal = TSSSeedRand(10);
s32 next = TSSNegExp
(10);
TSS
Rand(), TSSSeedRand(),TSS
Uniform()
s32 TSSRand
(void)
This function returns the next random number in the range 0 to 32767, or -1 if there is an error. The function exits with one of the following results:
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
s32 next = TSSRand
();
TSS
SeedRand(), TSSNegExp(),TSS
Uniform()
Seeds the random number generator.
s32TSSSeedRand
(u32seed
)
This function exits with one of the following results:
TSS_OK.
Success.
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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.
TSSSeedRand()
uses the argument seed
as a seed for a new sequence of random numbers to be returned by subsequent calls to the TSSRand() routine. If TSSSeedRand()
is then called with the same seed value, the sequence of random numbers is repeated. If TSSRand() is called before any calls are made to TSSSeedRand()
, the same sequence is generated as when TSSSeedRand()
is first called with a seed value of 1.
This example seeds the random number generator with the number 10:
s32 retVal = TSSSeedRand
(10);
TSS
Rand(), TSSNegExp(),TSS
Uniform()
Prints a message to the virtual tester's error file.
s32TSSePrint
(char *message
)
This function exits with one of the following results:
TSS_OK.
Success.
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
This example prints to the error file the message Login failed.
s32 retVal = TSSePrint
("Login failed");
Prints a message to the virtual tester's output file.
s32TSSPrint
(char *message
)
This function exits with one of the following results:
TSS_OK.
Success.
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
This example prints the message Login successful.
s32 retVal = TSSPrint
("Login successful");
Gets the next uniformly distributed random number.
s32TSSUniform
(s32low
, s32high
)
low
The low end of the range.
high
The high end of the range.
This function returns the next uniformly distributed random number in the specified range, or -1 if there is an error. The function exits with one of the following results:
TSS_NOSERVER
. No previous successful call to TSSConnect()
.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
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 TSS_OK
.
This example gets the next uniformly distributed random number between -10 and 10.
int next = TSSUniform
(-10,10);
TSS
Rand(), TSSSeedRand(),TSS
NegExp()
char *TSSUniqueString
(void)
On success, this function returns a string guaranteed to be unique in the current test script or suite run. On failure, it returns NULL: call TSSErrorDetail()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.
char *str = TSSUniqueString
();
Rational TestManager Extensibility Reference | Rational Software Corporation |
Copyright (c) 2003, Rational Software Corporation | http://www.rational.com support@rational.com info@rational.com |