logging.md
1 <a id="top"></a> 2 # Logging macros 3 4 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: 5 6 ```cpp 7 TEST_CASE("Foo") { 8 INFO("Test case start"); 9 for (int i = 0; i < 2; ++i) { 10 INFO("The number is " << i); 11 CHECK(i == 0); 12 } 13 } 14 15 TEST_CASE("Bar") { 16 INFO("Test case start"); 17 for (int i = 0; i < 2; ++i) { 18 INFO("The number is " << i); 19 CHECK(i == i); 20 } 21 CHECK(false); 22 } 23 ``` 24 When the `CHECK` fails in the "Foo" test case, then two messages will be printed. 25 ``` 26 Test case start 27 The number is 1 28 ``` 29 When the last `CHECK` fails in the "Bar" test case, then only one message will be printed: `Test case start`. 30 31 ## Logging without local scope 32 33 > [Introduced](https://github.com/catchorg/Catch2/issues/1522) in Catch2 2.7.0. 34 35 `UNSCOPED_INFO` is similar to `INFO` with two key differences: 36 37 - Lifetime of an unscoped message is not tied to its own scope. 38 - An unscoped message can be reported by the first following assertion only, regardless of the result of that assertion. 39 40 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. 41 42 These differences make this macro useful for reporting information from helper functions or inner scopes. An example: 43 44 ```cpp 45 void print_some_info() { 46 UNSCOPED_INFO("Info from helper"); 47 } 48 49 TEST_CASE("Baz") { 50 print_some_info(); 51 for (int i = 0; i < 2; ++i) { 52 UNSCOPED_INFO("The number is " << i); 53 } 54 CHECK(false); 55 } 56 57 TEST_CASE("Qux") { 58 INFO("First info"); 59 UNSCOPED_INFO("First unscoped info"); 60 CHECK(false); 61 62 INFO("Second info"); 63 UNSCOPED_INFO("Second unscoped info"); 64 CHECK(false); 65 } 66 ``` 67 68 "Baz" test case prints: 69 ``` 70 Info from helper 71 The number is 0 72 The number is 1 73 ``` 74 75 With "Qux" test case, two messages will be printed when the first `CHECK` fails: 76 ``` 77 First info 78 First unscoped info 79 ``` 80 81 "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: 82 ``` 83 First info 84 Second info 85 Second unscoped info 86 ``` 87 88 ## Streaming macros 89 90 All these macros allow heterogeneous sequences of values to be streaming using the insertion operator (```<<```) in the same way that std::ostream, std::cout, etc support it. 91 92 E.g.: 93 ```c++ 94 INFO( "The number is " << i ); 95 ``` 96 97 (Note that there is no initial ```<<``` - instead the insertion sequence is placed in parentheses.) 98 These macros come in three forms: 99 100 **INFO(** _message expression_ **)** 101 102 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. 103 104 _Note that in Catch2 2.x.x `INFO` can be used without a trailing semicolon as there is a trailing semicolon inside macro. 105 This semicolon will be removed with next major version. It is highly advised to use a trailing semicolon after `INFO` macro._ 106 107 **UNSCOPED_INFO(** _message expression_ **)** 108 109 > [Introduced](https://github.com/catchorg/Catch2/issues/1522) in Catch2 2.7.0. 110 111 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. 112 113 **WARN(** _message expression_ **)** 114 115 The message is always reported but does not fail the test. 116 117 **FAIL(** _message expression_ **)** 118 119 The message is reported and the test case fails. 120 121 **FAIL_CHECK(** _message expression_ **)** 122 123 AS `FAIL`, but does not abort the test 124 125 ## Quickly capture value of variables or expressions 126 127 **CAPTURE(** _expression1_, _expression2_, ... **)** 128 129 Sometimes you just want to log a value of variable, or expression. For 130 convenience, we provide the `CAPTURE` macro, that can take a variable, 131 or an expression, and prints out that variable/expression and its value 132 at the time of capture. 133 134 e.g. `CAPTURE( theAnswer );` will log message "theAnswer := 42", while 135 ```cpp 136 int a = 1, b = 2, c = 3; 137 CAPTURE( a, b, c, a + b, c > b, a == 1); 138 ``` 139 will log a total of 6 messages: 140 ``` 141 a := 1 142 b := 2 143 c := 3 144 a + b := 3 145 c > b := true 146 a == 1 := true 147 ``` 148 149 You can also capture expressions that use commas inside parentheses 150 (e.g. function calls), brackets, or braces (e.g. initializers). To 151 properly capture expression that contains template parameters list 152 (in other words, it contains commas between angle brackets), you need 153 to enclose the expression inside parentheses: 154 `CAPTURE( (std::pair<int, int>{1, 2}) );` 155 156 157 --- 158 159 [Home](Readme.md#top)