NAME

Suite - class representing a test suite

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

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

SYNOPSIS

use Suite;

    # define a new test suite
    my $suite =  new Suite();

    # read on an existing suite
    my $suite = new Suite("name");

    # write to an existing suite
    my $suite = new Suite("name", 1);

    # rename files or directories
    $res = $suite->renameFolder($oldname, $newname);
    $res = $suite->renameFile($oldname, $newname);

    # remove files or directories
    $res = $suite->remove($name);

    # sync up the suite with the file tree, including source control if it
    # is defined
    $res = $suite->sync();

    # save any changes
    #suite->save();

    # release the suite (and its database)
    $suite->release();

The Suite object facilitates operations on test suite elements, including test cases, direcories, and other file objects in the tree. It seamlessly integrates with source control if that is enabled.

DATA STRUCTURE

path

the path to the test suite.

writeable

a boolean that indicates whether the suite is open read/write. Note that this only really effects the way the associated test database is opened. Any other operations are basically not permitted if the object is not opened for writing.

testDB

a handle to an associated test database. See TestDB for more information.

METHODS

new - create a new Suite object

$suite = new Suite();
    $suite = new Suite(suite);
    $suite = new Suite(suite, readWrite);
    $suite = new Suite(suite, readWrite, profName);

suite is the test suite in which we are operating

readWrite is a state flag that indicates whether the object should be writeable. If it is 0, the object and everything it opens will by default be opened read-only. If it is 1, the object and everything it opens will by default be opened in write mode. If it is 2, the suiteDB will be opened in write mode, but child objects will be opened read-only unless explicitly opened in write mode when first requested. This is useful when doing updates to meta-data and a test session, for example. The test database can be opened read-only, but the SuiteDB and specific session need to be writeable. The default value is 0 - read-only.

profName is an optional profile name. The Suite object can be used as an access conduit for various other objects even when managing a profile.

create - build a new test suite and return an handle to it

$suite = create Suite(suite, desc, profile);

suite is the test suite to create desc is a description for the suite profile is the name of the profile to use

returns a handle to the newly created suite, or undef if there was an error.

creator - get/set the suite creator

$name = $suite->creator( $name )

name is an optional creator name.

Returns the creator of the test suite, if any.

path - the pathname of the test suite

$path = $suite->path();

pathLen - length of a path to an object within the suite

$len = $suite->pathLen( $file ) ;

file is the name of a file.

Returns the length of the path to the file.

Lock - Lock all the datastores in order for a transaction

$suite->Lock() ;

Ensures all the relevant databases are locked in the right order.

Relock - share a read lock if needed

Unlock - Unlock all the datastores in order

$suite->Unlock() ;

Ensures all the relevant databases are unlocked in reverse order to how they were locked.

dataDir - return the path to a the suite's data directory

$dir = $suite->dataDir() ;

deletedDir - return the name of the deleted files directory

$dir = $suite->deletedDir() ;

profName - accessor for the profile name associated with this object

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

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

recycleDir - return the name of the recycle directory

$dir = $suite->recycleDir();

templateDir - return the path to the suite template directory

$dir = $suite->templateDir() ;

release - release this object and its dependent data structures

Note that this method calls save on any objects that are attached if those objects are writeable and still dirty

results - return a reference to a Result object.

$resH = $suiteH->results( [resH] ) ;

resH is an optional reference to an existing results object.

Returns a reference to a results object for the suite.

save - save the test suite

This will just sync out the testDB object.

$res = $suite->save();

returns 1 if the save succeeded.

rfields - get a requirements fields object

$rRef = $suite->rfields( [ $rRef [, $edit ] ] ) ;

$rRef is an optional reference to a rfields object to use.

$edit is a flag - if set, then the object will be in "edit" mode. Defaults to non-edit mode.

Returns a reference to a rfields object, instantiating one if required.

rundata - get the rundata fields and order

$rRef = $suite->rundata( [ $sess ] ) ;

$sess is an optional reference to a session object to use.

Returns a list with two references - a hash of testFields and a hash that maps fields to order.

schema - get a schema object

$sRef = $suite->schema( [ $sRef ] ) ;

$sRef is an optional reference to a schema object to use.

Returns a reference to a schema object, instantiating one if required.

suite - accessor for the suite name

$suiteName = $suite->suite( [ name ] ) ;

Returns the name of the current test suite, or undef if we are not operating on a test suite.

suiteDB - get a handle to a suiteDB object

$sdb = $suite->suiteDB( sdbh, readwrite );

sdbh is an optional handle to an existing suitedb object. That object will be registered and used from then on if it is provided.

