blob: e5288205c795df386c3dfd829bc488bf957b4a41 [file] [log] [blame]
onqtam8126b562016-05-27 17:01:15 +03001<!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
10**doctest** is different (but it's like [**Catch**](https://github.com/philsquared/Catch) in this regard). Because it decomposes natural C-style conditional expressions most of these forms are reduced to one or two that you will use all the time. That said there are a rich set of auxiliary macros as well. We'll describe all of these here.
11
12Most of these macros come in two forms:
13
14## Natural Expressions
15
16The ```REQUIRE``` family of macros tests an expression and aborts the test case if it fails.
17
18The ```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.
19
20The ```WARN``` family will just print the error when the condition is not met - but will not fail the test case.
21
22* **REQUIRE(** _expression_ **)**
23* **CHECK(** _expression_ **)**
24* **WARN(** _expression_ **)**
25
26Evaluates the expression and records the result. If an exception is thrown it is caught, reported, and counted as a failure (unless it is a **WARN**). These are the macros you will use most of the time
27
28Examples:
29
30```
31CHECK(str == "string value");
32CHECK(thisReturnsTrue());
33REQUIRE(i == 42);
34```
35
36* **REQUIRE_FALSE(** _expression_ **)**
37* **CHECK_FALSE(** _expression_ **)**
38* **WARN_FALSE(** _expression_ **)**
39
40Evaluates 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).
42
43Example:
44
45```
46REQUIRE_FALSE(thisReturnsFalse());
47```
48
49### Floating point comparisons
50
51When 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.
52
53**doctest** provides a way to perform tolerant comparisons of floating point values through 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 tolerance into account. Here's a simple example:
54
55```
56REQUIRE(performComputation() == doctest::Approx(2.1));
57```
58
59By default a small epsilon value 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.:
60
61```
62REQUIRE(22/7 == doctest::Approx(3.141).epsilon(0.01));
63```
64
65When 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.
66
67## Exceptions
68
69* **REQUIRE_THROWS(** _expression_ **)**
70* **CHECK_THROWS(** _expression_ **)**
71* **WARN_THROWS(** _expression_ **)**
72
73Expects that an exception (of any type) is be thrown during evaluation of the expression.
74
75* **REQUIRE_THROWS_AS(** _expression_, _exception type_ **)**
76* **CHECK_THROWS_AS(** _expression_, _exception type_ **)**
77* **WARN_THROWS_AS(** _expression_, _exception type_ **)**
78
79Expects that an exception of the _specified type_ is thrown during evaluation of the expression.
80
81* **REQUIRE_NOTHROW(** _expression_ **)**
82* **CHECK_NOTHROW(** _expression_ **)**
83* **WARN_NOTHROW(** _expression_ **)**
84
85Expects that no exception is thrown during evaluation of the expression.
86
87--------
88
89- Check out the [**example**](../../examples/assertion_macros/main.cpp) which shows many of these macros
90- Do not wrap assertion macros in ```try```/```catch``` - the REQUIRE macros throw exceptions to end the test case execution!
91
92---------------
93
94[Home](readme.html#reference)
95
96
97</xmp>
98<script src="strapdown.js/strapdown.js"></script>
99</html>