TestToolBox::TestEvents Class Reference

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

#include <TestEvents.h>

Inheritance diagram for TestToolBox::TestEvents:

[legend]

Collaboration diagram for TestToolBox::TestEvents:

[legend]

List of all members.

Classes
struct	FirstError
	Information about the first error which was detected. More...
Private Types
typedef std::vector< std::pair < bool, std::string > >	Events
	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.
Private Member Functions
	TestEvents (void)
	Constructor. Access/create instance via static method Get().
Private Attributes
FirstError	m_firstError
	Information about the first error within the current test.
Events	m_events
	Vector of stored (textual) test events.
Events::size_type	m_curCheckPos
	The position within vector of recorded events to check as next.
EventPosition	m_positionOfLastEvent
	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.
std::string	m_actLogPrefix
	prefix to be added to output string when logging Act() events
bool	m_active
	Flag indicating if the check functionality is active. If set to false, all calls to CheckFor... are ignored.
bool	m_checkForUnexpected
	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_detailedLog
	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_detailedCheckLog
	Flag indicating whether calls to TTB_CHECK macros shall be written to test protocol.
CheckType::Enum	m_checkType
	Current check mode used within TTB_EXP / ExpectResult().
int	m_doublePrecision
	Precision for double values when they are written to protocol or compared to each other within TTB_CHECK_EQUAL.
bool	m_curTestStillOk
	Flag indicating if the current test case is still ok.
long	m_numPerformedTests
	Number of all tests.
long	m_numFailedTests
	Number of failed tests.
std::string	m_descCurrentTest
	Description of the current test case.
int	m_widthCommandNameInLogFile
	Minimum width of the method name when written to protocol using macro TTB_CMD(). Used for improving readability of test protocols.
IEventReceiver *	m_pIEventReceiver
	Interface for processing all important test situations (e.g. detected error situations).
IProtocol *	m_pIProtocol
	Interface to test protocol.
CheckerForMultipleSequences *	m_pCheckerForMultipleSequences
	Internal impl class supporting complex checks for.
Friends
class	EventPosition
Support to enable usage as "EventReceiver"
virtual void	EventMsg (EventContext, const char *in_eventDescription)
	Signal actual event as occured during test execution.
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. Link to more background info about checking of recorded events
void	Act (const char *in_actualEvent,...)
	Signal that the given event (= actual result) has occured.
void	ActualResult (const char *in_actualEvent,...)
	Same as Act() for users preferring more self explaining code.
void	Act (std::string const &in_actualEvent)
	Same as Act() to support STL.
EventPosition	ExpectResult (const char *in_fileName, const long in_lineNum, const char *in_expectedEvent,...)
	Check whether the next stored event at the current check position is identical to the given event contents.
EventPosition	ExpectResultSequential (const char *in_fileName, const long in_lineNum, const char *in_expectedEvent,...)
	Check whether the given event contents are stored at the current check position or below. Sequence of events does matter.
EventPosition	ExpectResultVariable (const char *in_fileName, const long in_lineNum, const char *in_expectedEvent,...)
	Check whether the given event contents are stored somewhere in the remaining stored events. Sequence of events does not matter.
void	CheckForUnexpectedEvents (const char *in_context, const char *in_fileName=0, const long in_lineNum=0)
	Check if unexpected events have been recorded.
void	ResetCurrentCheckPosition (void)
	Set the current check position to the first event entry from the beginning which has not yet been verified.
void	SetCurrentCheckPosition (int in_newPos)
	Set the current check position to the given index value.
int	GetCurrentCheckPosition (void)
	Retrun the current check position within the vector of recorded test events.
void	ListAllStoredEvents (const char *in_fileName=0, const long in_lineNum=0, CheckType::Enum in_checkType=CheckType::eNOT_SET)
	Write all stored events as informational message.
void	ClearAllStoredEvents (void)
	Clear all stored events.
void	SetCheckType (CheckType::Enum in_mode)
	Set mode of checking used within TTB_EXP and ExpectResult().
void	ResetCheckType (void)
	Reset mode of checking used within TTB_EXP and ExpectResult().
CheckType::Enum	GetCheckType (void)
	Get mode of checking used within TTB_EXP and ExpectResult().
std::string	GetCheckTypeAsText (CheckType::Enum in_checkType)
	Convert given check mode to textual representation.
EventPosition	GetLastEventPosition (void)
	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.
void	SetDetailedLog (bool in_state, std::string const &in_prefixAct="")
	Activate/deactivate detailed logging of test activities as informational messages (calls to Act()/ActualResult(), TTB_INFO, TTB_CMD).
Checking of multiple sequences
void	DefineSequence (std::string const &in_nameSequence)
	Define and select a sequence for which expected events may follow in the expected order.
