NAME

SuiteDB - suite metadata class

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

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

SYNOPSIS

use SuiteDB;

    # open the suite Database for writing
    my $db = new SuiteDB(1);

    # who is the creator of this suite?
    my $name = $db->creator()

    # and what is the description
    my $desc = $db->description() ;

    # release the database
    $db->release();

The SuiteDB 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 - usually a value prefixed by the module that wanted to store it. The purpose of this data store is to act as a general use storage facility for meta information related to items in a Test Suite (e.g., test session summary information).

The data structure of this object is optimized to be most efficient when used in conjunction with MLDBM and a single key hashed database (with short key names). 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

{description}
{creator}
{lastEditUpdate}
{lastReqEditUpdate}
{lastRunUpdate}
{numSets}
{numSessions}
{SET_name}

numtests - the number of tests

locked - whether the set is locked or not

mtime - the last modification time of the set (really the last modification time of any session in the set).

summary - the summary of the set

sessions - the sessions that are in this set

{SESS_nnnn}

assignedto - the list of assignees

description - the description

numtests - the number of tests

numUntested - the number still untested

isActive - whether the session is active or not

locked - whether the session is locked or not

mtime - the last modification time of the session

summary - the summary of the session

testset - the name of the associated test set

user - the name of the user who last changed the set

variable - the hash of session variables

{TEST_uuid}

sessHash - a hash of test sessions

{result}

the result of running the test.

{when}

The time when the test was run.

METHODS

new - open the suiteDB

$suiteDb = new SuiteDB(name, [read/write [, timeout[, path]]]);

Creates a new suite database object, optionally opening a non-default target file and optionally making it writeable.

name the name of the test suite to open
read/write boolean set to True if the suite 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 suite database object.

initialize - reset the database file.

Removes everything from the database.

returns true if it succeeded, false if it did not.

path - get/set the path to the file

returns a path to the file.

print - print the contents of the suiteDB

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

returns the string-ified version of the entire database.

profName - accessor for the profile name associated with this object

profName = $sdb->profName( [ name ] ) ;

Returns the name of the profile associated with this object. This ONLY happens if we are working in profile management mode.

release - save and release the data object

$suiteDb->release() ;

save - save the database

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

deleteSession - delete a session from the database

$suiteDb->deleteSession($session);

deletes a session if it is defined.

deleteSet - delete a set from the database

$suiteDb->deleteSet($name);

deletes a set if it is defined.

multiLists - return a list of multi-select lists in metadata

@mlists = $suiteDB->multiLists() ;

session - accessor for session data

$suiteDb->session(ID);
    $suiteDb->session(ID, ref);

With an ID parameter, retrieves the data for a specific session.

With an ID and a ref, sets the parameters for a session to ref.

returns the pointer a SuiteDB::Session object that represents the specific session.

The session meta data that is stored in this database includes:

assignedto

to whom this session is assigned (comma separated list).

description

The session description.

numtests

The number of tests.

numUntested

The number of tests still not tested.

isActive

Whether the session is currently active or not.

locked

Is the session locked?

mtime

The last modification time of the session.

summary

The summary of the session.

testset

The test set to which this session is attached.

user

The last user to modify the session.

variable

A hash of all variables defined for the session.

sessionList - return a list of sessions in the suite, or in a set

@sessionList = $suiteH->sessionList() ;
    @sessionList = $suiteH->sessionList(set) ;

    # get the list of sessions that have no test set
    @sessionList = $suiteH->sessionList(undef, 1) ;

set - accessor for set data

$setHash = $suiteDb->set(ID);
    $setHash = $suiteDb->set(ID, ref);

With an ID parameter, retrieves the data for a specific set.

With an ID and a ref, sets the parameters for a set to ref.

Adds a lastChangeTime key to the dataset when updating a test set. Returns the pointer to the data for a specific set.

Returns a reference to an object that has test set meta data, including:

numtests

The number of tests selected by the set.

locked

Whether the set is locked or not.

mtime

The last time the set was modified.

summary

The summary description of the test set.

sessions

A reference to a list of associated test sessions.

setList - return a list of sets in the suite

@setList = $suiteDb->setList( [ setGroup [, children ] ] ) ;

setGroup is an optional testset group name. If provided, only sets within that group are returned. If set to "", then only sets in NO group will be returned.

if the optional children parameter is true, then sets in the setGroup and all child set groups will be returned.

