1
// Copyright 2005, Google Inc.
2
// All rights reserved.
3
//
4
// Redistribution and use in source and binary forms, with or without
5
// modification, are permitted provided that the following conditions are
6
// met:
7
//
8
//     * Redistributions of source code must retain the above copyright
9
// notice, this list of conditions and the following disclaimer.
10
//     * Redistributions in binary form must reproduce the above
11
// copyright notice, this list of conditions and the following disclaimer
12
// in the documentation and/or other materials provided with the
13
// distribution.
14
//     * Neither the name of Google Inc. nor the names of its
15
// contributors may be used to endorse or promote products derived from
16
// this software without specific prior written permission.
17
//
18
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29

30
// The Google C++ Testing and Mocking Framework (Google Test)
31
//
32
// This file implements the AssertionResult type.
33

34
// IWYU pragma: private, include "gtest/gtest.h"
35
// IWYU pragma: friend gtest/.*
36
// IWYU pragma: friend gmock/.*
37

38
#ifndef GOOGLETEST_INCLUDE_GTEST_GTEST_ASSERTION_RESULT_H_
39
#define GOOGLETEST_INCLUDE_GTEST_GTEST_ASSERTION_RESULT_H_
40

41
#include <memory>
42
#include <ostream>
43
#include <string>
44
#include <type_traits>
45

46
#include "gtest/gtest-message.h"
47
#include "gtest/internal/gtest-port.h"
48

49
GTEST_DISABLE_MSC_WARNINGS_PUSH_(4251                                   \
50
/* class A needs to have dll-interface to be used by clients of class B */)
51

