TestDB - test case database class
Shane P. McCarron <shane@aptest.com>
Copyright 2002-2011 Applied Testing and Technology, Inc. All Rights Reserved.
use TestDB; Open the cache Database for writing my $db = new TestDB(1); get a handle to the whole test database $data = $db->test(); get a handle to a specific test's data $data = $db->test($testID); release the database $db-E<gt>release();
The TestDB object is a generic multi-level data structure storage facility. The data stored in this facility is expected to be keyed by a unique value - probably the ID of the test case.
The data structure of this object is optimized to be most efficient when used in conjunction with MLDBM and a single key hashed database. This object CAN use serialized objects as well, but it is MUCH slower. Note that when using MLDBM, the save method doesn't do anything (except possibly for the first time it is called if the database had not yet been converted to MLDBM format).
$tdb = new TestDB(suite, [read/write [, timeout[, path]]]);
Creates a new test database object, optionally opening a non-default target file and optionally making it writeable.
boolean set to True if the test database needs to be writeable or False if it can be readOnly.
the number of seconds to wait for a lock. Defaults to 60 seconds.
a path to an alternate database (the default is implementation defined).
returns a reference to the test database object.
$fref = $tdb->field( fname ) ;
fname is the name of a test case field.
Returns a reference to the field definition, or undef if the field does not exist. This is a convenience function - short cut to schema->field.
$path = $tdb->filesPath( [ $directory ] ) ;
directory is an optional folder within the test tree.
Returns the full filesystem path to directory within the tree.
$suffix = $tdb->fileSuffix() ;
Returns '.bts".
$ref = $tdb->idField() ;
Returns a reference to a field object of type ID.
Removes all tests from the database. Must have a write lock before you can do this.
returns true if it succeeded, false if it did not.
$newName = $tdb->makeName($folder, $pattern, $asFolder);
folder is a folder in which the test will be created. Note that this string should contain the '.dir' suffixes, and should be relative to the suite. As with all directory names, it should NOT end in a slash.
pattern is a string on which the name will be based.
asFolder is a flag that indicates whether to create the name as a folder instead of a test case.
Returns a new name that is unique in the folder, and is based upon pattern. If there was an error, returns undef.
$tdb->numTests();
returns the number of tests in the database.
$pfx = $tdb->outlinePrefix( [ prefix ] ) ;
If prefix is supplied, sets the outlinePrefix for this test suite to that value.
Returns the previous prefix value .
returns a path to the cache file.
$tdb->print(); $tdb->print(ID);
returns the string-ified version of the entire database, or just the contents of the test ID.
$res = $tdb->deleted(name) ;
Returns true if the file is in $deletedDir, and false if it is not.
$res = $tdb->recycled(name) ;
Returns true if the file is in the recycle bin, and false if it is not.
$tdb->release() ;
$tdb->buildReqLinks( [ reqDB ]) ;
reqDB is an optional handle to a requirements database. If provided, then the corresponding back link table is also populated.
Traverse all tests in the database looking for requirements linkage. If there are requirements, then populate its entry in the reqsByUUID hash. If there is a reqDB connection, then ensure the requirement actually exists. If it does not, silently clean it out of the test case.
Returns nothing.
hashRef = $tdb->reqsByUUID( $uuid [, $ref ] ) ;
uuid is a uuid of a test case.
ref is an optional reference to a hash of requirement UUIDs.
Returns a reference to a hash of requirement UUIDs that are associated with the test case.
returns the path saved into, or undef if the save failed.
@list = $tdb->allTests( [includeRecycled [, includeDeleted ] ] ) ;
includeRecycled is an optional boolean. It defaults to false.
returns a list of all tests
@list = $tdb->tests( [includeRecycled] ) ;
includeRecycled is a boolean. If true, items in the recycle bin are included as well. Defaults to false.
returns a list of defined tests
$tdb->test(); $tdb->test(ID); $tdb->test(ID, ref);
With no parameter, retrieves a pointer to the raw test database hash.
With an ID parameter, retrieves the data for a specific ID.
With an ID and a ref, sets the parameters for a test to ref.
returns the pointer to the entire hash, or to the data for a specific test.
Returns the current ID for a test case that matches the UUID. Returns undef if there is no such test case. If called with no UUID parameter, returns a reference to the entire hash table.
Returns the UUID associated with a requirement named name. If no such requirement is in the database, returns undef.
$tdb->Lock() ;
Ensures the caches and this database are locked.
$tdb->Unlock() ;
Ensures the caches and this database are unlocked.
$tdb->delete($test);
deletes a test if it is defined. Also updates the collection of UUIDs so the test is no longer indexed.
$id = $tdb->displayID( name, noPath, asText, onclick ) ; ($id, $noPathId) = $rdb->displayID( name, undef, asText, onclick ) ;
name is the name of a requirement.
noPath is an optional boolean flag that indicates whether to include the path in the ID. It defaults to false. In an array context, this flag is ignored since it returns both forms.
asText is an optional boolean flag that indicates whether the content should be emitted as test only, or if it is intended for markup use. It defaults to false (markup use).
onclick is an optional javascript function that can take the UUID as a parameter. If supplied, the returned name will be wrapped in an "span" element and passed the UUID.
Returns the displayID, including the outline number if appropriate. In an array context, returns (id, noPathId).
$id = $tdb->displayIDByUUID( uuid, noPath, asText, onclick ) ; ($id, $noPathId) = $rdb->displayIDByUUID( name, undef, asText, onclick ) ;
noPath is an optional boolean flag that indicates whether to include the path in the ID. It defaults to false. In an array context this is ignored.
asText is an optional boolean flag that indicates whether the content should be emitted as text only, or if it is intended for markup use. It defaults to false (markup use).
onclick is an optional javascript function that can take the UUID as a parameter. If supplied, the returned name will be wrapped in an "span" element and passed the UUID.
Returns the displayID, including the outline number if appropriate. In an array context, returns the id with and without path information.
@list = $testDB->unnumbered( [ $directory, $recurse ] ) ;
directory is an optional folder to start looking from.
recurse is an optional flag to look at subfolders of directory or the current directory. It defaults to true.
Updates the associated SuiteDB, if there is one, to ensure the last edit time is correct.
Returns undef if there is no SuiteDB associated with this session, or 1 when it succeeds.
$tdb->SQL_deleteTestCase(UUID) ;
Returns nothing.
@cols = $testDB->SQL_tableDef( tname ) ;
tname is the name of a SQL table
Returns a list item per column, formatted for use in a CREATE statement.
@tfields = $tdb->SQL_tableFields( tableName ) ;
tableName is the name of the SQL field. We can derive the ATM field from this easily.
Returns a list of column names for the table.
my @tlist = $tdb->SQL_tlist();
Returns a list of all tables this object will operate upon.
my $tname = $tdb->SQL_tname;
Returns the name of the table for this object.
$tdb->SQL_updateTestCase(UUID, hash) ;
UUID is the ID of the test case to update.
hash is the data to populate the test case record with.
Returns nothing.
SQL_insertMulti(tdata, fname [, tname, trow, values] ) ;
tdata is a reference to the test case data hash.
fname is the name of the field to populate.
tname is an optional ATM table name that this field is within.
trow is an optional table row number for this field in an optional ATM table.
values are the values set in that row of the table for this field.
Returns nothing.
SQL_insertTabledata(tdata, tableName )
tdata is a reference to the test case data hash.
tableName is the name of the table to populate.
Returns nothing.
$tdb->SQL_createIndices( );
Add the index fields to the tables.
Returns nothing.
$tdb->SQL_createTable( );
The primary table associated with a test suite will only have a single record per test case. This will contain all fields that are NOT multi-select lists and NOT in a table. Each table referenced in an ATM test suite will have its own SQL table. Each multi-select list will also have its own SQL table.
Returns nothing.
$sqltype = $tdb-SQL_type(fref)
fref is a reference to a schema field definition.
This is just a thin veneer over the base ApTest::DBI type method, which will interrogate the underlying database and pick the best type. This function ascertains the base ATM type and passes that to the parent method, since Schema fields use a combination of type and style to define the actual "type".
Returns the most likely SQL type to use for the field.
$val = $tdb->SQL_value(fref, value) ;
fref is a reference to a SchemaField object.
value is the value to use.
Returns a suitable quoted value.
Copyright © 2000-2013 Applied Testing and Technology, Inc. All rights reserved.