Reserved fields are defined in this file. Test suites can also extend the collection of fields through the RUNDATA file. Fields have the following attributes and potential values:

name

The name is the identifier user for the field within the test session data store.

type

The type of the field dictates how it is presented, populated, and stored. Supported types include: text, textarea, hidden, single, and multi. Reserved types that are used by ATM include: minutes24, minutes8, notes, result, and time.

values

The list of values that are available for use in a list, or the default value in the case of a text or textarea item. In a list, items are ', ' separated, and if prefixed with '*' are default values.

label

The label to use when presenting the field.

size

The size of the field when presented for editing. In a textarea field, this is ROWSxCOLUMNS, and single and multi fields this is the height of the multi-select window, and in other fields is the width of the field.

style

The presentation style for the field. Only applies to text and textarea fields. Available styles are: "html", "formatted", and "asis".

flags

Flags are a comma separated list of settings that modify the behavior of a field. Legal values are: mandatory and selectable.

$session = new TestSession(suite, [sessID [, read/write [, timeout]]]);

Creates a new session object, optionally specifying several parameters:

suite

the name of the test suite this session is in

sessID

the session ID to use. Only specify this if the session already exists.

read/write

boolean set to True if the existing session needs to be writeable. Defaults to readOnly.

timeout

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

username

the user to be for opening the session. Defaults to the currently active user.

returns a reference to the TestSession object.

returns a path to the rundata file, if any. Also permits setting of the path for testing purposes.

returns a path to the persistent store for this object.

($staffSecs, $clockSecs) = $session->plannedtimes() ;

Returns the number of seconds the test session is expected to take to execute and the clock time budgeted, or 0 if there is no corresponding time field in the schema.

$hRef = $session->assignedTimes( [user1, user2...] ) ;

userN is an optional list of user names on which to report. Otherwise return a hash of all users who have assignments in the session.

Returns a reference to a hash of user IDs. Each hash entry is a hash that contains:

testCount
    testsRun
    plannedRunTime
    actualRunTime
    plannedUntestedTime

$resRef = $session->results( [resultsRef ] ) ;

resultsRef is an optional reference to a Results object.

Returns a reference to a Results object for the associated test suite.

$status = $session->saveAsText() ;

Returns the output of the session's save method, but forcing the session to write out into a flag file instead of a DBM file.

save(useDBM, session)

useDBM is a boolean - if set then the object gets written out as a MLDBM file. Note that if the session started out as a DBM file, it is already TIEd. In that instance save is a no-op, regardless of the state of the useDBM flag.

If session is defined, it is the name of a session to save into. Note that this only takes effect if there is not already a session number defined for this object. If the session is "new", then the method will create a new session by using the next available session identifier.

returns undef if the save failed. Returns the sessionId saved into if the save succeeded.

$session->populate($tid) ;

Selects random values for all menu fields. Creates random text content for text fields, and random paragraphs for textareas. For tables, ensures that there are several rows.

If no test id parameter is passed, instead populates the session variables.

$session->print();
    $session->print(testNum);

returns the string-ified version of the entire session, or just the contents of test testNum, if specified.

$count = $session->clear();
    $count = $session->clear(exclusionList);
    $count = $session->clear(exclusionList, testIndex);

exclusionList is a reference to an array of fields that should NOT be cleared. If the exclusionList is not defined, it defaults to a test suite-specific list of fields. Note that the "id" field is never cleared.

testIndex is the index into the collection of tests.

Returns the number of tests cleared.

$session->copy($osessH [, $testset]) ;

osessH is a handle to the session from which to copy.

testset is an optional name of a test set to use, overriding the set in the other session.

$count = $session->countTests(useCache);

useCache is a boolean that indicates whether the cache should be used when counting. It defaults to false.

Selectors need to have been defined via the selector() method prior to calling this method, or all tests will be selected.

$testNum = $session->currTest() ;

Returns a reference to the currently executing test hash, or undef if no test is in use.

