Test Script Services Reference |
This section documents functions that may be required by applications. They are not typically used by test scripts.
A suite can contain multiple test scripts of different types. When TestManager executes a suite, a separate session is started for each type of script in the suite. Each session lasts until all scripts of the type have finished executing. Thus, if a suite contains three Visual Basic test scripts and six VU test scripts, two sessions are started and each remains active until all scripts of the respective types finish.
In a given suite run, a session can be run directly (inside the TestManager process space) or by a separate TSS server process (proxy). The latter happens only if the following two conditions are met:
rttssremote.lib
.
Unlike most TSS methods, the Session methods do not generate error codes or throw exceptions. Instead, they return status values indicating success or the cause of failure.
Commonly used with TestManager.
Applications can use the session methods listed in the following table to manage proxy TSS servers and sessions on behalf of test scripts. These methods are not needed for sessions that are directly executed by TestManager. These are methods of class TSSSession
.
Connect
Connects to a TSS proxy server.
Context
Passes context information to a TSS server.
Disconnect
Disconnects from a TSS proxy server.
ServerStart
Starts a TSS proxy server.
ServerStop
Stops a TSS proxy server.
Shutdown
Stops logging and initializes TSS.
Connects to a TSS proxy server.
Connect
(host
As String,port
As Integer,id
As Long) As Long
This method exits with one of the following results:
ERROR_CONVERT_BSTR
. An encountered string cannot be converted.
ERROR_INVALID_PARM
. A required argument is missing or invalid.
TSS_NOOP
. A connection and ID had already been established for this execution thread.
port
.
TSS_SYSERROR
. A system error occurred. Call ErrorDetail
for information.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
For scripts that are executed by a proxy process rather than directly by the TSEE, this function must be called before any other TSS functions. This function is also required when a script starts a new thread of execution.
The direct TSS DLL ignores host
and port
, and associates the id
with the current execution thread. If the thread already had an ID, id
is ignored. (You cannot change id
.)
This example connects to a TSS server running on host 192.36.25.107. The port
is defined in the example for ServerStart.
Dim session as New TSSSession
session.Connect
"192.36.25.107",port ,0
Passes context information to a TSS server.
Context
(ctx
As ContextKey,value
As String) As Long
ctx
The type of context information to pass: Can be one of the following:
value
The information of type
ctx
to pass.
This methodexits with one of the following results:
ERROR_CONVERT_BSTR
. An encountered string cannot be converted.
ERROR_INVALID_PARM
. A required argument is missing or invalid.
TSS_OK
. Success.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_INVALID
. The specified ctx
is invalid.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
This call is useful for test scripts that are executed by a stand-alone process -- outside the TestManager framework -- and that also make TSS calls. The call passes information, such as the log file name, that would be passed through shared memory if the script were executed by TestManager.
Test scripts that are executed by a proxy TSS server process should make this call immediately after TSSSession.Connect, before accessing any other TSS services. Otherwise, inconsistent results can occur.
This example passes a working directory to the current proxy TSS server.
Dim session As New TSSSession
session.Context
CTXT_workingDir,"C:\temp"
Disconnects from a TSS proxy server.
Disconnect
()
This call closes the connection established by TSSSession.Cconnect()
and performs any required cleanup operations.
This example disconnects from the TSS server.
Dim session as New TSSSession
session.Disconnect
ServerStart
(port
As Integer) As Long
port
The listening port for the TSS server. If specified as
0
(recommended), the system chooses the port and returns its number to port
.
This method exits with one of the following results:
TSS_OK
. Success.
TSS_NOOP
. A TSS server was already listening on port
.
ErrorDetail
for information.
TSS_SYSERROR
. A system error occurred. Call ErrorDetail
for information.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
No TSS server is started if one is already running. A test script that is to be executed by a proxy server and that might be the first to execute should make this call.
This example starts a proxy TSS server on a system-designated port, whose number is returned to port
.
Dim port As Long
port = 0
Dim session as New TSSSession
session.ServerStart
port
ServerStop
(port
As Integer) As Long
port
The port number that the TSS server to be stopped is listening on.
This methodexits with one of the following results:
TSS_OK
. Success.
TSS_NOOP
. No TSS server was listening on port
.
TSS_SYSERROR
. A system error occurred. Call ErrorDetail
for information.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
In a test suite with multiple scripts, only the last executed script should make this call.
This example stops a proxy TSS server that was started by the example for ServerStart.
session.ServerStop
port
Stops logging and initializes TSS.
Shutdown
()
This method exits with one of the following results:
TSS_OK.
Success.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_INVALID
. The specified ctx
is invalid.
TSS_ABORT
. Pending abort resulting from a user request to stop a suite run.
This call stops logging functions, pauses a playback session, and initializes TSS to resume logging and executing the next task.
This example shuts down logging during session execution so that logging can be restarted for the next task.
Dim session As New TSSSession
...
session.Shutdown
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 |