ITest

General purpose abstract class for writing Test Framework tests.

Use ITest to derive subclasses for testing features of your test targets. ITest provides an output stream in which you can record any tesxt output. ITest provides input text arguments that you can use to parameterize the kind of test to be performed. Meta-information on the test may also be defined and obtained using the copyInfo and lookupInfo methods.


ITest - Member Functions and Data by Group

Constructors & Destructor

Class constructors and destructors.


[view class]
~ITest
public:
virtual ~ITest()
ITest destructor. It does not delete the target. Subclasses must handle the target themselves.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ITest
Constructors.


Overload 1
protected:
ITest(const ITest& test)
Copy constructor which creates an ITest object from an existing one.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
ITest()
Default constructor to create an ITest object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Assignment Operators

Use this operator to assign an ITest class to another.


[view class]
operator =
public:
ITest& operator =(const ITest& test)
Standard assignment operator for ITest.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Exceptions

Class exception member functions used to determine the status of a test run.


[view class]
exceptionStage
public:
virtual EStage exceptionStage() const
A public exception method to determine when an exception occurred in run.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Execution

Class member functions used to execute the test.


[view class]
run
public:
virtual void run()
This method is the public means of telling the test to execute itself. You can call run to execute a test instance.

Derived classes should not override this function. The run function calls following the framework methods:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Execution Results

Class member functions used to determine that status of the test.


[view class]
runCount
public:
virtual unsigned long runCount() const
Returns the number of times run has been called.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
success
public:
bool success() const
This method returns the success state of the last run. You may call success after a test has been run to see if the test succeeded. This value is not meaningful if the data member isReset is true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Input Configuration

Manipulate the test's input arguments.


[view class]
copyInputs
public:
void copyInputs(int& argc, char * *& argv) const
Create a copy of the current input arguments.

Copies parameters that take UNIX-style parameters to argv.

argc
UNIX-style argc parameter
argv
UNIX-style argument vector

Derived classes should not override this function.

You can call copyInputs after running a test to correlate inputs with the test results. The caller owns the string array and should delete the storage.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setInputs
public:
void setInputs(const int argc, const char * const* argv)
Deletes current inputs and creates IString objects for each item in argv and adds the text to the inputs.
Setups new input values. Copies UNIX-style input text to internal storage.
argc
UNIX-style argc parameter
argv
UNIX-style argument vector

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Main Testing Functions

Main member functions used to setup the actual tests.


[view class]
addInfo
protected:
virtual void addInfo(const IString&, const IString&)
This member function adds a key/value pair of Istring values to the test meta information. These are most often used when overriding the copyInfo member function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
cleanup
protected:
virtual void cleanup()
A framework method that derived classes override to restore the system to its previous state.

Any actions within setup which need to be undone (for example, storage allocation), should be undone here.

ITest::run always calls cleanup, even if an exception occurs.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
print
Allows customization of the way a test prints.
protected:
virtual void print(ITieredTextBuffer&)
Allows customization of the way a test prints by printing to an ITieredTextBuffer object. Derived classes may override this function to customize the way a test prints via operator<<(ITieredTextBuffer). In the subclass implementation, be sure to call the print method in the immediate base class before doing anything else. Then output your own information with a final carriage return. If a subclass overrides print, this additional information is included in the test result.

Note: The content of the print method is printed out only when you set (through the command line) the echotier level equal to or below ITieredTextBuffer::kDetail.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
reset
protected:
virtual void reset()
Resets the internal state of ITest back to the initial state.

Overriding methods should call the inherited method first. This method is used to perform necessary re-initialization operations for tests that can be run more than once. ITest::run calls this method before running a test a second or later time. ITest::run does not call reset before running a test for the first time. Derived classes that should not be run more than once, can use this method to ensure that multiple calls to run do no harm.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setup
protected:
virtual void setup()
A framework method that subclasses override to do whatever setup work the test will need.

Subclasses may override setup to perform any appropriate initialization before test is called. For example, a test might instantiate a target object to be tested if there is not one already.

Note: Anything that is done in setup should be undone, if necessary, in cleanup.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
test
protected:
virtual void test() = 0
The framework method that subclasses override to actually perform the test.

The only ITest method that subclasses are required to call inside a test is setSuccess.

Note: Derived classes must override this method, even if they do not override any of the other methods in this class.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Meta-information

Member functions used to setup or retrieve test meta information.


[view class]
copyInfo
public:
virtual void copyInfo()
This method is used to store meta-information about the client test. Derived classes should override this function.

You can specify various types of meta-information, including the purpose of a test and the name of the class being tested. You can retrieve and display this information by using the -info option when you start RunTest.

When you assign information to a test, associate each test class with key/value pairs in a dictionary. This supports categorization of different kinds of tests and analysis of large numbers of test results.

The text values for the keys can be used with the -info option of RunTest to query a specific key/value pair in the dictionary. The following shows the predefined keys and values:

        KEY             KEYWORD(VALUE)        DESCRIPTION
    ---------------     --------------        -------------------------------------
    kDescriptionKey     Description           Description of this test subclass
    kInputSyntaxKey     Input Syntax          Input syntax for text arguments
    kTargetClassKey     Target Class          Name of target class
    kTestNameKey        Test Name             Name of test
    kTestVersionKey     Test Version          Version number of test
    kTestTypeKey        Test Type             Type of test (eg. unit, regression, etc.)
    kComponentKey       Component             Name of component to which this test applies

