diff options
Diffstat (limited to 'docs/reference/matchers.md')
| -rw-r--r-- | docs/reference/matchers.md | 38 |
1 files changed, 34 insertions, 4 deletions
diff --git a/docs/reference/matchers.md b/docs/reference/matchers.md index 243e3f9..8b3d140 100644 --- a/docs/reference/matchers.md +++ b/docs/reference/matchers.md @@ -42,6 +42,8 @@ Matcher | Description | `Lt(value)` | `argument < value` | | `Ne(value)` | `argument != value` | | `IsFalse()` | `argument` evaluates to `false` in a Boolean context. | +| `DistanceFrom(target, m)` | The distance between `argument` and `target` (computed by `abs(argument - target)`) matches `m`. | +| `DistanceFrom(target, get_distance, m)` | The distance between `argument` and `target` (computed by `get_distance(argument, target)`) matches `m`. | | `IsTrue()` | `argument` evaluates to `true` in a Boolean context. | | `IsNull()` | `argument` is a `NULL` pointer (raw or smart). | | `NotNull()` | `argument` is a non-null pointer (raw or smart). | @@ -109,6 +111,33 @@ use the regular expression syntax defined [here](../advanced.md#regular-expression-syntax). All of these matchers, except `ContainsRegex()` and `MatchesRegex()` work for wide strings as well. +## Exception Matchers + +| Matcher | Description | +| :---------------------------------------- | :------------------------------- | +| `Throws<E>()` | The `argument` is a callable object that, when called, throws an exception of the expected type `E`. | +| `Throws<E>(m)` | The `argument` is a callable object that, when called, throws an exception of type `E` that satisfies the matcher `m`. | +| `ThrowsMessage<E>(m)` | The `argument` is a callable object that, when called, throws an exception of type `E` with a message that satisfies the matcher `m`. | + +Examples: + +```cpp +auto argument = [] { throw std::runtime_error("error msg"); }; + +// Checks if the lambda throws a `std::runtime_error`. +EXPECT_THAT(argument, Throws<std::runtime_error>()); + +// Checks if the lambda throws a `std::runtime_error` with a specific message +// that matches "error msg". +EXPECT_THAT(argument, + Throws<std::runtime_error>(Property(&std::runtime_error::what, + Eq("error msg")))); + +// Checks if the lambda throws a `std::runtime_error` with a message that +// contains "msg". +EXPECT_THAT(argument, ThrowsMessage<std::runtime_error>(HasSubstr("msg"))); +``` + ## Container Matchers Most STL-style containers support `==`, so you can use `Eq(expected_container)` @@ -171,6 +200,11 @@ messages, you can use: | `Property(&class::property, m)` | `argument.property()` (or `argument->property()` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. The method `property()` must take no argument and be declared as `const`. | | `Property(property_name, &class::property, m)` | The same as the two-parameter version, but provides a better error message. +{: .callout .warning} +Warning: Don't use `Property()` against member functions that you do not own, +because taking addresses of functions is fragile and generally not part of the +contract of the function. + **Notes:** * You can use `FieldsAre()` to match any type that supports structured @@ -189,10 +223,6 @@ messages, you can use: EXPECT_THAT(s, FieldsAre(42, "aloha")); ``` -* Don't use `Property()` against member functions that you do not own, because - taking addresses of functions is fragile and generally not part of the - contract of the function. - ## Matching the Result of a Function, Functor, or Callback | Matcher | Description | |