TestSession
TestSession |
|
TestSession - class representing a test session
Shane P. McCarron <shane@aptest.com>
Copyright 2001-2007 Applied Testing and Technology, Inc. All Rights Reserved.
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).
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:
$session = new TestSession(suite, [sessID [, read/write [, timeout]]]);
Creates a new session object, optionally specifying several parameters:
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.
$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.
$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.
$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.
@sFlist = $session->sortedFlist() ;
Returns a list of field names that are sorted by field label case insensitively.
$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.
$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 ] );
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.
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.
@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.
$tdb->SQL_deleteTestInstance(tid) ;
Returns nothing.
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_insertMulti(tdata, fname );
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_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
$tid = $session->tcByUUID( uuid );
returns the test case index corresponding to the given uuid
$note = $session->note($tid);
$newNote = $session->note($tid, $text [, $result, clocktime, stafftime [, imported] ]);
if result is not specified, then the note is a "note", otherwise it is a "result".
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.
$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->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.
$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);
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.
$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);
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.
Defined attributes for a testCase include:
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.
$session->profName();
returns a string containing the name of the associated profile.
$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);
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]);
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 );
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.
$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;
# 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 - class representing a execution field
$field = new TestSession::Field(name) ;
Creates a field object. Returns a reference to the created object.
$output = $field->asHtml($value) ;
Returns the content, annotated according to its style.
$label = $field->label() ;
If no label is defined for a field, uses the field's name.
$prompt = $field->prompt() ;
If no prompt is defined for a field, uses the value of the label accessor.
$size = $field->size() ;
my ($rows, $cols) = $field->size() ;
Returns a size or a height and width, depending upon the type of the field.
$size = $field->sizeAsHtml(limit);
returns a string suitable for use in the appropriate input element.
$style = $field->style() ;
Returns the style for the field, or "text" if no style is defined.
$type = $field->type() ;
Returns the type for the field, or "text" if no type is defined.
$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.
@list = $field->valuesList() ;
Returns the values as a list, or undef if the field is NOT a list field.
@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.
$flags = $field->getFlags();
Returns a value for the FLAGS field of a SCHEMA2 file.
$state = $field->isList() ;
Returns true if the field is a list type field, and false if it is not.
$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.
$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.
Hey! The above document had some coding errors, which are explained below:
Copyright © 2000-2007 Applied Testing and Technology, Inc. All rights reserved.