Gitiles
Code Review Sign In
gerrit.cesnet.cz / github / onqtam / doctest / 2dac7206e91dd63e2b46fbc362893704a35ff798 / . / doc / html_generated / logging.html
blob: 90809073443218d042ee7c5bdd889f244f38b804 [file] [log] [blame]
onqtamb8220c52017-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
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]8Additional messages can be logged during a test case (safely even in [**concurrent threads**](faq.html#is-doctest-thread-aware)).
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]9
10## INFO()
11
onqtam2a069c42020-12-15 21:02:28 +0200[diff] [blame]12The ```INFO()``` macro allows heterogeneous sequences of expressions to be captured by listing them with commas.
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]13
14```
onqtam2a069c42020-12-15 21:02:28 +0200[diff] [blame]15INFO("The number is ", i);
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]16```
17
18This 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
onqtam50146342019-08-12 22:29:59 +0300[diff] [blame]20The expression is **NOT** evaluated right away - instead it gets lazily evaluated only when needed.
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]21
22Some notes:
23
onqtam50146342019-08-12 22:29:59 +0300[diff] [blame]24- the lazy stringification means the expressions will be evaluated when an assert fails and not at the point of capture - so the value might have changed by then
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]25- refer to the [**stringification**](stringification.html) page for information on how to teach doctest to stringify your types
26
onqtam50146342019-08-12 22:29:59 +0300[diff] [blame]27The lazy evaluation 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.
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]28
29There is also the **```CAPTURE()```** macro which is a convenience wrapper of **```INFO()```**:
30
31```
32CAPTURE(some_variable)
33```
34
35This will handle the stringification of the variable name for you (actually it works with any expression, not just variables).
36
37This would log something like:
38
39```
40 some_variable := 42
41```
42
43## Messages which can optionally fail test cases
44
45There are a few other macros for logging information:
46
47- ```MESSAGE(message)```
48- ```FAIL_CHECK(message)```
49- ```FAIL(message)```
50
51```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.
52
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]53```
onqtam2a069c42020-12-15 21:02:28 +0200[diff] [blame]54FAIL("This is not supposed to happen! some var: ", var);
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]55```
56
onqtam2a069c42020-12-15 21:02:28 +0200[diff] [blame]57Also there is no lazy stringification here - strings are always constructed and printed.
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]58
59There are also a few more intended for use by third party libraries such as mocking frameworks:
60
61- ```ADD_MESSAGE_AT(file, line, message)```
62- ```ADD_FAIL_CHECK_AT(file, line, message)```
63- ```ADD_FAIL_AT(file, line, message)```
64
65They can be useful when integrating asserts from a different framework with doctest.
66
67------
68
69- Check out the [**example**](../../examples/all_features/logging.cpp) which shows how all of these are used.
70
71---
72
73[Home](readme.html#reference)
74
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]75<p align="center"><img src="../../scripts/data/logo/icon_2.svg"></p>
76
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]77
78</xmp>
79<script src="strapdown.js/strapdown.js"></script>
80</html>