From 1701325caa11af8ceff92c7254e12f5a8f77ada5 Mon Sep 17 00:00:00 2001 From: Omer Ozarslan Date: Sun, 3 Feb 2019 19:41:41 -0600 Subject: [PATCH] Document unscoped info --- docs/logging.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 60 insertions(+), 2 deletions(-) diff --git a/docs/logging.md b/docs/logging.md index f6ad81a3..e896a570 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -1,7 +1,7 @@ # 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: +Additional messages can be logged during a test case. Note that the messages logged with `INFO` are scoped and thus will not be reported if failure occurs in scope preceding the message declaration. An example: ```cpp TEST_CASE("Foo") { @@ -28,6 +28,60 @@ The number is 1 ``` When the last `CHECK` fails in the "Bar" test case, then only one message will be printed: `Test case start`. +## Logging without local scope + +`UNSCOPED_INFO` is similar to `INFO` with two key differences: + +- Lifetime of an unscoped message is not tied to its own scope. +- An unscoped message can be reported by the first following assertion only, regardless of the result of that assertion. + +In other words, lifetime of `UNSCOPED_INFO` is limited by the following assertion (or by the end of test case/section, whichever comes first) whereas lifetime of `INFO` is limited by its own scope. + +These differences make this macro useful for reporting information from helper functions or inner scopes. An example: + +```cpp +void print_some_info() { + UNSCOPED_INFO("Info from helper"); +} + +TEST_CASE("Baz") { + print_some_info(); + for (int i = 0; i < 2; ++i) { + UNSCOPED_INFO("The number is " << i); + } + CHECK(false); +} + +TEST_CASE("Qux") { + INFO("First info"); + UNSCOPED_INFO("First unscoped info"); + CHECK(false); + + INFO("Second info"); + UNSCOPED_INFO("Second unscoped info"); + CHECK(false); +} +``` + +"Baz" test case prints: +``` +Info from helper +The number is 0 +The number is 1 +``` + +With "Qux" test case, two messages will be printed when the first `CHECK` fails: +``` +First info +First unscoped info +``` + +"First unscoped info" message will be cleared after the first `CHECK`, while "First info" message will persist until the end of the test case. Therefore, when the second `CHECK` fails, three messages will be printed: +``` +First info +Second info +Second unscoped info +``` ## Streaming macros @@ -43,11 +97,15 @@ 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. +The message is logged to a buffer, but only reported with next assertions that are 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. _Note that in Catch2 2.x.x `INFO` can be used without a trailing semicolon as there is a trailing semicolon inside macro. This semicolon will be removed with next major version. It is highly advised to use a trailing semicolon after `INFO` macro._ +**UNSCOPED_INFO(** _message expression_ **)** + +Similar to `INFO`, but messages are not limited to their own scope: They are removed from the buffer after each assertion, section or test case, whichever comes first. + **WARN(** _message expression_ **)** The message is always reported but does not fail the test.