readwrite is a boolean indicating what mode the suiteDB object should be opened in. If not provided, the default is the mode of the Suite object.

Returns a handle to the suite database.

idFromUUID - get the ID of a test based upon its UUID

$id = $suite->idFromUUID( uuid );

uuid is a UUID to look up.

Returns the id for the test, or undef if no such test is defined.

testDB - get a handle to the test database

$tdb = $suite->testDB( [tdb [, mode] ] ) ;

tdb is an optional reference to an already opened test database.

mode is an optional flag to indicate whether it should be opened in read or write mode. The default is whatever mode the suite was opened in.

Returns a reference to a test database. If one is opened, the Suite object will remember that it needs to be released.

variables - return a handle to a VariableSet object for the suite

$vars = $suite->variables ( vars );

vars is an optional reference to a variable object. If provided, then that object is used and is saved into the associated suiteDB.

accountDB - get a handle to an account database

$acctH = $suiteH->accountDB(readwrite);

Returns a handle to an account database.

activeSessions - return a list of active sessions

@sessList = $suite->activeSessions() ;
    @sessList = $suite->activeSessions(set) ;

If the set parameter is supplied, only looks at the sessions in that set. Otherwise looks at all sessions.

add - add a folder or file to a suite

$ret = $suite->add(relativePath [, fromCopy ] );

Adds a file or folder at suiteRoot/relativePath to the suite database.

fromCopy is a flag that indicates we are adding as a result of a copy.

Returns 1 on success, 0 on failure.

allocateID - find the next available ID

$newID = $req->allocateID( folder ) ;

folder is a folder within the suite.

Returns the next available numeric ID for this folder. If inRequirements() is true, then operates in the requirements tree, otherwise operates in the test case tree. If the style of the associated ID field is "autonumber" then a suite-wide number is used. Otherwise, a per-folder number is used.

Returns undef if the folder does not exist.

allocateRemoved - alocate a directory for emptying the trash

path = $suite->allocateRemoved( inRequirements ) ;

Returns the next folder that can be created in the deleted tree.

copyFile - copy a file within the tree

$res = $suite->copyFile(oldFile, newFile, fromFolder);

oldFile is the path to the original file.

newFile is the path where the copy should be placed.

fromFolder is a boolean indicating if we are operating under copyFolder already. This is passed to source control operations.

Returns the name of the new file, or undef on failure.

copyFolder - copy a folder and the files within it

$res = $suite->copyFolder(old, new, callBack);

old is the old folder name.

new is the new folder name.

All files and folders under old are copied into new. All appropriate source control operations are also performed.

Returns 0 on failure, and non-zero on success.

checkSession - see if a session exists

$boolean = $suite->checkSession(sessId) ;

Returns true if a session sessId exists in the suite.

checkSet - see if a set exists

$boolean = $suite->checkSet(setName) ;

Returns true if a set setName exists in the suite.

copySession - copy a test session

$newSessH = $suite->copySession(desc, oldSessId[, clear[, user[, updateSet [,setName] ]]]);

desc - a new description for the copy

oldSessId - the session ID to copy

clear - a boolean indicating whether to clear out any accumulated data in the new session

user - the userName of the copier (defaults to Framework::username())

updateSet - boolean to indicate whether the parent set should be told of its new child or not. Useful if we are actually copying to a new set.

setName - The real set name to use.

Creates a new test session, updates test database to reflect the session usage, and returns the handle to the newly created session.

returns undef if the creation fails.

copySet - copy a test set and its sessions

Returns a list of sessions copied.

copySetGroup - copy a test set group

$suiteH->copySetGroup(oldGroup, newGroup, sessions [, callBack ] ) ;

sessions is a string that says what to do with sessions that are in copied test sets:

no dont copy sessions at all
clear copy but clear the sessions of rundata
results copy only the results
notes copy only notes
assignedto copy only assignments
all copy all data

callBack is an optional reference to a function that will be called with progress messages.

Returns a reference to a list of test sessions created as a result of the copy.

Returns undef if the oldGroup was not defined or the newGroup already exists.

copySuite - copy a test suite

$newHandle = $sh->copySuite("newname", copysets, copysessions, clear, dbmFlag, callback, copyReports);

newname is a name for the new test suite.

copysets is true if test sets are to be copied.

copysessions is true if test sessions are to be copied.

clear is "no" if the results of sessions should not be cleared.

dbmFlag is true if the data should be saved in dbm format. Otherwise it is saved in an architecture neutral "Dump" format.

callback is an optional reference to a function that will be called with progress messages.

copyReports is an optional boolean. If true, custom report definitions are copied as well. Defaults to false.

