NAME

TestSession - class representing a test session

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

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

SYNOPSIS

use TestSession;

    # create a new TestSession object
    my $session = new TestSession([$suite]);

    # set its description
    $session->description("A sample session");

    # define a selector
    $session->selector("TestType", "smoke");

    # fetch the tests
    $session->selectTests();

    # set the variable defaults using account defaults
    $session->setVariables(1);

    # set another variable value
    $session->variable("email_address", "username\@example.com");

    # now write it out as a new DBM-format session
    my $sessId = $session->save(1, "new");

    # now release the first one
    $sess = undef;

    # open up an existing session and use it
    my $sess = new TestSession($suite, $session);

    # get its description
    my $desc = $session->description();

    # get the number of tests
    my $numtests = $session->numtests();

    # get the set of schema selectors for the session
    my $selectors = $session->selector();

The TestSession object maps a test session state into an object that can be manipulated by a test framework. It relies upon some external methods to ensure seamless integration into whatever test framework is using it. It supports serialized objects on disk as well as directly TIEd data files.

The data structure of this object is optimized to be most efficient when used in conjunction with MLDBM and a single key hashed database. This object CAN use serialized objects as well, but it is MUCH slower. Note that when using MLDBM, the save method doesn't do anything (except possibly for the first time it is called if the database had not yet been converted to MLDBM format).

DATA STRUCTURE

user

the name of the user that last updated this session

lock

a handle to the lock that is set for the object

writeable

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

sessionId

the session identifier

locked

A flag that indicates whether the session is locked to changes.

usingDBM

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

data->
variables

a hash of session variables and their values: {variables}->{name}->{value, isDefault}

selectors

a hash of schema fields and their values: {selectors}->{name}->@values

suite

the test suite for this session

tpno

the current test number

currTest

the test most recently started and when it was started, as a hash:

tid

The id as an ordinal number.

when

The time when the test was started (as a time int).

lastTest

the test most recently completed as an ordinal number.

testset

the name of the test set this session is based upon

description

the description of the session

dbdata

a hash of store/fetch persistent key/value pairs: {dbdata}->{keyname}

numtests

a scalar of the number of tests

numUntested

a scalar of the number of tests that have no result at all

resultCounters

a hash of the number of tests that have each result

Test_n

a hash of information about each test in the session: {TEST_n}->{id, results, rundata, runresults, assignedto}

Reserved fields

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.

METHODS

new - Create a new, unpopulated test session

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

runpath - get the path to the suites rundata definition

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

path - get the path to the session

returns a path to the persistent store for this object.

plannedtimes - retrieved the planned times for a session

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

assignedTimes - return a hash of assignees and progress

$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

results - accessor for a Results object

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

saveAsText - save the session as a serialized object

$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 - write out the object

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.

populate - populate all rundata fields of a testcase

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

print - print the contents of the session

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

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

clear - clear the data in one or all tests

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

copy - copy another session object's data into this one

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

countTests - return a count of the tests that match selectors

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

currTest - set/get the currently executing test case

$testNum = $session->currTest() ;

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

currTestStatus - set/get the status of the currently executing test case

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

edit - accessor to indicate if we are editing the data

field - get the fieldlist

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

historyFields - return a list of fields with the history flag

@list = $sess->historyFields() ;

fieldEntryWrap - output an entry, wrapping the content

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

fieldEntryVar - output an entry with a special variable suffix

$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

fieldEntry - output a formatted result field entry

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

fieldOrder - return the defined rundata field names in a list

$list = $session->fieldOrder() ;

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

buildSelectorTable - create a table of selector fields

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

getSelsFromArgs - update selector collection from an ARGS hash

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

fieldSelection - return a selection input item for a field

$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 - get a list of rundata fields

@flist = $session->flist() ;

Returns an array of field names.

auditFlist - get a list of fields that are kept in the audit trail

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

write - write out the rundata file

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.

serialize - create a serialized version of the rundata fields

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

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

sortedFlist - get a list of rundata fields ordered by label

@sFlist = $session->sortedFlist() ;

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

generateCSV - uses Text::CSV_XS to generate CSV data of field values.

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

generateVarXML - create structured XML for session variables.

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

   where

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

generateXLS - uses Spreadsheet::Write to generate Excel data of field values.

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

generateXML - create structured XML from a list of fields names.

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

generateMarkup - generate a version of a test case with HTML markup

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

id - get the ID associated with a test

$idString = $session->id() ;

Returns the "name" of the test case.

displayID - get the displayable ID for a test

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

isNumber - return whether a field is to be treated as numeric

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

isActive - is this test session active

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

refresh - re-synchronize the test collection with the set

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

resList - accessor for the associated result list

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

returns an array of results

