TestEvents.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
///
/// \file
/// \author Gerald Fahrnholz
/// 
/// \defgroup GrpTestEvents Using TestEvents
/// @{
/// \ingroup GrpTestUtils 
/// \brief
/// Class TestEvents stores (asynchronous) test events and 
/// supports automatic verification by comparing the actual test events
/// with the expected results.
/// In addition you can also check arbitrary expressions and values
/// 
/// \sa TestEvents.h (File documentation)
/// \sa TestToolBox::TestEvents (class documentation)
/// \sa GrpTestExtensionsForBoost (unit test using boost.Test and TestEvents)
/// 
////////////////////////////////////////////////////////////////////////////////

#pragma once


//************************************************************************
//      P r e c o m p i l e r   I n c l u d e   D i r e c t i v e s
//************************************************************************

#include <string>
#include "TestToolBox/IEventReceiver.h"
#include "TestToolBox/CommonSources/ObjectLock.h"

// Declaration of methods within TestInstanceDll
#ifdef USE_TEST_INSTANCE_DLL
#    include "TestToolBox/TestInstanceDll.h"
#endif

#pragma warning( push )
#pragma warning( disable : 4996 ) // vsprintf declared deprecated

namespace TestToolBox
{
    // forward declarations
    class CheckerForMultipleSequences;

    //---------------------------------------------------------------
    /// \name Macros to call a method and log info about the call to test protocol
    ///
    /// Depending on the number of arguments given to the called method you have to
    /// use TTB_CMD1, TTB_CMD2, TTB_CMD3, ...
    /// \{