doSQL is an optional boolean. If true, then the SQL store will be updated against the new copy after the copying is complete. Defaults to false.

copySearches is an optional boolean. If true, then the saved searches will also be copied. Defaults to false.

acctDB is an optional handle to an account database. This will be handed to the newSuite object for use in synchronizing.

copyPermissions is an optional boolean. If true, then the access permissions will also be copied. Defaults to true.

newSuiteH is an optional reference to a new suite object. If this is passed in, then the tests and requirements will not be copied, but all the other items may be as requested.

returns the handler to the newly created suite, or undef of the suite cannot be copied.

copyRequirement - copy a requirement file

$res = $suite->copyRequirement(oldreq, newreq) ;

oldreq is the name of the old requirement file.

newreq is the name for the new requirement file.

Note that if the requirements are in autonumber mode, then the new name is really used just for its path, and a name is allocated.

Returns the new name if the copy succeeded. undef if it failed.

copyTestCase - copy a test case file

$res = $suite->copyTestCase(oldcase, newcase) ;

oldcase is the name of the old test case file.

newcase is the name for the new test case file.

Note that if the tests are in autonumber mode, then the new name is really used just for its path, and a name is allocated.

Returns the new name if the copy succeeded. undef if it failed.

createSession - create a test session

$newSessId = $suite->createSession(setId, name, desc, user, useSet, testCases, requirements);

setId - the set in which to create the session if setID is actually a HANDLE to a set object, use that set.

name - the name for the session

desc - the long description for the session

user - the userName of the copier (defaults to Framework::username())

useSet - boolean. Should the set be used to populate the session?

testCases - an arrayref of test case UUIDs to create a session from

requirements - an arrayref of requirement UUIDs to create a session from

Creates a new test session, updates test database to reflect the session usage, and returns the handle to the newly created session.

Can specify testCases or requirements but not both. Specifying either forces useSet to be 0.

returns undef if the creation fails.

createSet - create a test set

$setH = $suite->createSet(name, desc, user);

name - the name for the set

desc - the long description for the set

user - the userName of the copier (defaults to Framework::username())

Creates a new test set, updates test database to reflect the set usage, and returns the handle to the newly created set.

returns undef if the creation fails.

createSetGroup - create a test set group

$result = $suite->createSetGroup(name, desc, user);

name - the name for the set group

desc - the long description for the set group

user - the userName of the copier (defaults to Framework::username())

Creates a new test set group and stores its description.

Returns 1 on success, 0 on failure.

createRequirementsFromTests - ensure there are requirements to suppor test cases

$numCreated = $suite->createRequirementsFromTests(sess, fieldMap [, $callBack ] ) ;

sess is a reference to a TestSession object with test cases to create against.

fieldMap is a reference to a hash mapping requirement field names to test case field names. During requirement creation, matching fields will be populated with data from the source test case.

callBack is a reference to a function to call periodically to track creation progress. The default is no function.

Returns the number of requirements created. Note that if there is already a requirement that references the test case, it will be skipped.

createTestsFromRequirements - ensure there are tests cases to suppor requirements

$numCreated = $suite->createTestsFromRequirements(reqColl, fieldMap [, $byDir [, $callBack ] ] ) ;

reqColl is a reference to a ReqCollection object with requirements to create against.

fieldMap is a reference to a hash of req fields and the names of test case fields they should populate.

byDir is an optional flag indicating whether a directory should be created for each requirement, or only a single test case. The default is false.

callBack is a reference to a function to call periodically to track creation progress. The default is no function.

Returns the number of test cases created. Note that if there is already a test case that references the requirement, it will be skipped.

searchTest - search a test case for various criteria

$res = $suite->searchTest(name, rules) ;

name is the name of the test case.

rules is a reference to a hash of field names, each of which contains a search pattern and a replacement pattern.

Returns 1 if the test case matched, 0 if it did not, and undef if the test case was not available.

testCase - get a handle to a testcase

$suite->testCase(name);

name is the name of the test case

returns a handle to a test case object

testLocked - check to see if a test is locked

$locked = $suite->testLocked(test) ;

test is the path to a test in the suite.

Returns true if this test is "locked".

updateSuiteDB - update the suite metadata

$suite->updateSuiteDB() ;

Ensures the metadata about the test suite is up to date in the suiteDB. Note that this is only SOME of the meta data, since things like the schema are cached in suiteDB by their editors.

Returns undef if there is no SuiteDB associated with this session, 0 if the update failed, and 1 if it succeeded.

updateTest - update a test case against conversion rules

$res = $suite->updateTest(name, rules) ;

name is the name of the test case.