void	StoreExpectedEventWithinSelectedSequence (std::string const &in_expectedEvent, const char *in_fileName, const long in_lineNum)
	Define the next expected event for the currently selected sequence.
void	CheckDefinedSequences (const char *in_fileName=0, const long in_lineNum=0)
	Check if the event sequences defined by DefineSequence() and subsequent calls to TTB_EXP() match with the sequence of recorded events.
void	SetDetailedLogSequences (bool in_detailedLog)
	Log results of checking multiple sequences even when check was successful.
Check expressions and values
Methods to be used from test scripts to verify that a given value or expression fulfilles the expectations. Link to more background info about checking of expressions and values
bool	CheckCondition (const char *in_fileName, const long in_lineNum, std::string const &in_expressionAsText, bool in_expressionValue)
	Check if the given boolean value or expression is true.
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)
	Check if the given values or expressions are 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)
	Check if the given double values or expressions are equal.
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 if the given values or expressions fulfill a user defined compare function (predicate).
void	SetDoublePrecision (int in_precision)
	Set the precision for comparing and logging double values via TTB_CHECK_EQUAL.
int	GetDoublePrecision (void)
	Get the current precision for comparing and logging double values via TTB_CHECK_EQUAL.
void	SetDetailedCheckLog (bool in_detailedLog)
	Activate or deactivate logging of successfully checked values to protocol file.
General control of test
void	StartNewTestCase (const std::string &in_rDescTestCase)
	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	Command (std::string const &in_cmd, std::string const &in_params="")
	Write given textual information about a method call to test output / protocol.
void	Info (std::string const &in_info)
	Write given textual information to test output / protocol.
void	Section (std::string const &in_sectionName)
	Write given textual information about a new section within your test case to test output. Used for better structuring test output.
void	GenerateErrorMessage (const char *in_fileName, const long in_lineNum, std::string const &in_errorInfo)
	Generate an error for the current test case and write info to protocol and standard out stream.
bool	CheckForUnexpectedEvents (std::string &out_rResult)
	Unexpected remaining events of the current test case are reported in out_rResult and signalled by a return value of false.
void	ListAllStoredEvents (std::string &out_rListOfEvents)
	List all events in the same sequence as they have been generated.
void	AddTestEvent (const std::string &in_rEvent)
	Adds a test event entry.
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.
EventPosition	CheckForTestEventSequential (const std::string &in_rEvent, std::string &out_rResult1, std::string &out_rResult2)
EventPosition	CheckForTestEventVariable (const std::string &in_rEvent, std::string &out_rResult1, std::string &out_rResult2)
	Checks if the given test event (= expected result) has been found on any position following the current position.
bool	AllTestsHaveSucceeded (void)
	Check if all tests have succeeded (i.e. no errors were found).
bool	GetTestResult (long &out_rNumPerformedTests, long &out_rNumFailedTests, std::string &out_rDescFirstFailedTest, std::string &out_rDescError)
	Get total result data of the whole test.
bool	CurTestIsStillOk (void)
	Check whether the current test case is still without errors.
std::string	GetDescCurTest (void)
	Get the description of the current test.
void	Reset (void)
	Reset for a new test sequence.

---

Detailed Description

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.

See also:

TestEvents.h (File documentation)

GrpTestExtensionsForBoost (unit test using boost.Test and TestEvents)

Using TestEvents (Usage documentation)

---

Member Function Documentation

EventPosition TestToolBox::TestEvents::ExpectResult	(	const char *	in_fileName,
		const long	in_lineNum,
		const char *	in_expectedEvent,
			...
	)

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.

void TestToolBox::TestEvents::CheckForUnexpectedEvents	(	const char *	in_context,
		const char *	in_fileName = 0,
		const long	in_lineNum = 0
	)

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 TestToolBox::TestEvents::ClearAllStoredEvents

(

void

)

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 TestToolBox::TestEvents::SetDetailedLog	(	bool	in_state,
		std::string const &	in_prefixAct = ""
	)			[inline]

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.

bool TestToolBox::TestEvents::CheckCondition	(	const char *	in_fileName,
		const long	in_lineNum,
		std::string const &	in_expressionAsText,
		bool	in_expressionValue
	)

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.

template<typename T >

bool TestToolBox::TestEvents::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
	)			[inline]

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.

bool TestToolBox::TestEvents::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
	)

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.

template<typename T , typename CompareOp >

bool TestToolBox::TestEvents::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
	)			[inline]

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.

EventPosition TestToolBox::TestEvents::CheckForTestEventSequential	(	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

---

The documentation for this class was generated from the following file:

• TestEvents.h