Suite

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

suite is the test suite in which we are operating

readWrite is a boolean that indicates whether the object should be writeable.

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

$path = $suite->path();

$dir = $suite->recycleDir();

This will just sync out the testDB object.

$res = $suite->save();

returns 1 if the save succeeded.

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

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

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

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

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

$ret = $suite->add(relativePath);

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

Returns 1 on success, 0 on failure.

$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 1 on success, and 0 on failure.

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

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.

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

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

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 if true of the results of sessions should be cleared.

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

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

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

oldcase is the name of the old test case.

newcase is the name for the new test case.

Returns 1 if the copy succeeded. 0 if it failed.

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

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?

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.

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

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

$suite->testCase(name);

name is the name of the test case

returns a handle to a test case object

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

$hRef = $suiteH->userHash() ;

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

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

returns 1 if successful, undef if not.

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

Removes the set named $set, as well as all of its sessions.

Returns 1 on success, undef on failure.

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

Returns nothing.

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

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

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

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

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

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

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

Name is the name of the item to text.

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

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

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

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

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

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

file is the file to recycle.

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

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

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

oldname - the original name newname - the new name

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

returns 1 if the rename succeeded, otherwise returns 0.

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

oldname - the original name

newname - the new name

Recurses through the tree renaming the components in a folder.

returns 1 if the rename succeeded, otherwise returns 0.

Returns 1 on success.

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

@rH = $suite->reportDB() ;

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

If called with a set parameter, only returns the sessions in that set.

If the set is unavailable, returns undef.

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

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

@setList = $suite->setList() ;

Returns an array of set names.

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

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

$res = $suite->sync(refresh);

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

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 sync'd into the database.

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

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