Test Script Services Reference |
Use the synchronization methods to synchronize virtual testers during script playback. You can insert synchronization points and wait periods, and you can manage variables shared among virtual testers.
Commonly used with TestManager.
The following table lists the synchronization methods. They are methods of class TSSSync
.
SharedVarAssign
Performs a shared variable assignment operation.
SharedVarEval
Gets the value of a shared variable and operates on the value as specified.
SharedVarWait
Waits for the value of a shared variable to match a specified range.
SyncPoint
Puts a synchronization point in a script.
Performs a shared variable assignment operation.
SharedVarAssign
(name
As String,value
As Long, [op
As Long]) As Long
name
The name of the shared variable to operate on.
value
The right-side value of the assignment expression.
op
Assignment operator. Can be one of the following:
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_INVALID
. The entered name
is not a shared variable.
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.
Shared variables require configuration. For details, see Appendix A.
This example adds 5 to the value of the shared variable lineCounter
and puts the new value of lineCounter
in returnval
.
Dim returnVal as Long
Dim sync As New TSSSync
returnVal = sync.SharedVarAssign
"lineCounter", 5, SHVOP_add
Gets the value of a shared variable and operates on the value as specified.
SharedVarEval
(name
As String,value
As Long, [op
As Long]) As Long
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_INVALID
. The entered name
is not a shared variable.
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.
Shared variables require configuration. For details, see Appendix A.
This example post-decrements the value of shared variable lineCounter
and stores the result in val
.
Dim val, retVal as Long
Dim sync As New TSSSync
retVal = sync.SharedVarEval
"lineCounter", val, SHVADJ_post_inc
SharedVarAssign
, SharedVarWait
Waits for the value of a shared variable to match a specified range.
SharedVarWait
(name
As String,min
As Long, [max
As Long], [adjust
As Long], [timeout
As Long], [returnVal
As Long]) As Long
On success, this method returns 1
(condition was met before time-out) or 0
(time-out expired before the condition was met).
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_INVALID
. The entered name
is not a shared variable.
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 call provides a method of blocking a virtual tester until a user-defined global event occurs.
If virtual testers are blocked on an event using the same shared variable, TestManager guarantees that the virtual testers are unblocked in the same order in which they were blocked.
Although this alone does not ensure an exact multiuser timing order in which statements following a wait are executed, the additional proper use of the arguments min
, max
, and adjust
allows control over the order in which multiuser operations occur. (UNIX or Windows NT determines the order of the scheduling algorithms. For example, if two virtual testers are unblocked from a wait in a given order, the tester that was unblocked last might be released before the tester that was unblocked first.)
If a shared variable's value is modified, any subsequent attempt to modify this value -- other than through SharedVarWait
-- blocks execution until all virtual testers already blocked have had an opportunity to unblock. This ensures that events cannot appear and then quickly disappear before a blocked virtual tester is unblocked. For example, if two virtual testers were blocked waiting for name
to equal or exceed N
, and if another virtual tester assigned the value N
to name
, then TestManager guarantees both virtual testers the opportunity to unblock before any other virtual tester is allowed to modify name
.
Offering the opportunity for all virtual testers to unblock does not guarantee that all virtual testers actually unblock, because if SharedVarWait
is called with a nonzero value of adjust
by one or more of the blocked virtual testers, the shared variable value changes during the unblocking script. In the previous example, if the first user to unblock had called SharedVarWait
with a negative adjust
value, the event waited on by the second user would no longer be true after the first user unblocked. With proper choice of adjust
values, you can control the order of events.
Shared variables require configuration. For details, see Appendix A.
This example returns 1
if the shared variable inProgress
reaches a value between 10 and 20 within 60000 milliseconds of the time of the call. Otherwise, it returns 0
. svVal
contains the value of inProgress
at the time of the return, before it is adjusted. (In this case, the adjustment value is 0 so the value of the shared variable is not adjusted.)
Dim retVal, svVal As Long
svVal = 0
Dim sync As New TSSSync
retVal = sync.SharedVarWait
"inProgress",10,20,0,60000,svVal
SharedVarAssign
, SharedVarEval
Puts a synchronization point in a script.
SyncPoint
(label
As String)
label
The name of the synchronization point.
This method maygenerate one of the following error codes:
ERROR_CONVERT_BSTR
. An encountered string cannot be converted.
ERROR_INVALID_PARM
. A required argument is missing or invalid.
TSS_NOOP
. The TSS server is running proxy.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_INVALID
. The synchronization point label
is invalid.
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 script pauses at a synchronization point until the release criteria specified by the suite have been met. If the criteria are met, the script delays a random time specified in the suite and then resumes execution.
Typically, it is better to insert a synchronization point into a suite from TestManager rather than use the SyncPoint
call inside a script.
If you insert a synchronization point into a suite, synchronization occurs at the beginning of the script. If you insert a synchronization point into a script with SyncPoint, synchronization occurs at the point of insertion. You can insert the command anywhere in the script.
Shared variables require configuration. For details, see Appendix A.
This example creates a sync point named BlockUntilSaveComplete
.
Dim sync As New TSSSync
sync.SyncPoint
"BlockUntilSaveComplete"
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 |