rules is a reference to a hash of field names, each of which contains a search pattern and a replacement pattern.

Returns 1 if the test case was changed, 0 if it was not, and undef if the test case was not available.

userHash - return a hashref mapping user IDs to full names

$hRef = $suiteH->userHash() ;

Returns a reference to a hash of data mapping user IDs to full names.

userList - return a list of users who have access to this suite

@ulist = $suite->userList( [alevel] ) ;

alevel is an optional access level. The default is the lowest level that still gives access.

Returns a list of userids that have the requested access level or better.

userPerms - return a hash of users and access levels for this suite

@ulist = $suite->userPerms( ) ;

Returns a hash of userids with access to this suite, and their access level.

deleteSetGroup - remove a set group and its contents

$sessAryRef = $suite->removeGroup( group [, callBack ] ) ;

group is the name of a group to remove.

callBack is an optional reference to a function that will be called with progress messages.

Returns a reference to a list of removed sets and sessions, or undef if there was an error.

deleteSession - delete a test session

$suite->deleteSession(sess [user [, updateSet]]);

sess is the session to remove

user is an optional user name - defaults to the current user.

updateSet is a flag that indicates whether the corresponding set should also be updated. This defaults to true.

The session folder and all its data are moved into the deleted files tree for later cleanup.

returns 1 if successful, undef if not.

deleteSet - delete a test set

$result = $suite->deleteSet($set) ;

Removes the set named $set, as well as all of its sessions. Actually moves it into the deletedDir tree for later removal when things are cleaned up.

Returns 1 on success, undef on failure.

description - get/set the suite description

$desc = $suite->description( $desc )

desc is an optional description to save.

Returns the description for the test suite, if any.

dirList - return a customized list of folders

$output = $suite->dirList( exclude, excludeDeep, skipLocked, incRecyc ) ;

exclude is an exact match pattern to exclude.

excludeDeep is a matter that a directory name must start with to be excluded.

skipLocked is a flag. If true, locked folders are not returned.

incRecyc is a flag. If true, foldes in the recycle tree are also included. Defaults to false.

Returns a list of folders, customized based upon the parameters passed in. Note that this method relies upon folderList, which in turn uses the inRequirements flag to learn what mode we are in.

displayID - get the aggregate name of a test or requirement

$name = $suite->displayID( $filePath, noPath, asText, onclick ) ;
    $name = $suite->displayID( $dirPath, isReq, noPath, asText, onclick ) ;

filePath is the path to a file.

dirPath is the path to a folder. If this is a path to a folder, an additional parameter specifies whether it is a requirement folder or not.

noPath is an optional boolean flag that indicates whether to include the path in the ID. It defaults to false.

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

Returns the name associated with the object pointed to by path.

If in requirements mode, then this is a path relative to the requirements directory of the suite. Otherwise it is a path relative to the test cases of the suite.

cleanLandfill - permanently remove files from the deleted area

$count = $suite->cleanLandfill( [ callBack, [ ignoreReferences ] ] ) ;

callBack is an optional reference to a callBack function. If provided, the callBack will be invoked periodically with progress messages.

ignoreReferences is a boolean that indicates whether files that are referenced from other, active areas of the system should be removed or not. The default is false - referenced files are NOT removed.

This method examines all files that are in the "Deleted" area and permanently removes them from the system. Files that are referenced from test sessions, test sets, active requirements, or active test cases are NOT removed unless ignoreReferences is true.

Returns the number of items permanently removed.

emptyTrash - empty the trash

$suite->emptyTrash() ;

Permanently removes the files and folders in the $recycleDir tree. In reality, copies them into a the $deletedDir tree first so that they continue to be available for test sessions unless the system configuration setting saveTrash is set to 0, in which case the files are actually removed.

Returns nothing.

filterDB - get a handle to the saved filter database

$fdbH = $suite->filterDB( [fdbH [, writable] ]) ;

fdbH is an optional handle to an already open filterDB.

writable is an optional flag indicating whether the database should be open readonly or readwrite. If not defined, it defaults to the current state of the suite object.

Returns a handle to a FilterDB object.

folderList - get a list of folders

@list = $suite->folderList( [ dir ] ) ;

dir is an optional directory within the tree from which to start. If not provided, this defaults to the top level.

Returns a list of folders in user-defined order. Note that this method switches between the test and requirements trees based upon the inRequirements setting.

folderLocked - check to see if a folder is locked

$locked = $suite->folderLocked(dir) ;

dir is a directory in the suite.

Returns true if this directory is "locked". A directory is locked if it or any of its parents is locked. A directory is unlocked if it or any of its parents are explicitly unlocked.

