// Copyright 2007, Google Inc.

// All rights reserved.

//

// Redistribution and use in source and binary forms, with or without

// modification, are permitted provided that the following conditions are

// met:

//

//     * Redistributions of source code must retain the above copyright

// notice, this list of conditions and the following disclaimer.

//     * Redistributions in binary form must reproduce the above

// copyright notice, this list of conditions and the following disclaimer

// in the documentation and/or other materials provided with the

// distribution.

//     * Neither the name of Google Inc. nor the names of its

// contributors may be used to endorse or promote products derived from

// this software without specific prior written permission.

//

// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

// Google Mock - a framework for writing C++ mock classes.

//

// This file implements the ON_CALL() and EXPECT_CALL() macros.

//

// A user can use the ON_CALL() macro to specify the default action of

// a mock method.  The syntax is:

//

//   ON_CALL(mock_object, Method(argument-matchers))

//       .With(multi-argument-matcher)

//       .WillByDefault(action);

//

//  where the .With() clause is optional.

//

// A user can use the EXPECT_CALL() macro to specify an expectation on

// a mock method.  The syntax is:

//

//   EXPECT_CALL(mock_object, Method(argument-matchers))

//       .With(multi-argument-matchers)

//       .Times(cardinality)

//       .InSequence(sequences)

//       .After(expectations)

//       .WillOnce(action)

//       .WillRepeatedly(action)

//       .RetiresOnSaturation();

//

// where all clauses are optional, and .InSequence()/.After()/

// .WillOnce() can appear any number of times.

// GOOGLETEST_CM0002 DO NOT DELETE

#ifndef GMOCK_INCLUDE_GMOCK_GMOCK_SPEC_BUILDERS_H_

#define GMOCK_INCLUDE_GMOCK_GMOCK_SPEC_BUILDERS_H_

#include <map>

#include <set>

#include <sstream>

#include <string>

#include <vector>

#include "gmock/gmock-actions.h"

#include "gmock/gmock-cardinalities.h"

#include "gmock/gmock-matchers.h"

#include "gmock/internal/gmock-internal-utils.h"

#include "gmock/internal/gmock-port.h"

#include "gtest/gtest.h"

#if GTEST_HAS_EXCEPTIONS

# include <stdexcept>  // NOLINT

#endif

GTEST_DISABLE_MSC_WARNINGS_PUSH_(4251 \

/* class A needs to have dll-interface to be used by clients of class B */)

namespace testing {

// An abstract handle of an expectation.

class Expectation;

// A set of expectation handles.

class ExpectationSet;

// Anything inside the 'internal' namespace IS INTERNAL IMPLEMENTATION

// and MUST NOT BE USED IN USER CODE!!!

namespace internal {

// Implements a mock function.

template <typename F> class FunctionMocker;

// Base class for expectations.

class ExpectationBase;

// Implements an expectation.

template <typename F> class TypedExpectation;

// Helper class for testing the Expectation class template.

class ExpectationTester;

// Base class for function mockers.

template <typename F> class FunctionMockerBase;

// Protects the mock object registry (in class Mock), all function

// mockers, and all expectations.

//

// The reason we don't use more fine-grained protection is: when a

// mock function Foo() is called, it needs to consult its expectations

// to see which one should be picked.  If another thread is allowed to

// call a mock function (either Foo() or a different one) at the same

// time, it could affect the "retired" attributes of Foo()'s

// expectations when InSequence() is used, and thus affect which

// expectation gets picked.  Therefore, we sequence all mock function

// calls to ensure the integrity of the mock objects' states.

GTEST_API_ GTEST_DECLARE_STATIC_MUTEX_(g_gmock_mutex);

// Untyped base class for ActionResultHolder<R>.

class UntypedActionResultHolderBase;

// Abstract base class of FunctionMockerBase.  This is the

// type-agnostic part of the function mocker interface.  Its pure

// virtual methods are implemented by FunctionMockerBase.

class GTEST_API_ UntypedFunctionMockerBase {