testMap - accessor for a test case execution map entries

$suiteDb->testMap(UUID);
    $suiteDb->testMap(UUID, ref);

With an UUID parameter, retrieves the data for a specific testcase.

With an UUID and a ref, sets the parameters for a testcase map to ref.

returns the pointer a SuiteDB::TestMap object that represents the specific test case.

The test case meta data that is stored in this database includes:

sessHash

A hash of test sessions - each entry contains

result

The result of running the test.

when

The time when the test was run.

lastEditUpdate - return the timestamp of the last edit change

$time = $suiteDb->lastEditUpdate() ;

lastFolderUpdate - return the timestamp of the last folder edit change

$time = $suiteDb->lastFolderUpdate() ;

lastReqEditUpdate - return the timestamp of the last requirements edit change

$time = $suiteDb->lastReqEditUpdate() ;

lastReqFolderUpdate - return the timestamp of the last requirements folder change

$time = $suiteDb->lastReqFolderUpdate() ;

lastRunUpdate - return the timestamp of the last run status change

$time = $suiteDb->lastRunUpdate() ;
    $time = $suiteDb->lastRunUpdate(setName) ;

lastUserPermUpdate - return the timestamp of the last run status change

$time = $suiteDb->lastUserPermUpdate() ;
    $time = $suiteDb->lastUserPermUpdate( timeStamp) ;

Returns the timestamp of the last time the user permission table for this suite was updated. If the table does not exist, returns 0.

numReqs - Accessor for number of requirements

$tests = $suiteDb->numReqs() ;

numSessions - Accessor for number of sessions in the suite

$sessCount = $suiteDb->numSessions( [num] ) ;

numSets - Accessor for number of sets in the suite

$setCount = $suiteDb->numSets( [num] ) ;

numTests - Accessor for number of tests

$tests = $suiteDb->numTests() ;

dirtyFlag - set the last update time at now and mark dirty

$val = $suiteDb->dirtyFlag( [ state ] ) ;

If state is supplied, it is a value to set. When state is 0, the data is NOT dirty. When state is 1, the associated "Run" data was updated, and the data is dirty. When state is 2, the associated "Edit" data was updated and the data is dirty.

Returns undef if the database is not writeable. Otherwise returns the current value of the dirtyFlag state;

results - get a handle to a test suite results object

$rRef = $suiteDb->results( [ $rRef ] ) ;

$rRef is an optional reference to a results object. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.

userPerms - get/set user permission hash

$permRef = $suiteDb->userPerms( [ $data ] ) ;

If the optional $data parameter is provided, the data is updated to that hash ref.

Returns a reference to a hash that maps userids to access level numbers.

variables - get a handle to a test suite variableset object

$vRef = $suiteDb->variables( [ $vRef ] ) ;

$vRef is an optional reference to a VariableSet object. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.

rfields - get a handle to a requirements field object

$rRef = $suiteDb->rfields( [ $rRef ] ) ;

$rRef is an optional reference to a requirements field object. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.

Note that ReqFields uses the Parent base class, so we need to be certain to NOT attempt to serialize that part of the object.

rundata - accessor for rundata field definitions

($fieldRef, $orderRef) = $suiteDb->rundata( [ $runRef, $orderRef ] ) ;

$runRef is an optional reference to a testFields hash from TestSession. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.

$orderRef is an optional reference to a list of defined rundata fields in order. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.

Note that unlike other suiteDB caching objects, this one will NOT automatically acquire the data if it is not in the cache.

schema - get a handle to a test suite schema object

$sRef = $suiteDb->schema( [ $sRef [, update ] ] ) ;

$sRef is an optional reference to a schema object. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.

$update is a flag. If true, then the cached image is updated even if an sRef is not passed in.

variableSet - get a handle to a test suite variable set

$vset = $suiteDb->dirtyFlag( [ curSet ] ) ;

If curSet is supplied, it is used as a handle to a variable set object for the suiteDB. Otherwise, one is initialized.

Returns a handle to a variable set.

Lock - override the lock method

$suiteDB->Lock() ;

Ensures the caches and this database are locked.

Unlock - override the unlock method

$suiteDB->Unlock() ;

Ensures the caches and this database are unlocked.

field - get a reference to a field object for a SQL field

$fref = $sdb->field( columnName )

columnName is the name of a SQL table column.

Returns a reference to an object that supports (at least) the isDate method.