fullname - return the fullname for a user

$fname = $suite->fullname(user, includeID) ;

Returns the fullname or the userID in parens if the fullname is not found. If user is a comma separated list, returns the fullnames of all users in the list.

maxSession - what is the highest numbered session in the suite

my $count = $suiteH->maxSession() ;

Returns the highest numbered session in the suite.

lastEditUpdate - accessor for last edit time of test suite

$time = $suite->lastEditUpdate( [ stamp ] ) ;

Returns the timestamp of the last update to tests in this suite. If the optional stamp parameter is provided, sets it.

Note that this data is cached in the suite object, so long running tasks may have inaccurate data.

lastFolderUpdate - accessor for last test case folder change time

$time = $suite->lastFolderUpdate( [ stamp ] ) ;

Returns the timestamp of the last update to tests in this suite. If the optional stamp parameter is provided, sets it.

Note that this data is cached in the suite object, so long running tasks may have inaccurate data.

lastReqEditUpdate - accessor for last edit time of requirements in test suite

$time = $suite->lastReqEditUpdate( [ stamp ] ) ;

Returns the timestamp of the last update to requirements in this suite. If the optional stamp parameter is provided, sets it.

Note that this data is cached in the suite object, so long running tasks may have inaccurate data.

lastReqFolderUpdate - accessor for last requirements folder change time

$time = $suite->lastReqFolderUpdate( [ stamp ] ) ;

Returns the timestamp of the last update to requirements in this suite. If the optional stamp parameter is provided, sets it.

Note that this data is cached in the suite object, so long running tasks may have inaccurate data.

lastRunUpdate - accessor for last run status change in test suite

$time = $suite->lastRunUpdate( [ stamp ] ) ;

Returns the timestamp of the last run status change in this suite. If the optional stamp parameter is provided, sets it.

Note that this data is cached in the suite object, so long running tasks may have inaccurate data.

lastUserPermUpdate - accessor for last user permissions update in this test suit

$time = $suite->lastUserPermUpdate( [ stamp ] ) ;

Returns the timestamp of the last update to the user permissions list in this suite. If the optional stamp parameter is provided, sets it.

Note that this data is cached in the suite object, so long running tasks may have inaccurate data.

lockedFilesAndFolders - return a list of folders and tests that are locked

@flist = $suite->lockedFilesAndFolders( dir );

Returns an entry per file that is locked within and beneath the directory "dir" in the suite. If dir is undefined or "", then it is the top of the suite. In any case, files in the recycle bin are silently ignored.

lockedSetsAndSessions - return a list of sets and sessions that are locked

@slist = $suite->lockedSetsAndSessions( [ setGroup ] )

setGroup is an optional setGroup folder within the set list.

Returns a list of setGroups, sets, and sessions that are locked.

lockFolder - lock a folder and its contents

$status = $suite->lockFolder( dir, cascade )

dir is the name of a directory within the suite.

cascade says whether to do child folders or not.

Locks the folder, any test cases therein, and optionall any child folders.

Returns 1 on success, 0 on any failure (like no permission).

lockReq - lock a requirement

$suite->lockReq(reqname) ;

Locks the requirement.

lockSetGroup - lock a set group and its contents

$status = $suite->lockSetGroup( group, cascade )

group is the name of a set group within the suite.

cascade says whether to do child folders or not.

Locks the folder, any sets therein, and optionally any child folders.

Returns 1 on success, 0 on any failure (like no permission).

lockSet - lock a test set and (optionally) its sessions

$sessRef = $suite->lockSet(setName, sessions) ;

setName is the name of a set to lock.

sessions is a boolean. If true then sessions in the set are locked as well. Defaults to false.

Returns an array reference to the list of locked sessions. Returns undef if there was an error.

lockTest - lock a test case

$suite->lockTest(testname) ;

Locks the test case.

unlockFolder - unlock a folder and its contents

$status = $suite->unlockFolder( dir, cascade )

dir is the name of a directory within the suite.

cascade is a boolean that indicates whether to perform the operation on subfolders. Default is false.

Unlocks the folder, any folders therein, and any test cases therein.

Returns 1 on success, 0 on any failure (like no permission).

unlockReq - unlock a requirement

$suite->unlockReq(requirement) ;

Unlocks the requirement.

unlockSetGroup - unlock a set group and its contents

$status = $suite->unlockSetGroup( group, cascade )

group is the name of a set group within the suite.

cascade says whether to do child folders or not.

Locks the folder, any sets therein, and optionally any child folders.

Returns 1 on success, 0 on any failure (like no permission).

unlockSet - unlock a test set and (optionally) its sessions