 public:

  UntypedFunctionMockerBase();

  virtual ~UntypedFunctionMockerBase();

  // Verifies that all expectations on this mock function have been

  // satisfied.  Reports one or more Google Test non-fatal failures

  // and returns false if not.

  bool VerifyAndClearExpectationsLocked()

      GTEST_EXCLUSIVE_LOCK_REQUIRED_(g_gmock_mutex);

  // Clears the ON_CALL()s set on this mock function.

  virtual void ClearDefaultActionsLocked()

      GTEST_EXCLUSIVE_LOCK_REQUIRED_(g_gmock_mutex) = 0;

  // In all of the following Untyped* functions, it's the caller's

  // responsibility to guarantee the correctness of the arguments'

  // types.

  // Performs the default action with the given arguments and returns

  // the action's result.  The call description string will be used in

  // the error message to describe the call in the case the default

  // action fails.

  // L = *

  virtual UntypedActionResultHolderBase* UntypedPerformDefaultAction(

      void* untyped_args, const std::string& call_description) const = 0;

  // Performs the given action with the given arguments and returns

  // the action's result.

  // L = *

  virtual UntypedActionResultHolderBase* UntypedPerformAction(

      const void* untyped_action, void* untyped_args) const = 0;

  // Writes a message that the call is uninteresting (i.e. neither

  // explicitly expected nor explicitly unexpected) to the given

  // ostream.

  virtual void UntypedDescribeUninterestingCall(

      const void* untyped_args,

      ::std::ostream* os) const

          GTEST_LOCK_EXCLUDED_(g_gmock_mutex) = 0;

  // Returns the expectation that matches the given function arguments

  // (or NULL is there's no match); when a match is found,

  // untyped_action is set to point to the action that should be

  // performed (or NULL if the action is "do default"), and

  // is_excessive is modified to indicate whether the call exceeds the

  // expected number.

  virtual const ExpectationBase* UntypedFindMatchingExpectation(

      const void* untyped_args,

      const void** untyped_action, bool* is_excessive,

      ::std::ostream* what, ::std::ostream* why)

          GTEST_LOCK_EXCLUDED_(g_gmock_mutex) = 0;

  // Prints the given function arguments to the ostream.

  virtual void UntypedPrintArgs(const void* untyped_args,

                                ::std::ostream* os) const = 0;

  // Sets the mock object this mock method belongs to, and registers

  // this information in the global mock registry.  Will be called

  // whenever an EXPECT_CALL() or ON_CALL() is executed on this mock

  // method.

  // FIXME: rename to SetAndRegisterOwner().

  void RegisterOwner(const void* mock_obj)

      GTEST_LOCK_EXCLUDED_(g_gmock_mutex);

  // Sets the mock object this mock method belongs to, and sets the

  // name of the mock function.  Will be called upon each invocation

  // of this mock function.

  void SetOwnerAndName(const void* mock_obj, const char* name)

      GTEST_LOCK_EXCLUDED_(g_gmock_mutex);

  // Returns the mock object this mock method belongs to.  Must be

  // called after RegisterOwner() or SetOwnerAndName() has been

  // called.

  const void* MockObject() const

      GTEST_LOCK_EXCLUDED_(g_gmock_mutex);

  // Returns the name of this mock method.  Must be called after

  // SetOwnerAndName() has been called.

  const char* Name() const

      GTEST_LOCK_EXCLUDED_(g_gmock_mutex);

  // Returns the result of invoking this mock function with the given

  // arguments.  This function can be safely called from multiple

  // threads concurrently.  The caller is responsible for deleting the

  // result.

  UntypedActionResultHolderBase* UntypedInvokeWith(void* untyped_args)

      GTEST_LOCK_EXCLUDED_(g_gmock_mutex);

 protected:

