#include "lib/test/event-log.hpp"

Description

Helper to log and verify the occurrence of events.

The EventLog object is a front-end handle, logging flexible information records into a possibly shared (vector) buffer in heap storage. An extended query DSL allows to write assertions to cover the occurrence of events in unit tests.

Warning: not threadsafe

See also: EventLog_test

Definition at line 275 of file event-log.hpp.

Public Types
using	ArgSeq = lib::diff::RecordSetup< string >::Storage

using	Iter = lib::RangeIter< Log::const_iterator >

typedef Iter	const_iterator

typedef const Entry	value_type

Public Member Functions
	EventLog (string logID)

	EventLog (CStr logID)

template<class X >
	EventLog (const X *const obj)

string	getID () const

EventLog &	joinInto (EventLog &otherLog)
	Merge this log into another log, forming a combined log.

EventLog &	clear ()
	purge log contents while retaining just the original Header-ID

EventLog &	clear (string alteredLogID)
	purge log contents and also reset Header-ID

EventLog &	clear (CStr alteredLogID)

template<class X >
EventLog &	clear (const X *const obj)

EventLog &	event (string text)
	log some text as event

EventLog &	event (string classifier, string text)
	log some event, with additional ID or classifier

template<typename... ELMS>
EventLog &	event (string classifier, ELMS const &...initialiser)

EventLog &	call (string target, string function)
	Log occurrence of a function call with no arguments.

EventLog &	call (string target, string function, ArgSeq &&args)
	Log a function call with a sequence of stringified arguments.

EventLog &	call (CStr target, CStr function, ArgSeq &&args)

template<typename... ARGS>
EventLog &	call (string target, string function, ARGS const &...args)
	Log a function call with arbitrary arguments.

template<class X , typename... ARGS>
EventLog &	call (const X *const targetObj, string function, ARGS const &...args)
	Log a function call on given object ("`this`")...

template<typename... ARGS>
EventLog &	call (CStr target, string function, ARGS const &...args)

template<typename... ELMS>
EventLog &	note (ELMS const &...initialiser)

EventLog &	warn (string text)
	Log a warning entry.

EventLog &	error (string text)
	Log an error note.

EventLog &	fatal (string text)
	Log a fatal failure.

EventLog &	create (string text)
	Log the creation of an object.

EventLog &	destroy (string text)
	Log the destruction of an object.

template<typename X , typename... ARGS>
EventLog &	addAttrib (string const &key, X &&initialiser, ARGS &&...args)
	Qualify the latest entry: set further attribute(s)

bool	empty () const

const_iterator	begin () const

const_iterator	end () const

EventMatch	verify (string match) const
	start a query to match for some substring.

EventMatch	verifyMatch (string regExp) const
	start a query to match with a regular expression

EventMatch	verifyEvent (string match) const
	start a query to match for some event.

EventMatch	verifyEvent (string classifier, string match) const
	start a query to match for an specific kind of element

template<typename X >
EventMatch	verifyEvent (string classifier, X const &something) const

EventMatch	verifyCall (string match) const
	start a query to match especially a function call

EventMatch	ensureNot (string match) const
	start a query to ensure the given expression does not match.

Friends
const_iterator	begin (EventLog const &log)

const_iterator	end (EventLog const &log)

bool	operator== (EventLog const &l1, EventLog const &l2)
	equality comparison is based on the actual log contents

bool	operator!= (EventLog const &l1, EventLog const &l2)

Private Member Functions
void	log (std::initializer_list< string > const &ili)

template<typename ATTR , typename ARGS >
void	log (Symbol typeID, ATTR &&attribs, ARGS &&args)

Private Attributes
std::shared_ptr< Log >	log_

Constructor & Destructor Documentation

◆ EventLog() [1/3]

EventLog ( string logID )

explicit

Definition at line 604 of file event-log.cpp.

References EventLog::log().

Here is the call graph for this function:

◆ EventLog() [2/3]

EventLog ( CStr logID )

inlineexplicit

Definition at line 301 of file event-log.hpp.

◆ EventLog() [3/3]

template<class X >

EventLog ( const X *const obj )

inlineexplicit

Definition at line 307 of file event-log.hpp.

Member Typedef Documentation

◆ ArgSeq

using ArgSeq = lib::diff::RecordSetup<string>::Storage

Definition at line 347 of file event-log.hpp.

◆ Iter

using Iter = lib::RangeIter<Log::const_iterator>

Definition at line 451 of file event-log.hpp.

◆ const_iterator