$sessRef = $suite->unlockSet(setName, sessions) ;

setName is the name of a set to unlock.

sessions is a boolean. If true then sessions in the set are locked as well. Defaults to false.

Returns an array reference to the list of locked sessions. Returns undef if there was an error.

unlockTest - unlock a test case

$suite->unlockTest(testname) ;

Unlocks the test case.

newFolder - create a folder in a suite

$res = $suite->newFolder(name) ;

name is the name of the folder to create.

Creates the folder, possibly also creating intervening folders as needed. Uses the internal add operator to ensure that each folder is added to the source control system if there is one.

Returns 1 on success, 0 on failure.

openRequirementByName - open up a requirement file

$ref = $suite->openRequirementByName(name, writeable) ;

name is the name of a requirement case to open.

writeable is a boolean, and defaults to the state of the current suite object.

Returns a reference to the requirement object.

openRequirementByUUID - open up a Requirement by its UUID

$ref = $suite->openRequirementByUUID(UUID, writeable) ;

UUID is the UUID of a requirement to open.

writeable is a boolean, and defaults to the state of the current suite object.

Returns a reference to the requirement object. Returns undef if the requirement is not available.

openRequirementCollection - open a requirement collection

$collPtr = $suite->openRequirementCollection(name, readWrite);

name - the collection to open

readWrite - optional parameter for open status. If not specified, uses the setting on the Suite object.

returns undef if the collection cannot be opened. Returns a pointer to the collection if successful.

openSession - open a test session

$sessPtr = $suite->openSession(sessId, readWrite);

sessId - the session to open

readWrite - optional parameter for open status. If not specified, uses the setting on the Suite object.

returns undef if the session cannot be opened. Returns a pointer to the session if successful.

openSet - open a test set

$setPtr = $suite->openSet(setName, readWrite);

setName - the set to open

readWrite - optional parameter for open status. If not specified, uses the setting on the Suite object.

returns undef if the set cannot be opened. Returns a pointer to the set if successful.

openTestCase - open up a test case

$ref = $suite->openTestCase(name, writeable) ;

name is the name of a test case to open.

writeable is a boolean, and defaults to the state of the current suite object.

Returns a reference to the test case object.

openTestCaseByUUID - open up a test case

$ref = $suite->openTestCaseByUUID(UUID, writeable) ;

UUID is the UUID of a test case to open.

writeable is a boolean, and defaults to the state of the current suite object.

Returns a reference to the test case object.

canRename - check if a file or folder can be renamed

$res = $suite->canRename(oldname, newname) ;

oldname is the name of the item to move.

newname is the new name for the item.

If the item to move is a folder, then find the longest item in the folder to set an upper bound.

Returns true if the rename will work. Returns false if it would not.

canRecycle - check if a file is eligible for recycling

$res = $suite->canRecycle(name);

Name is the name of the item to recycle.

Returns true if it can be recycled, and false if not.

isNumbered - return whether ids are numbered or not

$state = $suite->isNumbered() ;

Uses the inRequirements state to determine which schema to query.

isOutline - return whether in outline mode or not

$state = $suite->isOutline() ;

Uses the inRequirements state to determine which schema to query.

isRecycling - accessor for recycle operation

$state = $suite->isRecycling( [ state ] ) ;

state is an optional parameter to set the state.

Returns true if we are in the middle of a recycle operation, and false if not.

recycled - check if a file is already in the trash

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

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

recycleFolder - migrate a folder and its contents to the recycle bin

$res = $suite->recycleFolder(name) ;

name is the name of the folder to recycle.

Places the folder into the "trash", possibly renaming it if there is a conflict by adding a numeric suffix to the name.

Note that when source control is enabled, some special operations have to take place:

First - it is NOT possible to get here if source control is enabled and there is no removeFolder operation. The option to remove a folder will simply not appear in the UI.

If there is a source control renameFolder operation, that is used.

If not, use copyFolder to move the tree over, then use removeFolder to wipe the original.

recycleFile - migrate a file to the recycle bin

$status = $suite->recycleFile(file);

file is the file to recycle.

Places the file in the recycle bin, possibly renaming it to avoid a conflict.

removeFolder - remove a folder and its contents

removeFile - remove a file

$res = $suite->removeFile(name[, fromFolder]);

name - the name to remove

fromFolder - flag to indicate we were called from removeFolder.

Updates the test database and performs any source control operations if necessary. Note that if the item being removed is NOT in the recycle area already, it is automatically "recycled" by performing a recycleFile operation.

returns 1 if the remove succeeded, otherwise returns 0.

renameFile - rename a file