52
namespace testing {
53

54
// A class for indicating whether an assertion was successful.  When
55
// the assertion wasn't successful, the AssertionResult object
56
// remembers a non-empty message that describes how it failed.
57
//
58
// To create an instance of this class, use one of the factory functions
59
// (AssertionSuccess() and AssertionFailure()).
60
//
61
// This class is useful for two purposes:
62
//   1. Defining predicate functions to be used with Boolean test assertions
63
//      EXPECT_TRUE/EXPECT_FALSE and their ASSERT_ counterparts
64
//   2. Defining predicate-format functions to be
65
//      used with predicate assertions (ASSERT_PRED_FORMAT*, etc).
66
//
67
// For example, if you define IsEven predicate:
68
//
69
//   testing::AssertionResult IsEven(int n) {
70
//     if ((n % 2) == 0)
71
//       return testing::AssertionSuccess();
72
//     else
73
//       return testing::AssertionFailure() << n << " is odd";
74
//   }
75
//
76
// Then the failed expectation EXPECT_TRUE(IsEven(Fib(5)))
77
// will print the message
78
//
79
//   Value of: IsEven(Fib(5))
80
//     Actual: false (5 is odd)
81
//   Expected: true
82
//
83
// instead of a more opaque
84
//
85
//   Value of: IsEven(Fib(5))
86
//     Actual: false
87
//   Expected: true
88
//
89
// in case IsEven is a simple Boolean predicate.
90
//
91
// If you expect your predicate to be reused and want to support informative
92
// messages in EXPECT_FALSE and ASSERT_FALSE (negative assertions show up
93
// about half as often as positive ones in our tests), supply messages for
94
// both success and failure cases:
95
//
96
//   testing::AssertionResult IsEven(int n) {
97
//     if ((n % 2) == 0)
98
//       return testing::AssertionSuccess() << n << " is even";
99
//     else
100
//       return testing::AssertionFailure() << n << " is odd";
101
//   }
102
//
103
// Then a statement EXPECT_FALSE(IsEven(Fib(6))) will print
104
//
105
//   Value of: IsEven(Fib(6))
106
//     Actual: true (8 is even)
107
//   Expected: false
108
//
109
// NB: Predicates that support negative Boolean assertions have reduced
110
// performance in positive ones so be careful not to use them in tests
111
// that have lots (tens of thousands) of positive Boolean assertions.
112
//
113
// To use this class with EXPECT_PRED_FORMAT assertions such as:
114
//
115
//   // Verifies that Foo() returns an even number.
116
//   EXPECT_PRED_FORMAT1(IsEven, Foo());
117
//
118
// you need to define:
119
//
120
//   testing::AssertionResult IsEven(const char* expr, int n) {
121
//     if ((n % 2) == 0)
122
//       return testing::AssertionSuccess();
123
//     else
124
//       return testing::AssertionFailure()
125
//         << "Expected: " << expr << " is even\n  Actual: it's " << n;
126
//   }
127
//
128
// If Foo() returns 5, you will see the following message:
129
//
130
//   Expected: Foo() is even
131
//     Actual: it's 5
132
//
133

134
// Returned AssertionResult objects may not be ignored.
135
// Note: Disabled for SWIG as it doesn't parse attributes correctly.
136
#if !defined(SWIG)
137
class [[nodiscard]] AssertionResult;
138
#endif  // !SWIG
139

140
class GTEST_API_ AssertionResult {
141
 public:
142
  // Copy constructor.
143
  // Used in EXPECT_TRUE/FALSE(assertion_result).
144
  AssertionResult(const AssertionResult& other);
145

146
// C4800 is a level 3 warning in Visual Studio 2015 and earlier.
147
// This warning is not emitted in Visual Studio 2017.
148
// This warning is off by default starting in Visual Studio 2019 but can be
149
// enabled with command-line options.
150
#if defined(_MSC_VER) && (_MSC_VER < 1910 || _MSC_VER >= 1920)
151
  GTEST_DISABLE_MSC_WARNINGS_PUSH_(4800 /* forcing value to bool */)
152
#endif
153

154
  // Used in the EXPECT_TRUE/FALSE(bool_expression).
155
  //
156
  // T must be contextually convertible to bool.
157
  //
158
  // The second parameter prevents this overload from being considered if
159
  // the argument is implicitly convertible to AssertionResult. In that case
160
  // we want AssertionResult's copy constructor to be used.
161
  template <typename T>
162
  explicit AssertionResult(
163
      const T& success,
164
      typename std::enable_if<
165
          !std::is_convertible<T, AssertionResult>::value>::type*
166
      /*enabler*/
167
      = nullptr)
168
      : success_(success) {}
169

170
#if defined(_MSC_VER) && (_MSC_VER < 1910 || _MSC_VER >= 1920)
171
  GTEST_DISABLE_MSC_WARNINGS_POP_()
172
#endif
173

174
  // Assignment operator.
175
  AssertionResult& operator=(AssertionResult other) {
176
    swap(other);
177
    return *this;
178
  }
179

180
  // Returns true if and only if the assertion succeeded.
181
  operator bool() const { return success_; }  // NOLINT
182

183
  // Returns the assertion's negation. Used with EXPECT/ASSERT_FALSE.
184
  AssertionResult operator!() const;
185

186
  // Returns the text streamed into this AssertionResult. Test assertions
187
  // use it when they fail (i.e., the predicate's outcome doesn't match the
188
  // assertion's expectation). When nothing has been streamed into the
189
  // object, returns an empty string.
190
  const char* message() const {
191
    return message_ != nullptr ? message_->c_str() : "";
192
  }
193
  // Deprecated; please use message() instead.
194
  const char* failure_message() const { return message(); }
195

196
  // Streams a custom failure message into this object.
197
  template <typename T>
198
  AssertionResult& operator<<(const T& value) {
199
    AppendMessage(Message() << value);
200
    return *this;
201
  }
202

203
  // Allows streaming basic output manipulators such as endl or flush into
204
  // this object.
205
  AssertionResult& operator<<(
206
      ::std::ostream& (*basic_manipulator)(::std::ostream& stream)) {
207
    AppendMessage(Message() << basic_manipulator);
208
    return *this;
209
  }
210

211
 private:
212
  // Appends the contents of message to message_.
213
  void AppendMessage(const Message& a_message) {
214
    if (message_ == nullptr) message_ = ::std::make_unique<::std::string>();
215
    message_->append(a_message.GetString().c_str());
216
  }
217

218
  // Swap the contents of this AssertionResult with other.
219
  void swap(AssertionResult& other);
220

221
  // Stores result of the assertion predicate.
222
  bool success_;
223
  // Stores the message describing the condition in case the expectation
224
  // construct is not satisfied with the predicate's outcome.
225
  // Referenced via a pointer to avoid taking too much stack frame space
226
  // with test assertions.
227
  std::unique_ptr< ::std::string> message_;
228
};
229

230
// Makes a successful assertion result.
231
GTEST_API_ AssertionResult AssertionSuccess();
232

233
// Makes a failed assertion result.
234
GTEST_API_ AssertionResult AssertionFailure();
235

236
// Makes a failed assertion result with the given failure message.
237
// Deprecated; use AssertionFailure() << msg.
238
GTEST_API_ AssertionResult AssertionFailure(const Message& msg);
239

240
}  // namespace testing
241

242
GTEST_DISABLE_MSC_WARNINGS_POP_()  // 4251
243

244
#endif  // GOOGLETEST_INCLUDE_GTEST_GTEST_ASSERTION_RESULT_H_
245

246