typedef Iter const_iterator

Definition at line 453 of file event-log.hpp.

◆ value_type

typedef const Entry value_type

Definition at line 454 of file event-log.hpp.

Member Function Documentation

◆ log() [1/2]

void log ( std::initializer_list< string > const & ili )

inlineprivate

Definition at line 282 of file event-log.hpp.

References EventLog::log_.

Referenced by EventLog::EventLog(), EventLog::call(), EventLog::clear(), EventLog::create(), EventLog::destroy(), EventLog::error(), EventLog::event(), EventLog::event(), EventLog::event(), EventLog::fatal(), EventLog::joinInto(), and EventLog::warn().

Here is the caller graph for this function:

◆ log() [2/2]

template<typename ATTR , typename ARGS >

void log	(	Symbol	typeID,
		ATTR &&	attribs,
		ARGS &&	args
	)

inlineprivate

Definition at line 289 of file event-log.hpp.

References EventLog::log_.

◆ getID()

string getID ( ) const

inline

Returns: logID defined with the ctor to distinguish this log instance

Definition at line 317 of file event-log.hpp.

References EventLog::log_.

Referenced by EventLog::clear(), EventLog::joinInto(), ActivityDetector::DiagnosticFun< RET, ARGS >::operator string(), and ActivityDetector::DiagnosticFun< RET, ARGS >::operator()().

Here is the caller graph for this function:

◆ joinInto()

EventLog & joinInto ( EventLog & otherLog )

Merge this log into another log, forming a combined log.

Parameters

otherLog target to integrate this log's contents into.

Returns: reference to the merged new log instance

See also: EventLog_test::verify_logJoining()

Remarks: EventLog uses a heap based, sharable log storage, where the EventLog object is just a front-end (shared ptr). The joinInto operation both integrates this logs contents into the other log, and then disconnects from the old storage and connects to the storage of the combined log.

Warning: beware of clone copies. Since copying EventLog is always a shallow copy, all copied handles actually refer to the same log storage. If you invoke joinInto in such a situation, only the current EventLog front-end handle will be rewritten to point to the combined log, while any other clone will continue to point to the original log storage.

Definition at line 625 of file event-log.cpp.

References EventLog::getID(), EventLog::log(), and EventLog::log_.

Referenced by TestTracking_test::demonstrate_checkAllocator(), MockElm::joinLog(), MockElm::joinLog(), and EventLog_test::verify_logJoining().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ clear() [1/4]

EventLog & clear ( )

purge log contents while retaining just the original Header-ID

Definition at line 643 of file event-log.cpp.

References EventLog::clear(), and EventLog::getID().

Referenced by EventLog::clear(), EventLog::clear(), EventLog::clear(), ActivityDetector::clear(), TestTracking_test::demonstrate_checkAllocator(), TestTracking_test::demonstrate_logObject(), LateBindInstance_test::verify_forwarding(), and EventLog_test::verify_logPurging().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ clear() [2/4]

EventLog & clear ( string alteredLogID )

purge log contents and also reset Header-ID

Note: actually we're starting a new log and let the previous one go away.

Warning: while this also unties any joined logs, other log front-ends might still hold onto the existing, combined log. Just we are detached and writing to a pristine log.

Definition at line 658 of file event-log.cpp.

References EventLog::log(), and EventLog::log_.

Here is the call graph for this function:

◆ clear() [3/4]

EventLog & clear ( CStr alteredLogID )

Definition at line 666 of file event-log.cpp.

References EventLog::clear().

Here is the call graph for this function:

◆ clear() [4/4]

template<class X >

EventLog & clear ( const X *const obj )

inline

Definition at line 338 of file event-log.hpp.

References EventLog::clear(), and lib::idi::instanceTypeID().

Here is the call graph for this function:

◆ event() [1/3]

EventLog & event ( string text )

log some text as event

Definition at line 676 of file event-log.cpp.

References EventLog::log().

Referenced by MockElm::MockElm(), SimulatedCommandHandler::SimulatedCommandHandler(), MockElm::buildMutator(), TestTracking_test::demonstrate_checkAllocator(), TestTracking_test::demonstrate_logObject(), MockElm::doReset(), ActivityDetector::incrementSeq(), TestMutationTarget::initMutation(), TestMutationTarget::inject(), MockElm::kill(), TestMutationTarget::logAssignment(), TestMutationTarget::logMutation(), TestMutationTarget::logScopeCompletion(), TestMutationTarget::logSkip(), EventLog_test::verify_backwardMatch(), EventLog_test::verify_eventLogging(), LateBindInstance_test::verify_forwarding(), EventLog_test::verify_logJoining(), EventLog_test::verify_negatedMatch(), and EventLog_test::verify_simpleUsage().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ event() [2/3]

