Declaration: Test.h
Taxonomy Categories:
Member Functions:
Interface Category:
Developer Tool Programmer Interface.
Inherits From:
MCollectible, TAbstractTest
Inherited By:
TBaseComparisonTest
TTestCollection
TTestMultiplexer
TTimingTest
Purpose:
The core of the Test framework. It is an abstract base class that defines the protocol for test running behavior. In addition, it provides a large body of useful testing functionality including functions for managing input to the test, diagnostic output text, and test metainformation.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
This class is a framework class. To use it, derive it and override the Test function, and optionally the associated framework functions: Reset, Setup, and Cleanup.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
virtual ~ TTest ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::operator=
TTest & operator =(const TTest & test)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Assignment operator.
Calling Context:
Called when an object is assigned to another compatible object.
Parameters:
- const TTest & test -The right-hand side object.
Return Value:
A non-const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::Hash
virtual long Hash () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the hash value for the test.
Calling Context:
Called by Test framework and directly.
Parameters:
Return Value:
Returns the hash value for the test.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::operator<<=
virtual TStream & operator <<= (TStream & fromWhere)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Stream-in operator.
Calling Context:
Called to stream in data.
Parameters:
- TStream & fromWhere -The stream the object is streamed in from.
Return Value:
Returns a reference to the stream the object streams itself in from.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::operator>>=
virtual TStream & operator >>=(TStream & toWhere) const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Stream-out operator.
Calling Context:
Called to stream out data.
Parameters:
- TStream & toWhere -The stream the object is streamed out to.
Return Value:
Returns a reference to the stream the object streams itself out to.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::SetTarget
void SetTarget (void * target)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Sets the object being tested to the given target.
Calling Context:
Called by RunTest and directly.
Parameters:
- void * target -The target to be set.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::GetTarget
void * GetTarget () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Gets the target being tested.
Calling Context:
Called by Test framework and directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::SetInputs
void SetInputs (const TSequenceOf < TText > & textsFromWhere)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Sets the inputs for the test. Takes the inputs as a sequence of TText arguments.
Calling Context:
Called by RunTest and directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::CopyInputs
void CopyInputs (TSequenceOf < TText > & textsToWhere) const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Copies the inputs of the test to the given sequence.
Calling Context:
Call this function directly.
Parameters:
- TSequenceOf < TText > & textsToWhere -The sequence where the arguments are copied.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The caller owns the TText objects or string array. Derived classes should not override CopyInputs.
Member Function: TTest::CreateNewInputIterator
TIteratorOver < TText > * CreateNewInputIterator () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns an iterator over the input TText objects.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns an iterator over the input TText objects.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::IsInteractive
bool IsInteractive () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns a flag indicating whether interactive testing is enabled.
Calling Context:
Called by Test framework and directly.
Parameters:
Return Value:
Returns true if interactive testing is enabled.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Derived classes should refer to this flag to determine if interactive operations are permitted.
Member Function: TTest::SetInteractive
void SetInteractive (bool interactive)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Sets a flag indicating whether interactive testing is enabled.
Calling Context:
Called by Test framework and directly.
Parameters:
- bool interactive -A flag indicating whether interactive testing is enabled.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Derived classes should refer to this flag to determine if interactive operations are permitted.
Member Function: TTest::Run
virtual void Run ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
The public means of telling the test to execute itself. Run calls Test to actually perform the test. Run also calls the framework functions Reset (if Run has been called before), Setup, Test, and Cleanup.
Calling Context:
Called by RunTest.
Parameters:
Return Value:
None.
Exceptions:
Any exceptions during a function before Cleanup are caught and cause remaining functions to be skipped. Exceptions thrown during Cleanup are caught separately. Exceptions are not passed through to the caller.
Concurrency:
Not multithread safe.
Other Considerations:
Derived classes should not override Run.
Member Function: TTest::GetSuccess
bool GetSuccess () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the success of the last Run for the test.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if the test ran successfully.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::OutputTextStream
TTieredTextBuffer & OutputTextStream ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns a reference to the TTieredTextBuffer object used by this test. Derived classes can use the returned reference transparently to produce textual output.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns a reference to a TTieredTextBuffer object for the test.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::SetOutputTextBuffer
void SetOutputTextBuffer (const TTieredTextBuffer &)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Sets the TTieredTextBuffer object used by this test to the given output buffer.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::GetOutputTextBuffer
void GetOutputTextBuffer (TTieredTextBuffer &) const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns a copy of the TTieredTextBuffer object used by this test.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::IsSaveBufferedData
bool IsSaveBufferedData () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns true if SetSaveBufferedData is set; else false.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if SetSaveBufferedData() has been called with true; else false.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::SetSaveBufferedData
void SetSaveBufferedData (bool saveData =true)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
To turn on of turn off saving of buffered test data.
Calling Context:
Call this function directly.
Parameters:
- bool saveData =true -The default.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::GetExceptionStage
virtual EStage GetExceptionStage () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the stage in which an exception, if any, occurred during the last Run.
Calling Context:
Called by Test framework and directly.
Parameters:
Return Value:
Returns the stage in which an exception occurred.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::CreateException
virtual TStandardException* CreateException () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
If the last call to Run generated an exception, CreateException returns a copy of the exception that was thrown. CreateException only returns exceptions generated during Run, Reset, Setup, or Test.
Calling Context:
Call this function directly.
Parameters:
Return Value:
If the last call to Run generated an exception, returns copy of the exception that was thrown. Otherwise, NIL is returned.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The caller owns storage of the exception that is returned.
Member Function: TTest::CreateCleanupException
virtual TStandardException* CreateCleanupException () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
If the last call to Run generated an exception during the call to Cleanup, CreateCleanupException returns a copy of the exception that was thrown. CreateCleanupException only returns exceptions generated during Cleanup.
Calling Context:
Call this function directly.
Parameters:
Return Value:
If the last call to Run generated an exception, returns copy of the exception that was thrown. Otherwise, NIL is returned.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The caller owns storage of the exception that is returned.
Member Function: TTest::GetStartTime
virtual const TTime & GetStartTime () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the time at which the Test function was called.
Calling Context:
Called by Test framework and directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::GetStopTime
virtual const TTime & GetStopTime () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the time at which the Test function completed.
Calling Context:
Called by Test framework and directly.
Parameters:
Return Value:
Returns the time at which the Test function completed.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::GetElapsedTime
virtual TTime GetElapsedTime () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the time elapsed since Test was first called, if the Run function has not completed yet. Otherwise, it returns the difference between the stop and the start time.
Calling Context:
Called by Test framework and directly.
Parameters:
Return Value:
Returns the time elapsed since Test was first called, if the Run function has not completed yet. Otherwise, it returns the difference between the stop and the start time.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::GetRunCount
virtual unsigned long GetRunCount () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns the number of times that Run has been called since this object was created.
Calling Context:
Called by Test framework and directly.
Parameters:
Return Value:
Returns the number of times that Run has been called since this object was created.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::CopyInfo
virtual void CopyInfo (TDictionaryOf<TStandardText,TText>& infoDict) const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
A framework function to be overridden by derived classes. Derived classes should add key-value pairs for their derived class to infoDictionary by calling the TDictionaryOf::AddKeyValuePair.
Calling Context:
Called by Test framework and directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
In your derived class implementation, be sure to call the CopyInfo function of your immediate base class first. Then add the key-value pairs for your derived class. The key and the value should both be TSimpleText objects on the heap. Callers own the objects returned in infoDict.
Member Function: TTest::LookupInfo
virtual bool LookupInfo (const TStandardText & key, TText & info) const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Lookup Info looks for the information corresponding to the given key. If found, it copies the information into info and returns true. Otherwise, LookupInfo leaves info untouched and returns false.
Calling Context:
Call this function directly.
Parameters:
- const TStandardText & key -The key to be looked up.
- TText & info -The value found in the dictionary for the given key.
Return Value:
Returns true if the key is found in the dictionary.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Derived classes should not override LookupInfo.
Member Function: TTest::CreateTest
- static TTest * CreateTest (const TText & commandLine)
- static TTest * CreateTest (const TSequenceOf < TText > & commandArgs)
- static TTest * CreateTest (TTextArgumentDictionary &, const TSequenceOf < TText > & testArguments)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
- Instantiates the test given command line arguments.
- Instantiates the test given a sequence of command arguments.
- Instantiates the test given the TTextArgumentDictionary with parsed arguments and a separate sequence of arguments for the test.
Calling Context:
- Called by Test framework.
- Called by Test framework.
- Called by Test framework.
Parameters:
Return Value:
Returns a TTest object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
- TTest ()
- TTest (const TTest & test)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
- Default constructor.
- Copy constructor.
Calling Context:
- Called by the stream-in operators.
- Called to copy an object.
Parameters:
- Takes no parameters.
- const TTest & test -The test object to be copied.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::Reset
virtual void Reset ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Reset only applies to tests that can be run more than once. Such tests perform necessary reinitialization operations in the Reset function, which TTest::Run calls before running a test after it has already been run.
Calling Context:
Called by Test framework.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Reset is a framework function that derived classes override. Overriding functions should call the inherited function first.
Member Function: TTest::Setup
virtual void Setup ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
A framework function that derived classes override to do whatever setup work the test needs. Derived classes can override Setup to perform any appropriate initialization before Test is called.
Calling Context:
Called by Test framework.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::Test
virtual void Test ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
A framework function that derived classes override to actually perform the test. The TTest function that derived classes are required to call is SetSuccess or SetStickySuccess inside Test.
Calling Context:
Called by Test framework.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Derived classes must override this function, even if they do not override any of the other functions (for example, Setup, Reset, Cleanup).
Member Function: TTest::Cleanup
virtual void Cleanup ()
Interface Category:
Developer Tool Programmer Interface.
Purpose:
A framework function that derived classes override to restore the system to its previous state. Any actions with Setup that need to be undone should be undone here.
Calling Context:
Called by Test framework.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::Print
virtual void Print (TTieredTextBuffer &)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
A framework function that derived classes can override to customize the way a test prints via operator<<(TTieredTextBuffer, TTest).
Calling Context:
Called by Test framework.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
In your derived class implementation, be sure to call the Print function of your immediate base class first. Then, output your own information with a final carriage return.
Member Function: TTest::SetSuccess
virtual void SetSuccess (bool success)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Derived classes call SetSuccess at anytime, but particularly during Test, to indicate the test's success.
Calling Context:
Call this function directly.
Parameters:
- bool success -A flag indicating whether the test succeeded.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::SetStickySuccess
virtual void SetStickySuccess (bool success)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Derived classes call SetStickySuccess at anytime, but particularly during Test, to indicate the test's success. The difference between SetStickySuccess and SetSuccess is that SetStickySuccess is called to preserve the failure of a test. Once SetStickySuccess is called with false, the success value remains 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 is reset in TTest::Reset so that the success can be set to any value in the next run of the test.
Calling Context:
Call this function directly.
Parameters:
- bool success -A flag indicating whether the test succeeded.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::IsSuccessUndecided
virtual bool IsSuccessUndecided () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns a Boolean indicating whether SetSuccess or SetStickySuccess has been called.
Calling Context:
Called by Test framework and directly.
Parameters:
Return Value:
Returns true if SetSuccess or SetStickySuccess has been called.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::IsReset
virtual bool IsReset () const
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Returns a flag indicating whether the test is in a reset state.
Calling Context:
Called by Test framework.
Parameters:
Return Value:
Returns true if the test is in a reset state.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TTest::HandleException
virtual void HandleException (const TStandardException & theException)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Handles exceptions generated by the Run function anywhere except during the Cleanup function. The TTest implementation of HandleException makes a copy of theException.
Calling Context:
Called by Test framework.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Derived classes that override HandleException should call the inherited version. Derived classes can override HandleException to be notified when an exception occurs in any part of a test except Cleanup, or to repair a test after an exception so that it can be streamed to the log.
Member Function: TTest::HandleCleanupException
virtual void HandleCleanupException (const TStandardException & theException)
Interface Category:
Developer Tool Programmer Interface.
Purpose:
Handles exceptions generated by the Run function during a call to the Cleanup function. The TTest implementation of HandleException makes a copy of theException.
Calling Context:
Called by Test framework.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.