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

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

Description

ongoing evaluation and match within an [EventLog].

Remarks
an EventMatch object is returned when building query expression to verify the occurrence of some events within the EventLog. This "matcher" object implements the query logic with backtracking. The query expressions are added as filter functors to a filtering iterator; when all of the log's contents are filtered away, the evaluation counts as failed.

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

Public Member Functions

EventMatchafter (string match)
 find a match (substring match) of the given text in an EventLog entry before the current position, switching to backwards search direction
 
EventMatchafterCall (string match)
 find a function invocation backwards, before the current point of reference
 
EventMatchafterEvent (string match)
 
EventMatchafterEvent (string classifier, string match)
 
EventMatchafterMatch (string regExp)
 
template<typename... ARGS>
EventMatcharg (ARGS const &...args)
 refine filter to additionally require specific arguments More...
 
template<typename... ARGS>
EventMatchargMatch (ARGS const &...regExps)
 refine filter to additionally cover all arguments with a series of regular expressions. More...
 
template<typename ARG >
EventMatchargPos (size_t idx, ARG const &arg)
 refine filter to additionally require match on a specific positional argument
 
EventMatchattrib (string key, string valueMatch)
 refine filter to additionally match on a specific attribute
 
EventMatchbefore (string match)
 find a match (substring match) of the given text in an EventLog entry after the current position More...
 
EventMatchbeforeCall (string match)
 find a match for some function invocation after the current point of reference More...
 
EventMatchbeforeEvent (string match)
 find a match for an "event" after the current point of reference More...
 
EventMatchbeforeEvent (string classifier, string match)
 
EventMatchbeforeMatch (string regExp)
 find a match with the given regular expression
 
EventMatchid (string classifier)
 refine filter to additionally match on the ID attribute
 
EventMatchkey (string key)
 refine filter to additionally require the presence an attribute
 
EventMatchlocate (string match)
 basic search function: continue linear lookup over the elements of the EventLog to find a match (substring match) of the given text. More...
 
EventMatchlocateCall (string match)
 basic search for some specific function invocation More...
 
EventMatchlocateEvent (string match)
 basic search for a matching "event" More...
 
EventMatchlocateEvent (string classifier, string match)
 
EventMatchlocateMatch (string regExp)
 basic search like locate() but with the given regular expression
 
EventMatchon (string targetID)
 refine filter to additionally match the 'this' attribute
 
EventMatchon (const char *targetID)
 
template<typename X >
EventMatchon (const X *const targetObj)
 
 operator bool () const
 final evaluation of the match query, usually triggered from the unit test CHECK(). More...
 
EventMatchtype (string typeID)
 refine filter to additionally require a matching log entry type
 

Friends

class EventLog
 

Private Types

using ArgSeq = lib::diff::RecordSetup< string >::Storage
 
using Filter = decltype(buildSearchFilter(std::declval< Log const & >()))
 
using RExSeq = std::vector< std::regex >
 

Private Member Functions

 EventMatch (Log const &srcSeq)
 
void evaluateQuery (string matchSpec, Literal rel="after")
 this is actually called after each refinement of the filter and matching conditions. More...
 
bool foundSolution ()
 core of the evaluation machinery: apply a filter predicate and then pull through the log to find a acceptable entry
 
void refineSerach_matchArgsRegExp (RExSeq &&regExpSeq, string rendered_regExps)
 
void refineSerach_matchArgument (size_t idx, string match)
 
void refineSerach_matchArguments (ArgSeq &&argSeq)
 

Private Attributes

string lastMatch_
 record last match for diagnostics
 
bool look_for_match_
 support for positive and negative queries. More...
 
Filter solution_
 match predicate evaluator
 
string violation_
 record when the underlying query has failed
 

Constructor & Destructor Documentation

◆ EventMatch()

EventMatch ( Log const &  srcSeq)
private

for creating EventLog matchers

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

Member Function Documentation

◆ operator bool()

operator bool ( ) const
inline

final evaluation of the match query, usually triggered from the unit test CHECK().

Note
failure cause is printed to STDERR.

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

◆ locate()

EventMatch & locate ( string  match)

basic search function: continue linear lookup over the elements of the EventLog to find a match (substring match) of the given text.

The search begins at the current position and proceeds in the currently configured direction. Initially the search starts at the first record and proceeds forward.

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

Referenced by EventLog::ensureNot(), and EventLog::verify().

+ Here is the caller graph for this function:

◆ locateEvent()

EventMatch & locateEvent ( string  match)

basic search for a matching "event"

Parameters
matchperform a substring match against the arguments of the event
See also
beforeEvent() for a description of possible "events"

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

Referenced by EventLog::verifyEvent().

+ Here is the caller graph for this function:

◆ locateCall()

EventMatch & locateCall ( string  match)

basic search for some specific function invocation

