NAME

TestDB - test case database class

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

Copyright 2002-2011 Applied Testing and Technology, Inc. All Rights Reserved.

SYNOPSIS

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).

DATA STRUCTURE

lock

a handle to the lock that is set for the object

writeable

a boolean that indicates whether the session is open read/write

usingDBM

a boolean to indicate if the file is from a DBM source

data->

a hash of stored test data

{data}->{ID}

{data}->{ID+SESSION}

METHODS

new - open the testDB

$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.

read/write

boolean set to True if the test database needs to be writeable or False if it can be readOnly.

timeout

the number of seconds to wait for a lock. Defaults to 60 seconds.

path

a path to an alternate database (the default is implementation defined).

returns a reference to the test database object.

field - get a reference to a test case field

$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.

filesPath - return a path to the tests tree

$path = $tdb->filesPath( [ $directory ] ) ;

directory is an optional folder within the test tree.

Returns the full filesystem path to directory within the tree.

fileSuffix - return the suffix for test case files.

$suffix = $tdb->fileSuffix() ;

Returns '.bts".

idField - return a reference to the field of type ID

$ref = $tdb->idField() ;

Returns a reference to a field object of type ID.

initialize - reset the database file.

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.

makeName - create a test/folder name in a folder

$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.

numTests - accessor for the number of stored tests

$tdb->numTests();

returns the number of tests in the database.

outlinePrefix - get/set the outline number prefix

$pfx = $tdb->outlinePrefix( [ prefix ] ) ;

If prefix is supplied, sets the outlinePrefix for this test suite to that value.

Returns the previous prefix value .

path - get/set the path to the cache file

returns a path to the cache file.

print - print the contents of the testDB

$tdb->print();
    $tdb->print(ID);

returns the string-ified version of the entire database, or just the contents of the test ID.

deleted - check if a file is already in $deletedDir

$res = $tdb->deleted(name) ;

Returns true if the file is in $deletedDir, and false if it is not.

recycled - check if a file is already in the trash

$res = $tdb->recycled(name) ;

Returns true if the file is in the recycle bin, and false if it is not.

release - release the database

$tdb->release() ;

buildReqLinks - populate table of test uuid to requirements

$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.

reqsByUUID - accessor to find requirements addressed by test UUID

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.

save - save the database

returns the path saved into, or undef if the save failed.

allTests - return the list of tests, including deleted ones

@list = $tdb->allTests( [includeRecycled [, includeDeleted ] ] ) ;

includeRecycled is an optional boolean. It defaults to false.

returns a list of all tests

tests - return the list of defined 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

test - accessor for test data

$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.

testByUUID - accessor for test case name by UUID

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.

getNameByUUID - see testByUUID

getUUIDByName - return the UUID associated with a name

Returns the UUID associated with a requirement named name. If no such requirement is in the database, returns undef.

Lock - override the lock method

$tdb->Lock() ;

Ensures the caches and this database are locked.

Unlock - override the unlock method

$tdb->Unlock() ;

Ensures the caches and this database are unlocked.

delete - delete a test from the database

$tdb->delete($test);

deletes a test if it is defined. Also updates the collection of UUIDs so the test is no longer indexed.

displayID - get the display ID for a testcase

$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).

displayIDByUUID - get the display ID for a test by UUID

$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.

unnumbered - return a list of test cases whose IDs are not numeric

@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.

updateSuiteDB - update the suite database

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.

SQL_deleteTestCase - remove a test case altogether

$tdb->SQL_deleteTestCase(UUID) ;

Returns nothing.

SQL_tableDef - return a list of table column definitions

@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.

SQL_tableFields - return the fields that make up a table

@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.

SQL_tlist - return a list of all tables used by this object

my @tlist = $tdb->SQL_tlist();

Returns a list of all tables this object will operate upon.

SQL_tname - return the table name

my $tname = $tdb->SQL_tname;

Returns the name of the table for this object.

SQL_updateTestCase - update test case data in a SQL store

$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 - put entries for a multi-select list in the table

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 - put entries for an ATM table in the SQL table

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.

SQL_createIndices - create the indexes for the tables

$tdb->SQL_createIndices( );

Add the index fields to the tables.

Returns nothing.

SQL_createTable - create the table(s)

$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.

SQL_type - determine the best SQL type for an ATM type

$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.

SQL_value - determine the best SQL value

$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.