$res = $suite->rename(oldname, newname[, origname]);

oldname - the original name newname - the new name origname - a name to use in messages instead of oldname

Updates the test database and performs any source control operations if necessary.

Note that if autonumbering by folder is enabled, and the rename is not into the trash, then the target name is really advice on the folder, and the new file name will be auto-allocated.

Returns the new file name if the rename succeeded, otherwise returns undef.

The origname argument is used in bulk renames where in auto-outlined suites the displayID of oldname may not be correct.

renameFolder - rename a directory

$res = $suite->rename(oldname, newname [ , callBack ] );

oldname - the original name

newname - the new name

callBack - an optional reference to a function through which to report progress.

emptyingTrash - an optional flag that indicates the rename is just to empty the trash. Test / requirement counts are not adjusted in this case.

Recurses through the tree renaming the components in a folder.

returns 1 if the rename succeeded, otherwise returns 0.

renameSet - rename a test set

Returns 1 on success.

Returns undef if the oldset was not defined or the newset already exists.

renameSetGroup - rename a test set group

$suiteH->renameSetGroup(oldGroup, newGroup) ;

Returns 1 on success.

Returns undef if the oldGroup was not defined or the newGroup already exists.

renumberTree - renumber tests/requirements in a tree so they are sequential

$status = $suite->renumberTree( nameField [, callback [, folder, recursive] ] );

nameField is the name of a field into which to copy the basename of the ID of the file IFF the file did not have a numeric name to start with.

callback is an optional reference to a function that will be called as each folder is processed.

folder is an option folder to start renumbering from - only legal when numbering is by folder.

recursive is an optional flag to indicate that by folder renumbering should do this folder and all child folders.

renumberTree will walk the tree in the current user-defined order, renaming the files to be sequential. The walk is breadth first, so files in parent folders will have lower numbers than files in child folders when in suite-wide numbering mode.

Note that renumber is a transaction. It will tie up the various databases for its entire execution. It should only be called as a management option, and only when the system is quiescent.

Returns 1 on success, 0 on failure.

reportDB - get a handle to the report database

$rdbH = $suite->reportDB( [rdbH [, writable] ]) ;

rdbH is an optional handle to an already open reportDB.

writable is an optional flag indicating whether the database should be open readonly or readwrite. If not defined, it defaults to the current state of the suite object.

Returns a handle to a reportDB object.

reqActive - are requirements active for this suite

$state = $suite->reqActive() ;

Returns true if requirements are in use by this test suite, and false if they are not. Note that the overarching configuration setting ATMConfig::useRequirements takes precedence using the following rules:

If useRequirements is 0, then requirements are OFF everywhere.

    If useRequirements is 1, then requirements are ON everywhere.

    If useRequirements is -1, then each suite has its own setting, with
    the default setting being OFF if there is no suite-specific setting.

reqDB - get a handle to the requirements database

$reqH = $suite->reqDB( [reqdb [, mode] ] ) ;

reqDir - return the path to the requirements tree for this suite

$path = $suite->reqDir( [subdir] ) ;

subdir is an optional directory within the requirements tree.

Returns the path to the requirements directory. If there was no REQUIREMENTS tree in the suite, silently creates one.

reqLocked - check to see if a requirement is locked

$locked = $suite->reqLocked(req) ;

req is the path to a requirement in the suite.

Returns true if this requirement is "locked".

searchDB - get a handle to the saved search database

$sdbH = $suite->searchDB( [sdbH [, writable] ]) ;

sdbH is an optional handle to an already open searchDB.

writable is an optional flag indicating whether the database should be open readonly or readwrite. If not defined, it defaults to the current state of the suite object.

Returns a handle to a SearchDB object.

sessionList - get a list of sessions

@sessList = $suite->sessionList();
    @sessList = $suite->sessionList(set) ;
    @sessList = $suite->sessionList(undef, noSet) ;

If called with a set parameter, only returns the sessions in that set. If called with the noSet parameger, only returns the sessions that are associated with no test set.

If the set is unavailable, returns undef.

sessLocked - return whether a session is locked or not

$state = $suite->sessLocked(sessNum);

state = 1 if locked, 0 if unlocked. Returns undef if the session is not found.

groupDesc - retrieve the description for a group

$desc = $suite->groupDesc( setGroup ) ;

Returns the description for a setGroup, if any. If setGroup is "" or "/", returns the description of the test suite.

groupList - retrieve the list of set groups

@list = $suite->groupList( [ setGroup ] ) ;

Returns a list of group names. If the optional setGroup parameter is provided, then returns the list of group names that are within THAT group.

groupLocked - determine if a test set group is locked

