catch2/docs/logging.md

Logging macros

Additional messages can be logged during a test case. Note that the messages are scoped and thus will not be reported if failure occurs in scope preceding the message declaration. An example:

TEST_CASE("Foo") {
    INFO("Test case start");
    for (int i = 0; i < 2; ++i) {
        INFO("The number is " << i);
        CHECK(i == 0);
    }
}

TEST_CASE("Bar") {
    INFO("Test case start");
    for (int i = 0; i < 2; ++i) {
        INFO("The number is " << i);
        CHECK(i == i);
    }
    CHECK(false);
}

When the CHECK fails in the "Foo" test case, then two messages will be printed.

Test case start
The number is 1

When the last CHECK fails in the "Bar" test case, then only one message will be printed: Test case start.

Streaming macros

All these macros allow heterogenous sequences of values to be streaming using the insertion operator (<<) in the same way that std::ostream, std::cout, etc support it.

E.g.:

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

(Note that there is no initial << - instead the insertion sequence is placed in parentheses.) These macros come in three forms:

INFO( message expression )

The message is logged to a buffer, but only reported with the next assertion that is logged. This allows you to log contextual information in case of failures which is not shown during a successful test run (for the console reporter, without -s). Messages are removed from the buffer at the end of their scope, so may be used, for example, in loops.

WARN( message expression )

The message is always reported but does not fail the test.

FAIL( message expression )

The message is reported and the test case fails.

FAIL_CHECK( message expression )

AS FAIL, but does not abort the test

Quickly capture a variable value

CAPTURE( expression )

Sometimes you just want to log the name and value of a variable. While you can easily do this with the INFO macro, above, as a convenience the CAPTURE macro handles the stringising of the variable name for you (actually it works with any expression, not just variables).

E.g.

CAPTURE( theAnswer );

This would log something like:

"theAnswer := 42"

Deprecated macros

SCOPED_INFO and SCOPED_CAPTURE

These macros are now deprecated and are just aliases for INFO and CAPTURE (which were not previously scoped).

---

Home