onqtam | 8126b56 | 2016-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 | |
| 8 | Most 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 | |
| 12 | Most of these macros come in two forms: |
| 13 | |
| 14 | ## Natural Expressions |
| 15 | |
| 16 | The ```REQUIRE``` family of macros tests an expression and aborts the test case if it fails. |
| 17 | |
| 18 | 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. |
| 19 | |
| 20 | The ```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 | |
| 26 | Evaluates 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 | |
| 28 | Examples: |
| 29 | |
| 30 | ``` |
| 31 | CHECK(str == "string value"); |
| 32 | CHECK(thisReturnsTrue()); |
| 33 | REQUIRE(i == 42); |
| 34 | ``` |
| 35 | |
| 36 | * **REQUIRE_FALSE(** _expression_ **)** |
| 37 | * **CHECK_FALSE(** _expression_ **)** |
| 38 | * **WARN_FALSE(** _expression_ **)** |
| 39 | |
| 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). |
| 42 | |
| 43 | Example: |
| 44 | |
| 45 | ``` |
| 46 | REQUIRE_FALSE(thisReturnsFalse()); |
| 47 | ``` |
| 48 | |
| 49 | ### Floating point comparisons |
| 50 | |
| 51 | 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. |
| 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 | ``` |
| 56 | REQUIRE(performComputation() == doctest::Approx(2.1)); |
| 57 | ``` |
| 58 | |
| 59 | By 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 | ``` |
| 62 | REQUIRE(22/7 == doctest::Approx(3.141).epsilon(0.01)); |
| 63 | ``` |
| 64 | |
| 65 | When 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 | |
| 73 | Expects 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 | |
| 79 | Expects 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 | |
| 85 | Expects 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> |