TestSession
TestSession |
|
TestSession - class representing a test session
Shane P. McCarron <shane@aptest.com>
Copyright 2001-2006 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.
$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->clearCommands() ;
Returns nothing.
$cmd = $session->command() ;
Returns the first command in the queue, or undef if there is no command pending.
$session->command(cmdString) ;
Pushes a command into the queue.
$cmd = $session->commandMonitor() ;
Returns the first command in the queue, or undef if there is no command pending.
$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 true.
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.
$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 ) ;
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.
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);
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.
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.
$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.
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)
Returns the "name" of the test with ATM suffixes removed and whitespace inserted after slashes.
$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" and 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.
$desc = $session->selDesc(field, selRef) ;
field is the name of the field.
selRef is a hash reference to a selector.
Returns a string that is a description of the selection in the context of the field type.
$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.
$hash = $session->userHash();
Returns the reference to a userHash structure. This may be retrieved from the associated schema if there is one, or from the Account object if there is not. Once retrieved, it is cached locally. Subsequent calls will return a reference to the cached userHash.
@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->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.
$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.
$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.
$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.
$runData = $session->runData($tid);
$runData = $session->runData($tid, $text);
Returns the contents of the runData field.
$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 );
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.
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->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->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.
$vset = $session->variableSet();
$vset = $session->variableSet(setH);
setH is a handle to a variable set.
Returns a handle to a VariableSet object.
Returns a reference to a schema object.
$session->suite();
$session->suite(userName);
returns a string containing the name of the associated test suite.
$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.
$suiteDBH = $session->suiteDB();
$suiteDBH = $session->suiteDB(handle);
handle is the handle to an existing suiteDB object.
Returns the handle to a suiteDB. If one is not already associated with the session, acquires one in write mode.
$testDBH = $session->testDB();
$testDBH = $session->testDB(handle);
handle is the handle to an existing testDB object.
Returns the handle to a testDB. If one is not already associated with the session, acquires one in read mode.
$session->reordered();
$session->reordered(state);
returns a boolean indicating if the object has a custom order to its tests.
$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.
@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 run data 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.
$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 true if the field is a field that contains a date, and false if it is not.
Copyright © 2000-2006 Applied Testing and Technology, Inc. All rights reserved.