Inside of copyInfo, derived classes should call the inherited implementation (IDerived::copyInfo should call IBase::copyInfo). Then copyInfo should add key/value pairs to infoMap by calling the addInfo method.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
lookupInfo
public:
virtual bool lookupInfo(const IString& key, IString& info)
Looks for the information corresponding to the given key. If found, it copies the information into the info parameter and returns true. Otherwise, lookupInfo leaves info untouched and returns false. Derived classes should not override this function.

key
IString for the key
info
IString for returned value

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addInfo
protected:
virtual void addInfo(const IString&, const IString&)
This member function adds a key/value pair of Istring values to the test meta information. These are most often used when overriding the copyInfo member function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Output

Member functions used by the tests to display output.


[view class]
outputTextStream
public:
ITieredTextBuffer& outputTextStream()
Returns a reference to a ITieredTextBuffer object. Derived classes may use the returned reference transparently to produce textual output.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
print
Allows customization of the way a test prints.
protected:
virtual void print(ITieredTextBuffer&)
Allows customization of the way a test prints by printing to an ITieredTextBuffer object. Derived classes may override this function to customize the way a test prints via operator<<(ITieredTextBuffer). In the subclass implementation, be sure to call the print method in the immediate base class before doing anything else. Then output your own information with a final carriage return. If a subclass overrides print, this additional information is included in the test result.

Note: The content of the print method is printed out only when you set (through the command line) the echotier level equal to or below ITieredTextBuffer::kDetail.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Public Data Members

Public data members used to store meta-information about this test. See the member functions copyInputs, setInputs, copyInfo, lookupInfo, and addInfo.


[view class]
kComponentKey
Name of component that this test applies to.


Overload 1
Name of component that this test applies to (non-AIX platforms).
public:
static const IString & _Import kComponentKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Name of component that this test applies to (AIX Platform).
public:
static const IString& kComponentKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
kDescriptionKey
Description of this test subclass.


Overload 1
Description of this test subclass (non-AIX platforms).
public:
static const IString & _Import kDescriptionKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Description of this test subclass (AIX platform).
public:
static const IString& kDescriptionKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
kInputSyntaxKey
Input syntax for text arguments.


Overload 1
Input syntax for text arguments (AIX platform).
public:
static const IString& kInputSyntaxKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Input syntax for text arguments (non-AIX platforms).
public:
static const IString & _Import kInputSyntaxKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
kTargetClassKey
Name of the target class.


Overload 1
Name of the target class (non-AIX platforms).
public:
static const IString & _Import kTargetClassKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Name of the target class (AIX platform).
public:
static const IString& kTargetClassKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
kTestNameKey
The name of the test.


Overload 1
The name of the test (non-AIX platforms).
public:
static const IString & _Import kTestNameKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
The name of the test (AIX platform).
public:
static const IString& kTestNameKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
kTestTypeKey
A type of test. For example, unit or regression test.


Overload 1
A type of test (non-AIX platforms).
public:
static const IString & _Import kTestTypeKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
A type of test (AIX platform).
public:
static const IString& kTestTypeKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
kTestVersionKey
Version number of the test.


Overload 1
Version number of the test (AIX platform).
public:
static const IString& kTestVersionKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Version number of the test (non-AIX platforms).
public:
static const IString & _Import kTestVersionKey

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Test Control

Member functions used to control the test status keeping.


[view class]
copyInputs
public:
void copyInputs(int& argc, char * *& argv) const
Create a copy of the current input arguments.

Copies parameters that take UNIX-style parameters to argv.

argc
UNIX-style argc parameter
argv
UNIX-style argument vector

Derived classes should not override this function.

You can call copyInputs after running a test to correlate inputs with the test results. The caller owns the string array and should delete the storage.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setInputs
public:
void setInputs(const int argc, const char * const* argv)
Deletes current inputs and creates IString objects for each item in argv and adds the text to the inputs.
Setups new input values. Copies UNIX-style input text to internal storage.
argc
UNIX-style argc parameter
argv
UNIX-style argument vector

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isReset
protected:
virtual bool isReset() const
Returns true if the test has been reset without running.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isSuccessUndecided
protected:
virtual bool isSuccessUndecided() const
Returns true if setSuccess has not been called or if reset has been called, otherwise returns false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setStickySuccess
protected:
virtual void setStickySuccess(bool success)
Used to preserve the failure state of a test until the next run of the test.

The difference between setStickySuccess and setSuccess is that setStickySuccess is called to preserve the failure of a test until the next run of the test. Once setStickySuccess is called with false, the success value will remain false from that point on. It can no longer be changed to true even if setSuccess or setStickySuccess is called with true. If a test is run more than once, the "sticky" flag will be reset in ITest:reset so that success can be set to any value in the next run of the test.

Derived classes can call setStickySuccess at anytime, but especially during test to indicate the test's success.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setSuccess
Sets the success state of a test.
protected:
virtual void setSuccess(bool success)
Subclasses call setSuccess at anytime, but especially during test to indicate the test's success. You can call setSuccess more than once. For example, a derived class might call setSuccess(true) in setup, but then call setSuccess(false) in test.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ITest - Enumerations


[view class]
EStage
enum EStage { kNone, 
              kRun, 
              kReset, 
              kSetup, 
              kTest, 
              kCleanup }
Possible exception value settings are:

kNone
Exception did not occur
kRun
Exception in run() but not in any of the following:
kReset
exception in reset()
kSetup
Exception in setup()
kTest
exception in test()
kCleanup
Exception in cleanup()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ITest - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data