SQL_deleteTestSession - remove a test case altogether

$tdb->SQL_deleteTestSession(sessNum) ;

Returns nothing.

SQL_tname - return the table name

my $tname = $sdb->SQL_tname;

Returns the name of the table for this object.

SQL_updateTestSession - update test session metadata in a SQL store

$sdb->SQL_updateTestSession(sessNum, hash) ;

sessNum is the ID of the test session to update.

hash is the data to populate the test session record with.

Returns nothing.

SQL_insertMulti - put entries for a multi-select list in the table

SQL_insertMulti(sessNum, sdata, fname );

sessNum is the session number we are updating.

sdata is a reference to the session meta data hash.

fname is the name of the field to populate.

Returns nothing.

SQL_createIndices - create table indices

$sdb->SQL_createIndices();

Returns nothing.

SQL_createTable - create the table(s)

$sdb->SQL_createTable();

Returns nothing.

SQL_makeTables - force creation of SQL tables

$sdb->SQL_makeTables() ;

Returns nothing.

SQL_tableDef - return a list of table column definitions

@cols = $suiteDB->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 a list of column names in a table

@cols = $suiteDB->SQL_tableFields( tname ) ;

tname is the name of a SQL table.

Returns a list of fields that are used in the table.

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

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

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

SQL_type - determine the best SQL type for an ATM type

$sqltype = $sdb->SQL_type(fref)

fref is a reference to a session variable 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 = $sdb->SQL_value(fref, value) ;

fref is a reference to a Variable object.

value is the value to use.

Returns a suitable quoted value.

SuiteDB::TestMap

NAME

SuiteDB::TestMap - class for manipulating a mapping from tests to sessions.

METHODS

new - create a new TestMap object

$tmap = new SuiteDB::TestMap(UUID) ;

Creates a TestMap object. Returns a reference to the created object.

entry - accessor for a session entry

my $entry = $tmap->entry(sessnum) ;

sessnum is a session number - note that these are NOT stored with leading zeroes.

Returns a reference to the hash entry for this entry, or undef if there is no entry for the session.

numEntries - accessor for number of entries

$num = $tmap->numEntries() ;

Returns the number of result entries ;

sortedList - return a list of history entries in date order

my @list = $tmap->sortedList( direction )

direction is a boolean - false means descending, true means ascending

Returns a list of hash entries sorted in the described order

update - update a testMap entry

$tmap->update( $session, $href ) ;

session is the session number to update.

href is a reference to a hash that contains at least a 'result' and a 'when' entry.

DESTROY() - tidy up

SuiteDB::Session

NAME

SuiteDB::Session - class for manipulating session metadata

METHODS

new - create a new Session object

$session = new SuiteDB::Session(sessnum) ;

Creates a session object. Returns a reference to the created object.

defaultVariable - return a variable OR the default if it is not set

$value = $session->defaultVariable() ;

Returns the value of the variable from the session, or the default value if the session has no setting for the variable.

variable - accessor for variable attributes

$session->variable(varName) ;
varName

the name of the variable.

returns the value of variable in a scalar context.

refreshable - is the session refreshable?

my $refreshable = $session->refreshable();

Returns true if refreshable, false if not. Defaults to true.

resCounter - count for each type of result

my $count = $session->resCounter( resultName ) ;

Returns the number of times that result is currently set for this session.

displaySetName

$dname = $session->displaySetName() ;

checkSession - check if a session passes various filters

my $bool = $sess->checkSession( filtRef ) ;

filtRef is a reference to a hash of filters. filter settings are:

sesslist - list of sessions (rarely used)
    sessnumLow - low end of range of session numbers
    sessnumHigh - high end of range of session numbers
    users - list of modifying users
    assignees - list of assigned users
    testsets - list of test sets to match
    schedule - schedule settings
    locked - locked or unlocked
    date - the last mod date if it is interesting; also startdate and enddate for range
    run - types of "run"
    VAR_* - session variable selections

Returns true of the session passes the filters, false if it does not.

DESTROY() - tidy up

SuiteDB::Set

NAME

SuiteDB::Set - class for manipulating set metadata

METHODS

new - create a new Set object

$set = SuiteDB::Set->new(setname, hashRef) ;

Creates a set object. Returns a reference to the created object.

Copyright © 2000-2013 Applied Testing and Technology, Inc. All rights reserved.