EventLog & event	(	string	classifier,
		string	text
	)

log some event, with additional ID or classifier

Parameters

classifier	info to be saved into the `ID` attribute
text	actual payload info, to be logged as argument

Definition at line 683 of file event-log.cpp.

References EventLog::log().

Here is the call graph for this function:

◆ event() [3/3]

template<typename... ELMS>

EventLog & event	(	string	classifier,
		ELMS const &...	initialiser
	)

inline

Definition at line 360 of file event-log.hpp.

References EventLog::log().

Here is the call graph for this function:

◆ call() [1/6]

EventLog & call	(	string	target,
		string	function
	)

Log occurrence of a function call with no arguments.

Parameters

target	the object or scope on which the function is invoked
function	name of the function being invoked

Definition at line 690 of file event-log.cpp.

References EventLog::call().

Referenced by MockElm::MockElm(), SimulatedCommandHandler::SimulatedCommandHandler(), Tracker::Tracker(), Tracker::Tracker(), Tracker::Tracker(), Tracker::Tracker(), MockElm::~MockElm(), Tracker::~Tracker(), ZombieNexus::act(), MockElm::buildMutator(), EventLog::call(), EventLog::call(), EventLog::call(), EventLog::call(), EventLog::call(), ZombieNexus::change(), TrackingFactory::create(), TrackingFactory::dispose(), MockElm::doClearErr(), MockElm::doClearMsg(), MockElm::doErr(), MockElm::doExpand(), MockElm::doFlash(), MockElm::doMark(), MockElm::doMsg(), MockElm::doReset(), MockElm::doReveal(), MockElm::kill(), lib::test::anonymous_namespace{tracking-allocator.cpp}::logAlloc(), ZombieNexus::mark(), ZombieNexus::markAll(), ZombieNexus::note(), PlaceholderCommand< ARGS >::operate(), ActivityDetector::DiagnosticFun< RET, ARGS >::operator()(), Tracker::operator=(), Tracker::operator=(), SimulatedCommandHandler::performExec(), SimulatedCommandHandler::performUndo(), ZombieNexus::routeAdd(), ZombieNexus::routeDetach(), PlaceholderCommand< ARGS >::undo(), EventLog_test::verify_callLogging(), and EventLog_test::verify_eventLogging().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ call() [2/6]

EventLog & call	(	string	target,
		string	function,
		ArgSeq &&	args
	)

Log a function call with a sequence of stringified arguments.

Definition at line 696 of file event-log.cpp.

References EventLog::log().

Here is the call graph for this function:

◆ call() [3/6]

EventLog & call	(	CStr	target,
		CStr	function,
		ArgSeq &&	args
	)

Definition at line 703 of file event-log.cpp.

References EventLog::call().

Here is the call graph for this function:

◆ call() [4/6]

template<typename... ARGS>

EventLog & call	(	string	target,
		string	function,
		ARGS const &...	args
	)

inline

Log a function call with arbitrary arguments.

Definition at line 380 of file event-log.hpp.

References EventLog::call().

Here is the call graph for this function:

◆ call() [5/6]

template<class X , typename... ARGS>

EventLog & call	(	const X *const	targetObj,
		string	function,
		ARGS const &...	args
	)

inline

Log a function call on given object ("`this`")...

Definition at line 388 of file event-log.hpp.

References EventLog::call(), and lib::idi::instanceTypeID().

Here is the call graph for this function:

◆ call() [6/6]

template<typename... ARGS>

EventLog & call	(	CStr	target,
		string	function,
		ARGS const &...	args
	)

inline

Definition at line 395 of file event-log.hpp.

References EventLog::call().

Here is the call graph for this function:

◆ note()

template<typename... ELMS>

EventLog & note ( ELMS const &... initialiser )

inline

Definition at line 402 of file event-log.hpp.

References EventLog::log_.

Referenced by MockElm::doClearErr(), MockElm::doClearMsg(), MockElm::doErr(), MockElm::doFlash(), MockElm::doMark(), MockElm::doMsg(), EventLog_test::verify_genericLogging(), and EventLog_test::verify_regExpMatch().

Here is the caller graph for this function:

◆ warn()

EventLog & warn ( string text )

Log a warning entry.

Definition at line 710 of file event-log.cpp.