Parameters
matchperform a substring match against the name of the function invoked

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

Referenced by EventLog::verifyCall().

+ Here is the caller graph for this function:

◆ before()

EventMatch & before ( string  match)

find a match (substring match) of the given text in an EventLog entry after the current position

Remarks
the name of this junctor might seem counter intuitive; it was chosen due to expected DSL usage: log.verify("α").before("β"). Operationally this means first to find a Record matching the substring "α" and then to forward from this point until hitting a record to match "β".

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

Referenced by EventLog_test::verify_logJoining(), and AbstractTangible_test::verify_mockManipulation().

+ Here is the caller graph for this function:

◆ beforeEvent()

EventMatch & beforeEvent ( string  match)

find a match for an "event" after the current point of reference

Remarks
the term "event" designates several types of entries, which typically capture something happening within the observed entity. Especially, the following record types qualify as event:
  • event
  • error
  • create
  • destroy
  • logJoin
Parameters
matchperform a substring match against the arguments of the event
See also
::findEvent

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

Referenced by BusTerm_test::attachNewBusTerm(), AbstractTangible_test::markState(), AbstractTangible_test::revealer(), EventLog_test::verify_logJoining(), and Nexus::wasInvoked().

+ Here is the caller graph for this function:

◆ beforeCall()

EventMatch & beforeCall ( string  match)

find a match for some function invocation after the current point of reference

Parameters
matchperform a substring match against the name of the function invoked
See also
::findCall

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

Referenced by BusTerm_test::attachNewBusTerm(), AbstractTangible_test::markState(), AbstractTangible_test::revealer(), EventLog_test::verify_logJoining(), Nexus::wasBound(), and Nexus::wasInvoked().

+ Here is the caller graph for this function:

◆ arg()

EventMatch& arg ( ARGS const &...  args)
inline

refine filter to additionally require specific arguments

Remarks
the refined filter works on each record qualified by the query expression established thus far; it additionally looks into the arguments (children list) of the log entry.
Warning
match is processed by comparison of string representation.

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

References EventMatch::refineSerach_matchArguments().

Referenced by BusTerm_test::attachNewBusTerm(), AbstractTangible_test::markState(), AbstractTangible_test::revealer(), EventLog_test::verify_logJoining(), AbstractTangible_test::verify_mockManipulation(), Nexus::wasBound(), and Nexus::wasInvoked().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ argMatch()

EventMatch& argMatch ( ARGS const &...  regExps)
inline

refine filter to additionally cover all arguments with a series of regular expressions.

Note
For this match to succeed, any arguments of the log entry must be covered by applying the given regular expressions consecutively. Each regular expression is applied to further arguments, as long as it matches. It is possible to have just one RegExp to "rule them all", but as soon as there is one argument, that can not be covered by the next RegExp, the whole match counts as failed.

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

References EventMatch::refineSerach_matchArgsRegExp().

Referenced by EventLog_test::verify_logJoining().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ evaluateQuery()

void evaluateQuery ( string  matchSpec,
Literal  rel = "after" 
)
private

this is actually called after each refinement of the filter and matching conditions.

The effect is to search for an (intermediary) solution right away and to mark failure as soon as some condition can not be satisfied. Rationale is to indicate the point where a chained match fails

See also
::operator bool() for extracting the result
Parameters
matchSpecdiagnostics description of the predicate just being added
relindication of the searching relation / direction

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

References EventMatch::look_for_match_.

Referenced by EventMatch::argPos().

+ Here is the caller graph for this function:

◆ refineSerach_matchArgument()

void refineSerach_matchArgument ( size_t  idx,
string  match 
)
private

refine filter condition additionally to match a specific positional call argument.

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

Referenced by EventMatch::argPos().

+ Here is the caller graph for this function:

◆ refineSerach_matchArguments()

void refineSerach_matchArguments ( ArgSeq &&  argSeq)
private

refine filter condition additionally to match a sequence of call arguments.

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

Referenced by EventMatch::arg(), and EventMatch::argPos().

+ Here is the caller graph for this function:

◆ refineSerach_matchArgsRegExp()

void refineSerach_matchArgsRegExp ( RExSeq &&  regExpSeq,
string  rendered_regExps 
)
private

refine filter condition additionally to cover call arguments by a sequence of regular expressions. Each regExp is used consecutively, until it fails to match; at that point, the next regExp is tried. When reaching the end of the argument sequence, we also expect to have used up all available regular expressions.

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

Referenced by EventMatch::argMatch(), and EventMatch::argPos().

+ Here is the caller graph for this function:

Member Data Documentation

◆ look_for_match_

bool look_for_match_
private

support for positive and negative queries.

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

Referenced by EventLog::ensureNot(), and EventMatch::evaluateQuery().

+ Inheritance diagram for EventMatch:
+ Collaboration diagram for EventMatch:

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