You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/assertions.md
+45-63Lines changed: 45 additions & 63 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,6 +3,7 @@
3
3
4
4
**Contents**<br>
5
5
[Natural Expressions](#natural-expressions)<br>
6
+
[Floating point comparisons](#floating-point-comparisons)<br>
6
7
[Exceptions](#exceptions)<br>
7
8
[Matcher expressions](#matcher-expressions)<br>
8
9
[Thread Safety](#thread-safety)<br>
@@ -22,7 +23,7 @@ Most of these macros come in two forms:
22
23
The ```REQUIRE``` family of macros tests an expression and aborts the test case if it fails.
23
24
The ```CHECK``` family are equivalent but execution continues in the same test case even if the assertion fails. This is 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.
24
25
25
-
***REQUIRE(**_expression_**)** and
26
+
***REQUIRE(**_expression_**)** and
26
27
***CHECK(**_expression_**)**
27
28
28
29
Evaluates the expression and records the result. If an exception is thrown, it is caught, reported, and counted as a failure. These are the macros you will use most of the time.
@@ -34,101 +35,82 @@ CHECK( thisReturnsTrue() );
34
35
REQUIRE( i == 42 );
35
36
```
36
37
37
-
***REQUIRE_FALSE(**_expression_**)** and
38
+
Expressions prefixed with `!` cannot be decomposed. If you have a type
39
+
that is convertible to bool and you want to assert that it evaluates to
40
+
false, use the two forms below:
41
+
42
+
43
+
***REQUIRE_FALSE(**_expression_**)** and
38
44
***CHECK_FALSE(**_expression_**)**
39
45
40
-
Evaluates the expression and records the _logical NOT_ of the result. If an exception is thrown it is caught, reported, and counted as a failure.
41
-
(these forms exist as a workaround for the fact that ! prefixed expressions cannot be decomposed).
46
+
Note that there is no reason to use these forms for plain bool variables,
47
+
because there is no added value in decomposing them.
42
48
43
49
Example:
50
+
```cpp
51
+
Status ret = someFunction();
52
+
REQUIRE_FALSE(ret); // ret must evaluate to false, and Catch2 will print
53
+
// out the value of ret if possibly
44
54
```
45
-
REQUIRE_FALSE( thisReturnsFalse() );
46
-
```
47
-
48
-
Do note that "overly complex" expressions cannot be decomposed and thus will not compile. This is done partly for practical reasons (to keep the underlying expression template machinery to minimum) and partly for philosophical reasons (assertions should be simple and deterministic).
49
-
50
-
Examples:
51
-
*`CHECK(a == 1 && b == 2);`
52
-
This expression is too complex because of the `&&` operator. If you want to check that 2 or more properties hold, you can either put the expression into parenthesis, which stops decomposition from working, or you need to decompose the expression into two assertions: `CHECK( a == 1 ); CHECK( b == 2);`
53
-
*`CHECK( a == 2 || b == 1 );`
54
-
This expression is too complex because of the `||` operator. If you want to check that one of several properties hold, you can put the expression into parenthesis (unlike with `&&`, expression decomposition into several `CHECK`s is not possible).
55
-
56
55
57
56
### Floating point comparisons
58
57
```cpp
59
58
#include <catch2/catch_approx.hpp>
60
59
```
61
60
62
-
When 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.
61
+
### Other limitations
63
62
64
-
Catch provides a way to perform tolerant comparisons of floating point values through use of a wrapper class called `Approx`. `Approx` can be used on either side of a comparison expression. It overloads the comparisons operators to take a tolerance into account. Here's a simple example:
63
+
Note that expressions containing either of the binary logical operators,
64
+
`&&` or `||`, cannot be decomposed and will not compile. The reason behind
65
+
this is that it is impossible to overload `&&` and `||` in a way that
66
+
keeps their short-circuiting semantics, and expression decomposition
67
+
relies on overloaded operators to work.
65
68
66
-
```cpp
67
-
REQUIRE( performComputation() == Approx( 2.1 ) );
68
-
```
69
+
Simple example of an issue with overloading binary logical operators
70
+
is a common pointer idiom, `p && p->foo == 2`. Using the built-in `&&`
71
+
operator, `p` is only dereferenced if it is not null. With overloaded
72
+
`&&`, `p` is always dereferenced, thus causing a segfault if
73
+
`p == nullptr`.
69
74
70
-
Catch also provides a user-defined literal for `Approx`; `_a`. It resides in
71
-
the `Catch::literals` namespace and can be used like so:
72
-
```cpp
73
-
using namespace Catch::literals;
74
-
REQUIRE( performComputation() == 2.1_a );
75
-
```
75
+
If you want to test expression that contains `&&` or `||`, you have two
76
+
options.
76
77
77
-
`Approx` is constructed with defaults that should cover most simple cases.
78
-
For the more complex cases, `Approx` provides 3 customization points:
78
+
1) Enclose it in parentheses. Parentheses force evaluation of the expression
79
+
before the expression decomposition can touch it, and thus it cannot
80
+
be used.
79
81
80
-
*__epsilon__ - epsilon serves to set the coefficient by which a result
81
-
can differ from `Approx`'s value before it is rejected.
82
-
_By default set to `std::numeric_limits<float>::epsilon()*100`._
83
-
*__margin__ - margin serves to set the the absolute value by which
84
-
a result can differ from `Approx`'s value before it is rejected.
85
-
_By default set to `0.0`._
86
-
*__scale__ - scale is used to change the magnitude of `Approx` for relative check.
87
-
_By default set to `0.0`._
82
+
2) Rewrite the expression. `REQUIRE(a == 1 && b == 2)` can always be split
83
+
into `REQUIRE(a == 1); REQUIRE(b == 2);`. Alternatively, if this is a
84
+
common pattern in your tests, think about using [Matchers](#matcher-expressions).
85
+
instead. There is no simple rewrite rule for `||`, but I generally
86
+
believe that if you have `||` in your test expression, you should rethink
87
+
your tests.
88
88
89
-
#### epsilon example
90
-
```cpp
91
-
Approx target = Approx(100).epsilon(0.01);
92
-
100.0 == target; // Obviously true
93
-
200.0 == target; // Obviously still false
94
-
100.5 == target; // True, because we set target to allow up to 1% difference
95
-
```
96
89
97
-
#### margin example
98
-
```cpp
99
-
Approx target = Approx(100).margin(5);
100
-
100.0 == target; // Obviously true
101
-
200.0 == target; // Obviously still false
102
-
104.0 == target; // True, because we set target to allow absolute difference of at most 5
103
-
```
90
+
## Floating point comparisons
104
91
105
-
#### scale
106
-
Scale can be useful if the computation leading to the result worked
107
-
on different scale than is used by the results. Since allowed difference
108
-
between Approx's value and compared value is based primarily on Approx's value
109
-
(the allowed difference is computed as
110
-
`(Approx::scale + Approx::value) * epsilon`), the resulting comparison could
111
-
need rescaling to be correct.
92
+
Comparing floating point numbers is complex, and [so it has its own
Expects that an exception of the _specified type_ is thrown during evaluation of the expression. Note that the _exception type_ is extended with `const&` and you should not include it yourself.
130
112
131
-
***REQUIRE_THROWS_WITH(**_expression_, _string or string matcher_**)** and
113
+
***REQUIRE_THROWS_WITH(**_expression_, _string or string matcher_**)** and
132
114
***CHECK_THROWS_WITH(**_expression_, _string or string matcher_**)**
133
115
```cpp
134
116
#include<catch2/matchers/catch_matchers.hpp>
@@ -166,8 +148,8 @@ REQUIRE_NOTHROW([&](){
166
148
167
149
To support Matchers a slightly different form is used. Matchers have [their own documentation](matchers.md#top).
168
150
169
-
***REQUIRE_THAT(**_lhs_, _matcher expression_**)** and
170
-
***CHECK_THAT(**_lhs_, _matcher expression_**)**
151
+
***REQUIRE_THAT(**_lhs_, _matcher expression_**)** and
152
+
***CHECK_THAT(**_lhs_, _matcher expression_**)**
171
153
172
154
Matchers can be composed using `&&`, `||` and `!` operators.
Copy file name to clipboardExpand all lines: docs/ci-and-misc.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
<aid="top"></a>
2
2
# CI and other odd pieces
3
3
4
-
This page talks about how Catch integrates with Continuous Integration
4
+
This page talks about how Catch integrates with Continuous Integration
5
5
Build Systems may refer to low-level tools, like CMake, or larger systems that run on servers, like Jenkins or TeamCity. This page will talk about both.
6
6
7
7
## Continuous Integration systems
@@ -11,9 +11,9 @@ Probably the most important aspect to using Catch with a build server is the use
11
11
Two of these reporters are built in (XML and JUnit) and the third (TeamCity) is included as a separate header. It's possible that the other two may be split out in the future too - as that would make the core of Catch smaller for those that don't need them.
12
12
13
13
### XML Reporter
14
-
```-r xml```
14
+
```-r xml```
15
15
16
-
The XML Reporter writes in an XML format that is specific to Catch.
16
+
The XML Reporter writes in an XML format that is specific to Catch.
17
17
18
18
The advantage of this format is that it corresponds well to the way Catch works (especially the more unusual features, such as nested sections) and is a fully streaming format - that is it writes output as it goes, without having to store up all its results before it can start writing.
0 commit comments