    /// Base macro
#define TTB_CMD(method) \
    TestToolBox::TestEvents::Get()->Command (#method); \
    method ();
#define TTB_CMD1(method,p1) \
    TestToolBox::TestEvents::Get()->Command (#method, #p1); \
    method ( p1 );
#define TTB_CMD2(method,p1,p2) \
    TestToolBox::TestEvents::Get()->Command (#method, #p1 " " #p2); \
    method ( p1, p2 );
#define TTB_CMD3(method,p1,p2,p3) \
    TestToolBox::TestEvents::Get()->Command (#method, #p1 " " #p2 " " #p3); \
    method ( p1, p2, p3 );
#define TTB_CMD4(method,p1,p2,p3,p4) \
    TestToolBox::TestEvents::Get()->Command (#method, #p1 " " #p2 " " #p3 " " #p4); \
    method ( p1, p2, p3, p4 );
#define TTB_CMD5(method,p1,p2,p3,p4,p5) \
    TestToolBox::TestEvents::Get()->Command (#method, #p1 " " #p2 " " #p3 " " #p4 " " #p5); \
    method ( p1, p2, p3, p4, p5 );
#define TTB_CMD6(method,p1,p2,p3,p4,p5,p6) \
    TestToolBox::TestEvents::Get()->Command (#method, #p1 " " #p2 " " #p3 " " #p4 " " #p5 " " #p6); \
    method ( p1, p2, p3, p4, p5, p6 );
#define TTB_CMD7(method,p1,p2,p3,p4,p5,p6,p7) \
    TestToolBox::TestEvents::Get()->Command (#method, #p1 " " #p2 " " #p3 " " #p4 " " #p5 " " #p6 " " #p7); \
    method ( p1, p2, p3, p4, p5, p6, p7 );
#define TTB_CMD8(method,p1,p2,p3,p4,p5,p6,p7,p8) \
    TestToolBox::TestEvents::Get()->Command (#method, #p1 " " #p2 " " #p3 " " #p4 " " #p5 " " #p6 " " #p7 " " #p8); \
    method ( p1, p2, p3, p4, p5, p6, p7, p8 );
#define TTB_CMD9(method,p1,p2,p3,p4,p5,p6,p7,p8,p9) \
    TestToolBox::TestEvents::Get()->Command (#method, #p1 " " #p2 " " #p3 " " #p4 " " #p5 " " #p6 " " #p7 " " #p8 " " #p9); \
    method ( p1, p2, p3, p4, p5, p6, p7, p8, p9 );
#define TTB_CMD10(method,p1,p2,p3,p4,p5,p6,p7,p8,p9,p10) \
    TestToolBox::TestEvents::Get()->Command (#method, #p1 " " #p2 " " #p3 " " #p4 " " #p5 " " #p6 " " #p7 " " #p8 " " #p9 " " #p10); \
    method ( p1, p2, p3, p4, p5, p6, p7, p8, p9, p10 );
#define TTB_CMD11(method,p1,p2,p3,p4,p5,p6,p7,p8,p9,p10,p11) \
    TestToolBox::TestEvents::Get()->Command (#method, #p1 " " #p2 " " #p3 " " #p4 " " #p5 " " #p6 " " #p7 " " #p8 " " #p9 " " #p10 " " #p11); \
    method ( p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11 );
#define TTB_CMD12(method,p1,p2,p3,p4,p5,p6,p7,p8,p9,p10,p11,p12) \
    TestToolBox::TestEvents::Get()->Command (#method, #p1 " " #p2 " " #p3 " " #p4 " " #p5 " " #p6 " " #p7 " " #p8 " " #p9 " " #p10 " " #p11 " " #p12); \
    method ( p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11, p12);

    /// \}

    //---------------------------------------------------------------
    /// \name Macro to log the occurance of a relevant test event in stream syntax
    ///
    /// <br>Example TTB_ACT_S("Event occured: x=" << x << " y=" << y);
    /// \{
#define TTB_ACT_S(expression) \
    {\
    std::ostringstream oss; \
    oss << expression; \
    TestToolBox::TestEvents::Get()->Act (oss.str().c_str()); \
}

    /// \}

    //---------------------------------------------------------------
    /// \name Macros to check the recorded test events
    ///
    /// There are macros of several types from which you have to choose depending on the kind of
    /// checks you want to perform. The general syntax is TTB_EXP<checkType>, where
    /// checkType is
    /// - "empty" (e.g. TTB_EXP). To be used when checking for strict sequences for all events,
    ///   the checkmode for these type of macros can also be changed via TestEvents::SetCheckType.
    /// - "_SEQ" (e.g. TTB_EXP_SEQ). To be used when checking for a sequence of events which may be
    ///   overlayed with other events between.
    /// - "_VAR" (e.g. TTB_EXP_VAR). To be used when sequence does not matter at all.
    ///
    /// In the simplest case the argument for a macro is the expected event string containing
    /// all formatted arguments (e.g. "Recorded value=3.14").
    /// For this simple task use one of the macros TTB_EXP, TTB_EXP_SEQ or TTB_EXP_VAR.
    ///
    /// You can also specify some arguments to build the final string analogous to <strong>printf syntax</strong>.
    /// Depending on the number of arguments given to the called method you have to
    /// use TTB_EXP<checkType>1, TTB_EXP<checkType>2, TTB_EXP_<checkType>3, ...
    /// <br>Example: TTB_EXP_SEQ2("Recorded x=%.2f y=%.2f", x,y);
    ///
    /// For using <strong>stream syntax with manipulators</strong> to format the
    /// final event string use macros of the form TTB_EXP<checkType>_S.
    /// <br>Example TTB_EXP_S("Recorded x=" << x << " y=" << y);
    /// \{

#define TTB_EXP_S(expression) \
    {\
    std::ostringstream oss; \
    oss << expression; \
    TestToolBox::TestEvents::Get()->ExpectResult  (__FILE__,__LINE__,oss.str().c_str()); \
}
    /// Base macro
#define TTB_EXP(stringValue)                         TestToolBox::TestEvents::Get()->ExpectResult  (__FILE__,__LINE__,stringValue)
#define TTB_EXP1(formatString,p1)                    TestToolBox::TestEvents::Get()->ExpectResult  (__FILE__,__LINE__,formatString,p1)
#define TTB_EXP2(formatString,p1,p2)                 TestToolBox::TestEvents::Get()->ExpectResult  (__FILE__,__LINE__,formatString,p1,p2)
#define TTB_EXP3(formatString,p1,p2,p3)              TestToolBox::TestEvents::Get()->ExpectResult  (__FILE__,__LINE__,formatString,p1,p2,p3)
#define TTB_EXP4(formatString,p1,p2,p3,p4)           TestToolBox::TestEvents::Get()->ExpectResult  (__FILE__,__LINE__,formatString,p1,p2,p3,p4)
#define TTB_EXP5(formatString,p1,p2,p3,p4,p5)        TestToolBox::TestEvents::Get()->ExpectResult  (__FILE__,__LINE__,formatString,p1,p2,p3,p4,p5)
#define TTB_EXP6(formatString,p1,p2,p3,p4,p5,p6)     TestToolBox::TestEvents::Get()->ExpectResult  (__FILE__,__LINE__,formatString,p1,p2,p3,p4,p5,p6)
#define TTB_EXP7(formatString,p1,p2,p3,p4,p5,p6,p7)  TestToolBox::TestEvents::Get()->ExpectResult  (__FILE__,__LINE__,formatString,p1,p2,p3,p4,p5,p6,p7)

    /// \brief Verify that the specified event value can be found at the current position or behind.
    /// The current position will be set to the position one afterwards of the found event position.
    /// Using this macro instead of \ref TTB_EXP you explicitly allow a variable sequence of test events.
    /// You can use printf-syntax and specify additional arguments by using macros
    /// TTB_EXP_VAR1, TTB_EXP_VAR2
#define TTB_EXP_SEQ_S(expression) \
    {\
    std::ostringstream oss; \
    oss << expression; \
    TestToolBox::TestEvents::Get()->ExpectResultSequential  (__FILE__,__LINE__,oss.str().c_str()); \
}
#define TTB_EXP_SEQ(stringValue)                         TestToolBox::TestEvents::Get()->ExpectResultSequential  (__FILE__,__LINE__,stringValue)
#define TTB_EXP_SEQ1(formatString,p1)                    TestToolBox::TestEvents::Get()->ExpectResultSequential  (__FILE__,__LINE__,formatString,p1)
#define TTB_EXP_SEQ2(formatString,p1,p2)                 TestToolBox::TestEvents::Get()->ExpectResultSequential  (__FILE__,__LINE__,formatString,p1,p2)
#define TTB_EXP_SEQ3(formatString,p1,p2,p3)              TestToolBox::TestEvents::Get()->ExpectResultSequential  (__FILE__,__LINE__,formatString,p1,p2,p3)
#define TTB_EXP_SEQ4(formatString,p1,p2,p3,p4)           TestToolBox::TestEvents::Get()->ExpectResultSequential  (__FILE__,__LINE__,formatString,p1,p2,p3,p4)
#define TTB_EXP_SEQ5(formatString,p1,p2,p3,p4,p5)        TestToolBox::TestEvents::Get()->ExpectResultSequential  (__FILE__,__LINE__,formatString,p1,p2,p3,p4,p5)
#define TTB_EXP_SEQ6(formatString,p1,p2,p3,p4,p5,p6)     TestToolBox::TestEvents::Get()->ExpectResultSequential  (__FILE__,__LINE__,formatString,p1,p2,p3,p4,p5,p6)
#define TTB_EXP_SEQ7(formatString,p1,p2,p3,p4,p5,p6,p7)  TestToolBox::TestEvents::Get()->ExpectResultSequential  (__FILE__,__LINE__,formatString,p1,p2,p3,p4,p5,p6,p7)

    /// \brief Verify that one of the entries stored anywhere within TestEvents has the specified value.
    /// The current position will only be adjusted if the element is found at the current position.
    /// Using this macro instead of \ref TTB_EXP you explicitly allow a variable sequence of test events.
    /// You can use printf-syntax and specify additional arguments by using macros
    /// TTB_EXP_VAR1, TTB_EXP_VAR2
#define TTB_EXP_VAR_S(expression) \
    {\
    std::ostringstream oss; \
    oss << expression; \
    TestToolBox::TestEvents::Get()->ExpectResultVariable  (__FILE__,__LINE__,oss.str().c_str()); \
}
#define TTB_EXP_VAR(stringValue)                         TestToolBox::TestEvents::Get()->ExpectResultVariable  (__FILE__,__LINE__,stringValue)
#define TTB_EXP_VAR1(formatString,p1)                    TestToolBox::TestEvents::Get()->ExpectResultVariable  (__FILE__,__LINE__,formatString,p1)
#define TTB_EXP_VAR2(formatString,p1,p2)                 TestToolBox::TestEvents::Get()->ExpectResultVariable  (__FILE__,__LINE__,formatString,p1,p2)
#define TTB_EXP_VAR3(formatString,p1,p2,p3)              TestToolBox::TestEvents::Get()->ExpectResultVariable  (__FILE__,__LINE__,formatString,p1,p2,p3)
#define TTB_EXP_VAR4(formatString,p1,p2,p3,p4)           TestToolBox::TestEvents::Get()->ExpectResultVariable  (__FILE__,__LINE__,formatString,p1,p2,p3,p4)
#define TTB_EXP_VAR5(formatString,p1,p2,p3,p4,p5)        TestToolBox::TestEvents::Get()->ExpectResultVariable  (__FILE__,__LINE__,formatString,p1,p2,p3,p4,p5)
#define TTB_EXP_VAR6(formatString,p1,p2,p3,p4,p5,p6)     TestToolBox::TestEvents::Get()->ExpectResultVariable  (__FILE__,__LINE__,formatString,p1,p2,p3,p4,p5,p6)
#define TTB_EXP_VAR7(formatString,p1,p2,p3,p4,p5,p6,p7)  TestToolBox::TestEvents::Get()->ExpectResultVariable  (__FILE__,__LINE__,formatString,p1,p2,p3,p4,p5,p6,p7)

    /// \}

    //---------------------------------------------------------------
    /// \name Macros for comparing expressions and values
    ///

#define TTB_CHECK_COND(expression) \
    TestToolBox::TestEvents::Get()->CheckCondition( __FILE__,__LINE__, #expression, expression);

#define TTB_CHECK_EQUAL(left,right) \
    TestToolBox::TestEvents::Get()->CheckEqual( __FILE__,__LINE__, #left, left, #right, right);

#define TTB_CHECK(left, op, right) \
    TestToolBox::TestEvents::Get()->Check(__FILE__,__LINE__,#left,left,#op,op,#right,right);

    /// \}

//---------------------------------------------------------------
/// \name General macros
///

/// Write a (possibly longer) textual message to test protocol
#define TTB_INFO(message)                        TestToolBox::TestEvents::Get()->Info (message)

/// Writes a (short) textual message to test protocol and adds horizontal lines before and after it
#define TTB_SECTION(sectionName)                 TestToolBox::TestEvents::Get()->Section (sectionName)

/// Write an informational message about the stored test events to test protcol
#define TTB_LIST_ALL_STORED_EVENTS()                     TestToolBox::TestEvents::Get()->ListAllStoredEvents  (__FILE__,__LINE__)

/// Explicitly chek in unexpected evetns have been recorded
#define TTB_CHECK_FOR_UNEXPECTED_EVENTS()                TestToolBox::TestEvents::Get()->CheckForUnexpectedEvents  ("explicit check", __FILE__,__LINE__)

/// \brief Check if the event sequences defined by DefineSequence() and subsequent
/// calls to TTB_EXP() match with the sequence of recorded events
#define TTB_CHECK_DEFINED_SEQUENCES() TestToolBox::TestEvents::Get()->CheckDefinedSequences (__FILE__,__LINE__)

/// \}

///\cond do not document

// DEPRECATED MACROS:
// Macros to simplify testing when used together with BOOST_TEST
#define TTB_CHECK_SECTION() \
    BOOST_CHECK((TTB::TestEvents::Get()->CurTestIsStillOk())); \
    TestToolBox::TestEvents::Get()->CheckForUnexpectedEvents  ("explicit check", __FILE__,__LINE__); \
    BOOST_MESSAGE("\n---- TEST_EVENT check section\n"); \
    TestToolBox::TestEvents::Get()->StartNewTestCase("TEST_EVENT next test case");

#define TTB_NEXT_SECTION(infoAboutNextSection) \
    BOOST_CHECK((TTB::TestEvents::Get()->CurTestIsStillOk())); \
    TestToolBox::TestEvents::Get()->CheckForUnexpectedEvents  ("explicit check", __FILE__,__LINE__); \
    BOOST_MESSAGE("\n---- TEST_EVENT next section: " #infoAboutNextSection "\n"); \
    TestToolBox::TestEvents::Get()->StartNewTestCase("TEST_EVENT next test case");


    struct IEventReceiver;
    struct IProtocol;
    class TestEvents;
    class EventPosition;

    ///\endcond do not document

    //-------------------------------------------------------------------------

    /// Mode of checking recorded events
    namespace CheckType
    {
        enum Enum
        {
            /// check type is not set
            eNOT_SET,    

            /// all events are checked for exact order
            eSTRICT,     

            /// the events must follow each other, but it is
            /// allowed that other events may lay between
            eSEQUENTIAL, 

            /// the events must follow each other, but it is
            /// allowed that other events may lay between;
            /// in contrast to eSEQUENTIAL multiple sequences
            /// can be defined in advance before checking the
            /// recorded events if they fulfill all requirements
            /// concerning the sequential orders; this setting is
            /// especially useful when there are identical events
            /// which belong to different sequences and there are
            /// several tries needed to check all possibilities of
            /// attaching an event to any of the exepected orders
            eMULTIPLE_SEQUENCES, 

            /// the events may occur in any order
            eVARIABLE
        };
    }





    //-------------------------------------------------------------------------

    /// Position where a given event was found within the vector of
    /// events
    class EventPosition
    {
    public:
        EventPosition()
            :  m_position (-1)
        {}
        EventPosition (int in_pos)
            :  m_position (in_pos)
        {}
        EventPosition (std::vector<int>::size_type in_sizePos)
            :  m_position (static_cast<int>(in_sizePos))
        {}

        void Reset (void)
        {m_position = -1;}

        operator int() const
        {return m_position;}

        void StorePos (int & out_rPos)
        {out_rPos = m_position;}

        bool IsOk (void)
        {return m_position >= 0;} // i.e. the event was found

    private:
        int m_position;
    };

    //-------------------------------------------------------------------------

    /// \brief This class stores the test events as they occure during test execution.
    /// When verifying the test results only the first error within a test case
    /// is reported. Further errors are ignored.
    ///
    /// \nosubgrouping 
    /// \sa TestEvents.h (File documentation)
    /// \sa GrpTestExtensionsForBoost (unit test using boost.Test and TestEvents)
    /// \sa GrpTestEvents (Usage documentation)
    class TestEvents : public AutoCriticalSection, public IEventReceiver
    {
    private:

        /// \brief Constructor.
        /// Access/create instance via static method Get()
        explicit TestEvents (void);

    public:
        ///\cond
        std::string const S_UNEXPECTED_EVENTS;
        std::string const S_EVENT_NOT_FOUND;
        std::string const S_EXPECTED;
        std::string const S_FOUND;
        std::string const S_SEPARATOR_LINE_1;
        std::string const S_SEPARATOR_LINE_2;

        //*****  Construction and initialization  *****

        // Destructor
        ~TestEvents();

        // Get the pointer to the only instance of this class
#ifdef USE_TEST_INSTANCE_DLL
        static TestEvents* CreateNewInstanceForUsageInDll(void){return new TestEvents;};
        static TestEvents* Get (void)
        {return TTB_GetInstance_TestEvents();}
        static void Cleanup (void)
        {TTB_CleanupInstance_TestEvents();}
#else
        static TestEvents* Get (void)
        {if (!s_pTestEvents) s_pTestEvents = new TestEvents;
        return s_pTestEvents;}
        static TestEvents* s_pTestEvents;
        static void Cleanup (void)
        {delete s_pTestEvents; s_pTestEvents = 0;}
#endif


        void ConnectWithEventReceiver (IEventReceiver* in_pIEventReceiver)
        {m_pIEventReceiver = in_pIEventReceiver;}

        void ConnectWithProtocol (IProtocol* in_pIProtocol)
        {m_pIProtocol = in_pIProtocol;}

        /// Support pretty output format by defining minimum length of logged command name
        /// within protocol file.
        void SetWidthCommandNameInLogFile (int in_width)
        {m_widthCommandNameInLogFile = in_width;}

        ///\endcond


        //---------------------------------------------------------------
        /// \name Support to enable usage as "EventReceiver"
        /// \{

        virtual void EventMsg(
            EventContext, // in_context
            const char*  in_eventDescription)
        {Act(in_eventDescription);}

        /// \}

        //---------------------------------------------------------------
        /// \name Recording and verification of test events
        ///
        /// Methods to be directly called from the test scripts to
        /// control recording and verification of test events.
        /// See also the convenience macros TTB_EXP() which simplify the explicit
        /// call of the member functions.
        ///
        /// <a href="http://www.gerald-fahrnholz.de/sw/display_contents.php?&menu=OFF&file_name=test_verification.htm#checkTestEvents">
        /// Link to more background info about checking of recorded events</a>
        ///
        /// \{

        /// Signal that the given event (= actual result) has occured 
        void Act (const char* in_actualEvent, ...);

        /// Same as Act() for users preferring more self explaining code
        void ActualResult (const char* in_actualEvent, ...);

        /// Same as Act() to support STL
        void Act (std::string const & in_actualEvent)
        {Act(in_actualEvent.c_str());}

        /// \brief Check whether the next stored event at the current check position is identical
        /// to the given event contents.
        ///
        /// Per default the sequence of events is strictly checked. You can change this behaviour
        /// with use of SetCheckType/ResetCheckType to gain the behaviour of methods
        /// TTB_EXP_SEQ/ExpectResultSequential or TTB_EXP_VAR/ExpectResultVariable.
        EventPosition ExpectResult(
            const char* in_fileName,
            const long  in_lineNum,
            const char* in_expectedEvent, ...);

        /// \brief Check whether the given event contents are stored at the current check position
        /// or below. Sequence of events does matter.
        EventPosition ExpectResultSequential(
            const char* in_fileName,
            const long  in_lineNum,
            const char* in_expectedEvent, ...);

        /// \brief Check whether the given event contents are stored somewhere in the remaining
        /// stored events. Sequence of events does not matter.
        EventPosition ExpectResultVariable(
            const char* in_fileName,
            const long  in_lineNum,
            const char* in_expectedEvent, ...);

        /// \brief Check if unexpected events have been recorded.
        ///
        /// Check if all stored events have been expected within the test script
        /// i.e. for all of them ExpectResult() or ExpectResultVariable() should
        /// have been called.
        void CheckForUnexpectedEvents (
            const char* in_context,
            const char* in_fileName = 0,
            const long  in_lineNum  = 0);

        /// \brief Set the current check position to the first event entry from the
        /// beginning which has not yet been verified.
        void ResetCurrentCheckPosition (void);

        /// \brief Set the current check position to the given index value
        void SetCurrentCheckPosition (int in_newPos);

        /// Retrun the current check position within the vector of recorded test events
        int GetCurrentCheckPosition (void);

        /// Write all stored events as informational message
        void ListAllStoredEvents (
            const char* in_fileName = 0,
            const long  in_lineNum  = 0,
            CheckType::Enum in_checkType = CheckType::eNOT_SET);

        /// \brief Clear all stored events
        ///
        /// Motivation: The events may have been written to test output as informational
        /// message (via LogCallsToAct(true) or ListAllStoredEvents()). With a call
        /// to ClearAllStoredEvents() all stored events will simply be cleared - whether
        /// they have been checked or not. No verification will be done.
        void ClearAllStoredEvents (void);

        /// Set mode of checking used within TTB_EXP and ExpectResult().
        void SetCheckType (CheckType::Enum in_mode)
        {m_checkType = in_mode;}

        /// Reset mode of checking used within TTB_EXP and ExpectResult().
        void ResetCheckType (void)
        {m_checkType = CheckType::eNOT_SET;}

        /// Get mode of checking used within TTB_EXP and ExpectResult()
        CheckType::Enum GetCheckType (void)
        {return m_checkType;}

        /// Convert given check mode to textual representation
        std::string GetCheckTypeAsText (CheckType::Enum in_checkType);

        /// \brief Return the position where the event was found during the last call of an
        /// EXP macro. If the event was not found at all -1 is returned. 
        EventPosition GetLastEventPosition (void)
        {return m_positionOfLastEvent;}

        /// \brief  Activate/deactivate detailed logging of test activities as
        /// informational messages (calls to Act()/ActualResult(), TTB_INFO, TTB_CMD)
        ///
        /// Optionally add a prefix to the test events (e.g. "TTB_EXP" leads to
        /// event entry "TTB_EXP(MyEventString);" instead of "MyEventString")
        /// A prefix can be added when writing the test script to enable simply copying
        /// from test output to test script.
        void SetDetailedLog (
            bool in_state,
            std::string const & in_prefixAct = "")
        {m_detailedLog = in_state; m_actLogPrefix = in_prefixAct;}

        /// \}

        //---------------------------------------------------------------
        /// \name Checking of multiple sequences
        ///
        /// \{

        /// \brief Define and select a sequence for which expected events may follow
        /// in the expected order.
        void DefineSequence (std::string const & in_nameSequence);

        /// Define the next expected event for the currently selected sequence
        void StoreExpectedEventWithinSelectedSequence(
            std::string const & in_expectedEvent,
            const char*         in_fileName,
            const long          in_lineNum);

        /// \brief Check if the event sequences defined by DefineSequence() and subsequent
        /// calls to TTB_EXP() match with the sequence of recorded events
        void CheckDefinedSequences (
            const char* in_fileName = 0,
            const long  in_lineNum  = 0);

        /// Log results of checking multiple sequences even when check was successful
        void SetDetailedLogSequences (bool in_detailedLog);

        /// \}


        //---------------------------------------------------------------
        /// \name Check expressions and values
        ///
        /// Methods to be used from test scripts to verify that a 
        /// given value or expression fulfilles the expectations.
        ///
        /// <a href="http://www.gerald-fahrnholz.de/sw/display_contents.php?&menu=OFF&file_name=test_verification.htm#checkExpressions">Link to more background info about checking of expressions and values</a>
        /// \{

        /// \brief Check if the given boolean value or expression is true.
        ///
        /// To automatically insert filename, line number and the textual 
        /// representation for the expression use macro TTB_CHECK_COND.
        bool CheckCondition (
            const char*         in_fileName,
            const long          in_lineNum,
            std::string const & in_expressionAsText,
            bool                in_expressionValue);

        /// \brief Check if the given values or expressions are equal.
        /// 
        /// To automatically insert filename, line number and the textual 
        /// representation for the expressions use macro TTB_CHECK_EQUAL.
        template <typename T>
        bool CheckEqual(
            const char*         in_fileName,
            const long          in_lineNum,
            std::string const & in_leftExpressionAsText,
            T const &           in_leftExpressionValue,
            std::string const & in_rightExpressionAsText,
            T const &           in_rightExpressionValue)
        {
            bool errorFound = (in_leftExpressionValue != in_rightExpressionValue);

            // assume T is a streamable type
            DisplayCheckInfo (
                in_fileName, in_lineNum,
                "CheckEqual", errorFound,
                in_leftExpressionAsText,  ToString(in_leftExpressionValue),
                in_rightExpressionAsText, ToString(in_rightExpressionValue),
                "==", typeid(in_leftExpressionValue).name());

            return errorFound;
        }

        /// \brief Check if the given double values or expressions are equal.
        ///
        /// Template specialization for type double. To automatically insert
        /// filename, line number and the textual representation for the
        /// expressions use macro TTB_CHECK_EQUAL.
        bool CheckEqual(
            const char*         in_fileName,
            const long          in_lineNum,
            std::string const & in_leftExpressionAsText,
            double const &      in_leftExpressionValue,
            std::string const & in_rightExpressionAsText,
            double const &      in_rightExpressionValue);

        /// \brief Check if the given values or expressions fulfill a user defined
        /// compare function (predicate).
        ///
        /// To automatically insert filename, line number and the textual 
        /// representation for the expressions and the compare function
        /// use macro TTB_CHECK.
        template <typename T, typename CompareOp>
        bool Check(
            const char*         in_fileName,
            const long          in_lineNum,
            std::string const & in_leftExpressionAsText,
            T const &           in_leftExpressionValue,
            std::string const & in_compareOpAsText,
            CompareOp &         in_compareOp,
            std::string const & in_rightExpressionAsText,
            T const &           in_rightExpressionValue)
        {
            // Check with user defined compare function
            bool errorFound = !in_compareOp(
                in_leftExpressionValue,in_rightExpressionValue);

            // assume T is a streamable type
            DisplayCheckInfo (
                in_fileName, in_lineNum,
                "Check", errorFound,
                in_leftExpressionAsText,  ToString(in_leftExpressionValue),
                in_rightExpressionAsText, ToString(in_rightExpressionValue),
                in_compareOpAsText, typeid(in_leftExpressionValue).name());

            return errorFound;
        }

        /// \brief Set the precision for comparing and logging double values
        /// via TTB_CHECK_EQUAL
        void SetDoublePrecision (int in_precision)
        {m_doublePrecision = in_precision;}

        /// \brief Get the current precision for comparing and logging double values
        /// via TTB_CHECK_EQUAL
        int GetDoublePrecision (void)
        {return m_doublePrecision;}


        /// \brief Activate or deactivate logging of successfully checked values to
        /// protocol file
        void SetDetailedCheckLog (bool in_detailedLog)
        {m_detailedCheckLog = in_detailedLog;}

        /// \}

        //---------------------------------------------------------------
        /// \name General control of test
        /// \{

        /// \brief A new test case is started.
        /// If an error within preceeding test case has disabled verification
        /// it will be reactivated for the new test case.
        void StartNewTestCase (
            const std::string& in_rDescTestCase);

        /// \brief Write given textual information about a method call to test output / protocol
        void Command (
            std::string const & in_cmd,
            std::string const & in_params = "");

        /// \brief Write given textual information to test output / protocol
        void Info (
            std::string const & in_info);

        /// \brief Write given textual information about a new section within your test case to test output.
        /// Used for better structuring test output.
        void Section (
            std::string const & in_sectionName);

        /// \brief Generate an error for the current test case and write info to protocol and
        /// standard out stream.
        void GenerateErrorMessage (
            const char*         in_fileName,
            const long          in_lineNum,
            std::string const & in_errorInfo);

        /// \brief Unexpected remaining events of the current test case are reported
        /// in out_rResult and signalled by a return value of false.
        bool CheckForUnexpectedEvents (
            std::string& out_rResult);

        /// List all events in the same sequence as they have been generated
        void ListAllStoredEvents (
            std::string&       out_rListOfEvents);

        /// Adds a test event entry
        void AddTestEvent (
            const std::string& in_rEvent);

        /// Checks if the given test event (= expected result) has been found at current position.
        EventPosition CheckForTestEvent(
            const std::string& in_rEvent,
            std::string&       out_rResult1,
            std::string&       out_rResult2);

        /// Checks if the given test event (= expected result) has been found at current position
        /// or below. The current position is changed to one past the found entry
        EventPosition CheckForTestEventSequential(
            const std::string& in_rEvent,
            std::string&       out_rResult1,
            std::string&       out_rResult2);

        /// \brief Checks if the given test event (= expected result) has been found on any position
        /// following the current position.
        EventPosition CheckForTestEventVariable(
            const std::string& in_rEvent,
            std::string&       out_rResult1,
            std::string&       out_rResult2);

        /// Check if all tests have succeeded (i.e. no errors were found)
        bool AllTestsHaveSucceeded (void)
        {return m_numFailedTests == 0;}

        /// Get total result data of the whole test.
        bool GetTestResult (
            long&        out_rNumPerformedTests,
            long&        out_rNumFailedTests,
            std::string& out_rDescFirstFailedTest,
            std::string& out_rDescError);

        /// Check whether the current test case is still without errors
        bool CurTestIsStillOk (void)
        {return m_curTestStillOk;}

        /// Get the description of the current test
        std::string GetDescCurTest (void)
       {return m_descCurrentTest;}

        /// Reset for a new test sequence
        void Reset (void);

        /// \}

    private:

        /// Information about the first error which was detected
        struct FirstError
        {
            bool        m_exists;
            long        m_idxFirstFailedTest;
            std::string m_descFirstFailedTest;
            std::string m_descError;
            FirstError() : m_exists (false), m_idxFirstFailedTest(0){}
        };

        /// Information about the first error within the current test
        FirstError m_firstError;

        /// \brief Vector containing all test events to check for
        /// Each test event is represented by a textual line containing
        /// arbitrary information (e.g. function results, function names)
        /// and a flag indicating if the entry has already been marked
        /// as expected.
        typedef std::vector<std::pair <bool, std::string> > Events;

        /// Vector of stored (textual) test events
        Events m_events;

        /// The position within vector of recorded events to check as next.    
        Events::size_type m_curCheckPos;

        /// \brief Position where the event was found during the last call of an EXP macro.
        /// If the event was not found at all -1 is returned.
        EventPosition m_positionOfLastEvent;

        /// prefix to be added to output string when logging Act() events
        std::string m_actLogPrefix;

        /// \brief Flag indicating if the check functionality is active.
        /// If set to false, all calls to CheckFor... are ignored.
        bool m_active;

        /// \brief Flag indicating whether the check for unexpected events shall be performed
        /// The check is performed only once (i.e. the flag is set to false after the
        /// check has executed)
        bool m_checkForUnexpected;

        /// \brief Flag indicating whether calls to Act/ActualResult() shall be written
        /// as info to the environment specific output stream.
        /// Motivation: analysis of error situations
        bool m_detailedLog;

        /// \brief Flag indicating whether calls to TTB_CHECK macros shall be written
        /// to test protocol
        bool m_detailedCheckLog;

        /// Current check mode used within TTB_EXP / ExpectResult()
        CheckType::Enum m_checkType;

        /// \brief Precision for double values when they are written to protocol or compared to
        /// each other within TTB_CHECK_EQUAL
        int m_doublePrecision;

        /// Flag indicating if the current test case is still ok.
        bool m_curTestStillOk;

        /// Number of all tests
        long m_numPerformedTests;

        /// Number of failed tests
        long m_numFailedTests;

        /// Description of the current test case
        std::string m_descCurrentTest;

        /// \brief Minimum width of the method name when written to protocol using macro TTB_CMD().
        /// Used for improving readability of test protocols
        int m_widthCommandNameInLogFile;

        /// Interface for processing all important test situations (e.g. detected error situations)
        IEventReceiver* m_pIEventReceiver;

        /// Interface to test protocol
        IProtocol* m_pIProtocol;

        /// Internal impl class supporting complex checks for
        CheckerForMultipleSequences* m_pCheckerForMultipleSequences;

        friend class EventPosition;

    private:

        ///\cond do not document

        /// \brief Increment current position within array of events until the next
        /// entry to be checked is reached. If there are no unchecked entries the
        /// position is set to size of vector.
        void IncrementCurPos (void);

        // \brief Store the given error description.
        // If there is already an description stored the new one
        // will be ignored.
        void StoreError (
            const std::string& in_rErrStr1,
            const std::string& in_rErrStr2);

        /// \brief Check if the given result could be found within
        /// the vector of recorded events. The given check type specifies
        /// the allowed position of the searched event.
        EventPosition TestEvents::ExpectResultInternal(
            const char*     in_fileName,
            const long      in_lineNum,
            const char*     in_formattedResult,
            CheckType::Enum in_checkType);

        /// Display info about a checked expression or value
        void DisplayCheckInfo (
            const char*         in_fileName,
            const long          in_lineNum,
            std::string const & in_checkType,
            bool                in_checkFailed,
            std::string const & in_paramLeftAsText,
            std::string const & in_paramValLeftAsText,
            std::string const & in_paramRightAsText = "",
            std::string const & in_paramValRightAsText = "",
            std::string const & in_compareOpAsText = "",
            std::string const & in_paramTypeAsText = "");

       void WriteEventEntry (
            int in_idxEvent,
            std::ostringstream & io_stream,
            std::string const & in_prefix = "");

        friend class CheckerForMultipleSequences;

        ///\endcond

    }; // class TestEvents


    ///\cond do not document
    // Use static member only when running without TestInstanceDLL
#ifndef USE_TEST_INSTANCE_DLL
    __declspec(selectany) TestEvents* TestEvents::s_pTestEvents = 0;
#endif
    ///\endcond

    //************************************************************************
    //************************************************************************

    /// Free function to get access to the singleton instance of class TestEvents
    static TestEvents* TheTestEvents (void)
    {return TestEvents::Get();}

}; // namespace TestToolBox


#pragma warning( pop )

/// @} // endGrpTestEvents

---