testList - retrieve the complete list of test IDs

@list = $session->testList();

returns an ordered list of test case IDs.

testUUIDList - retrieve the complete list of test UUIDs

@list = $session->testUUIDList();

returns an ordered list of test case UUIDs.

selDesc - get a description for a rundata selector

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

allSelDescs - return prose descriptions for all selectors

 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.

selectableList - return a list of selectable fields

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

sizeOf - Get the size of a rundata field

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

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

suffix - accessor for the suffix to use for fields

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

typeOf - Get the type of a rundata field

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

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

updateIDs - ensure that all ID attributes match UUIDs

$session->updateIDs() ;

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

Returns nothing.

userList - return a list of userIDs with access to this suite

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

Returns a list of users.

addTest - add a test to the session

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

deleteTest - delete a test from 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.

disableTest - mark a test as not in use for this 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.

insertTest - insert a test into 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.

insertTests - insert a collection of tests into 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.

enddateplanned - accessor for the planned end date

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

returns the planned end date.

enddatewindow - accessor for the end date window size

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

returns the planned end date window size.

startdateplanned - accessor for the planned start date

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

returns the planned start date.

startdatewindow - accessor for the start date window size

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

returns the planned start date window size.

enddateactual - accessor for the actual end date

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

returns the actual end date.

startdateactual - accessor for the actual start date

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

returns the actual start date.

description - accessor for the description

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

returns the description.

disabled - access the disabled test case list

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

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

lastTest - set/get the last test to post a result

$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 - get/set locked flag for session

$locked = $session->locked();

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

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

mtime - accessor for the modification time

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

returns the last modification time.

multiLists - return a list of multi-select lists

@mlists = $session->multiLists() ;

ctime - accessor for the creation time

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

returns the creation time

summary assignedto accessor for the assignees

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

summary - accessor for the summary

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

returns the summary.

testset - accessor for the associated test set name

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

returns the name of the test set.

useSelectedOrder - accessor for the selectedOrder flag

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

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

displaySetName - return a test set name for displaying

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.

SQL_deleteTestInstance - remove a test instance altogether

$tdb->SQL_deleteTestInstance(tid) ;

Returns nothing.

SQL_createQuery - construct a SQL query for use by _getTests

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

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

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

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

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

SQL_tname - return the table name

my $tname = $sdb->SQL_tname;

Returns the name of the table for this object.

SQL_updateTestInstance - update a test instance data in a SQL store

$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 - put out audit trail entries for a test

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

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.

SQL_tableDef - return a list of table column definitions

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

SQL_tableFields - return a list of column names in a table

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

tname is the name of a SQL table.

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

SQL_createIndices - Create the table indices

$session->SQL_createIndices( );

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

Returns nothing.

SQL_createTable - check if the session table is there, create if needed

$session->SQL_createTable( tname );

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

Returns nothing.

SQL_drop - drop the whole table

$session->SQL_drop() ;

Returns nothing.

SQL_initialize - delete the rows associated with this session

$session->SQL_initialze( );

Returns nothing.

SQL_type - determine the best SQL type for an ATM type

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

SQL_value - determine the best SQL value

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

tcById - return test case index # given its name

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

returns the test case index corresponding to the given name

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

tcByUUID - return test case index # given its uuid

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

returns the test case index corresponding to the given uuid

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

nextTest - find the next test in this session that matches criteria

$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 - get/add to a notation of a test case

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

noteText - Get the text portion of a note

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

notesText - Get the text portion of all notes

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

buildRundataHistory - create a rundata history hash from data in "notes"

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

numtests - accessor for the number of tests

$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

recalcResults - recalculate the result counters

$session->recalcResults();

returns the number of untested tests in the session

resCounter - accessor for the number of tests with a specific result

$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

numUntested - accessor for the number of tests still to do

$session->numUntested();

returns the number of untested tests in the session

notified - has a 'session complete' notification been sent for this session?

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

Returns 0 by default.

result - accessor for the result of a test

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

updateResCounters - update the result counters

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

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

rowNote - get/set the note for an individual row

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

rowResult - get/set the result for an individual row

$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 - get/add to the runData portion 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.

tpno - accessor for the test plan number item

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

returns the test plan seq number.

runmode - accessor for the runmode

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

runSelector - accessor for rundata selector attributes

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

reqCollection - accessor for an associated requirement collection

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.

reqSelector - accessor for requirement selector attributes

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

selector - accessor for selector attributes

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

agentSelector - accessor for agentSelector attributes

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

selectTests - select Tests that match the "selectors"

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

orAmongFields - accessor for OR vs. AND in searches

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

searchAndReplace - are we doing search and replace?

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

idsAsStrings - treat ID fields as text strings?

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

