#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

typedef Iter	const_iterator

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

typedef const Entry	value_type

Public Member Functions
	EventLog (string logID)

	EventLog (const char *logID)

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

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

const_iterator	begin () const

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

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

EventLog &	call (const char target, const char 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`")... More...

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

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

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

EventLog &	clear (const char *alteredLogID)

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

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

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

bool	empty () const

const_iterator	end () const

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

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

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

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

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

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

string	getID () const

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

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

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

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

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

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

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

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

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

Friends
const_iterator	begin (EventLog const &log)

const_iterator	end (EventLog const &log)

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

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

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_

Member Function Documentation

◆ 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 lib::idi::instanceTypeID().

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

Here is the call graph for this function:

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.

Referenced by EventLog_test::verify_logJoining(), and MockElm::verifyMark().

Here is the caller graph for this function:

◆ clear()

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.

◆ event()

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.

◆ call() [1/2]

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.

Referenced by MockElm::buildMutator(), TrackingFactory::create(), TrackingFactory::dispose(), MockElm::doExpand(), MockElm::doMark(), MockElm::doReveal(), MockElm::kill(), PlaceholderCommand< ARGS >::operate(), ActivityDetector::DiagnosticFun< RET, ARGS >::operator()(), and MockElm::~MockElm().

Here is the caller graph for this function:

◆ call() [2/2]

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 lib::idi::instanceTypeID().

Here is the call 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.

Referenced by MockElm::buildMutator().

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.

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

Here is the caller graph for this function:

◆ 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().

Referenced by BusTerm_test::attachNewBusTerm(), EventLog_test::verify_logJoining(), and MockElm::verifyMark().

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().

Referenced by Nexus::wasBound(), and Nexus::wasInvoked().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ verifyEvent() [1/2]

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().

Referenced by MockElm::verifyMark().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ verifyEvent() [2/2]

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().

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().

Referenced by BusTerm_test::attachNewBusTerm().

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(), and EventMatch::look_for_match_.

Referenced by BusTerm_test::attachNewBusTerm(), and EventLog_test::verify_logJoining().

Here is the call graph for this function:

Here is the caller graph for this function:

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

Member Function Documentation

◆ getID()

◆ joinInto()

◆ clear()

◆ event()

◆ call() [1/2]

◆ call() [2/2]

◆ create()

◆ destroy()

◆ verify()

◆ verifyMatch()

◆ verifyEvent() [1/2]

◆ verifyEvent() [2/2]

◆ verifyCall()

◆ ensureNot()