  typedef std::vector<const void*> UntypedOnCallSpecs;

  typedef std::vector<internal::linked_ptr<ExpectationBase> >

  UntypedExpectations;

  // Returns an Expectation object that references and co-owns exp,

  // which must be an expectation on this mock function.

  Expectation GetHandleOf(ExpectationBase* exp);

  // Address of the mock object this mock method belongs to.  Only

  // valid after this mock method has been called or

  // ON_CALL/EXPECT_CALL has been invoked on it.

  const void* mock_obj_;  // Protected by g_gmock_mutex.

  // Name of the function being mocked.  Only valid after this mock

  // method has been called.

  const char* name_;  // Protected by g_gmock_mutex.

  // All default action specs for this function mocker.

  UntypedOnCallSpecs untyped_on_call_specs_;

  // All expectations for this function mocker.

  //

  // It's undefined behavior to interleave expectations (EXPECT_CALLs

  // or ON_CALLs) and mock function calls.  Also, the order of

  // expectations is important.  Therefore it's a logic race condition

  // to read/write untyped_expectations_ concurrently.  In order for

  // tools like tsan to catch concurrent read/write accesses to

  // untyped_expectations, we deliberately leave accesses to it

  // unprotected.

  UntypedExpectations untyped_expectations_;

};  // class UntypedFunctionMockerBase

// Untyped base class for OnCallSpec<F>.

class UntypedOnCallSpecBase {

 public:

  // The arguments are the location of the ON_CALL() statement.

  UntypedOnCallSpecBase(const char* a_file, int a_line)

      : file_(a_file), line_(a_line), last_clause_(kNone) {}

  // Where in the source file was the default action spec defined?

  const char* file() const { return file_; }

  int line() const { return line_; }

 protected:

  // Gives each clause in the ON_CALL() statement a name.

  enum Clause {

    // Do not change the order of the enum members!  The run-time

    // syntax checking relies on it.

    kNone,

    kWith,

    kWillByDefault

  };

  // Asserts that the ON_CALL() statement has a certain property.

  void AssertSpecProperty(bool property,

                          const std::string& failure_message) const {

    Assert(property, file_, line_, failure_message);

  }

  // Expects that the ON_CALL() statement has a certain property.

  void ExpectSpecProperty(bool property,

                          const std::string& failure_message) const {

    Expect(property, file_, line_, failure_message);

  }

  const char* file_;

  int line_;

  // The last clause in the ON_CALL() statement as seen so far.

  // Initially kNone and changes as the statement is parsed.

  Clause last_clause_;

};  // class UntypedOnCallSpecBase

// This template class implements an ON_CALL spec.

template <typename F>

class OnCallSpec : public UntypedOnCallSpecBase {

 public:

  typedef typename Function<F>::ArgumentTuple ArgumentTuple;

  typedef typename Function<F>::ArgumentMatcherTuple ArgumentMatcherTuple;

  // Constructs an OnCallSpec object from the information inside

  // the parenthesis of an ON_CALL() statement.

  OnCallSpec(const char* a_file, int a_line,

             const ArgumentMatcherTuple& matchers)

      : UntypedOnCallSpecBase(a_file, a_line),

        matchers_(matchers),

        // By default, extra_matcher_ should match anything.  However,

        // we cannot initialize it with _ as that triggers a compiler

        // bug in Symbian's C++ compiler (cannot decide between two

        // overloaded constructors of Matcher<const ArgumentTuple&>).

        extra_matcher_(A<const ArgumentTuple&>()) {

  }

  // Implements the .With() clause.

  OnCallSpec& With(const Matcher<const ArgumentTuple&>& m) {

    // Makes sure this is called at most once.

    ExpectSpecProperty(last_clause_ < kWith,

                       ".With() cannot appear "

                       "more than once in an ON_CALL().");

    last_clause_ = kWith;

    extra_matcher_ = m;

    return *this;

  }

