Gitiles
Code Review Sign In
gerrit.cesnet.cz / github / onqtam / doctest / 4ca98877b41a3f01bccc1c9d057b69c1fe0620f4 / . / doc / html_generated / assertions.html
blob: 12db9a6ea2c39b148f13138ac1099aca339a0c37 [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
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]22Note 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.
23
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]24## Expression decomposing asserts
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]25
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]26These are of the form ```CHECK(expression)``` (Same for ```REQUIRE``` and ```WARN```).
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]27
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]28```expression``` can be a binary comparison like ```a == b``` or just a single thing like ```vec.isEmpty()```.
29
30If 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]31
32Examples:
33
34```
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]35CHECK(flags == state::alive | state::moving);
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]36CHECK(thisReturnsTrue());
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]37REQUIRE(i < 42);
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]38```
39
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]40Negating asserts - ```<LEVEL>_FALSE(expression)``` - evaluates the expression and records the _logical NOT_ of the result.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]41
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]42These forms exist as a workaround for the fact that ```!``` prefixed expressions cannot be decomposed properly.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]43
44Example:
45
46```
47REQUIRE_FALSE(thisReturnsFalse());
48```
49
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]50Note 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.
51
52Examples:
53
54```
55INFO("this is relevant to all asserts, and here is some var: " << local);
56
57CHECK_MESSAGE(a < b, "relevant only to this assert " << other_local << "more text!");
58
59CHECK(b < c); // here only the first INFO() will be relevant
60```
61
62For more information about the ```INFO()``` macro and logging with the streaming ```operator<<``` visit the [logging page](logging.html).
63
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]64## Binary and unary asserts
65
66These asserts don't use templates to decompose the comparison expressions for the left and right parts.
67
onqtam4aff18c2017-05-17 04:10:03 +0300[diff] [blame]68These 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]69
70```<LEVEL>``` is one of 3 possible: ```REQUIRE```/```CHECK```/```WARN```.
71
72- ```<LEVEL>_EQ(left, right)``` - same as ```<LEVEL>(left == right)```
73- ```<LEVEL>_NE(left, right)``` - same as ```<LEVEL>(left != right)```
74- ```<LEVEL>_GT(left, right)``` - same as ```<LEVEL>(left > right)```
75- ```<LEVEL>_LT(left, right)``` - same as ```<LEVEL>(left < right)```
76- ```<LEVEL>_GE(left, right)``` - same as ```<LEVEL>(left >= right)```
77- ```<LEVEL>_LE(left, right)``` - same as ```<LEVEL>(left <= right)```
78- ```<LEVEL>_UNARY(expr)``` - same as ```<LEVEL>(expr)```
79- ```<LEVEL>_UNARY_FALSE(expr)``` - same as ```<LEVEL>_FALSE(expr)```
80
81## Fast asserts
82
onqtam4aff18c2017-05-17 04:10:03 +0300[diff] [blame]83These 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]84
85The difference is they don't evaluate the expression in a ```try/catch``` block - if the expression throws the whole test case ends.
86
onqtam4aff18c2017-05-17 04:10:03 +0300[diff] [blame]87There 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]88
89```<LEVEL>``` is one of 3 possible: ```REQUIRE```/```CHECK```/```WARN```.
90
91- ```FAST_<LEVEL>_EQ(left, right)``` - almost the same as ```<LEVEL>(left == right)```
92- ```FAST_<LEVEL>_NE(left, right)``` - almost the same as ```<LEVEL>(left != right)```
93- ```FAST_<LEVEL>_GT(left, right)``` - almost the same as ```<LEVEL>(left > right)```
94- ```FAST_<LEVEL>_LT(left, right)``` - almost the same as ```<LEVEL>(left < right)```
95- ```FAST_<LEVEL>_GE(left, right)``` - almost the same as ```<LEVEL>(left >= right)```
96- ```FAST_<LEVEL>_LE(left, right)``` - almost the same as ```<LEVEL>(left <= right)```
97- ```FAST_<LEVEL>_UNARY(expr)``` - almost the same as ```<LEVEL>(expr)```
98- ```FAST_<LEVEL>_UNARY_FALSE(expr)``` - almost the same as ```<LEVEL>_FALSE(expr)```
99
100## Exceptions
101
102```<LEVEL>``` is one of 3 possible: ```REQUIRE```/```CHECK```/```WARN```.
103
104- ```<LEVEL>_THROWS(expression)```
105
106Expects that an exception (of any type) is thrown during evaluation of the expression.
107
108* ```<LEVEL>_THROWS_AS(expression, exception_type)```
109
110Expects that an exception of the _specified type_ is thrown during evaluation of the expression.
111
onqtam6a5da422017-09-04 17:56:08 +0300[diff] [blame]112Note that ```const``` and ```&``` are added to the exception type - so users are expected to specify just the type of the exception - the standard practice for exceptions in C++ is ```Throw by value, catch by (const) reference```.
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]113
114```
onqtam6a5da422017-09-04 17:56:08 +0300[diff] [blame]115CHECK_THROWS_AS(func(), std::exception); // note the reference and the const
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]116```
117
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]118* ```<LEVEL>_NOTHROW(expression)```
119
120Expects that no exception is thrown during evaluation of the expression.
121
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]122Note 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.
123
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]124## Floating point comparisons
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]125
126When 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.
127
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]128**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]129
130```
131REQUIRE(performComputation() == doctest::Approx(2.1));
132```
133
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]134By 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]135
136```
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]137REQUIRE(22.0/7 == doctest::Approx(3.141).epsilon(0.01)); // allow for a 1% error
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]138```
139
140When 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.
141
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]142--------
143
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]144- 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]145- Do not wrap assertion macros in ```try```/```catch``` - the REQUIRE macros throw exceptions to end the test case execution!
146
147---------------
148
149[Home](readme.html#reference)
150
151
152</xmp>
153<script src="strapdown.js/strapdown.js"></script>
154</html>