catch2/docs/assertions.md

65 lines
2.5 KiB
Markdown
Raw Normal View History

2013-06-10 09:18:26 +02:00
# Assertion Macros
2013-10-02 09:17:46 +02:00
Most test frameworks have a large collection of assertion macros to capture all possible conditional forms (```_EQUALS```, ```_NOTEQUALS```, ```_GREATER_THAN``` etc).
2013-06-10 09:18:26 +02:00
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.
Most of these macros come in two forms:
## Natural Expressions
2013-10-02 09:17:46 +02:00
The ```REQUIRE``` family of macros tests an expression and aborts the test case if it fails.
2014-06-11 09:17:17 +02:00
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.
2013-10-02 09:17:46 +02:00
* **REQUIRE(** _expression_ **)** and
* **CHECK(** _expression_ **)**
2013-06-10 09:18:26 +02:00
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
Examples:
```c++
CHECK( str == "string value" );
CHECK( thisReturnsTrue() );
REQUIRE( i == 42 );
```
2013-10-02 09:17:46 +02:00
* **REQUIRE_FALSE(** _expression_ **)** and
* **CHECK_FALSE(** _expression_ **)**
2013-06-10 09:18:26 +02:00
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.
(these forms exist as a workaround for the fact that ! prefixed expressions cannot be decomposed).
Example:
```c++
REQUIRE_FALSE( thisReturnsFalse() );
```
## Exceptions
2013-10-02 09:17:46 +02:00
* **REQUIRE_THROWS(** _expression_ **)** and
* **CHECK_THROWS(** _expression_ **)**
2013-06-10 09:18:26 +02:00
Expects that an exception (of any type) is be thrown during evaluation of the expression.
2014-05-29 00:27:34 +02:00
* **REQUIRE_THROWS_AS(** _expression_, _exception type_ **)** and
2013-10-02 09:17:46 +02:00
* **CHECK_THROWS_AS(** _expression_, _exception type_ **)**
2013-06-10 09:18:26 +02:00
Expects that an exception of the _specified type_ is thrown during evaluation of the expression.
2013-10-02 09:17:46 +02:00
* **REQUIRE_NOTHROW(** _expression_ **)** and
* **CHECK_NOTHROW(** _expression_ **)**
2013-06-10 09:18:26 +02:00
Expects that no exception is thrown during evaluation of the expression.
## Matcher expressions
To support Matchers a slightly different form is used. Matchers will be more fully documented elsewhere. *Note that Matchers are still at early stage development and are subject to change.*
2013-10-02 09:17:46 +02:00
* **REQUIRE_THAT(** _lhs_, _matcher call_ **)** and
* **CHECK_THAT(** _lhs_, _matcher call_ **)**
2013-06-10 09:18:26 +02:00
---
2014-05-29 00:27:34 +02:00
[Home](../README.md)