NAME

TestCase - class representing a test case

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

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

SYNOPSIS

use TestCase;

Create an empty test case
my $case = new TestCase();

get the value of a field
$value = $case->valueOf(field)

set the value of a field
$value = $case->valueOf(field, value)

get/set the location of the test case
$value = $case->path(value)

save the Test Case
$res = $case->save();

The TestCase object permits creation of/access to a test case and its contents. Such objects can be sued to create new test cases, read existing test cases, or update existing test cases.

The data structure uses hashs to capture the majority of the field data. However, since field data is "ordered", there is also an index array that keeps track of the order in which the data was read/created, and should be emitted if the save or print methods are called.

DATA STRUCTURE

path

the path to the test case.

lock

a handle to the lock that is set for the object.

writeable

a boolean that indicates whether the testcase is open read/write. Note that this does not really effect the way in which the file is opened - the file is only opened when it is read in. This controls whether the file can be updated.

testDB

a handle to an associated test database. If defined, the methods will use and update an associated TestDB object. See TestDB for more information.

fields->[ ]

an ordered list of field identifiers.

data->

a hash of fields and their values. {data}->{name}

METHODS

new - create a new TestCase object

$tc = new TestCase()
$tc = new TestCase(suite)
$tc = new TestCase(suite, name)
$tc = new TestCase(suite, name, readWrite)
$tc = new TestCase(suite, name, readWrite, testDbHandle)

suite is the test suite in which we are operating

name is the name of the test in that suite

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

testDbHandle is a ref to a TestDB object. If it is not provided, a testDB will be opened, used, and released automatically.

schema is a ref to a Schema object. If it is not provided, one will be opened, used, and released automatically.

newByUUID - open a test case using its UUID

$tc = TestCase::newByUUID(suite, UUID)
$tc = TestCase::newByUUID(suite, UUID, readWrite)
$tc = TestCase::newByUUID(suite, UUID, readWrite, testDbHandle)

suite is the test suite in which we are operating

UUID is the UUID of the test in that suite

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

testDbHandle is a ref to a TestDB object. If it is not provided, a testDB will be opened, used, and released automatically.

schema is a ref to a Schema object. If it is not provided, one will be opened, used, and released automatically.

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

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

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.

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

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

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.

generateMarkup - generate an HTML page for the contents of this test case

generateMarkup walks through all the fields defined in a test case, emitting the HTML associated with those fields. It does this in SCHEMA order, regardless of the order of the fields in the test case itself.

$output = $tc->generateMarkup(template, showValues, showLabels);

template is the template to populate.

showValues is a boolean flag that indicates whether the values of session variables should be interpolated. If true, values are ONLY interpolated if there is also a session associated with this test case object.

showLabels is a boolean flag indicating whether field labels should be included in the output.

fieldList is a comma-separated list of field names in which values should be highlited if they are present.

pattern is a reference to a hash describing the pattern to highlight. The hash has three elements; pat is a string; isRE indicates if it is a regular expression; isCaseSensitive indicates if it is case sensitive.

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

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

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

   where

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

displayID - return a displayable ID

$theID = $test->displayID( [ noPath [, asText [, onClick ] ] ] ) ;

noPath is an optional boolean flag that indicates whether to include the path in the ID. It defaults to false.

asText is an optional boolean flag that indicates whether to return a straight text version of the ID. It defaults to false.

onClick is an optional string to use in an onclick handler for the ID. If supplied, the ID is wrapped in a span with the appropriate onClick text.

Returns a version of the test ID that is designed to be displayed.

dirtyFlag - accessor for the flag indicating if data has changed.

$tc->dirtyFlag();
$tc->dirtyFlag(1|0) ;

Calling this method with no arguments will return whether or not any data has changed since the ojbect was originally created.

When ever you DO change part of the object (most notably "data") you should call this method with the true value.

lastValueOf - extract or append the last value of a field in a table

$last = $tc->lastValueOf(field) ;
$last = $tc->lastValueOf(field, value) ;

Returns the last value of a field. If the field is NOT in a table, just returns the field's value. If the field does not exist, or the field has no value, returns undef.

If a value is supplied, appends a value to the field if it's a table field, otherwise just replaces the value. (Note that it doesn't keep the other fields in the row in sync - that's up to the calling code.)

locked - accessor for test case locked state

$locked = $tc->locked( [state] )

state is the optional state for the locked flag. 1 for locked, 0 for unlocked.

Returns the current state of the flag.

populate - populate all fields of a test case with content

$tc->populate() ;

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

addHistory - add a history entry

$tc->addHistory( message [, user ] ) ;

message is a message to put in the history list.

user is an optional username. Defaults to the current user.

Adds an entry to the history table if there is one. Updates the muser and mdate fields to be the current user.

fromDisk - get/set the flag for whether the test is from disk or not

$boolean = $tc->fromDisk();

Returns a boolean indicating whether or not the test was read from its source file on the disk.

id - get/set the ID of a test

$id = $tc->id(path);

Returns the current setting of the special Id field of the object.

If path is defined, sets the contents of the Id field according to path.

identifier - get/set the formal identifier of the test

$ident = $tc->identifier(myID);

The identifier is the unique, test suite relative path name for the test case.

init - initialize the test case with common data

$tc->init() ;

Establishes values for common fields and empty values in all other fields in an empty test case.

mtime - accessor for the modification time of the source

$time = $tc->mtime();
$time = $tc->mtime(time);

path - the pathname of the test object

$path = $tc->path()

release - release the object

Really a no-op, since this object does not have a database.

sandbox - get/set reference to sandbox

my $sbRef = tcRef->sandbox( sbRef ) ;

Returns a reference to a sandbox object.

clear - clear a test case's data

$tc->clear();
$tc->clear( exclusions );

clear() deletes all the data in a test case, with the exception of the 'id' 'atm_id' fields. If an arrayref of field names is passed to clear(), those fields are also not cleared.

save - save the test object

# save a test that was read from disk initially
# note that if it was NOT opened for writing initially, this might not work.
$res = $tc->save();

# save a test case that was read from disk, and use the Schema defined order
# for the fields
$res = $tc->save(1);

# save a test that was created in memory (or to an alternate location)
$res = $tc->save(useSchema, path);

returns 1 if the save succeeded.

schema - get/set the reference to a schema for this test case

my $schema = new Schema();
my $tc = new TestCase();
$tc->schema($schema);

If this method is called with a handle, it is assumed to be a handle to a schema object.

Otherwise, it will check to see if a schema has already been associated with this test case. If not, it will get one.

Returns a handle to the schema associated with this object.

session - get/set the reference to a TestSession object

If this method is called with a handle, it is assumed to be a handle to a TestSession object.

Returns a handle to the schema associated with this object.

UUID - get the UUID for a test case

$uuid = $tc->UUID() ;

returns the value of the UUID field from the testcase. If there is not yet a UUID field, creates a new UUID for the test case, updates the test case, and returns that value.

returns undef if the test case was not opened in write mode or if we no longer have a handle to a test database AND we need to create the UUID.

rawValue - get the raw value of a field

$val = $tc->rawValue(field);

returns the value of the field.

valueAsList - get the value of a field as a list

@list = $tc->valueAsList(field) ;

Returns the value for the field as a list, having split the items up if the field is of the appropriate type.

valueOf - get/set the value of a field

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

returns the value of the field. If the field was not previously defined, then the value is set AND the field is appended to the ordered list of fields in $tc->{fields}.

If the value is a "list" field according to the schema, then we use the schema object to reorder the values into a legal set that is in the schema defined order BEFORE we store it.

valueOfAsText - return the value of a field in text form

$val = $tc->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.

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