1 // Copyright 2024 The Abseil Authors.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 //
15 // -----------------------------------------------------------------------------
16 // File: status_matchers.h
17 // -----------------------------------------------------------------------------
18 //
19 // Testing utilities for working with `absl::Status` and `absl::StatusOr`.
20 //
21 // Defines the following utilities:
22 //
23 // ===============
24 // `IsOkAndHolds(m)`
25 // ===============
26 //
27 // This gMock matcher matches a StatusOr<T> value whose status is OK
28 // and whose inner value matches matcher m. Example:
29 //
30 // ```
31 // using ::testing::MatchesRegex;
32 // using ::absl_testing::IsOkAndHolds;
33 // ...
34 // absl::StatusOr<string> maybe_name = ...;
35 // EXPECT_THAT(maybe_name, IsOkAndHolds(MatchesRegex("John .*")));
36 // ```
37 //
38 // ===============================
39 // `StatusIs(status_code_matcher)`
40 // ===============================
41 //
42 // This is a shorthand for
43 // `StatusIs(status_code_matcher, ::testing::_)`
44 // In other words, it's like the two-argument `StatusIs()`, except that it
45 // ignores error message.
46 //
47 // ===============
48 // `IsOk()`
49 // ===============
50 //
51 // Matches an `absl::Status` or `absl::StatusOr<T>` value whose status value
52 // is `absl::StatusCode::kOk.`
53 //
54 // Equivalent to 'StatusIs(absl::StatusCode::kOk)'.
55 // Example:
56 // ```
57 // using ::absl_testing::IsOk;
58 // ...
59 // absl::StatusOr<string> maybe_name = ...;
60 // EXPECT_THAT(maybe_name, IsOk());
61 // Status s = ...;
62 // EXPECT_THAT(s, IsOk());
63 // ```
64
65 #ifndef ABSL_STATUS_STATUS_MATCHERS_H_
66 #define ABSL_STATUS_STATUS_MATCHERS_H_
67
68 #include <ostream> // NOLINT
69 #include <type_traits>
70 #include <utility>
71
72 #include "gmock/gmock.h" // gmock_for_status_matchers.h
73 #include "absl/base/config.h"
74 #include "absl/status/internal/status_matchers.h"
75
76 namespace absl_testing {
77 ABSL_NAMESPACE_BEGIN
78
79 // Returns a gMock matcher that matches a StatusOr<> whose status is
80 // OK and whose value matches the inner matcher.
81 template <typename InnerMatcherT>
82 status_internal::IsOkAndHoldsMatcher<typename std::decay<InnerMatcherT>::type>
IsOkAndHolds(InnerMatcherT && inner_matcher)83 IsOkAndHolds(InnerMatcherT&& inner_matcher) {
84 return status_internal::IsOkAndHoldsMatcher<
85 typename std::decay<InnerMatcherT>::type>(
86 std::forward<InnerMatcherT>(inner_matcher));
87 }
88
89 // Returns a gMock matcher that matches a Status or StatusOr<> whose status code
90 // matches code_matcher and whose error message matches message_matcher.
91 // Typically, code_matcher will be an absl::StatusCode, e.g.
92 //
93 // StatusIs(absl::StatusCode::kInvalidArgument, "...")
94 template <typename StatusCodeMatcherT, typename StatusMessageMatcherT>
StatusIs(StatusCodeMatcherT && code_matcher,StatusMessageMatcherT && message_matcher)95 status_internal::StatusIsMatcher StatusIs(
96 StatusCodeMatcherT&& code_matcher,
97 StatusMessageMatcherT&& message_matcher) {
98 return status_internal::StatusIsMatcher(
99 std::forward<StatusCodeMatcherT>(code_matcher),
100 std::forward<StatusMessageMatcherT>(message_matcher));
101 }
102
103 // Returns a gMock matcher that matches a Status or StatusOr<> and whose status
104 // code matches code_matcher. See above for details.
105 template <typename StatusCodeMatcherT>
StatusIs(StatusCodeMatcherT && code_matcher)106 status_internal::StatusIsMatcher StatusIs(StatusCodeMatcherT&& code_matcher) {
107 return StatusIs(std::forward<StatusCodeMatcherT>(code_matcher), ::testing::_);
108 }
109
110 // Returns a gMock matcher that matches a Status or StatusOr<> which is OK.
IsOk()111 inline status_internal::IsOkMatcher IsOk() {
112 return status_internal::IsOkMatcher();
113 }
114
115 ABSL_NAMESPACE_END
116 } // namespace absl_testing
117
118 #endif // ABSL_STATUS_STATUS_MATCHERS_H_
119