Gitiles
Code Review Sign In
gerrit.cesnet.cz / github / onqtam / doctest / 24e4879bd0a932b1a724f54356894929e95f931c / . / doc / html_generated / assertions.html
blob: 3681dabc3a591fa7169c7b7238356f471852116f [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
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]10**doctest** is different (but it's like [**Catch**](https://github.com/philsquared/Catch) 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
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]42Negating 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
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]52Note that 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. All the other binary/unary/fast asserts don't have this variation.
53
54Examples:
55
56```
57INFO("this is relevant to all asserts, and here is some var: " << local);
58
59CHECK_MESSAGE(a < b, "relevant only to this assert " << other_local << "more text!");
60
61CHECK(b < c); // here only the first INFO() will be relevant
62```
63
64For more information about the ```INFO()``` macro and logging with the streaming ```operator<<``` visit the [logging page](logging.html).
65
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]66## Binary and unary asserts
67
68These asserts don't use templates to decompose the comparison expressions for the left and right parts.
69
onqtam4aff18c2017-05-17 04:10:03 +0300[diff] [blame]70These have the same guarantees as the expression decomposing ones - just less templates - [**25%-45% faster**](benchmarks.html#cost-of-an-assertion-macro) for compile times.
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]71
72```<LEVEL>``` is one of 3 possible: ```REQUIRE```/```CHECK```/```WARN```.
73
74- ```<LEVEL>_EQ(left, right)``` - same as ```<LEVEL>(left == right)```
75- ```<LEVEL>_NE(left, right)``` - same as ```<LEVEL>(left != right)```
76- ```<LEVEL>_GT(left, right)``` - same as ```<LEVEL>(left > right)```
77- ```<LEVEL>_LT(left, right)``` - same as ```<LEVEL>(left < right)```
78- ```<LEVEL>_GE(left, right)``` - same as ```<LEVEL>(left >= right)```
79- ```<LEVEL>_LE(left, right)``` - same as ```<LEVEL>(left <= right)```
80- ```<LEVEL>_UNARY(expr)``` - same as ```<LEVEL>(expr)```
81- ```<LEVEL>_UNARY_FALSE(expr)``` - same as ```<LEVEL>_FALSE(expr)```
82
83## Fast asserts
84
onqtam4aff18c2017-05-17 04:10:03 +0300[diff] [blame]85These are the faster versions of the binary and unary asserts - by [**60-80%**](benchmarks.html#cost-of-an-assertion-macro) of compile time.
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]86
87The difference is they don't evaluate the expression in a ```try/catch``` block - if the expression throws the whole test case ends.
88
onqtam4aff18c2017-05-17 04:10:03 +0300[diff] [blame]89There is also the [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](configuration.html#doctest_config_super_fast_asserts) config identifier that makes them even faster by another [**50-80%**](benchmarks.html#cost-of-an-assertion-macro)!
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]90
91```<LEVEL>``` is one of 3 possible: ```REQUIRE```/```CHECK```/```WARN```.
92
93- ```FAST_<LEVEL>_EQ(left, right)``` - almost the same as ```<LEVEL>(left == right)```
94- ```FAST_<LEVEL>_NE(left, right)``` - almost the same as ```<LEVEL>(left != right)```
95- ```FAST_<LEVEL>_GT(left, right)``` - almost the same as ```<LEVEL>(left > right)```
96- ```FAST_<LEVEL>_LT(left, right)``` - almost the same as ```<LEVEL>(left < right)```
97- ```FAST_<LEVEL>_GE(left, right)``` - almost the same as ```<LEVEL>(left >= right)```
98- ```FAST_<LEVEL>_LE(left, right)``` - almost the same as ```<LEVEL>(left <= right)```
99- ```FAST_<LEVEL>_UNARY(expr)``` - almost the same as ```<LEVEL>(expr)```
100- ```FAST_<LEVEL>_UNARY_FALSE(expr)``` - almost the same as ```<LEVEL>_FALSE(expr)```
101
102## Exceptions
103
104```<LEVEL>``` is one of 3 possible: ```REQUIRE```/```CHECK```/```WARN```.
105
106- ```<LEVEL>_THROWS(expression)```
107
108Expects that an exception (of any type) is thrown during evaluation of the expression.
109
onqtam2d97b852018-11-30 18:06:17 +0200[diff] [blame]110- ```<LEVEL>_THROWS_AS(expression, exception_type)```
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]111
112Expects that an exception of the _specified type_ is thrown during evaluation of the expression.
113
onqtam2d97b852018-11-30 18:06:17 +0200[diff] [blame]114Note 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]115
116```
onqtam2d97b852018-11-30 18:06:17 +0200[diff] [blame]117CHECK_THROWS_AS(func(), const std::exception&);
118CHECK_THROWS_AS(func(), std::exception); // same as above
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]119```
120
onqtam2d97b852018-11-30 18:06:17 +0200[diff] [blame]121- ```<LEVEL>_THROWS_WITH(expression, c_string)```
122
123Expects 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)).
124
125```
126CHECK_THROWS_WITH(func(), "invalid operation!");
127```
128
129- ```<LEVEL>_NOTHROW(expression)```
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]130
131Expects that no exception is thrown during evaluation of the expression.
132
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]133Note 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.
134
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]135## Using asserts out of a testing context
136
137Asserts 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).
138
139A ```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.
140
141The results would be best when using the [**fast asserts**](assertions.html#fast-asserts) coupled with the [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](configuration.html#doctest_config_super_fast_asserts) config identifier and by defining your own macro aliases - like shown [**here**](../../examples/all_features/doctest_proxy.h).
142
143Checkout 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).
144
145Currently [**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.
146
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]147## Floating point comparisons
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]148
149When 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.
150
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]151**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]152
153```
154REQUIRE(performComputation() == doctest::Approx(2.1));
155```
156
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]157By 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]158
159```
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]160REQUIRE(22.0/7 == doctest::Approx(3.141).epsilon(0.01)); // allow for a 1% error
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]161```
162
163When 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.
164
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]165--------
166
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]167- 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]168- Do not wrap assertion macros in ```try```/```catch``` - the REQUIRE macros throw exceptions to end the test case execution!
169
170---------------
171
172[Home](readme.html#reference)
173
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]174<p align="center"><img src="../../scripts/data/logo/icon_2.svg"></p>
175
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]176
177</xmp>
178<script src="strapdown.js/strapdown.js"></script>
179</html>