References EventLog::log().

Referenced by SimulatedCommandHandler::SimulatedCommandHandler(), TrackingFactory::dispose(), EventLog_test::verify_genericLogging(), and EventLog_test::verify_logPurging().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ error()

EventLog & error ( string text )

Log an error note.

Definition at line 717 of file event-log.cpp.

References EventLog::log().

Referenced by ZombieNexus::act(), ZombieNexus::change(), TrackingFactory::create(), lib::test::anonymous_namespace{tracking-allocator.cpp}::logAlarm(), ZombieNexus::mark(), ZombieNexus::markAll(), ZombieNexus::note(), ZombieNexus::routeAdd(), ZombieNexus::routeDetach(), and EventLog_test::verify_genericLogging().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fatal()

EventLog & fatal ( string text )

Log a fatal failure.

Definition at line 724 of file event-log.cpp.

References EventLog::log().

Referenced by EventLog_test::verify_genericLogging(), and EventLog_test::verify_regExpMatch().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ create()

EventLog & create ( string text )

Log the creation of an object.

Such an entry can be matched as event

Definition at line 733 of file event-log.cpp.

References EventLog::log().

Referenced by MockElm::MockElm(), EventLog_test::verify_genericLogging(), and EventLog_test::verify_logPurging().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ destroy()

EventLog & destroy ( string text )

Log the destruction of an object.

Can be matched as event.

Definition at line 740 of file event-log.cpp.

References EventLog::log().

Referenced by MockElm::~MockElm(), MockElm::kill(), and EventLog_test::verify_genericLogging().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ addAttrib()

template<typename X , typename... ARGS>

EventLog & addAttrib	(	string const &	key,
		X &&	initialiser,
		ARGS &&...	args
	)

inline

Qualify the latest entry: set further attribute(s)

Definition at line 431 of file event-log.hpp.

References EventLog::log_.

Referenced by ActivityDetector::DiagnosticFun< RET, ARGS >::operator()().

Here is the caller graph for this function:

◆ empty()

bool empty ( ) const

inline

Definition at line 445 of file event-log.hpp.

References EventLog::log_.

◆ begin()

const_iterator begin ( ) const

inline

Definition at line 456 of file event-log.hpp.

References EventLog::log_.

◆ end()

const_iterator end ( ) const

inline

Definition at line 457 of file event-log.hpp.

◆ verify()

EventMatch verify ( string match ) const

start a query to match for some substring.

The resulting matcher object will qualify on any log entry containing the given string. By adding subsequent further query expressions on the returned matcher object, the query can be refined. Moreover it is possible to chain up further search queries, which will be executing starting from the position of the previous match. The final result can be retrieved by bool conversion

Definition at line 752 of file event-log.cpp.

References EventMatch::locate(), and EventLog::log_.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ verifyMatch()

EventMatch verifyMatch ( string regExp ) const

start a query to match with a regular expression

Parameters

regExp definition

Remarks: the expression will work against the full string representation of the log entries. Meaning, it can also match type and attributes

Definition at line 761 of file event-log.cpp.

References EventMatch::locateMatch(), and EventLog::log_.

Referenced by EventLog_test::verify_regExpMatch(), TestMutationTarget::verifyMatch(), MockElm::verifyMatch(), Nexus::wasBound(), Nexus::wasInvoked(), and Nexus::wasInvoked().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ verifyEvent() [1/3]

EventMatch verifyEvent ( string match ) const

start a query to match for some event.

Remarks: only a subset of all log entries is treated as "event", any other log entry will not be considered for this query. Besides the regular events, also errors, creation and destruction of objects count as "event".

Parameters

match text to (substring)match against the argument logged as event

Definition at line 770 of file event-log.cpp.

References EventMatch::locateEvent(), and EventLog::log_.

Referenced by BusTerm_test::attachNewBusTerm(), TestTracking_test::demonstrate_checkAllocator(), EventLog_test::verify_eventLogging(), LateBindInstance_test::verify_forwarding(), EventLog_test::verify_genericLogging(), AbstractTangible_test::verify_mockManipulation(), EventLog_test::verify_regExpMatch(), TestMutationTarget::verifyEvent(), MockElm::verifyEvent(), EventLog::verifyEvent(), TestMutationTarget::verifyEvent(), MockElm::verifyEvent(), MockElm::verifyMark(), MockElm::verifyMark(), and ActivityDetector::verifySeqIncrement().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ verifyEvent() [2/3]

EventMatch verifyEvent	(	string	classifier,
		string	match
	)		const

