| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 1 | <!DOCTYPE html> |
| 2 | <html> |
| 3 | <title>logging</title> |
| 4 | <xmp theme="united" style="display:none;"> |
| 5 | |
| 6 | ## Logging macros |
| 7 | |
| onqtam | f8d5719 | 2018-08-23 16:02:12 +0300 | [diff] [blame] | 8 | Additional messages can be logged during a test case (safely even in [**concurrent threads**](faq.html#is-doctest-thread-aware)). |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 9 | |
| 10 | ## INFO() |
| 11 | |
| 12 | The ```INFO()``` macro allows heterogenous sequences of values to be streamed using the insertion operator (```<<```) in the same way that ```std::ostream```, ```std::cout```, etc support it. |
| 13 | |
| 14 | ``` |
| 15 | INFO("The number is " << i); |
| 16 | ``` |
| 17 | |
| 18 | This message will be relevant to all asserts after it in the current scope or in scopes nested in the current one and will be printed later only if an assert fails. |
| 19 | |
| 20 | Note that there is no initial ```<<``` - instead the insertion sequence is placed in parentheses. |
| 21 | |
| 22 | The message is **NOT** constructed right away - instead it gets lazily stringified only when needed. This means that rvalues (temporaries) cannot be passed to the ```INFO()``` macro. All literals are treated as rvalue references by the standard - except for C string literals (```"like this one"```). That means that even normal integer literals cannot be used directly - they need to be stored in a variable/constant before being passed to ```INFO()```. If C++14 is used (or Visual Studio 2017+) doctest provides the ```TO_LVALUE()``` macro to help in this regard - it turns any literal or constexpr value to an lvalue and can be used like this: |
| 23 | |
| 24 | ``` |
| 25 | constexpr int foo() { return 42; } |
| 26 | TEST_CASE("playing with literals and constexpr values") { |
| 27 | INFO(TO_LVALUE(6) << " and this is a C string literal " << TO_LVALUE(foo())); |
| 28 | CHECK(false); |
| 29 | } |
| 30 | ``` |
| 31 | |
| 32 | ```TO_LVALUE()``` can also help in contexts where you might want to avoid a ```static constexpr``` member to be ODR-used - see [**```DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE```**](configuration.html#doctest_config_assertion_parameters_by_value). |
| 33 | |
| 34 | Some notes: |
| 35 | |
| 36 | - the lazy stringification means the values will be stringified when an assert fails and not at the point of capture - so the value might have changed |
| 37 | - if the library is built with C++11 rvalue reference support (see [**```DOCTEST_CONFIG_WITH_RVALUE_REFERENCES```**](configuration.html#doctest_config_with_rvalue_references)) then deleted overloads are provided to prohibit rvalues from being captured in an **```INFO()```** call - since the lazy stringification actually caches pointers to the objects. For C++98 temporaries will again not work but there will be horrible compilation errors |
| 38 | - the [**```DOCTEST_CONFIG_NUM_CAPTURES_ON_STACK```**](configuration.html#doctest_config_num_captures_on_stack) config identifier can be used to control how much stack space is used to avoid heap allocations for the streaming macros |
| 39 | - stream manipulators (from ```<iomanip>```) can be used but need to be created as local variables and used as lvalues |
| 40 | - refer to the [**stringification**](stringification.html) page for information on how to teach doctest to stringify your types |
| 41 | |
| 42 | The lazy stringification and the stack usage means that in the common case when no asserts fail the code runs super fast. This makes it suitable even in loops - perhaps to log the iteration. |
| 43 | |
| 44 | There is also the **```CAPTURE()```** macro which is a convenience wrapper of **```INFO()```**: |
| 45 | |
| 46 | ``` |
| 47 | CAPTURE(some_variable) |
| 48 | ``` |
| 49 | |
| 50 | This will handle the stringification of the variable name for you (actually it works with any expression, not just variables). |
| 51 | |
| 52 | This would log something like: |
| 53 | |
| 54 | ``` |
| 55 | some_variable := 42 |
| 56 | ``` |
| 57 | |
| 58 | ## Messages which can optionally fail test cases |
| 59 | |
| 60 | There are a few other macros for logging information: |
| 61 | |
| 62 | - ```MESSAGE(message)``` |
| 63 | - ```FAIL_CHECK(message)``` |
| 64 | - ```FAIL(message)``` |
| 65 | |
| 66 | ```FAIL()``` is like a ```REQUIRE``` assert - fails the test case and exits it. ```FAIL_CHECK()``` acts like a ```CHECK``` assert - fails the test case but continues with the execution. ```MESSAGE()``` just prints a message. |
| 67 | |
| 68 | In all these macros the messages are again composed using the ```<<``` streaming operator - like this: |
| 69 | |
| 70 | ``` |
| 71 | FAIL("This is not supposed to happen! some var: " << var); |
| 72 | ``` |
| 73 | |
| 74 | Also there is no lazy stringification here - strings are always constructed and printed and thus there are no limitations to the values being logged - temporaries and rvalues are accepted - unlike with the ```INFO()``` macro. |
| 75 | |
| 76 | There are also a few more intended for use by third party libraries such as mocking frameworks: |
| 77 | |
| 78 | - ```ADD_MESSAGE_AT(file, line, message)``` |
| 79 | - ```ADD_FAIL_CHECK_AT(file, line, message)``` |
| 80 | - ```ADD_FAIL_AT(file, line, message)``` |
| 81 | |
| 82 | They can be useful when integrating asserts from a different framework with doctest. |
| 83 | |
| 84 | ------ |
| 85 | |
| 86 | - Check out the [**example**](../../examples/all_features/logging.cpp) which shows how all of these are used. |
| 87 | |
| 88 | --- |
| 89 | |
| 90 | [Home](readme.html#reference) |
| 91 | |
| onqtam | f8d5719 | 2018-08-23 16:02:12 +0300 | [diff] [blame] | 92 | <p align="center"><img src="../../scripts/data/logo/icon_2.svg"></p> |
| 93 | |
| onqtam | b8220c5 | 2017-05-16 00:21:15 +0300 | [diff] [blame] | 94 | |
| 95 | </xmp> |
| 96 | <script src="strapdown.js/strapdown.js"></script> |
| 97 | </html> |