$locked = $suite->groupLocked(group) ;

Returns true if the group is locked, false otherwise.

setList - get a list of sets

@setList = $suite->setList( [$setGroup] ) ;

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

Returns an array of set names.

setLocked - return whether a set is locked or not

$state = $suite->setLocked(setName);

state = 1 if locked, 0 if unlocked. Returns undef if the set is not found.

sync - synchronize the tree with the test database

$res = $suite->sync(refresh [, doSQL [, callBack ] ]);

refresh = 1 if the sessions should all be refreshed against the database too.

doSQL is a boolean - set to true if the SQL datastores should be updated as well. Defaults to true.

callBack is a reference to a function that will get called each time a new folder is traversed. The default is that there is no function. If a function reference is supplied, that function will be called with a single parameter; the name of the folder being traversed.

Updates the test database, ensuring that all the test files in the tree are included. Accesses the source control update method, so if there is source control enabled, it will synchronize from the source tree as well.

Ensures that the information in the SuiteDB is also up to date, polling the test sessions for their meta data.

returns -1 if the sync failed, otherwise returns the number of test cases (and requirements) sync'd into the database.

inRequirements - state flag for whether we are operating on requirements

$state = $suite->inRequirements( boolean ) 

boolean is optional parameter to set the state. Defaults to false.

Returns the previous state.

isAvailable - is an operation available

$avail = $suite->isAvailable(operation);

Where operation is one of those operations defined in the config.pl file for source control.

Returns 1 if the operation is available, 0 if it is not.

updateReqID - update the id field in a requirement

$suite->updateReqID(name, req) ;

name is the name of the requirement to update.

req is an optional reference to a Requirement object. If one is not provided, it will be opened.

Ensures the id field matches its current location in the tree.

updateTcID - update the id field in a test case

$suite->updateTcID(name, test) ;

name is the name of the test case to update.

test is an optional reference to a test case object for that test. If one is not provided, it will be opened.

Ensures the test case id field matches its current location in the tree.

SQL_allTables - return a list of all SQL table structures for suite

$tableHash = $suiteH->SQL_allTables( deep ) ;

deep is an optional parameter that causes a two level hash to be returned. In this case, the top level hash is the master table name, and it contains a hash of all the tables related to that master table.

Returns a hash of table definitions. The key is the name of the table, and the value is a hash of table fields and their declarations.

Returns undef if SQL is not active for the suite.

SQL_getInfo - get database tunable parameter settings

$hashRef = $suite->SQL_getInfo() ;

Returns a reference to a hash of interesting setting values indexed by setting name. The settings retrieved include:

maxColumnsInTable
    maxColumnNameLength
    maxTableNameLength

Returns undef if SQL is not active for the suite.

SQL_isConsistent - ensure the ATM and SQL schemas are consistent

$state = $suiteH->SQL_isConsistent() ;

Returns true if the SQL store is active, ready, and its table definitions are the same as what ApTest Manager things they ought to be.

SQL_ready - accessor for the suite SQL ready flag

$rdy = $suiteH->SQL_ready() ;

    $rdy = $suiteH->SQL_ready( [ rdyState [, actState ] ] ) ;

rdyState sets the readiness state.

actState sets the active state.

Returns the current readiness of the suite to work with its defined SQL store. Optionally sets the state.

SQL_renameTestCase - rename a test case

$suiteH->SQL_renameTestCase(UUID, new)

UUID is the uuid if the test case.

new is the new "id" for the test case.

All tables that reflect the "id" in addition to the "atm_id" of a test case will be updated.

SQL_sync - force a rebuild of just the SQL tables

$suiteH->SQL_sync( [ callback ] ) ;

callback is a reference to an optional callback function that will get called periodically with progress messages.

SQL_sync will initialize and rebuild all tables in a related SQL datastore against the data already in the Test Suite databases. Note that this is NOT the same as a traditional "sync" operation.

SQL_deleteSuiteInfo - remove suite data

$tdb->SQL_deleteSuiteInfo() ;

Returns nothing.

SQL_tname - return the table name

my $tname = $suiteH->SQL_tname;

Returns the name of the master table for this object.

SQL_updateSuiteInfo - update suite information data tables

$suiteH->SQL_updateSuiteInfo() ;

Updates the suiteInfo, accounts, and authentication tables.

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 = $suite->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 = $suite->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 user by this object

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

Returns a list of all tables this object will operate upon. Note that the Suite object is funny, since it uses a static collection of tables. If there are multiple suites sharing a SQL datastore, all those suites will put the data in the same tables. This only works because the table columns in this instance do not vary by suite.

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.

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