跳到主要内容

logging

Logging macros​

Additional messages can be logged during test case execution (and can be safely logged even in concurrent threads).

INFO()​

The INFO() macro allows capturing a sequence of heterogeneous expressions by listing them with commas.

INFO("The number is ", i);

This message will be associated with all subsequent assertions in the current scope or scopes nested within the current scope, and will only be printed later if an assertion fails.

The expressions are not evaluated immediately - instead, lazy evaluation is used, and they are only evaluated when needed.

Some notes:

  • Lazy stringification means that the expressions will be evaluated when the assertion fails, not at the point of capture - so the values may have changed by then
  • For information on how to teach doctest to stringify your types, see the stringification page

Lazy evaluation means the code runs very fast in common cases where no assertions fail. This makes it suitable even for loops - perhaps to log iterations.

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

CAPTURE(some_variable)

This handles stringification of the variable name for you (in fact it works with any expression, not just variables).

This logs something like:

  some_variable := 42

Messages which can optionally fail test cases​

There are several other macros for logging information:

  • MESSAGE(message)
  • FAIL_CHECK(message)
  • FAIL(message)

FAIL() is like a REQUIRE assertion - the test case fails and exits immediately. FAIL_CHECK() behaves like a CHECK assertion - the test case fails, but execution continues. MESSAGE() simply prints a message.

FAIL("This is not supposed to happen! some var: ", var);

There is no lazy stringification here either - the string is always constructed and printed.

There are also some for use by third-party libraries such as mocking frameworks:

  • ADD_MESSAGE_AT(file, line, message)
  • ADD_FAIL_CHECK_AT(file, line, message)
  • ADD_FAIL_AT(file, line, message)

They are very useful when integrating assertions from different frameworks with doctest.

  • Check out the example which shows how to use all of these.