third-party/unittest/googletest/include/gtest/gtest-assertion-result.h

   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 class GTEST_API_ AssertionResult {
 134  public:
 135   // Copy constructor.
 136   // Used in EXPECT_TRUE/FALSE(assertion_result).
 137   AssertionResult(const AssertionResult& other);
 138
 139 // C4800 is a level 3 warning in Visual Studio 2015 and earlier.
 140 // This warning is not emitted in Visual Studio 2017.
 141 // This warning is off by default starting in Visual Studio 2019 but can be
 142 // enabled with command-line options.
 143 #if defined(_MSC_VER) && (_MSC_VER < 1910 || _MSC_VER >= 1920)
 144   GTEST_DISABLE_MSC_WARNINGS_PUSH_(4800 /* forcing value to bool */)
 145 #endif
 146
 147   // Used in the EXPECT_TRUE/FALSE(bool_expression).
 148   //
 149   // T must be contextually convertible to bool.
 150   //
 151   // The second parameter prevents this overload from being considered if
 152   // the argument is implicitly convertible to AssertionResult. In that case
 153   // we want AssertionResult's copy constructor to be used.
 154   template <typename T>
 155   explicit AssertionResult(
 156       const T& success,
 157       typename std::enable_if<
 158           !std::is_convertible<T, AssertionResult>::value>::type*
 159       /*enabler*/
 160       = nullptr)
 161       : success_(success) {}
 162
 163 #if defined(_MSC_VER) && (_MSC_VER < 1910 || _MSC_VER >= 1920)
 164   GTEST_DISABLE_MSC_WARNINGS_POP_()
 165 #endif
 166
 167   // Assignment operator.
 168   AssertionResult& operator=(AssertionResult other) {
 169     swap(other);
 170     return *this;
 171   }
 172
 173   // Returns true if and only if the assertion succeeded.
 174   operator bool() const { return success_; }  // NOLINT
 175
 176   // Returns the assertion's negation. Used with EXPECT/ASSERT_FALSE.
 177   AssertionResult operator!() const;
 178
 179   // Returns the text streamed into this AssertionResult. Test assertions
 180   // use it when they fail (i.e., the predicate's outcome doesn't match the
 181   // assertion's expectation). When nothing has been streamed into the
 182   // object, returns an empty string.
 183   const char* message() const {
 184     return message_ != nullptr ? message_->c_str() : "";
 185   }
 186   // Deprecated; please use message() instead.
 187   const char* failure_message() const { return message(); }
 188
 189   // Streams a custom failure message into this object.
 190   template <typename T>
 191   AssertionResult& operator<<(const T& value) {
 192     AppendMessage(Message() << value);
 193     return *this;
 194   }
 195
 196   // Allows streaming basic output manipulators such as endl or flush into
 197   // this object.
 198   AssertionResult& operator<<(
 199       ::std::ostream& (*basic_manipulator)(::std::ostream& stream)) {
 200     AppendMessage(Message() << basic_manipulator);
 201     return *this;
 202   }
 203
 204  private:
 205   // Appends the contents of message to message_.
 206   void AppendMessage(const Message& a_message) {
 207     if (message_ == nullptr) message_ = ::std::make_unique<::std::string>();
 208     message_->append(a_message.GetString().c_str());
 209   }
 210
 211   // Swap the contents of this AssertionResult with other.
 212   void swap(AssertionResult& other);
 213
 214   // Stores result of the assertion predicate.
 215   bool success_;
 216   // Stores the message describing the condition in case the expectation
 217   // construct is not satisfied with the predicate's outcome.
 218   // Referenced via a pointer to avoid taking too much stack frame space
 219   // with test assertions.
 220   std::unique_ptr< ::std::string> message_;
 221 };
 222
 223 // Makes a successful assertion result.
 224 GTEST_API_ AssertionResult AssertionSuccess();
 225
 226 // Makes a failed assertion result.
 227 GTEST_API_ AssertionResult AssertionFailure();
 228
 229 // Makes a failed assertion result with the given failure message.
 230 // Deprecated; use AssertionFailure() << msg.
 231 GTEST_API_ AssertionResult AssertionFailure(const Message& msg);
 232
 233 }  // namespace testing
 234
 235 GTEST_DISABLE_MSC_WARNINGS_POP_()  // 4251
 236
 237 #endif  // GOOGLETEST_INCLUDE_GTEST_GTEST_ASSERTION_RESULT_H_