start a query to match for an specific kind of element

Parameters

classifier select kind of event by match on type or ID

Definition at line 779 of file event-log.cpp.

References EventMatch::locateEvent(), and EventLog::log_.

Here is the call graph for this function:

◆ verifyEvent() [3/3]

template<typename X >

EventMatch verifyEvent	(	string	classifier,
		X const &	something
	)		const

inline

Definition at line 501 of file event-log.hpp.

References util::toString(), and EventLog::verifyEvent().

Here is the call graph for this function:

◆ verifyCall()

EventMatch verifyCall ( string match ) const

start a query to match especially a function call

Parameters

match text to match against the function name

Definition at line 788 of file event-log.cpp.

References EventMatch::locateCall(), and EventLog::log_.

Referenced by BusTerm_test::attachNewBusTerm(), BusTerm_test::pushDiff(), EventLog_test::verify_callLogging(), LateBindInstance_test::verify_forwarding(), TestMutationTarget::verifyCall(), MockElm::verifyCall(), and ActivityDetector::verifyInvocation().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ensureNot()

EventMatch ensureNot ( string match ) const

start a query to ensure the given expression does not match.

Remarks: the query expression is built similar to the other queries, but the logic of evaluation is flipped: whenever we find any match the overall result (when evaluating to bool) will be false.

Note: since the chained search involves backtracking, this should perform an exhaustive negation, searching for a possible match until no further search options are left.

Definition at line 805 of file event-log.cpp.

References EventMatch::locate(), EventLog::log_, and EventMatch::look_for_match_.

Referenced by BusTerm_test::attachNewBusTerm(), ActivityDetector::ensureNoInvocation(), TestMutationTarget::ensureNot(), MockElm::ensureNot(), EventLog_test::verify_callLogging(), LateBindInstance_test::verify_forwarding(), EventLog_test::verify_logJoining(), EventLog_test::verify_logPurging(), AbstractTangible_test::verify_mockManipulation(), EventLog_test::verify_negatedMatch(), and EventLog_test::verify_regExpMatch().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ log_

std::shared_ptr<Log> log_

private

Definition at line 278 of file event-log.hpp.

Referenced by EventLog::addAttrib(), EventLog::begin(), EventLog::clear(), EventLog::empty(), EventLog::ensureNot(), EventLog::getID(), EventLog::joinInto(), EventLog::log(), EventLog::log(), EventLog::note(), EventLog::verify(), EventLog::verifyCall(), EventLog::verifyEvent(), EventLog::verifyEvent(), and EventLog::verifyMatch().

Friends And Related Symbol Documentation

◆ begin

const_iterator begin ( EventLog const & log )

friend

Definition at line 459 of file event-log.hpp.

◆ end

const_iterator end ( EventLog const & log )

friend

Definition at line 460 of file event-log.hpp.

◆ operator==

bool operator==	(	EventLog const &	l1,
		EventLog const &	l2
	)

friend

equality comparison is based on the actual log contents

Definition at line 520 of file event-log.hpp.

◆ operator!=

bool operator!=	(	EventLog const &	l1,
		EventLog const &	l2
	)

friend

Definition at line 527 of file event-log.hpp.

Collaboration diagram for EventLog:

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

Description

Public Types

Public Member Functions

Friends

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ EventLog() [1/3]

◆ EventLog() [2/3]

◆ EventLog() [3/3]

Member Typedef Documentation

◆ ArgSeq

◆ Iter

◆ const_iterator

◆ value_type

Member Function Documentation

◆ log() [1/2]

◆ log() [2/2]

◆ getID()

◆ joinInto()

◆ clear() [1/4]

◆ clear() [2/4]

◆ clear() [3/4]

◆ clear() [4/4]

◆ event() [1/3]

◆ event() [2/3]

◆ event() [3/3]

◆ call() [1/6]

◆ call() [2/6]

◆ call() [3/6]

◆ call() [4/6]

◆ call() [5/6]

◆ call() [6/6]

◆ note()

◆ warn()

◆ error()

◆ fatal()

◆ create()

◆ destroy()

◆ addAttrib()

◆ empty()

◆ begin()

◆ end()

◆ verify()

◆ verifyMatch()

◆ verifyEvent() [1/3]

◆ verifyEvent() [2/3]

◆ verifyEvent() [3/3]

◆ verifyCall()

◆ ensureNot()

Member Data Documentation

◆ log_

Friends And Related Symbol Documentation

◆ begin

◆ end

◆ operator==

◆ operator!=