docs/assertions.md

   1 # Assertion Macros
   2
   3 Most test frameworks have a large collection of assertion macros to capture all possible conditional forms (```_EQUALS```, ```_NOTEQUALS```, ```_GREATER_THAN``` etc).
   4
   5 Catch is different. 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 auxilliary macros as well. We'll describe all of these here.
   6
   7 Most of these macros come in two forms:
   8
   9 ## Natural Expressions
  10
  11 The ```REQUIRE``` family of macros tests an expression and aborts the test case if it fails.
  12 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.
  13
  14 * **REQUIRE(** _expression_ **)** and
  15 * **CHECK(** _expression_ **)**
  16
  17 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
  18
  19 Examples:
  20 ```
  21 CHECK( str == "string value" );
  22 CHECK( thisReturnsTrue() );
  23 REQUIRE( i == 42 );
  24 ```
  25
  26 * **REQUIRE_FALSE(** _expression_ **)** and
  27 * **CHECK_FALSE(** _expression_ **)**
  28
  29 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.
  30 (these forms exist as a workaround for the fact that ! prefixed expressions cannot be decomposed).
  31
  32 Example:
  33 ```
  34 REQUIRE_FALSE( thisReturnsFalse() );
  35 ```
  36
  37 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).
  38
  39 Examples:
  40 * `CHECK(a == 1 && b == 2);`
  41 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);`
  42 * `CHECK( a == 2 || b == 1 );`
  43 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).
  44
  45
  46 ### Floating point comparisons
  47
  48 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.
  49
  50 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:
  51
  52 ```
  53 REQUIRE( performComputation() == Approx( 2.1 ) );
  54 ```
  55
  56 This way `Approx` is constructed with reasonable defaults, covering most simple cases of rounding errors. If these are insufficient, each `Approx` instance has 3 tuning knobs, that can be used to customize it for your computation.
  57
  58 * __epsilon__ - epsilon serves to set the percentage by which a result can be erroneous, before it is rejected. By default set to `std::numeric_limits<float>::epsilon()*100`.
  59 * __margin__ - margin serves to set the the absolute value by which a result can be erroneous before it is rejected. By default set to `0.0`.
  60 * __scale__ - scale serves to adjust the base for comparison used by epsilon. By default set to `1.0`.
  61
  62 #### epsilon example
  63 ```cpp
  64 Approx target = Approx(100).epsilon(0.01);
  65 100.0 == target; // Obviously true
  66 200.0 == target; // Obviously still false
  67 100.5 == target; // True, because we set target to allow up to 1% error
  68 ```
  69
  70 #### margin example
  71 _Margin check is used only if the relative (epsilon and scale based) check fails._
  72 ```cpp
  73 Approx target = Approx(100).margin(5);
  74 100.0 == target; // Obviously true
  75 200.0 == target; // Obviously still false
  76 104.0 == target; // True, because we set target to allow absolute error up to 5
  77 ```
  78
  79 #### scale
  80 Scale can be useful if the computation leading to the result worked on different scale, than is used by the results (and thus expected errors are on a different scale than would be expected based on the results alone), i.e. an additional not scaling difference will be accepted, because | current - target | < eps_rel + eps_abs (while eps_rel = max(current, target) * epsilon, eps_abs = epsilon * scale) will be checked.
  81
  82
  83 ## Exceptions
  84
  85 * **REQUIRE_NOTHROW(** _expression_ **)** and
  86 * **CHECK_NOTHROW(** _expression_ **)**
  87
  88 Expects that no exception is thrown during evaluation of the expression.
  89
  90 * **REQUIRE_THROWS(** _expression_ **)** and
  91 * **CHECK_THROWS(** _expression_ **)**
  92
  93 Expects that an exception (of any type) is be thrown during evaluation of the expression.
  94
  95 * **REQUIRE_THROWS_AS(** _expression_, _exception type_ **)** and
  96 * **CHECK_THROWS_AS(** _expression_, _exception type_ **)**
  97
  98 Expects that an exception of the _specified type_ is thrown during evaluation of the expression. Note that the _exception type_ is used verbatim and you should include (const) reference.
  99
 100 * **REQUIRE_THROWS_WITH(** _expression_, _string or string matcher_ **)** and
 101 * **CHECK_THROWS_WITH(** _expression_, _string or string matcher_ **)**
 102
 103 Expects that an exception is thrown that, when converted to a string, matches the _string_ or _string matcher_ provided (see next section for Matchers).
 104
 105 e.g.
 106 ```cpp
 107 REQUIRE_THROWS_WITH( openThePodBayDoors(), Contains( "afraid" ) && Contains( "can't do that" ) );
 108 REQUIRE_THROWS_WITH( dismantleHal(), "My mind is going" );
 109 ```
 110
 111
 112 Please note that the `THROW` family of assertions expects to be passed a single expression, not a statement or series of statements. If you want to check a more complicated sequence of operations, you can use a C++11 lambda function.
 113
 114 ```cpp
 115 REQUIRE_NOTHROW([&](){
 116     int i = 1;
 117     int j = 2;
 118     auto k = i + j;
 119     if (k == 3) {
 120         throw 1;
 121     }
 122 }());
 123 ```
 124
 125 ## Matcher expressions
 126
 127 To support Matchers a slightly different form is used. Matchers have [their own documentation](matchers.md).
 128
 129 * **REQUIRE_THAT(** _lhs_, _matcher expression_ **)** and
 130 * **CHECK_THAT(** _lhs_, _matcher expression_ **)**
 131
 132 Matchers can be composed using `&&`, `||` and `!` operators.
 133
 134 ## Thread Safety
 135
 136 Currently assertions in Catch are not thread safe.
 137 For more details, along with workarounds, see the section on [the limitations page](limitations.md#thread-safe-assertions).
 138
 139 ---
 140
 141 [Home](Readme.md)