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
49GTEST_DISABLE_MSC_WARNINGS_PUSH_(4251 \
50/* class A needs to have dll-interface to be used by clients of class B */)
51
52namespace 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)
137class [[nodiscard]] AssertionResult;
138#endif // !SWIG
139
140class 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(a_message: 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(a_message: 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(s: 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.
231GTEST_API_ AssertionResult AssertionSuccess();
232
233// Makes a failed assertion result.
234GTEST_API_ AssertionResult AssertionFailure();
235
236// Makes a failed assertion result with the given failure message.
237// Deprecated; use AssertionFailure() << msg.
238GTEST_API_ AssertionResult AssertionFailure(const Message& msg);
239
240} // namespace testing
241
242GTEST_DISABLE_MSC_WARNINGS_POP_() // 4251
243
244#endif // GOOGLETEST_INCLUDE_GTEST_GTEST_ASSERTION_RESULT_H_
245