logging.rst

Logging messages

Sometimes, it might be useful to print some output from within a test or fixture -- and while this can be done trivially with a printf, it doesn't integrate well with the current output, nor does it work at all when the process is testing a redirected stdout.

For these cases, Criterion exposes a logging facility:

#include <criterion/criterion.h>
#include <criterion/logging.h>

Test(suite_name, test_name) {
    cr_log_info("This is an informational message. They are not displayed "
        "by default.");
    cr_log_warn("This is a warning. They indicate some possible malfunction "
        "or misconfiguration in the test.");
    cr_log_error("This is an error. They indicate serious problems and "
        "are usually shown before the test is aborted.");
}

cr_log_info, cr_log_warn and cr_log_error are all macros expanding to a call to the cr_log function. All of them take a mandatory format string, followed by optional parameters; for instance:

cr_log_info("%d + %d = %d", 1, 2, 3);

If using C++, the output stream objects info, warn and error are defined within the criterion::logging namespace, and can be used in conjunction with operator<<:

#include <criterion/criterion.h>
#include <criterion/logging.h>

using criterion::logging::info;
using criterion::logging::warn;
using criterion::logging::error;

Test(suite_name, test_name) {
    info << "This is an informational message. "
         << "They are not displayed by default."
         << std::flush;
    warn << "This is a warning. "
         << "They indicate some possible malfunction "
         << "or misconfiguration in the test."
         << std::flush;
    error << "This is an error. "
         << "They indicate serious problems and "
         << "are usually shown before the test is aborted."
         << std::flush;
}

Note that empty messages are ignored, and newlines in the log message splits the passed string into as many messages are there are lines.