$testStatus = $session->currTestStatus("Test Status") ;

If specified, the status is set for the currently executing test. The lastUpdate field is set to the current time.

$testStatus = $session->currTestStatus() ;

Returns a reference to the currently executing test hash, or undef if no test is in use.

$session->field(fname);

returns a reference to the descriptors for the requested field. If no field name is passed in, returns a reference to the entire collection of fields.

@list = $sess->historyFields() ;

$output = $sess->fieldEntryWrap(tid, field, value, suffix, fn);

tid - the test number

field - the field we are using

value - the value the field has in the test case

suffix - a suffix to use on the id

fn - pointer to a function to call to wrap each value. The arguments passed to the function are the field name and the value (which may be special in the case of an menu).

$session->fieldEntryVar(tid, field, suffix, fn);

tid - the test number

field - the field we are using

suffix - a suffix to attach to HTML form variable names

fn - the name of a javascript function to call on change

$session->fieldEntry(tid, field [, as_text]);

tid - the test number

field - the field to format (from the testFields list)

as-text - boolean indicating that the output should not include markup

Note that if the as_text flag is set, then for fields that MIGHT contain markup, this method does its best to format the output as ASCII.

Returns the formatted field data. If the field is not defined, returns undef.

$list = $session->fieldOrder() ;

Returns a reference to a list of field names in order.

$tableStr = $session->buildSelectorTable( testsel, allowNS, showSpecials, skipResults, skipAssigned, showDynamic ) ;

testsel is a reference to a set of selectors

allowNS is a boolean - if true, non-selectable fields are included.

showSpecials is a boolean. If true, then special modifies are show as well.

skipResults is a boolean. If true, then the results field will be skipped.

skipAssigned is a boolean. If true, then the assigned-to field will be skipped. Defaults to false.

showDynamic is a boolean. If true, then fields that can have dynamic selectors will show those options. Defaults to false.

Returns a table that includes all of the selectors, with any items in the passed in selector set pre-selected.

($rdSels, $warnings) = $s->getSelsFromArgs( $hashRef ) ;

hashRef is a reference to a hash of CGI parameters and their values.

If there are any issues with parsing, those issues are pushed into the referenced hash as key_WARNING.

Returns a reference to a hash of selectors suitable for pushing into the selector method, and a string of warnings suitable for displaying (if any).

$output = $s->fieldSelection($field, $currentSelection, $allowNonSelectable, $showSpecials, $showLabels, $showDynamic);

field is the field to present

currentSelection is a reference to an array of existing selections or a comma-separated string of current selections.

allowNonSelectable is a boolean that indicates whether even non-selectable fields should be presented (for use in report and edit selectors).

showSpecials is a boolean that indicates whether the special isCS and isRE selectors should also be shown on items that support those flags.

showLabels is a boolean that indicates whether the prompt should be supplied. If so, then the prompt and request are emitted as table cells. If not, then the input fields are just emitted as markup.

showDynamic is a boolean that indicates whether fields that can have dynamic selectors should show these as options. The default is false.

returns an input field appropriate for the field. If $field is empty, returns an empty string. If the field doesn't exist, returns undef. if field is not selectable, returns an empty string.

@flist = $session->flist() ;

Returns an array of field names.

@fnames = $session->auditFlist() ;

Returns a list of field names in alphabetical order. This will only include those fields for which the nohistory attribute is not "true".

my $status = $->writeFields() ;

Updates the rundata file for the current suite / profile with the current state of the rundata fields.

Returns 1 on success, 0 on failure.

my $text = $sess->serialize() ;

Returns a text representation of the rundata fields, suitable for saving.

@sFlist = $session->sortedFlist() ;

Returns a list of field names that are sorted by field label case insensitively.

$csv = $session->generateCSV($idx, \@fields [,$raw [, $burstTables] ]) ;

idx is a test item index.

fields is a reference to an array holding field names. These are used for an initial legend.