setVariables - set the variables to their defaults

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

sortKeys - accessor for test session sorting rules

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

arrange - method to arrange the current object using the current keys

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

suiteDir - accessor for test suite root

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

sync - synchronize the data into the SQL store and the suiteDB

$session->sync() ;

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

testCase - accessor for testCase attributes

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

testData - return a handle to a TestCase object for a tid

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

testItem - return a handle to a testItem object

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

profName - accessor for profile name attribute

$session->profName();

returns a string containing the name of the associated profile.

properties - return the contents of a property file about this session

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

cacheDB - Accessor for a cacheDB handle.

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

reordered - accessor to see if a session was reordered

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

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

refreshable - can the session be refreshed?

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

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

release - release the object and anything it opened

$session->release();

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

Returns the result of calling SUPER::release.

suiteDB - get a suiteDB object.

updateSuiteDB - update the suite database

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.

currentUser - accessor for who is accessing right now

$user = $session->currentUser();

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

user - accessor for user attribute

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

sessionId - accessor for sessionId attribute

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

variable - accessor for variable attributes

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

variableTable - return an HTML table of session vars

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

visibleList - return a list of visible execution fields

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

settableList - return a list of settable execution fields

@list = $session->settableList() ;

defaultVariable - get the value of a variable or its default

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

calcVariables - Calculate derived variable values

$session->calcVariables();

dbdata - accessor for dbdata persistent storage

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

dbdelete - delete accessor for dbdata persistent storage

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

stringMatch - check to see if a string matches

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

associateFile - associate a file with a result

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

javaScriptDependencies - set up depends for JS functions

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

runDataDefaults - execution field default values as a JavaScript object

$session->runDataDefaults;

EXAMPLES

# create a new session
    my $session = new TestSession("user");

    $session->selector("Version", "5");
    $session->selector("TestType", ["smoke", "stress", "functional"]) ;

    my $numTests = $session->selectTests();

    print "Number of tests selected was $numTests\n";

    $session->setVariables();   # brings in the default variables

    $session->description("My test session");

    # save in the next available session as a serialized object, not a DBM file
    my $sessId = $session->save(undef, "new")   

TestSession::Field

NAME

TestSession::Field - class representing a execution field

METHODS

new - create a new Field object

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

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

asHtml - render a field in HTML format

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

value is the value to render.

oval is a supporting value that will be used as a URL when interpreting atm_prid fields.

Returns the content, annotated according to its style.

label - accessor for a label to use for the field

$label = $field->label() ;

If no label is defined for a field, uses the field's name.

makeValid - return a value that is valid for the field

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

This method only transforms data from fields of type atm_minutes* - it uses the suffix as the multiplier for data that has a 'd' in it (as in days).

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

$multiple = $field->multiple() ;

Returns true if a field has multiple values, false if it does not.

prompt - accessor for a prompt to use when gathering input

$prompt = $field->prompt() ;

If no prompt is defined for a field, uses the value of the label accessor.

size - accessor for the size of a field

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

Returns a size or a height and width, depending upon the type of the field.

sizeAsHtml - get the size for a field

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

returns a string suitable for use in the appropriate input element.

style - accessor for the style of a field

$style = $field->style() ;

Returns the style for the field, or "text" if no style is defined.

type - accessor for the type of a field

$type = $field->type() ;

Returns the type for the field, or "text" if no type is defined.

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

$varName = $field->varName() ;

Returns the variable name to use for the field, or the name of the field if no special variable name is defined.

DESTROY() - tidy up

valuesList - return the values of a field as a list

@list = $field->valuesList() ;

Returns the values as a list, or undef if the field is NOT a list field.

descs - return the descriptions of a field as a list

@list = $field->descs() ;

Returns the descriptions as a list, or undef if the field is NOT a list field. If the field has no descriptions, then returns the output of valuesList instead.

getFlags - create a FLAGS field from settings

$flags = $field->getFlags();

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

isNumber - is this field numeric

$field->isNumber() ;

Returns true if it is numeric, and false if it is not.

isList - is this a list field

$state = $field->isList() ;

Returns true if the field is a list type field, and false if it is not.

isRange - is this a range field

$state = $field->isRange () ;

Returns true if the field is a field that can be searched using a range expression, and false if it is not.

isDate - is this a date field

$state = $field->isDate () ;

Returns 1 if the field is date only, 2 if it is a date/time field, and 0 if it is neither.

SQL_value - do a SQL transformation on a value for a field

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

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

TestSession::TestItem

NAME

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

METHODS

new - create a new TestItem object

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

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

valueOf - accessor for the value of a test item

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

Returns the value of a field in the test item.

valueOfAsText - return the value of a field in text form

$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

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