Lumiera  0.pre.03
»edit your freedom«
EventLog Class Reference

#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 284 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>
EventLogaddAttrib (string const &key, X &&initialiser, ARGS &&...args)
 Qualify the latest entry: set further attribute(s)
 
const_iterator begin () const
 
EventLogcall (string target, string function)
 Log occurrence of a function call with no arguments. More...
 
EventLogcall (string target, string function, ArgSeq &&args)
 Log a function call with a sequence of stringified arguments.
 
EventLogcall (const char *target, const char *function, ArgSeq &&args)
 
template<typename... ARGS>
EventLogcall (string target, string function, ARGS const &...args)
 Log a function call with arbitrary arguments.
 
template<class X , typename... ARGS>
EventLogcall (const X *const targetObj, string function, ARGS const &...args)
 Log a function call on given object ("`this`")... More...
 
template<typename... ARGS>
EventLogcall (const char *target, string function, ARGS const &...args)
 
EventLogclear ()
 purge log contents while retaining just the original Header-ID
 
EventLogclear (string alteredLogID)
 purge log contents and also reset Header-ID More...
 
EventLogclear (const char *alteredLogID)
 
template<class X >
EventLogclear (const X *const obj)
 
EventLogcreate (string text)
 Log the creation of an object. More...
 
EventLogdestroy (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...
 
EventLogerror (string text)
 Log an error note.
 
EventLogevent (string text)
 log some text as event
 
EventLogevent (string classifier, string text)
 log some event, with additional ID or classifier More...
 
EventLogfatal (string text)
 Log a fatal failure.
 
string getID () const
 
EventLogjoinInto (EventLog &otherLog)
 Merge this log into another log, forming a combined log. More...
 
template<typename... ELMS>
EventLognote (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...
 
EventLogwarn (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 326 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
otherLogtarget 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 634 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 667 of file event-log.cpp.

◆ event()

EventLog & event ( string  classifier,
string  text 
)

log some event, with additional ID or classifier

Parameters
classifierinfo to be saved into the ID attribute
textactual payload info, to be logged as argument

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

◆ call() [1/2]

EventLog & call ( string  target,
string  function 
)

Log occurrence of a function call with no arguments.

Parameters
targetthe object or scope on which the function is invoked
functionname of the function being invoked

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

Referenced by MockElm::buildMutator(), EventLog::call(), MockElm::doExpand(), MockElm::doMark(), MockElm::doReveal(), MockElm::kill(), PlaceholderCommand< ARGS >::operate(), ActivityDetector::DiagnosticFun< RET, ARGS >::operator()(), EventLog_test::verify_logJoining(), 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 389 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 742 of file event-log.cpp.

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

+ 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 749 of file event-log.cpp.

Referenced by MockElm::kill(), EventLog_test::verify_logJoining(), 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 761 of file event-log.cpp.

References EventMatch::locate().

Referenced by BusTerm_test::attachNewBusTerm(), EventLog_test::verify_logJoining(), AbstractTangible_test::verify_mockManipulation(), 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
regExpdefinition
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 770 of file event-log.cpp.

References EventMatch::locateMatch().

Referenced by EventLog_test::verify_logJoining(), 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
matchtext to (substring)match against the argument logged as event

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

References EventMatch::locateEvent().

Referenced by EventLog_test::verify_logJoining(), and 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
classifierselect kind of event by match on type or ID

Definition at line 788 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
matchtext to match against the function name

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

References EventMatch::locateCall().

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:

◆ 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 814 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: