Gitiles
Code Review Sign In
gerrit.cesnet.cz / github / onqtam / doctest / 43271a60ed5869e0c09eba716530f8c7e5b84804 / . / doc / html_generated / assertions.html
blob: 18274d64f06432243c3dbfc11b03257daf0d4f71 [file] [log] [blame]
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]1<!DOCTYPE html>
2<html>
3<title>assertions</title>
4<xmp theme="united" style="display:none;">
5
6## Assertion macros
7
8Most test frameworks have a large collection of assertion macros to capture all possible conditional forms (```_EQUALS```, ```_NOTEQUALS```, ```_GREATER_THAN``` etc).
9
onqtamd52859a2019-03-02 18:28:14 +0200[diff] [blame]10**doctest** is different (but it's like [**Catch**](https://github.com/catchorg/Catch2) in this regard). Because it decomposes comparison expressions most of these forms are reduced to one or two that you will use all the time. That said, there is a rich set of auxiliary macros as well.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]11
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]12There are 3 levels of assert severity for all assertion macros:
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]13
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]14- ```REQUIRE``` - this level will immediately quit the test case if the assert fails and will mark the test case as failed.
15- ```CHECK``` - this level will mark the test case as failed if the assert fails but will continue with the test case.
16- ```WARN``` - this level will only print a message if the assert fails but will not mark the test case as failed.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]17
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]18The ```CHECK``` level is mostly useful if you have a series of essentially orthogonal assertions and it is useful to see all the results rather than stopping at the first failure.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]19
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]20All asserts evaluate the expressions only once and if they fail - the values are [**stringified**](stringification.html) properly.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]21
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]22Since **doctest** is [**thread-safe**](faq.html#is-doctest-thread-aware) all asserts and [**logging**](logging.html) macros can be used in threads spawned from test cases.
23
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]24Note that the ```REQUIRE``` level of asserts uses exceptions to end the current test case. It might be dangerous to use this level of asserts inside destructors of user-defined classes - if a destructor is called during stack unwinding due to an exception and a ```REQUIRE``` assert fails then the program will terminate. Also since C++11 all destructors are by default ```noexcept(true)``` unless specified otherwise so such an assert will lead to ```std::terminate()``` being called.
25
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]26## Expression decomposing asserts
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]27
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]28These are of the form ```CHECK(expression)``` (Same for ```REQUIRE``` and ```WARN```).
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]29
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]30```expression``` can be a binary comparison like ```a == b``` or just a single thing like ```vec.isEmpty()```.
31
32If an exception is thrown it is caught, reported, and counted as a failure (unless the assert is of level ```WARN```).
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]33
34Examples:
35
36```
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]37CHECK(flags == state::alive | state::moving);
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]38CHECK(thisReturnsTrue());
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]39REQUIRE(i < 42);
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]40```
41
onqtam72ca33b2018-12-05 17:34:33 +0200[diff] [blame]42- Negating asserts - ```<LEVEL>_FALSE(expression)``` - evaluates the expression and records the _logical NOT_ of the result.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]43
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]44These forms exist as a workaround for the fact that ```!``` prefixed expressions cannot be decomposed properly.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]45
46Example:
47
48```
49REQUIRE_FALSE(thisReturnsFalse());
50```
51
onqtam72ca33b2018-12-05 17:34:33 +0200[diff] [blame]52- Using the [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](configuration.html#doctest_config_super_fast_asserts) config option can make compilation of asserts up to [**31-63%**](benchmarks.html#cost-of-an-assertion-macro) faster!
53- These asserts also have a ```_MESSAGE``` form - like ```CHECK_MESSAGE(expression, message)``` which is basically a code block ```{}``` with a scoped [**```INFO()```**](logging.html#info) logging macro together with the ```CHECK``` macro - that way the message will be relevant only to that assert. The binary/unary asserts don't have this variation yet.
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]54
55Examples:
56
57```
58INFO("this is relevant to all asserts, and here is some var: " << local);
59
60CHECK_MESSAGE(a < b, "relevant only to this assert " << other_local << "more text!");
61
62CHECK(b < c); // here only the first INFO() will be relevant
63```
64
65For more information about the ```INFO()``` macro and logging with the streaming ```operator<<``` visit the [logging page](logging.html).
66
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]67## Binary and unary asserts
68
69These asserts don't use templates to decompose the comparison expressions for the left and right parts.
70
onqtam72ca33b2018-12-05 17:34:33 +0200[diff] [blame]71These have the same guarantees as the expression decomposing ones but [**57-68% faster**](benchmarks.html#cost-of-an-assertion-macro) for compilation.
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]72
73```<LEVEL>``` is one of 3 possible: ```REQUIRE```/```CHECK```/```WARN```.
74
75- ```<LEVEL>_EQ(left, right)``` - same as ```<LEVEL>(left == right)```
76- ```<LEVEL>_NE(left, right)``` - same as ```<LEVEL>(left != right)```
77- ```<LEVEL>_GT(left, right)``` - same as ```<LEVEL>(left > right)```
78- ```<LEVEL>_LT(left, right)``` - same as ```<LEVEL>(left < right)```
79- ```<LEVEL>_GE(left, right)``` - same as ```<LEVEL>(left >= right)```
80- ```<LEVEL>_LE(left, right)``` - same as ```<LEVEL>(left <= right)```
81- ```<LEVEL>_UNARY(expr)``` - same as ```<LEVEL>(expr)```
82- ```<LEVEL>_UNARY_FALSE(expr)``` - same as ```<LEVEL>_FALSE(expr)```
83
onqtam72ca33b2018-12-05 17:34:33 +0200[diff] [blame]84Using the [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](configuration.html#doctest_config_super_fast_asserts) config option can make the binary asserts to compile up to [**84-91%**](benchmarks.html#cost-of-an-assertion-macro) faster!
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]85
86## Exceptions
87
88```<LEVEL>``` is one of 3 possible: ```REQUIRE```/```CHECK```/```WARN```.
89
90- ```<LEVEL>_THROWS(expression)```
91
92Expects that an exception (of any type) is thrown during evaluation of the expression.
93
onqtam2d97b852018-11-30 18:06:17 +0200[diff] [blame]94- ```<LEVEL>_THROWS_AS(expression, exception_type)```
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]95
96Expects that an exception of the _specified type_ is thrown during evaluation of the expression.
97
onqtam2d97b852018-11-30 18:06:17 +0200[diff] [blame]98Note that ```const``` and ```&``` are added to the exception type if missing (users shouldn't care) - the standard practice for exceptions in C++ is ```Throw by value, catch by (const) reference```.
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]99
100```
onqtam2d97b852018-11-30 18:06:17 +0200[diff] [blame]101CHECK_THROWS_AS(func(), const std::exception&);
102CHECK_THROWS_AS(func(), std::exception); // same as above
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]103```
104
onqtam2d97b852018-11-30 18:06:17 +0200[diff] [blame]105- ```<LEVEL>_THROWS_WITH(expression, c_string)```
106
107Expects that an exception is thrown during evaluation of the expression and is successfully translated to the _specified c string_ (see [**translating exceptions**](stringification.html#translating-exceptions)).
108
109```
110CHECK_THROWS_WITH(func(), "invalid operation!");
111```
112
113- ```<LEVEL>_NOTHROW(expression)```
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]114
115Expects that no exception is thrown during evaluation of the expression.
116
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]117Note that these asserts also have a ```_MESSAGE``` form - like ```CHECK_THROWS_MESSAGE(expression, message)``` - these work identically to the ```_MESSAGE``` form of the normal macros (```CHECK_MESSAGE(a < b, "this shouldn't fail")```) described earlier.
118
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]119## Using asserts out of a testing context
120
121Asserts can be used outside of a testing context (in code not called from a ```TEST_CASE()```) instead of [```assert()```](https://en.cppreference.com/w/cpp/error/assert).
122
123A ```doctest::Context``` object still has to be created somewhere and set as the default one using the ```setAsDefaultForAssertsOutOfTestCases()``` method - and then asserts will work. A handler can be registered by calling the ```setAssertHandler()``` method on the context object. If no handler is set then ```std::abort()``` is called on failure.
124
onqtam72ca33b2018-12-05 17:34:33 +0200[diff] [blame]125The results would be best when using the [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](configuration.html#doctest_config_super_fast_asserts) config identifier.
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]126
127Checkout the [**example**](../../examples/all_features/asserts_used_outside_of_tests.cpp) showcasing how that is done. For more information see the [**issue for the feature request**](https://github.com/onqtam/doctest/issues/114).
128
129Currently [**logging macros**](logging.html) cannot be used for extra context for asserts outside of a test run. That means that the ```_MESSAGE``` variants of asserts are also not usable - since they are just a packed ```INFO()``` with an assert right after it.
130
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]131## Floating point comparisons
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]132
133When comparing floating point numbers - especially if at least one of them has been computed - great care must be taken to allow for rounding errors and inexact representations.
134
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]135**doctest** provides a way to perform tolerant comparisons of floating point values through the use of a wrapper class called ```doctest::Approx```. ```doctest::Approx``` can be used on either side of a comparison expression. It overloads the comparisons operators to take a relative tolerance into account. Here's a simple example:
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]136
137```
138REQUIRE(performComputation() == doctest::Approx(2.1));
139```
140
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]141By default a small epsilon value (relative - in percentages) is used that covers many simple cases of rounding errors. When this is insufficient the epsilon value (the amount within which a difference either way is ignored) can be specified by calling the ```epsilon()``` method on the ```doctest::Approx``` instance. e.g.:
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]142
143```
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]144REQUIRE(22.0/7 == doctest::Approx(3.141).epsilon(0.01)); // allow for a 1% error
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]145```
146
147When dealing with very large or very small numbers it can be useful to specify a scale, which can be achieved by calling the ```scale()``` method on the ```doctest::Approx``` instance.
148
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]149--------
150
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]151- Check out the [**example**](../../examples/all_features/assertion_macros.cpp) which shows many of these macros
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]152- Do not wrap assertion macros in ```try```/```catch``` - the REQUIRE macros throw exceptions to end the test case execution!
153
154---------------
155
156[Home](readme.html#reference)
157
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]158<p align="center"><img src="../../scripts/data/logo/icon_2.svg"></p>
159
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]160
161</xmp>
162<script src="strapdown.js/strapdown.js"></script>
163</html>