Logging macros

Additional messages can be logged during a test case.

INFO()

The INFO() macro allows heterogenous sequences of values to be streamed using the insertion operator (<<) in the same way that std::ostream, std::cout, etc support it.

INFO("The number is " << i);

This message will be relevant to all asserts after it in the current scope or in scopes nested in the current one and will be printed later only if an assert fails.

Note that there is no initial << - instead the insertion sequence is placed in parentheses.

The message is NOT constructed right away - instead it gets lazily stringified only when needed. This means that rvalues (temporaries) cannot be passed to the INFO() macro.

Some notes:

• the lazy stringification means the values will be stringified when an assert fails and not at the point of capture - so the value might have changed
• if the library is built with C++11 rvalue reference support (see DOCTEST_CONFIG_WITH_RVALUE_REFERENCES) then deleted overloads are provided to prohibit rvalues from being captured in an INFO() call - since the lazy stringification actually caches pointers to the objects
• the DOCTEST_CONFIG_NUM_CAPTURES_ON_STACK config identifier can be used to control how much stack space is used to avoid heap allocations for the streaming macros
• stream manipulators (from <iomanip>) can be used but need to be created as local variables and used as lvalues

The lazy stringification and the stack usage means that in the common case when no asserts fail the code runs super fast. This makes it suitable even in loops - perhaps to log the iteration.

There is also the CAPTURE() macro which is a convenience wrapper of INFO():

CAPTURE(some_variable)

This will handle the stringification of the variable name for you (actually it works with any expression, not just variables).

This would log something like:

some_variable := 42

---

Home