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).
Use the datapool commands listed in the following table to access and manipulate datapools within your scripts.
DatapoolClose
Closes a datapool.
DatapoolColumnCount
Returns the number of columns in a datapool.
DatapoolColumnName
Returns the name of the specified datapool column.
DatapoolFetch
Moves the datapool cursor to the next row.
DatapoolOpen
Opens the named datapool and sets the row access order.
DatapoolRewind
Resets the datapool cursor to the beginning of the datapool access order.
DatapoolRowCount
Returns the number of rows in a datapool.
DatapoolSearch
< Searches a datapool for the named column with a specified value.
DatapoolSeek
Moves the datapool cursor forward.
DatapoolValue
Retrieves the value of the specified datapool column.
tsscmdDatapoolClose
dpid
dpid
The ID of the datapool to close. Returned by DatapoolOpen.
This command exits with one of the following results:
This example opens the datapool custdata
with default row access and closes it.
dpid = `tsscmd DatapoolOpen custdata`
tsscmd DatapoolClose
dpid
Returns the number of columns in a datapool.
columns = `tsscmdDatapoolColumnCount
dpid`
dpid
The ID of the datapool. Returned by DatapoolOpen.
On success, this command returns the number of columns in the specified datapool. The command exits with one of the following results:
This example opens the datapool custdata
and gets the number of columns.
dpid = `tsscmd DatapoolOpen custdata`
columns = `tsscmd DatapoolColumnCount
dpid`
Gets the name of the specified datapool column.
columnName
= `tsscmdDatapoolColumnName
dpid
columnNumber
`
dpid
The ID of the datapool. Returned by DatapoolOpen.
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 command returns the name of the specified datapool column. The command exits with one of the following results:
This example opens a three-column datapool and gets the name of the third column.
dpid = `tsscmd DatapoolOpen custdata`
tsscmd DatapoolFetch dpid
colName = `tsscmd DatapoolColumnName
dpid 3`
Moves the datapool cursor to the next row.
tsscmdDatapoolFetch
dpid
dpid
The ID of the datapool. Returned by DatapoolOpen.
This command exits with one of the following results:
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 DatapoolValue
.
The "next row" is determined by the assessFlags
passed with the open call. The default is the next row in sequence. See DatapoolOpen
.
After a datapool is opened, a DatapoolFetch
is required before the initial row can be accessed.
An end-of-file condition results if a script fetches past the end of the datapool, which can occur only if access flag NOWRAP
was set on the open call. If the end-of-file condition occurs, the next call to DatapoolValue
results in a runtime error.
This example opens datapool custdata
with default (sequential) access and positions the cursor to the first row.
dpid = `tsscmd DatapoolOpen custdata`
tsscmd DatapoolFetch
dpid
DatapoolOpen
, DatapoolSeek
, DatapoolValue
Opens the named datapool and sets the row access order.
dpid
=`tsscmdDatapoolOpen
[-accessaccessFlags
]name
[colname
=value
...]`
name
The name of the datapool to open. If
accessFlags
includes NO_OPEN,
no CSV datapool is opened; instead, name
refers to the specified name/value pairs 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:
SEQUENTIAL
- Physical order (default)
PRIVATE
- Virtual testers each work from their own sequential, random, or shuffle access order (default)
SHARED
- All virtual testers work from the same access order
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 PRIVATE
. Ignored if used with RANDOM
.
REWIND
specifies that the datapool should be rewound when opened. Ignored unless used with
PRIVATE
.
NO_OPEN
specifies that, instead of a CSV file, the opened datapool consists only of specified column/value pairs.
colname=value ...
Optionally, a list of one or more column/value pairs, where
colname
is the column name and value
is the override value to be returned by DatapoolValue for that column name.
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 DatapoolValue for that column name.
On success, this command returns a positive integer indicating the ID of the opened datapool. The command exits with one of the following results:
accessFlags
argument is or results in an invalid combination.
name
was found.
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 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.
If multiple virtual testers access the same datapool in a suite, the datapool cursor is managed as follows:
SHARED
option initializes the cursor. In the same suite run (and, with the PERSIST
flag, in subsequent suite runs), virtual testers that subsequently use the same datapool opened with SHARED share the initialized cursor.
PRIVATE
option initializes the private cursor for a virtual tester. In the same suite run, a subsequent open that uses PRIVATE sets the cursor to the last row accessed by that virtual tester.
This example opens the datapool named custdata
, with a modified row access.
dpid = `tsscmd DatapoolOpen
-a SHUFFLE -a PERSIST custdata`
Resets the datapool cursor to the beginning of the datapool access order.
tsscmdDatapoolRewind
dpid
dpid
The ID of the datapool. Returned by DatapoolOpen.
This command exits with one of the following results:
The datapool is rewound as follows:
SEQUENTIAL
, DatapoolRewind
resets the cursor to the first record in the datapool file.
RANDOM
or SHUFFLE
, DatapoolRewind
restarts the random number sequence.
SHARED
, DatapoolRewind
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.
dpid = `tsscmd DatapoolOpen custdata`
tsscmd DatapoolSeek dpid 2
tsscmd DatapoolRewind
dpid
Returns the number of rows in a datapool.
rows = `tsscmdDatapoolRowCount
dpid`
dpid
The ID of the datapool. Returned by DatapoolOpen.
On success, this command returns the number of rows in the specified datapool. The command exits with one of the following results:
This example opens the datapool custdata
and gets the number of rows in the datapool.
dpid = `tsscmd DatapoolOpen custdata`
rows = `tsscmd DatapoolRowCount
dpid`
Searches a datapool for a named column with a specified value.
tsscmdDatapoolSearch
dpid
column
=value
[...]
dpid
The ID of the datapool. Returned by DatapoolOpen.
column
=value
One or more column/value pairs to be searched for.
This command exits with one of the following results:
When a row is found containing the specified values, the cursor is set to that row.
This example searches the datapool custdata
for a row containing the column named Last
with the value Doe
:
dpid = `tsscmd DatapoolOpen custdata`
rowNumber=`tsscmd DatapoolSearch
dpid Last=Doe`
Moves the datapool cursor forward.
tsscmdDatapoolSeek
dpid
count
dpid
The ID of the datapool. Returned by DatapoolOpen.
count
A positive number indicating the number of rows to move forward in the datapool.
This command exits with one of the following results:
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 DatapoolValue
.
The meaning of "forward" depends on the accessFlags
passed with the open call; see DatapoolOpen
. This call is functionally equivalent to calling DatapoolFetch
count
times.
An end-of-file error results if cursor wrapping is disabled (by access flag NOWRAP
) and count
moves the access row beyond the last row. If DatapoolValue
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.
dpid = `tsscmd DatapoolOpen custdata`
tsscmd DatapoolSeek
dpid 2
DatapoolFetch
, DatapoolOpen
, DatapoolValue
Retrieves the value of the specified datapool column in the current row.
value
= `tsscmd DatapoolValue
dpid
columnName
`
dpid
The ID of the datapool. Returned by DatapoolOpen.
columnName
The name of the column whose value you want to retrieve.
On success, this command returns the value of the specified datapool column in the current row. The command exits with one of the following results:
columnName
is not a valid column in the datapool.
This call gets the value of the specified datapool column from the current datapool row, which has been loaded into memory either by DatapoolFetch
or DatapoolSeek
.
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 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
.
dpid = `tsscmd DatapoolOpen custdata`
tsscmd DatapoolFetch dpid
colVal = `tsscmd DatapoolValue
dpid Middle`
DatapoolFetch
, DatapoolOpen
, DatapoolSeek
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 |