raw is a scalar holding either 0 (the values are coded), or 1 (the values are "raw"

burstTables is a boolean. If true then fields that are in a table will have their rows split apart and multiple rows emitted.

$xml = $sess->generateVarXML([$raw]) ;

   where

    'raw' is a scalar holding either 0 (the values are coded), or 1 (the values
    are "raw"

$count = $test->generateXLS($idx, $worksheet, $lastRow, \@fields [,$raw [, $burstTables] ]) ;

idx is the test number to operate on.

worksheet is a reference to a Spreadsheet::WriteExcel worksheet object.

lastRow is the number of the last row in that spreadsheet.

fields is a reference to an array holding field names. These are used for an initial legend.

raw is a scalar holding either 0 (the values are coded), or 1 (the values are "raw"

burstTables is a boolean. If true then fields that are in a table will have their rows split apart and multiple rows emitted.

Returns the number of rows added to the worksheet. Returns undef if worksheet or idx is not defined.

$xml = $sess->generateXML($tid, \@fields [,$raw]) ;

   where

    'tid' is the text index in the session.

    'fields' is a reference to an array holding field names. These are used 
    for element names.

    'raw' is a scalar holding either 0 (the values are coded), or 1 (the values
    are "raw"

$output = $session->generateMarkup($tid, $template, $showValues, $showLabels, $test);
    $output = $session->generateMarkup($tid, $format, 1, 1) ;

tid is the test id in this session

template is a template string to populate

showValues is a boolean flag that indicates whether the values of session variables should be interpolated. Defaults to the default in TestCase, since values are actually interpolated in there.

showLabels is a boolean indicating whether field labels should be included or not. Defaults to true.

test is a reference to the test case. If not provided, the test case is loaded automatically.

req is a reference to a requirement. If not provided, and the test case is linked to a requirement, then the first such requirement is loaded.

returns the generated output, or undef if the output could not be generated.

$idString = $session->id() ;

Returns the "name" of the test case.

$idString = $session->displayId($tid [, noPath [, asText [, onClick ] ] ] )

Returns the "name" of the test with ATM suffixes removed and whitespace inserted after slashes. Defers to the displayIDByUUID method of testDB.

tid is the test case index in the session.

For other options, see "displayIDByUUID" in TestDB.

$schema->isNumber(field)

Searches the test case fields for a field named field. Returns true if the field has a numeric style, or false if it does not.

$session->isActive();

Accessor for the activity state of the session. If the state is being set, and if there is an associated SuiteDB, then the data is updated in there as well.

This method returns a true if the session is "in use", and false if it is not.

$session->refresh([ setHandle, destroyResults, refreshAssignments, testers ] );

setHandle is an optional handle to a set object. If not provided, the set will be opened automatically.

destroyResults is an optional flag that must be true in order for test cases with existing result data to be deleted from a session when they no longer exist in the parent set.

refreshAssignments indicates how any tester assignments should be populated. Legal values are 0 (none), 1 (new tests only), 2 (refresh all), 3 (assign new to specific testers). Detaults to 0.

testers is a reference to a list of assignees to use when refreshAssignments is set to 3.

This method will grab the test cases from the parent "set" and that match the original criteria and are NOT marked as disabled already in the object. It will also "disable" any tests that no longer match the selection criteria.

$session->resList();
    $session->resList(ref);

returns an array of results

@list = $session->testList();

returns an ordered list of test case IDs.

@list = $session->testUUIDList();

returns an ordered list of test case UUIDs.

$desc = $session->selDesc(field, selRef, updateDynamic) ;

field is the name of the field.

selRef is a hash reference to a selector.

updateDynamic is a boolean. If true, dynamic selectors will have their values refreshed before the description is produced. Defaults to true.

Returns a string that is a description of the selection in the context of the field type.

 my $prose = $sess->allSelDescs( [ skipResults [, asCSV ]] )

skipResults is an optional flag that indicates whether the result selector should be skipped. It defaults to false.

asCSV is an optional flag that indicates the output should be ready for inclusion in CSV output. If defaults to false.

Returns a prose description of all the selectors that actually have selected values.

@slist = $schema->selectableList( menuOnly [, prefix ] ) ;

menuOnly is a flag that indicates only menu fields should be included in the list. It defaults to false.

prefix is an optional string to attach to the front of the fieldnames.

Returns a list of fields that are not hidden and are marked as selectable.

$size = $session->sizeOf(field) ;

Returns the output if the field's size method, or "" if the field is not defined.

$suff = $session->suffix() ;
    $suff = $session->suffix($newsuff) ;

Returns the current suffix, after updating it if the suffix is supplied. The suffix is appended to input field variable names if, for example, the fields are being put into a complex form that reflects multiple test cases.

$type = $session->typeOf(field) ;

Returns the output if the field's type method, or "" if the field is not defined.

$session->updateIDs() ;

Walks through the session, updating the id attribute of each test case to correspond to the atm_id.

Returns nothing.

@list = $session->userList( [perms] ) ;

Returns a list of users.

$numTests = $session->addTest(tcRef)

tcRef is a reference to a test case structure (see the testCase interface elsewhere in this document).

Returns the new number of tests in the session.

$numTests = $session->deleteTest(tid) ;

tid is the index of the test in the session.

Renumbers the tests after it in the session.

Returns the new number of test cases. Returns undef if test tid is not in the session.

$numtests = $session->disableTest(tid) ;

tid is the index of the test in the session.

Adds the test to the list of tests that are disabled, then uses deleteTest to remove it from the session.

Returns the new number of tests in the session. Returns undef if test tid is not in the session.

$numtests = $session->inserTest(loc, tcRef) ;

loc is the index before which to insert the test.

tcRef is a reference to a test case data structure. See testCase elsewhere in this document.

Returns the new number of tests in the session.

$numTests = $session->insertTests(loc, tcRefAry) ;

loc is the location before which to insert the tests.

tcRefAryRef is a reference to an array of TestCase data structures. See testCase elsewhere in this document.

Renumbers the appropriate number of tests "up" in the session, then puts the new tests into the session in array order.

Returns the new number of tests in the session.

$session->enddateplanned();
    $session->enddateplanned(value);

returns the planned end date.

$session->enddatewindow();
    $session->enddatewindow(value);

returns the planned end date window size.

$session->startdateplanned();
    $session->startdateplanned(value);

returns the planned start date.

$session->startdatewindow();
    $session->startdatewindow(value);

returns the planned start date window size.

$session->enddateactual();
    $session->enddateactual(value);

returns the actual end date.

$session->startdateactual();
    $session->startdateactual(value);

returns the actual start date.

$session->description();
    $session->description(value);

returns the description.

$hashref = $session->disabled();
    $newState = $session->disabled($hashRef);

If hashref is not specified, then the current list is retrieved.

$testNum = $session->lastTest() ;

Returns the test instance number of the last test to post a result, or undef if no test has ever posted a result.

$locked = $session->locked();

Returns the state of the locked flag. Legal values for locked are:

0 - unlocked 1 - normal lock 2 - super-locked (reserved)

$session->mtime();
    $session->mtime(value);

returns the last modification time.

@mlists = $session->multiLists() ;

$session->ctime();
    $session->ctime(value);

returns the creation time

$session->assignedto();
    $session->assignedto(value);
    $session->assignedto(undef, recalc);

If the value parameter is undef, but recalc is true, traverse the session calculating the complete list of assignees and update the cache.

returns the assigness as a comma separated list.

$session->summary();
    $session->summary(value);

returns the summary.

$session->testset();
    $session->testset(value);

returns the name of the test set.

$session->useSelectedOrder();
    $session->useSelectedOrder(value);

returns the current setting - 1 for true, 0 for false. Defaults to false.

TestSession::displaySetName( name ) ;

    $session->displaySetName() ;

Returns a version of the test set name suitable for use in displays. If the session has no affiliated set, returns "" wrapped for italics.

Note that this can also be called as a class method, in which case it must be passed a parameter that is the name to display.

$tdb->SQL_deleteTestInstance(tid) ;

Returns nothing.

my $query - $session->SQL_createQuery();

Returns a query that will return a list of tests based upon selectors.

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

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

my $tname = $sdb->SQL_tname;

Returns the name of the table for this object.

$session->SQL_updateTestInstance(num, hash) ;

num is the test case number to update.

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

Returns nothing.

SQL_auditTrail(tid, tdata) ;

tid is the test index in the session.

tdata is a reference to the test case data hash.

Returns nothing.

SQL_insertMulti(tid, tdata, fname );

tid is the text index in the session.

tdata is a reference to the test case data hash.

fname is the name of the field to populate.

Returns nothing.

@cols = $sessH->SQL_tableDef( tname ) ;

tname is the name of a SQL table

Returns a list item per column, formatted for use in a CREATE statement.

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

tname is the name of a SQL table.

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

$session->SQL_createIndices( );

tname is the name of the session table. If the table is not present, then create one.

Returns nothing.

$session->SQL_createTable( tname );

tname is the name of the session table. If the table is not present, then create one.

Returns nothing.

$session->SQL_drop() ;

Returns nothing.

$session->SQL_initialze( );

Returns nothing.

$sqltype = $sess-SQL_type(fref)

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

fref is a reference to a SchemaField object.

value is the value to use.

Returns a suitable quoted value.

$tid = $session->tcById( id );

returns the test case index corresponding to the given name

if the test is not in the session, returns undef.

$tid = $session->tcByUUID( uuid );

returns the test case index corresponding to the given uuid

if the test is not in the session, returns undef.

$tid = $session->nextTest(curTest, user, selRef) ;

curTest is a place to start searching from. If undefined, start from the beginning.

user is the userid making the request.

selRef is a reference to a hash of selectors. It can contain:

results - a reference to an array of results to match against.

modes - a reference to an array of run modes to match against.

justme - a boolean. If true, then only tests assigned to userid.

testsel - a reference to a collection of test case selectors.

testrd - a reference to a collection of test rundata selectors (sans results, since those are passed separately).

reqsel - a reference to a collection of requirement selectors.

Returns the index of the next test in the session that matches the selection criteria. Returns undef if there are no tests that match the criteria.

$note = $session->note($tid);
    $newNote = $session->note($tid, $text [, $result, clocktime, stafftime [, imported[, rundataHash[, keepOldRundata[, checkForChange]]]]]);

if result is not specified, then the note is a "note", otherwise it is a "result".

rundataHash is a hashref of execution data to save with the result/note - the keys are the fields names, the values are the values to save.

keepOldRundata is a boolean flag (default 0) which, if true, forces note() to update the current collection of execution data with the supplied values, rather than clearing the collection and replacing it with the supplied data.

checkForChange is a boolean flag (default 0) which, if true, makes note() compare the incoming execution data with the existing data, and only save a result if there's a difference.

Returns the contents of the note field.

$text = $session->noteText(tid [, asText]) ;

tid - the test id to retrieve from. asText - optional parameter indicating whether the data should be flat text or markup. Defaults to markup.

Returns only the text portion of the most recent note for a test case.

$text = $session->notesText(tid [, asText]) ;

tid - the test id to retrieve from. asText - optional parameter indicating whether the data should be flat text or markup. Defaults to markup.

Returns only the text portion of the most recent note for a test case.

$hashRef = $session->buildRundataHistory( tid ) ;

tid is a test index in this session.

Examines the notes field, creating an atm_rundatahistory compatible hash table with one entry per recorded result in the notes.

$session->numtests();
    $session->numtests(value);

While you can set the number of tests in the session with this method, it is generally not a good idea unless you really know what you are doing.

returns the number of tests in the session

$session->recalcResults();

returns the number of untested tests in the session

$session->resCounter($res);

gets/sets the number of tests in the session with the result returns the number of tests in the session with the result

$session->numUntested();

returns the number of untested tests in the session

if ( $session->numUntested == 0 && ! $session->notified ) {
        $session->notified( 1 );
        ...
    }

Returns 0 by default.

$result = $session->result(tid);
    $session->result(tid, result);

gets/sets the result of a test.

Returns the result.

Note: setting the result using this method is deprecated. Results should be set using the note() method instead.

$sess->updateResCounters(result [, oldResult] ) ;

Update the counters for result (and oldResult, if provided). Also update the numUntested accumulator.

$note = $session->rowNote($tid, $row [, $note ] ) ;

tid is the id of the test to set.

row is the row to get / set. If row is not defined, then return a reference to a list of all row results.

note is an optional parameter to set the note. If row is not defined, and note is a reference to a list, then all row notes are set to the values in the list.

Returns the note for a step of a test case.

$result = $session->rowResult($tid, $row [, $result ] ) ;

tid is the id of the test to set.

row is the row to get / set. If row is not defined, then return a reference to a list of all row results.

result is an optional parameter to set the result. If row is not defined, and result is a reference to a list, then all row results are set to the values in the list.

Returns the result set for a step of a test case.

$runData = $session->runData($tid); 

Returns the contents of the runData field, with newlines translated to HTML line breaks for display.

$runData = $session->runData($tid, $text);

Sets the contents of the runData fields, and returns it as above.

$runData = $session->runData($tid, $text, 1);

Creates all the markup as if it was going to save, but just returns it instead of saving. Doesn't translate newlines.

$session->tpno();
    $session->tpno(value);

returns the test plan seq number.

$session->runmode();
    $session->runmode(value);

value is one of:

continue - just run all the tests

pause - pause briefly between each test

step - single test and wait for user action

error - stop only on error

single - single test and terminate (not selectable by a user - used to

run a single test when the launch1 button is checked)

returns the runmode.

$session->runSelector(rundataField, value, isCS, isRE, dynamic, updateDynamic, isEmpty, isNotEmpty);

if value is a HASH reference, it is assumed to be a ref to a pre-defined legal selector structure that is just dropped into the space.

returns pointer to rundata selector

if rundataField is not defined, then it returns a reference to a hash of all the selectors. The value of each hash element is an array of selected values for that field.

my $cRef = $session->reqCollection() ;

Returns a reference to a requirement collection object. If one is not yet associated with this test session, instantiates one and ensures any stored requirement selectors are propagated into it.

$session->reqSelector(reqField, value);

returns pointer to selector

if reqField is not defined, then it returns a reference to a hash of all the selectors. The value of each hash element is an array of selected values for that field.

Note that this is really just a thin veneer on top of the ReqCollection object selector method. Updates are retained locally so they can be stored with the set/session object, but all the logic is in ReqCollection so we are not duplicating code.

$session->selector(schemaField, value);

returns pointer to selector

if schemaField is not defined, then it returns a reference to a hash of all the selectors. The value of each hash element is an array of selected values for that field.

$session->selector(agentAttribute, value);

returns pointer to selector

if agentAttribute is not defined, then it returns a reference to a hash of all the selectors. The value of each hash element is an array of selected values for that field.

$session->selectTests( useCache, collection, sort );

useCache is a boolean. If set, the the cache database is used to speed up test case selection. It defaults to true.

collection is an arrayref of test IDs to select from.

sort is a boolean - if true, the results are sorted in session sortKey order. If false the results are in a pseudo-random order. Defaults to true.

returns the number of tests selected.

returns undef if the user is not defined and useDefaults is true.

$val = $session->orAmongFields();
    $val = $session->orAmongFields(true | false);

If this flag is set to true, then the selectTests function will do an OR among the selectors instead of requiring AND among the selectors.

Returns the current value.

$val = $session->searchAndReplace();
    $val = $session->searchAndReplace( 1 );

If this flag is set to true, then the selectTests function will allow pattern matching and case sensitivity for menu fields, and will treat 'any' as a regular non-special value. Will also expand username to full names for matching.

Returns the current value (default 0).

$val = $session->idsAsStrings();
    $val = $session->idsAsStrings( 1 );

If set to true, ID field selectors are treated just like normal strings. If set to false, it does its usual special handling of ID selectors.

Returns the current value (default 0).

$session->setVariables(useDefaults);

If the session has no variables in the object, then only the required variables will be included.

returns a handle to the set of variables selected/set. returns undef if there was an error.

$session->sortKeys();
    $session->sortKeys(\@keys);

Gets/sets the ordered list of keys on which the session should be sorted.

Each item starts with a + or a -, indicating whether the sort on that field is ascending or descending.

Note that the sort key is NOT persistent!

$session->arrange( [ order ] ) ;

order is a reference to a list of ordered test UUIDs. If supplied, then the current object will be ordered to match that list. Otherwise it will be ordered to match the order as defined by the sortKeys method.

Returns the number of tests in the object.

$session->suiteDir();
    $session->suiteDir(path);

Gets/sets the path to the test suite data root. This defaults to the root of the test suite/data, and is currently imported from DB::DB.

$session->sync() ;

Returns nothing. Note that if the SQL option is not enabled, this function does nothing.

$session->testCase(num, dataHash [, trustMe] );

num is the ordinal of the testCase

dataHash is a hash of fields for the testCase. If you "undef" a field, then its contents will be removed.

trustMe is an optional parameter - if provided, it means that the hash contains (at least) an ID and a UUID that are accurate and do not need to be verified with the associated TestDB.

Defined attributes for a testCase include:

atm_id

The UUID of the test case in the test database.

id

the ID of the test case (relative path to test suite root)

results

the current result of the test

notes

the notes for the test

rundata

any runtime journal data for the test

runresults

the results from any server-side execution

user

the user who ran it most recently

when

the time it was run most recently

exectimestaff

The amount of time it took the user to run the testcase. This is ONLY populated if there is a special PlannedTime field in the schema and the tester populates the time field while executing the test case.

exectimeclock

The amount of time it took the testcase to complete. This is ONLY populated if there is a special PlannedTime field in the schema and the tester populates the time field while executing the test case.

note that an attribute must be defined in the fields data structure in order to be legal.

returns the handle to the test case hash. If num is not defined, returns the handle to all test cases.

$tcRef = $sess->testData( tid [, writeable] )

tid is a test index.

Returns a handle to a TestCase object for the test case associated with the tid. Retrns undef if the test case is not available.

$tiRef = $sess->testItem( tid ) ;

tid is a test index.

Returns a handle to a testItem object with accessors for the various aspects of a test case in the test session.

$session->profName();

returns a string containing the name of the associated profile.

$props = $session->properties(tid, format);

tid is the index of a test in the session.

format is "perl" or "prop". Default is "prop".

Returns all of the required session property data in the requested format.

$cacheDBH = $session->cacheDB();
    $cacheDBH = $session->cacheDB(handle);

handle is the handle to an existing cacheDB object.

Returns the handle to a cacheDB. If one is not already associated with the session, acquires one in write mode.

$session->reordered();
    $session->reordered(state);

returns a boolean indicating if the object has a custom order to its tests.

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

Returns true if the session can be refreshed. Defaults to true.

$session->release();

Releases a testDB, suiteDB, and/or AccountDB if one was loaded while processing.

Returns the result of calling SUPER::release.

Updates the associated SuiteDB, if there is one, with data from the session that needs to be quickly available.

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

$user = $session->currentUser();

returns a string containing the name of the current user of the session.

$session->user();
    $session->user(userName);

returns a string containing the name of the user for the session, or undef if the user is not defined.

$session->sessionId();
    $session->sessionId(sessionId);

returns a string containing the session id for the session, or undef if the session id is not defined.

If a session id is passed in as a parameter, will set the session id to that value.

$session->variable(varName, value, isDefault);

varName

the name of the variable.

value

the value for the variable.

isDefault

a boolean to indicate if the value is set to the default for the session.

returns the value of variable in a scalar context.

$table = $sess->variableTable(header);

If the boolean header parameter is true, then emit the "header" row for such a table. Otherwise emit the data for this session.

Returns an html table of session variables suitable for inclusion in a report.

@list = $session->visibleList( withSyn ) ;

If passed a true value, visibleList() will return a list that includes field synonyms (e.g. timeclock as well as exectimeclock).

@list = $session->settableList() ;

$val = $session->defaultVariable(varName);

varName is the name of a session variable.

Returns the value of the session variable for this session, or the default value for the variable if its value is not yet defined.

Returns undef if there is no such variable, or if the variable does not have a default.

$session->calcVariables();

$session->dbdata(varName [, value]);

varName

optional name of the variable.

value

optional value for the variable.

returns the value of variable in a scalar context if the varName is given, else it returns the reference to the dbdata hash.

$session->dbdelete( regex );

regex

regular expression to match against key name to delete

deletes any keys matching the regular expression from the dbdata hash. returns the number of keys deleted.

$res = stringMatch(value, reference) ;

value is the string to check.

reference is a reference to a single selector.

Returns true if the selector criteria matches the value.

$reference = $sess->associateFile(tid, name, file)

tid is the test index with which to associate.

name is the name of the item to use.

file is either a file handle to content or the content itself.

Returns a string that can be used as a reference to the file in the notes field for the test.

$jsInit = $session->javaScriptDependencies(showMandatory);

showMandatory is a boolean indicating whether to show which fields are mandatory or not. Defaults to true.

Returns a set of javascript declarations that match the dependencies among fields in a session.

$session->runDataDefaults;

TestSession::Field - class representing a execution field

new - create a new Field object

$field = new TestSession::Field(name) ;

asHtml - render a field in HTML format

$output = $field->asHtml($value [, $oval] ) ;

label - accessor for a label to use for the field

$label = $field->label() ;

makeValid - return a value that is valid for the field

$valid = $field->makeValid(value) ;

multiple - accessor for whether a field has multiple values or not

$multiple = $field->multiple() ;

prompt - accessor for a prompt to use when gathering input

$prompt = $field->prompt() ;

size - accessor for the size of a field

$size = $field->size() ;
        my ($rows, $cols) = $field->size() ;

sizeAsHtml - get the size for a field

$size = $field->sizeAsHtml(limit);

style - accessor for the style of a field

$style = $field->style() ;

type - accessor for the type of a field

$type = $field->type() ;

varName - accessor for the HTML form variable name for a field

$varName = $field->varName() ;

DESTROY() - tidy up

valuesList - return the values of a field as a list

@list = $field->valuesList() ;

descs - return the descriptions of a field as a list

@list = $field->descs() ;

$flags = $field->getFlags();

Returns a value for the FLAGS field of a SCHEMA2 file.

isNumber - is this field numeric

$field->isNumber() ;

isList - is this a list field

$state = $field->isList() ;

isRange - is this a range field

$state = $field->isRange () ;

isDate - is this a date field

$state = $field->isDate () ;

my $val = $field->SQL_value($val) ;

Returns the value of the field after interpretation by TestDB object.

TestSession::TestItem - class with accessors for test items in a session

new - create a new TestItem object

$itemRef = new TestSession::TestItem(parentRef, idx) ;

valueOf - accessor for the value of a test item

$val = $itemRef->valueOf( field ) ;
    $val = $itemRef->valueOf( field, value ) ;

$val = $itemRef->valueOfAsText( field ) 

field is the name of a field to get the value for. Ensures the field data is properly formatted, then transforms it into text form laid out as best it can.

AUTOLOAD() - simple AUTOLOAD handler

DESTROY() - tidy up