  // Implements the .WillByDefault() clause.

  OnCallSpec& WillByDefault(const Action<F>& action) {

    ExpectSpecProperty(last_clause_ < kWillByDefault,

                       ".WillByDefault() must appear "

                       "exactly once in an ON_CALL().");

    last_clause_ = kWillByDefault;

    ExpectSpecProperty(!action.IsDoDefault(),

                       "DoDefault() cannot be used in ON_CALL().");

    action_ = action;

    return *this;

  }

  // Returns true iff the given arguments match the matchers.

  bool Matches(const ArgumentTuple& args) const {

    return TupleMatches(matchers_, args) && extra_matcher_.Matches(args);

  }

  // Returns the action specified by the user.

  const Action<F>& GetAction() const {

    AssertSpecProperty(last_clause_ == kWillByDefault,

                       ".WillByDefault() must appear exactly "

                       "once in an ON_CALL().");

    return action_;

  }

 private:

  // The information in statement

  //

  //   ON_CALL(mock_object, Method(matchers))

  //       .With(multi-argument-matcher)

  //       .WillByDefault(action);

  //

  // is recorded in the data members like this:

  //

  //   source file that contains the statement => file_

  //   line number of the statement            => line_

  //   matchers                                => matchers_

  //   multi-argument-matcher                  => extra_matcher_

  //   action                                  => action_

  ArgumentMatcherTuple matchers_;

  Matcher<const ArgumentTuple&> extra_matcher_;

  Action<F> action_;

};  // class OnCallSpec

// Possible reactions on uninteresting calls.

enum CallReaction {

  kAllow,

  kWarn,

  kFail,

};

}  // namespace internal

// Utilities for manipulating mock objects.

class GTEST_API_ Mock {

 public:

  // The following public methods can be called concurrently.

  // Tells Google Mock to ignore mock_obj when checking for leaked

  // mock objects.

  static void AllowLeak(const void* mock_obj)

      GTEST_LOCK_EXCLUDED_(internal::g_gmock_mutex);

  // Verifies and clears all expectations on the given mock object.

  // If the expectations aren't satisfied, generates one or more

  // Google Test non-fatal failures and returns false.

  static bool VerifyAndClearExpectations(void* mock_obj)

      GTEST_LOCK_EXCLUDED_(internal::g_gmock_mutex);

  // Verifies all expectations on the given mock object and clears its

  // default actions and expectations.  Returns true iff the

  // verification was successful.

  static bool VerifyAndClear(void* mock_obj)

      GTEST_LOCK_EXCLUDED_(internal::g_gmock_mutex);

 private:

  friend class internal::UntypedFunctionMockerBase;

  // Needed for a function mocker to register itself (so that we know

  // how to clear a mock object).

  template <typename F>

  friend class internal::FunctionMockerBase;

  template <typename M>

  friend class NiceMock;

  template <typename M>

  friend class NaggyMock;

  template <typename M>

  friend class StrictMock;

  // Tells Google Mock to allow uninteresting calls on the given mock

  // object.

  static void AllowUninterestingCalls(const void* mock_obj)

      GTEST_LOCK_EXCLUDED_(internal::g_gmock_mutex);

  // Tells Google Mock to warn the user about uninteresting calls on

  // the given mock object.

  static void WarnUninterestingCalls(const void* mock_obj)

      GTEST_LOCK_EXCLUDED_(internal::g_gmock_mutex);

  // Tells Google Mock to fail uninteresting calls on the given mock

  // object.

  static void FailUninterestingCalls(const void* mock_obj)

      GTEST_LOCK_EXCLUDED_(internal::g_gmock_mutex);

  // Tells Google Mock the given mock object is being destroyed and

  // its entry in the call-reaction table should be removed.

  static void UnregisterCallReaction(const void* mock_obj)

      GTEST_LOCK_EXCLUDED_(internal::g_gmock_mutex);

