From f8ed0e687c806bc70871f3f556d848a79bff4c01 Mon Sep 17 00:00:00 2001 From: Abseil Team Date: Tue, 24 Jun 2025 06:21:50 -0700 Subject: [PATCH] Add documentation for exception matchers. PiperOrigin-RevId: 775205267 Change-Id: I3ad59ff4b1fa095cbf7dd04dd97a152cb33c7435 --- docs/reference/matchers.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/reference/matchers.md b/docs/reference/matchers.md index 8ff9e0bc..8b3d1405 100644 --- a/docs/reference/matchers.md +++ b/docs/reference/matchers.md @@ -111,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()` | The `argument` is a callable object that, when called, throws an exception of the expected type `E`. | +| `Throws(m)` | The `argument` is a callable object that, when called, throws an exception of type `E` that satisfies the matcher `m`. | +| `ThrowsMessage(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()); + +// Checks if the lambda throws a `std::runtime_error` with a specific message +// that matches "error msg". +EXPECT_THAT(argument, + Throws(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(HasSubstr("msg"))); +``` + ## Container Matchers Most STL-style containers support `==`, so you can use `Eq(expected_container)`