event-log.hpp File Reference

Go to the source code of this file.

Description

Support for verifying the occurrence of events from unit tests.

Typically used within special rigging and instrumentation for tests, the [EventLog] allows to record invocations and similar events. It is implemented as a "PImpl" to allow sharing of logs, which helps to trace events from transient UI elements and from destructor code. The front-end used for access offers a query DSL, so the test code may express some expected patterns of incidence and verify match or non-match.

Usage

The EventLog just captures invocations in memory, as sequence of string records. The logging API offers some dedicated functions to record invocations, events, the creation and destruction of objects, warnings and error messages. Data passed to those logging functions is rendered into string, using Lumiera's generic string conversion helpers.

To verify and match on log contents, start an evaluation as a builder (DSL) expression, starting from one of the #verify functions, or starting with #ensureNot, to probe that a given set of matches does not occur in the log. These entrance functions set up the initial search condition, and further search conditions can be chained up by invoking suitable matching functions on the generated EventMatch builder. Most notably, it is possible to search for some further match condition before or after the position where the preceding condition produced a match – allowing to specify sequences and patterns of events to expect in the log

EventLog log("baked beans");
log.event("spam");
log.event("ham");

CHECK (log.verify("ham")
          .after("beans")
          .before("spam")
          .before("ham"));

In general, this kind of search with a switch of the search direction in the middle of a match requires some backtracking to try possible matches until exhaustion.

Failure of match prints a detailed trace message to STDERR, in order to deliver a precise indication what part of the condition failed.

Note

this sequence prints the matches succeeding at the point where each condition is added to the chain. Adding more conditions, especially when combined with changed search direction, might lead to backtracking, which happens silently within the search engine, without printing any further diagnostics. This means: the sequence of matches you see in this diagnostic output is not necessarily the last match path, which leads to final failure

Warning

as such EventLog is deliberately not threadsafe

See also

EventLog_test

usage example

Definition in file event-log.hpp.

#include "lib/error.hpp"
#include "lib/iter-cursor.hpp"
#include "lib/iter-chain-search.hpp"
#include "lib/format-util.hpp"
#include "lib/format-cout.hpp"
#include "lib/diff/record.hpp"
#include "lib/idi/genfunc.hpp"
#include "lib/symbol.hpp"
#include "lib/util.hpp"
#include <memory>
#include <vector>
#include <string>
#include <regex>

Classes
class	EventLog
	Helper to log and verify the occurrence of events. More...
class	EventMatch

Typedefs
using	Entry = lib::diff::Record< string >
using	Log = std::vector< Entry >

Functions
auto	buildSearchFilter (Log const &srcSeq)

Namespaces
	lib
	Implementation namespace for support and library code.