  // Returns the reaction Google Mock will have on uninteresting calls

  // made on the given mock object.

  static internal::CallReaction GetReactionOnUninterestingCalls(

      const void* mock_obj)

          GTEST_LOCK_EXCLUDED_(internal::g_gmock_mutex);

  // Verifies that all expectations on the given mock object have been

  // satisfied.  Reports one or more Google Test non-fatal failures

  // and returns false if not.

  static bool VerifyAndClearExpectationsLocked(void* mock_obj)

      GTEST_EXCLUSIVE_LOCK_REQUIRED_(internal::g_gmock_mutex);

  // Clears all ON_CALL()s set on the given mock object.

  static void ClearDefaultActionsLocked(void* mock_obj)

      GTEST_EXCLUSIVE_LOCK_REQUIRED_(internal::g_gmock_mutex);

  // Registers a mock object and a mock method it owns.

  static void Register(

      const void* mock_obj,

      internal::UntypedFunctionMockerBase* mocker)

          GTEST_LOCK_EXCLUDED_(internal::g_gmock_mutex);

  // Tells Google Mock where in the source code mock_obj is used in an

  // ON_CALL or EXPECT_CALL.  In case mock_obj is leaked, this

  // information helps the user identify which object it is.

  static void RegisterUseByOnCallOrExpectCall(

      const void* mock_obj, const char* file, int line)

          GTEST_LOCK_EXCLUDED_(internal::g_gmock_mutex);

  // Unregisters a mock method; removes the owning mock object from

  // the registry when the last mock method associated with it has

  // been unregistered.  This is called only in the destructor of

  // FunctionMockerBase.

  static void UnregisterLocked(internal::UntypedFunctionMockerBase* mocker)

      GTEST_EXCLUSIVE_LOCK_REQUIRED_(internal::g_gmock_mutex);

};  // class Mock

// An abstract handle of an expectation.  Useful in the .After()

// clause of EXPECT_CALL() for setting the (partial) order of

// expectations.  The syntax:

//

//   Expectation e1 = EXPECT_CALL(...)...;

//   EXPECT_CALL(...).After(e1)...;

//

// sets two expectations where the latter can only be matched after

// the former has been satisfied.

//

// Notes:

//   - This class is copyable and has value semantics.

//   - Constness is shallow: a const Expectation object itself cannot

//     be modified, but the mutable methods of the ExpectationBase

//     object it references can be called via expectation_base().

//   - The constructors and destructor are defined out-of-line because

//     the Symbian WINSCW compiler wants to otherwise instantiate them

//     when it sees this class definition, at which point it doesn't have

//     ExpectationBase available yet, leading to incorrect destruction

//     in the linked_ptr (or compilation errors if using a checking

//     linked_ptr).

class GTEST_API_ Expectation {

 public:

  // Constructs a null object that doesn't reference any expectation.

  Expectation();

  ~Expectation();

  // This single-argument ctor must not be explicit, in order to support the

  //   Expectation e = EXPECT_CALL(...);

  // syntax.

  //

  // A TypedExpectation object stores its pre-requisites as

  // Expectation objects, and needs to call the non-const Retire()

  // method on the ExpectationBase objects they reference.  Therefore

  // Expectation must receive a *non-const* reference to the

  // ExpectationBase object.

  Expectation(internal::ExpectationBase& exp);  // NOLINT

  // The compiler-generated copy ctor and operator= work exactly as

  // intended, so we don't need to define our own.

  // Returns true iff rhs references the same expectation as this object does.

  bool operator==(const Expectation& rhs) const {

    return expectation_base_ == rhs.expectation_base_;

  }

  bool operator!=(const Expectation& rhs) const { return !(*this == rhs); }

 private:

  friend class ExpectationSet;

  friend class Sequence;

  friend class ::testing::internal::ExpectationBase;

  friend class ::testing::internal::UntypedFunctionMockerBase;