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

~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

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.

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.

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.

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:

  - reset (if run has been called before)
  - setup
  - test (to actually perform the test)
  - cleanup

  Each time run is called, it increments the value returned by runCount.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Execution Results

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

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

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.

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

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.

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

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

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

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

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

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.

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

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

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.

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

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.

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None