Test Script Services Reference |
During testing, it is often necessary to supply an application with a range of test data. Thus, in the functional test of a data entry component, you may want to try out the valid range of data, and also to test how the application responds to invalid data. Similarly, in a performance test of the same component, you may want to test storage and retrieval components in different combinations and under varying load conditions.
A datapool is a source of data stored in a Rational project that a test script can draw upon during playback, for the purpose of varying the test data. You create datapools from TestManager, by clicking Tools > Manage > Datapools. For more information, see the datapool chapter in the Rational TestManager User's Guide. Optionally, you can import manually created datapool information stored in flat ASCII Comma Separated Values (CSV) files, where a row is a newline-terminated line and columns are fields in the line separated by commas (or some other field-delimiting character).
Commonly used with TestManager and QualityArchitect.
Use the datapool methods listed in the following table to access and manipulate datapools within your scripts. These are methods of class TSSDatapool
.
Close
Closes a datapool.
ColumnCount
Returns the number of columns in a datapool.
ColumnName
Returns the name of the specified datapool column.
Fetch
Moves the datapool cursor to the next row.
Open
Opens the named datapool and sets the row access order.
Rewind
Resets the datapool cursor to the beginning of the datapool access order.
RowCount
Returns the number of rows in a datapool.
Search
Searches a datapool for the named column with a specified value.
Seek
Moves the datapool cursor forward.
Value
Retrieves the value of the specified datapool column.
Close
() As Long
This method exits with one of the following results:
TSS_OK
. Success.
TSS_NOSERVER.
No previous successful call to TSSSession.Connect
.
TSS_INVALID
. The datapool identifier is invalid.
Only one open datapool at a time is supported. A Close is thus required between intervening Open
calls. For a script that opens only one datapool, Close is optional.
This example opens the datapool custdata
with default row access and closes it.
Dim retVal As Long
Dim dp As New TSSDatapool
dp.Open "custdata"
retVal = dp.Close
Returns the number of columns in a datapool.
ColumnCount
() As Long
On success, this method returns the number of columns in the open datapool.
This method may generate one of the followingerror codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_INVALID
. The datapool identifier 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.
This example opens the datapool custdata
and gets the number of columns.
Dim columns as Long
Dim dp As New TSSDatapool
dp.Open "custdata"
columns = dp.ColumnCount
Gets the name of the specified datapool column.
ColumnName
(columnNumber
As Long) As String
columnNumber
A positive number indicating the number of the column whose name you want to retrieve. The first column is number 1.
On success, this method returns the name of the specified datapool column.
This method may generate one of the followingerror codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_INVALID
. The datapool identifier or column number 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.
This example opens a three-column datapool and gets the name of the third column.
Dim colName as String
Dim dp as New TSSDatapool
if (dp.Fetch = True) Then
colName = dp.ColumnName
3
EndIf
Moves the datapool cursor to the next row.
Fetch
() As Boolean
This method returns True
(success) or False
(end-of-file).
This method may generate one of the following error codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_INVALID
. The datapool identifier 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.
This call positions the datapool cursor on the next row and loads the row into memory. To access a column of data in the row, call Value
.
The "next row" is determined by the assessFlags
passed with the open call. The default is the next row in sequence. See Open
.
After a datapool is opened, a Fetch
is required before the initial row can be accessed.
An end-of-file (TSS_EOF)
condition results if a script fetches past the end of the datapool, which can occur only if access flag TSS_DP_NOWRAP
was set on the open call. If the end-of-file condition occurs, the next call to Value
results in a runtime error.
This example opens datapool custdata
with default (sequential) access and positions the cursor to the first row.
Dim retVal As Boolean
Dim dp As New TSSDatapool
dp.Open "custdata"
retVal = dp.Fetch
Opens the named datapool and sets the row access order.
Open
(name
As String, [accessFlags
As Long], [overrides
[] As NamedValue])
name
The name of the datapool to open. If
accessFlags
includes TSS_DP_NO_OPEN,
no CSV datapool is opened; instead, name
refers to the contents of overrides
specifying a one-row table. Otherwise, the CSV file name
in the Rational project is opened.
accessFlags
Optional flags indicating how the datapool is accessed when a script is played back. Specify at most one value from each of the following categories:
TSS_DP_SEQUENTIAL
- Physical order (default)
TSS_DP_RANDOM
- Any order, including multiple access or no access
TSS_DP_PRIVATE
- Virtual testers each work from their own sequential, random, or shuffle access order (default)
TSS_DP_SHARED
- All virtual testers work from the same access order
TSS_DP_PERSIST
specifies that the datapool cursor is persistent across multiple script runs. For example, with a persistent cursor, if the row number after a suite run is 100, the first row accessed in a subsequent run is numbered 101. Cannot be used with TSS_DP_PRIVATE
. Ignored if used with TSS_DP_RANDOM
.
TSS_DP_REWIND
specifies that the datapool should be rewound when opened. Ignored unless used with
TSS_DP_PRIVATE
.
TSS_DP_NO_OPEN
specifies that, instead of a CSV file, the opened datapool consists only of column/value pairs specified in a local array overrides
[].
overrideCount
The number of columns in array
overrides
. Must be greater than 0 if access flag TSS_DP_
NO_OPEN is specified; otherwise, must be 0.
overrides
A local, two-dimensional array of column/value pairs, where
overrides
[n].name
is the column name and overrides
[n].value
is the value returned by Value for that column name.
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_INVALID
. The accessFlags
argument is or results in an invalid combination.
TSS_NOTFOUND
. No datapool of the given name
was found.
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.
If the accessFlags
argument is specified as 0 or omitted, the rows are accessed in the default order: sequentially, with no wrapping, and with a private cursor. If multiple accessFlags
are specified, they must be valid combinations as explained in the syntax table.
If accessFlags
specified with Open
contradict those specified with the datapool configuration section (see Appendix A), the Open
call fails with TSS_INVALID
. Otherwise, the two sets of access flags are combined.
If you close and then reopen a private-access datapool with the same accessFlags
and in the same or a subsequent script, access to the datapool is resumed as if it had never been closed.
A test script executed by TestManager can open only one datapool at a time.
If multiple virtual testers access the same datapool in a suite, the datapool cursor is managed as follows:
NamedValue
is a dimensioned array of name/value pairs. For example, an array of 10 name/value pairs could be implemented as follows:
Dim NV(9,1) As String NV(0,0)= "name1" NV(0,1)= "value1" NV(1,0)= "name2" NV(1,1)= "value2" ...
This example opens the datapool named custdata
, with a modified row access.
Dim dp As New TSSDatapool
dp.Open
"custdata",TSS_DP_SHUFFLE + TSS_DP_PERSIST
Resets the datapool cursor to the beginning of the datapool access order.
This method may generate one of the followingerror codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_INVALID
. The datapool identifier 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.
The datapool is rewound as follows:
DP_SEQUENTIAL
, Rewind
resets the cursor to the first record in the datapool file.
DP_RANDOM
or DP_SHUFFLE
, Rewind
restarts the random number sequence.
DP_SHARED
, Rewind
has no effect.
At the start of a suite, datapool cursors always point to the first row.
If you rewind the datapool during a suite run, previously accessed rows are fetched again.
This example opens the datapool custdata
with default (sequential) access, moves the access to the second row, and then resets access to the first row.
Dim dp As New TSSDatapool
dp.Open "custdata"
dp.Seek (2)
dp.Rewind
Returns the number of rows in a datapool.
RowCount
() As Long
On success, this method returns the number of rows in the open datapool.
This method may generate one of the followingerror codes:
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_INVALID
. The datapool identifier 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.
This example opens the datapool custdata
and gets the number of rows in the datapool.
Dim rows as Long
Dim dp As New TSSDatapool
dp.Open "custdata"
rows = dp.RowCount
Searches a datapool for a named column with a specified value.
Search
(keys
[] As NamedValue)
keys
An array containing values to be searched for.
This method may generate one of the followingerror codes:
ERROR_OUT_OF_MEMORY
. An attempt to allocate dynamic memory failed.
TSS_EOF
. The end of the datapool was reached.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_INVALID
. The datapool identifier 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.
When a row is found containing the specified values, the cursor is set to that row.
NamedValue
is a dimensioned array of name/value pairs. For example, an array of 10 name/value pairs could be implemented as:
Dim NV(9,1) As String NV(0,0)= "name1" NV(0,1)= "value1" NV(1,0)= "name2" NV(1,1)= "value2" ...
This example searches the datapool custdata
for a row containing the column named Last
with the value Doe
:
Dim toFind(0,1) As String
toFind(0,0)= "Last"
toFind(0,1)= "Doe"
Dim dp As New TSSDatapool
dp.Open "custdata"
if (dp.Fetch = True) Then
dp.Search
toFind
EndIf
Moves the datapool cursor forward.
Seek
(count
As Long)
count
A positive number indicating the number of rows to move forward in the datapool.
This method may generate one of the followingerror codes:
TSS_EOF
. The end of the datapool was reached.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_INVALID
. The datapool identifier 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.
This call moves the datapool cursor forward count
rows and loads that row into memory. To access a column of data in the row, call Value
.
The meaning of "forward" depends on the accessFlags
passed with the open call; see Open
. This call is functionally equivalent to calling Fetch
count
times.
An end-of-file (TSS_EOF) error results if cursor wrapping is disabled (by access flag TSS_DP_NOWRAP
) and count
moves the access row beyond the last row. If Value
is then called, a runtime error occurs.
This example opens the datapool custdata
with the default (sequential) access and moves the cursor forward two rows.
Dim dp As New TSSDatapool
dp.Open "custdata"
dp.Seek
2
Retrieves the value of the specified datapool column in the current row.
Value
(columnName
As String ) As Variant
columnName
The name of the column whose value you want to retrieve.
On success, this method returns the value of the specified datapool column in the current row.
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_EOF
. The end of the datapool was reached.
TSS_NOSERVER
. No previous successful call to TSSSession.Connect
.
TSS_INVALID
. The specified columnName
is not a valid column in the datapool.
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 gets the value of the specified datapool column from the current datapool row, which has been loaded into memory either by Fetch
or Seek
.
By default, the returned value is a column from a CSV datapool file located in a Rational datastore. If the datapool open call included the TSS_DP_NO_OPEN
access flag, the returned value comes from an override list provided with the open call.
This example retrieves the value of the column named Middle
in the first row of the datapool custdata
.
Dim colVal as Variant
Dim dp As New TSSDatapool
dp.Open "custdata"
if (dp.Fetch = True) Then
colVal = dp.Value
"Middle"
EndIf
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 |