You can find recipes for using Google Mock here. If you haven't yet,

please read the [ForDummies](V1_7_ForDummies.md) document first to make sure you understand

the basics.

**Note:** Google Mock lives in the `testing` name space. For

readability, it is recommended to write `using ::testing::Foo;` once in

your file before using the name `Foo` defined by Google Mock. We omit

such `using` statements in this page for brevity, but you should do it

in your own code.

# Creating Mock Classes #

## Mocking Private or Protected Methods ##

You must always put a mock method definition (`MOCK_METHOD*`) in a

`public:` section of the mock class, regardless of the method being

mocked being `public`, `protected`, or `private` in the base class.

This allows `ON_CALL` and `EXPECT_CALL` to reference the mock function

from outside of the mock class.  (Yes, C++ allows a subclass to change

the access level of a virtual function in the base class.)  Example:

```

class Foo {

 public:

  ...

  virtual bool Transform(Gadget* g) = 0;

 protected:

  virtual void Resume();

 private:

  virtual int GetTimeOut();

};

class MockFoo : public Foo {

 public:

  ...

  MOCK_METHOD1(Transform, bool(Gadget* g));

  // The following must be in the public section, even though the

  // methods are protected or private in the base class.

  MOCK_METHOD0(Resume, void());

  MOCK_METHOD0(GetTimeOut, int());

};

```

## Mocking Overloaded Methods ##

You can mock overloaded functions as usual. No special attention is required:

```

class Foo {

  ...

  // Must be virtual as we'll inherit from Foo.

  virtual ~Foo();

  // Overloaded on the types and/or numbers of arguments.

  virtual int Add(Element x);

  virtual int Add(int times, Element x);

  // Overloaded on the const-ness of this object.

  virtual Bar& GetBar();

  virtual const Bar& GetBar() const;

};

class MockFoo : public Foo {

  ...

  MOCK_METHOD1(Add, int(Element x));

  MOCK_METHOD2(Add, int(int times, Element x);

  MOCK_METHOD0(GetBar, Bar&());

  MOCK_CONST_METHOD0(GetBar, const Bar&());

};

```

**Note:** if you don't mock all versions of the overloaded method, the

compiler will give you a warning about some methods in the base class

being hidden. To fix that, use `using` to bring them in scope:

```

class MockFoo : public Foo {

  ...

  using Foo::Add;

  MOCK_METHOD1(Add, int(Element x));

  // We don't want to mock int Add(int times, Element x);

  ...

};

```

## Mocking Class Templates ##

To mock a class template, append `_T` to the `MOCK_*` macros:

```

template <typename Elem>

class StackInterface {

  ...

  // Must be virtual as we'll inherit from StackInterface.

  virtual ~StackInterface();

  virtual int GetSize() const = 0;

  virtual void Push(const Elem& x) = 0;

};

template <typename Elem>

class MockStack : public StackInterface<Elem> {

  ...

  MOCK_CONST_METHOD0_T(GetSize, int());

  MOCK_METHOD1_T(Push, void(const Elem& x));

};

```

## Mocking Nonvirtual Methods ##

Google Mock can mock non-virtual functions to be used in what we call _hi-perf

dependency injection_.

In this case, instead of sharing a common base class with the real

class, your mock class will be _unrelated_ to the real class, but

contain methods with the same signatures.  The syntax for mocking

non-virtual methods is the _same_ as mocking virtual methods:

```

// A simple packet stream class.  None of its members is virtual.

class ConcretePacketStream {

 public:

  void AppendPacket(Packet* new_packet);

  const Packet* GetPacket(size_t packet_number) const;

  size_t NumberOfPackets() const;

  ...

};

// A mock packet stream class.  It inherits from no other, but defines

// GetPacket() and NumberOfPackets().

class MockPacketStream {

 public:

  MOCK_CONST_METHOD1(GetPacket, const Packet*(size_t packet_number));

  MOCK_CONST_METHOD0(NumberOfPackets, size_t());

  ...

};

```

Note that the mock class doesn't define `AppendPacket()`, unlike the

real class. That's fine as long as the test doesn't need to call it.

Next, you need a way to say that you want to use

`ConcretePacketStream` in production code, and use `MockPacketStream`

in tests.  Since the functions are not virtual and the two classes are

unrelated, you must specify your choice at _compile time_ (as opposed

to run time).

One way to do it is to templatize your code that needs to use a packet

stream.  More specifically, you will give your code a template type

argument for the type of the packet stream.  In production, you will

instantiate your template with `ConcretePacketStream` as the type

argument.  In tests, you will instantiate the same template with

`MockPacketStream`.  For example, you may write:

```

template <class PacketStream>

void CreateConnection(PacketStream* stream) { ... }

template <class PacketStream>

class PacketReader {

 public:

  void ReadPackets(PacketStream* stream, size_t packet_num);

};

```

Then you can use `CreateConnection<ConcretePacketStream>()` and

`PacketReader<ConcretePacketStream>` in production code, and use

`CreateConnection<MockPacketStream>()` and

`PacketReader<MockPacketStream>` in tests.

```

  MockPacketStream mock_stream;

  EXPECT_CALL(mock_stream, ...)...;

  .. set more expectations on mock_stream ...

  PacketReader<MockPacketStream> reader(&mock_stream);

  ... exercise reader ...

```

## Mocking Free Functions ##

It's possible to use Google Mock to mock a free function (i.e. a

C-style function or a static method).  You just need to rewrite your

code to use an interface (abstract class).

Instead of calling a free function (say, `OpenFile`) directly,

introduce an interface for it and have a concrete subclass that calls

the free function:

```

class FileInterface {

 public:

  ...

  virtual bool Open(const char* path, const char* mode) = 0;

};

class File : public FileInterface {

 public:

  ...

  virtual bool Open(const char* path, const char* mode) {

    return OpenFile(path, mode);

  }

};

```

Your code should talk to `FileInterface` to open a file.  Now it's

easy to mock out the function.

This may seem much hassle, but in practice you often have multiple

related functions that you can put in the same interface, so the

per-function syntactic overhead will be much lower.

If you are concerned about the performance overhead incurred by

virtual functions, and profiling confirms your concern, you can

combine this with the recipe for [mocking non-virtual methods](#Mocking_Nonvirtual_Methods.md).

## The Nice, the Strict, and the Naggy ##

If a mock method has no `EXPECT_CALL` spec but is called, Google Mock

will print a warning about the "uninteresting call". The rationale is:

  * New methods may be added to an interface after a test is written. We shouldn't fail a test just because a method it doesn't know about is called.

  * However, this may also mean there's a bug in the test, so Google Mock shouldn't be silent either. If the user believes these calls are harmless, he can add an `EXPECT_CALL()` to suppress the warning.

However, sometimes you may want to suppress all "uninteresting call"

warnings, while sometimes you may want the opposite, i.e. to treat all

of them as errors. Google Mock lets you make the decision on a

per-mock-object basis.

Suppose your test uses a mock class `MockFoo`:

```

TEST(...) {

  MockFoo mock_foo;

  EXPECT_CALL(mock_foo, DoThis());

  ... code that uses mock_foo ...

}

```

If a method of `mock_foo` other than `DoThis()` is called, it will be

reported by Google Mock as a warning. However, if you rewrite your

test to use `NiceMock<MockFoo>` instead, the warning will be gone,

resulting in a cleaner test output:

```

using ::testing::NiceMock;

TEST(...) {

  NiceMock<MockFoo> mock_foo;

  EXPECT_CALL(mock_foo, DoThis());

  ... code that uses mock_foo ...

}

```

`NiceMock<MockFoo>` is a subclass of `MockFoo`, so it can be used

wherever `MockFoo` is accepted.

It also works if `MockFoo`'s constructor takes some arguments, as

`NiceMock<MockFoo>` "inherits" `MockFoo`'s constructors:

```

using ::testing::NiceMock;

TEST(...) {

  NiceMock<MockFoo> mock_foo(5, "hi");  // Calls MockFoo(5, "hi").

  EXPECT_CALL(mock_foo, DoThis());

  ... code that uses mock_foo ...

}

```

The usage of `StrictMock` is similar, except that it makes all

uninteresting calls failures:

```

using ::testing::StrictMock;

TEST(...) {

  StrictMock<MockFoo> mock_foo;

  EXPECT_CALL(mock_foo, DoThis());

  ... code that uses mock_foo ...

  // The test will fail if a method of mock_foo other than DoThis()

  // is called.

}

```

There are some caveats though (I don't like them just as much as the

next guy, but sadly they are side effects of C++'s limitations):

  1. `NiceMock<MockFoo>` and `StrictMock<MockFoo>` only work for mock methods defined using the `MOCK_METHOD*` family of macros **directly** in the `MockFoo` class. If a mock method is defined in a **base class** of `MockFoo`, the "nice" or "strict" modifier may not affect it, depending on the compiler. In particular, nesting `NiceMock` and `StrictMock` (e.g. `NiceMock<StrictMock<MockFoo> >`) is **not** supported.

  1. The constructors of the base mock (`MockFoo`) cannot have arguments passed by non-const reference, which happens to be banned by the [Google C++ style guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml).

  1. During the constructor or destructor of `MockFoo`, the mock object is _not_ nice or strict.  This may cause surprises if the constructor or destructor calls a mock method on `this` object. (This behavior, however, is consistent with C++'s general rule: if a constructor or destructor calls a virtual method of `this` object, that method is treated as non-virtual.  In other words, to the base class's constructor or destructor, `this` object behaves like an instance of the base class, not the derived class.  This rule is required for safety.  Otherwise a base constructor may use members of a derived class before they are initialized, or a base destructor may use members of a derived class after they have been destroyed.)

Finally, you should be **very cautious** about when to use naggy or strict mocks, as they tend to make tests more brittle and harder to maintain. When you refactor your code without changing its externally visible behavior, ideally you should't need to update any tests. If your code interacts with a naggy mock, however, you may start to get spammed with warnings as the result of your change. Worse, if your code interacts with a strict mock, your tests may start to fail and you'll be forced to fix them. Our general recommendation is to use nice mocks (not yet the default) most of the time, use naggy mocks (the current default) when developing or debugging tests, and use strict mocks only as the last resort.

## Simplifying the Interface without Breaking Existing Code ##

Sometimes a method has a long list of arguments that is mostly

uninteresting. For example,

```

class LogSink {

 public:

  ...

  virtual void send(LogSeverity severity, const char* full_filename,

                    const char* base_filename, int line,

                    const struct tm* tm_time,

                    const char* message, size_t message_len) = 0;

};

```

This method's argument list is lengthy and hard to work with (let's

say that the `message` argument is not even 0-terminated). If we mock

it as is, using the mock will be awkward. If, however, we try to

simplify this interface, we'll need to fix all clients depending on

it, which is often infeasible.

The trick is to re-dispatch the method in the mock class:

```

class ScopedMockLog : public LogSink {

 public:

  ...

  virtual void send(LogSeverity severity, const char* full_filename,

                    const char* base_filename, int line, const tm* tm_time,

                    const char* message, size_t message_len) {

    // We are only interested in the log severity, full file name, and

    // log message.

    Log(severity, full_filename, std::string(message, message_len));

  }

  // Implements the mock method:

  //

  //   void Log(LogSeverity severity,

  //            const string& file_path,

  //            const string& message);

  MOCK_METHOD3(Log, void(LogSeverity severity, const string& file_path,

                         const string& message));

};

```

By defining a new mock method with a trimmed argument list, we make

the mock class much more user-friendly.

## Alternative to Mocking Concrete Classes ##

Often you may find yourself using classes that don't implement

interfaces. In order to test your code that uses such a class (let's

call it `Concrete`), you may be tempted to make the methods of

`Concrete` virtual and then mock it.

Try not to do that.

Making a non-virtual function virtual is a big decision. It creates an

extension point where subclasses can tweak your class' behavior. This

weakens your control on the class because now it's harder to maintain

the class' invariants. You should make a function virtual only when

there is a valid reason for a subclass to override it.

Mocking concrete classes directly is problematic as it creates a tight

coupling between the class and the tests - any small change in the

class may invalidate your tests and make test maintenance a pain.

To avoid such problems, many programmers have been practicing "coding

to interfaces": instead of talking to the `Concrete` class, your code

would define an interface and talk to it. Then you implement that

interface as an adaptor on top of `Concrete`. In tests, you can easily

mock that interface to observe how your code is doing.

This technique incurs some overhead:

  * You pay the cost of virtual function calls (usually not a problem).

  * There is more abstraction for the programmers to learn.

However, it can also bring significant benefits in addition to better

testability:

  * `Concrete`'s API may not fit your problem domain very well, as you may not be the only client it tries to serve. By designing your own interface, you have a chance to tailor it to your need - you may add higher-level functionalities, rename stuff, etc instead of just trimming the class. This allows you to write your code (user of the interface) in a more natural way, which means it will be more readable, more maintainable, and you'll be more productive.

  * If `Concrete`'s implementation ever has to change, you don't have to rewrite everywhere it is used. Instead, you can absorb the change in your implementation of the interface, and your other code and tests will be insulated from this change.

Some people worry that if everyone is practicing this technique, they

will end up writing lots of redundant code. This concern is totally

understandable. However, there are two reasons why it may not be the

case:

  * Different projects may need to use `Concrete` in different ways, so the best interfaces for them will be different. Therefore, each of them will have its own domain-specific interface on top of `Concrete`, and they will not be the same code.

  * If enough projects want to use the same interface, they can always share it, just like they have been sharing `Concrete`. You can check in the interface and the adaptor somewhere near `Concrete` (perhaps in a `contrib` sub-directory) and let many projects use it.

You need to weigh the pros and cons carefully for your particular

problem, but I'd like to assure you that the Java community has been

practicing this for a long time and it's a proven effective technique

applicable in a wide variety of situations. :-)

## Delegating Calls to a Fake ##

Some times you have a non-trivial fake implementation of an

interface. For example:

```

class Foo {

 public:

  virtual ~Foo() {}

  virtual char DoThis(int n) = 0;

  virtual void DoThat(const char* s, int* p) = 0;

};

class FakeFoo : public Foo {

 public:

  virtual char DoThis(int n) {

    return (n > 0) ? '+' :

        (n < 0) ? '-' : '0';

  }

  virtual void DoThat(const char* s, int* p) {

    *p = strlen(s);

  }

};

```

Now you want to mock this interface such that you can set expectations

on it. However, you also want to use `FakeFoo` for the default

behavior, as duplicating it in the mock object is, well, a lot of

work.

When you define the mock class using Google Mock, you can have it

delegate its default action to a fake class you already have, using

this pattern:

```

using ::testing::_;

using ::testing::Invoke;

class MockFoo : public Foo {

 public:

  // Normal mock method definitions using Google Mock.

  MOCK_METHOD1(DoThis, char(int n));

  MOCK_METHOD2(DoThat, void(const char* s, int* p));

  // Delegates the default actions of the methods to a FakeFoo object.

  // This must be called *before* the custom ON_CALL() statements.

  void DelegateToFake() {

    ON_CALL(*this, DoThis(_))

        .WillByDefault(Invoke(&fake_, &FakeFoo::DoThis));

    ON_CALL(*this, DoThat(_, _))

        .WillByDefault(Invoke(&fake_, &FakeFoo::DoThat));

  }

 private:

  FakeFoo fake_;  // Keeps an instance of the fake in the mock.

};

```

With that, you can use `MockFoo` in your tests as usual. Just remember

that if you don't explicitly set an action in an `ON_CALL()` or

`EXPECT_CALL()`, the fake will be called upon to do it:

```

using ::testing::_;

TEST(AbcTest, Xyz) {

  MockFoo foo;

  foo.DelegateToFake(); // Enables the fake for delegation.

  // Put your ON_CALL(foo, ...)s here, if any.

  // No action specified, meaning to use the default action.

  EXPECT_CALL(foo, DoThis(5));

  EXPECT_CALL(foo, DoThat(_, _));

  int n = 0;

  EXPECT_EQ('+', foo.DoThis(5));  // FakeFoo::DoThis() is invoked.

  foo.DoThat("Hi", &n);           // FakeFoo::DoThat() is invoked.

  EXPECT_EQ(2, n);

}

```

**Some tips:**

  * If you want, you can still override the default action by providing your own `ON_CALL()` or using `.WillOnce()` / `.WillRepeatedly()` in `EXPECT_CALL()`.

  * In `DelegateToFake()`, you only need to delegate the methods whose fake implementation you intend to use.

  * The general technique discussed here works for overloaded methods, but you'll need to tell the compiler which version you mean. To disambiguate a mock function (the one you specify inside the parentheses of `ON_CALL()`), see the "Selecting Between Overloaded Functions" section on this page; to disambiguate a fake function (the one you place inside `Invoke()`), use a `static_cast` to specify the function's type. For instance, if class `Foo` has methods `char DoThis(int n)` and `bool DoThis(double x) const`, and you want to invoke the latter, you need to write `Invoke(&fake_, static_cast<bool (FakeFoo::*)(double) const>(&FakeFoo::DoThis))` instead of `Invoke(&fake_, &FakeFoo::DoThis)` (The strange-looking thing inside the angled brackets of `static_cast` is the type of a function pointer to the second `DoThis()` method.).

  * Having to mix a mock and a fake is often a sign of something gone wrong. Perhaps you haven't got used to the interaction-based way of testing yet. Or perhaps your interface is taking on too many roles and should be split up. Therefore, **don't abuse this**. We would only recommend to do it as an intermediate step when you are refactoring your code.

Regarding the tip on mixing a mock and a fake, here's an example on

why it may be a bad sign: Suppose you have a class `System` for

low-level system operations. In particular, it does file and I/O

operations. And suppose you want to test how your code uses `System`

to do I/O, and you just want the file operations to work normally. If

you mock out the entire `System` class, you'll have to provide a fake

implementation for the file operation part, which suggests that

`System` is taking on too many roles.

Instead, you can define a `FileOps` interface and an `IOOps` interface

and split `System`'s functionalities into the two. Then you can mock

`IOOps` without mocking `FileOps`.

## Delegating Calls to a Real Object ##

When using testing doubles (mocks, fakes, stubs, and etc), sometimes

their behaviors will differ from those of the real objects. This

difference could be either intentional (as in simulating an error such

that you can test the error handling code) or unintentional. If your

mocks have different behaviors than the real objects by mistake, you

could end up with code that passes the tests but fails in production.

You can use the _delegating-to-real_ technique to ensure that your

mock has the same behavior as the real object while retaining the

ability to validate calls. This technique is very similar to the

delegating-to-fake technique, the difference being that we use a real

object instead of a fake. Here's an example:

```

using ::testing::_;

using ::testing::AtLeast;

using ::testing::Invoke;

class MockFoo : public Foo {

 public:

  MockFoo() {

    // By default, all calls are delegated to the real object.

    ON_CALL(*this, DoThis())

        .WillByDefault(Invoke(&real_, &Foo::DoThis));

    ON_CALL(*this, DoThat(_))

        .WillByDefault(Invoke(&real_, &Foo::DoThat));

    ...

  }

  MOCK_METHOD0(DoThis, ...);

  MOCK_METHOD1(DoThat, ...);

  ...

 private:

  Foo real_;

};

...

  MockFoo mock;

  EXPECT_CALL(mock, DoThis())

      .Times(3);

  EXPECT_CALL(mock, DoThat("Hi"))

      .Times(AtLeast(1));

  ... use mock in test ...

```

With this, Google Mock will verify that your code made the right calls

(with the right arguments, in the right order, called the right number

of times, etc), and a real object will answer the calls (so the

behavior will be the same as in production). This gives you the best

of both worlds.

## Delegating Calls to a Parent Class ##

Ideally, you should code to interfaces, whose methods are all pure

virtual. In reality, sometimes you do need to mock a virtual method

that is not pure (i.e, it already has an implementation). For example:

```

class Foo {

 public:

  virtual ~Foo();

  virtual void Pure(int n) = 0;

  virtual int Concrete(const char* str) { ... }

};

class MockFoo : public Foo {

 public:

  // Mocking a pure method.

  MOCK_METHOD1(Pure, void(int n));

  // Mocking a concrete method.  Foo::Concrete() is shadowed.

  MOCK_METHOD1(Concrete, int(const char* str));

};

```

Sometimes you may want to call `Foo::Concrete()` instead of

`MockFoo::Concrete()`. Perhaps you want to do it as part of a stub

action, or perhaps your test doesn't need to mock `Concrete()` at all

(but it would be oh-so painful to have to define a new mock class

whenever you don't need to mock one of its methods).

The trick is to leave a back door in your mock class for accessing the

real methods in the base class:

```

class MockFoo : public Foo {

 public:

  // Mocking a pure method.

  MOCK_METHOD1(Pure, void(int n));

  // Mocking a concrete method.  Foo::Concrete() is shadowed.

  MOCK_METHOD1(Concrete, int(const char* str));

  // Use this to call Concrete() defined in Foo.

  int FooConcrete(const char* str) { return Foo::Concrete(str); }

};

```

Now, you can call `Foo::Concrete()` inside an action by:

```

using ::testing::_;

using ::testing::Invoke;

...

  EXPECT_CALL(foo, Concrete(_))

      .WillOnce(Invoke(&foo, &MockFoo::FooConcrete));

```

or tell the mock object that you don't want to mock `Concrete()`:

```

using ::testing::Invoke;

...

  ON_CALL(foo, Concrete(_))

      .WillByDefault(Invoke(&foo, &MockFoo::FooConcrete));

```

(Why don't we just write `Invoke(&foo, &Foo::Concrete)`? If you do

that, `MockFoo::Concrete()` will be called (and cause an infinite

recursion) since `Foo::Concrete()` is virtual. That's just how C++

works.)

# Using Matchers #

## Matching Argument Values Exactly ##

You can specify exactly which arguments a mock method is expecting:

```

using ::testing::Return;

...

  EXPECT_CALL(foo, DoThis(5))

      .WillOnce(Return('a'));

  EXPECT_CALL(foo, DoThat("Hello", bar));

```

## Using Simple Matchers ##

You can use matchers to match arguments that have a certain property:

```

using ::testing::Ge;

using ::testing::NotNull;

using ::testing::Return;

...

  EXPECT_CALL(foo, DoThis(Ge(5)))  // The argument must be >= 5.

      .WillOnce(Return('a'));

  EXPECT_CALL(foo, DoThat("Hello", NotNull()));

  // The second argument must not be NULL.

```

A frequently used matcher is `_`, which matches anything:

```

using ::testing::_;

using ::testing::NotNull;

...

  EXPECT_CALL(foo, DoThat(_, NotNull()));

```

## Combining Matchers ##

You can build complex matchers from existing ones using `AllOf()`,

`AnyOf()`, and `Not()`:

```

using ::testing::AllOf;

using ::testing::Gt;

using ::testing::HasSubstr;

using ::testing::Ne;

using ::testing::Not;

...

  // The argument must be > 5 and != 10.

  EXPECT_CALL(foo, DoThis(AllOf(Gt(5),

                                Ne(10))));

  // The first argument must not contain sub-string "blah".

  EXPECT_CALL(foo, DoThat(Not(HasSubstr("blah")),

                          NULL));

```

## Casting Matchers ##

Google Mock matchers are statically typed, meaning that the compiler

can catch your mistake if you use a matcher of the wrong type (for

example, if you use `Eq(5)` to match a `string` argument). Good for

you!

Sometimes, however, you know what you're doing and want the compiler

to give you some slack. One example is that you have a matcher for

`long` and the argument you want to match is `int`. While the two

types aren't exactly the same, there is nothing really wrong with

using a `Matcher<long>` to match an `int` - after all, we can first

convert the `int` argument to a `long` before giving it to the

matcher.

To support this need, Google Mock gives you the

`SafeMatcherCast<T>(m)` function. It casts a matcher `m` to type

`Matcher<T>`. To ensure safety, Google Mock checks that (let `U` be the

type `m` accepts):

  1. Type `T` can be implicitly cast to type `U`;

  1. When both `T` and `U` are built-in arithmetic types (`bool`, integers, and floating-point numbers), the conversion from `T` to `U` is not lossy (in other words, any value representable by `T` can also be represented by `U`); and

  1. When `U` is a reference, `T` must also be a reference (as the underlying matcher may be interested in the address of the `U` value).

The code won't compile if any of these conditions isn't met.

Here's one example:

```

using ::testing::SafeMatcherCast;

// A base class and a child class.

class Base { ... };

class Derived : public Base { ... };

class MockFoo : public Foo {

 public:

  MOCK_METHOD1(DoThis, void(Derived* derived));

};

...

  MockFoo foo;

  // m is a Matcher<Base*> we got from somewhere.

  EXPECT_CALL(foo, DoThis(SafeMatcherCast<Derived*>(m)));

```

If you find `SafeMatcherCast<T>(m)` too limiting, you can use a similar

function `MatcherCast<T>(m)`. The difference is that `MatcherCast` works

as long as you can `static_cast` type `T` to type `U`.

`MatcherCast` essentially lets you bypass C++'s type system

(`static_cast` isn't always safe as it could throw away information,

for example), so be careful not to misuse/abuse it.

## Selecting Between Overloaded Functions ##

If you expect an overloaded function to be called, the compiler may

need some help on which overloaded version it is.

To disambiguate functions overloaded on the const-ness of this object,

use the `Const()` argument wrapper.

```

using ::testing::ReturnRef;

class MockFoo : public Foo {

  ...

  MOCK_METHOD0(GetBar, Bar&());

  MOCK_CONST_METHOD0(GetBar, const Bar&());

};

...

  MockFoo foo;

  Bar bar1, bar2;

  EXPECT_CALL(foo, GetBar())         // The non-const GetBar().

      .WillOnce(ReturnRef(bar1));

  EXPECT_CALL(Const(foo), GetBar())  // The const GetBar().

      .WillOnce(ReturnRef(bar2));

```

(`Const()` is defined by Google Mock and returns a `const` reference

to its argument.)

To disambiguate overloaded functions with the same number of arguments

but different argument types, you may need to specify the exact type

of a matcher, either by wrapping your matcher in `Matcher<type>()`, or

using a matcher whose type is fixed (`TypedEq<type>`, `An<type>()`,

etc):

```

using ::testing::An;

using ::testing::Lt;

using ::testing::Matcher;

using ::testing::TypedEq;

class MockPrinter : public Printer {

 public:

  MOCK_METHOD1(Print, void(int n));

  MOCK_METHOD1(Print, void(char c));

};

TEST(PrinterTest, Print) {

  MockPrinter printer;

  EXPECT_CALL(printer, Print(An<int>()));            // void Print(int);

  EXPECT_CALL(printer, Print(Matcher<int>(Lt(5))));  // void Print(int);

  EXPECT_CALL(printer, Print(TypedEq<char>('a')));   // void Print(char);

  printer.Print(3);

  printer.Print(6);

  printer.Print('a');

}

```

## Performing Different Actions Based on the Arguments ##

When a mock method is called, the _last_ matching expectation that's

still active will be selected (think "newer overrides older"). So, you

can make a method do different things depending on its argument values

like this:

```

using ::testing::_;

using ::testing::Lt;

using ::testing::Return;

...

  // The default case.

  EXPECT_CALL(foo, DoThis(_))

      .WillRepeatedly(Return('b'));

  // The more specific case.

  EXPECT_CALL(foo, DoThis(Lt(5)))

      .WillRepeatedly(Return('a'));

```

Now, if `foo.DoThis()` is called with a value less than 5, `'a'` will

be returned; otherwise `'b'` will be returned.

## Matching Multiple Arguments as a Whole ##

Sometimes it's not enough to match the arguments individually. For

example, we may want to say that the first argument must be less than

the second argument. The `With()` clause allows us to match

all arguments of a mock function as a whole. For example,

```

using ::testing::_;

using ::testing::Lt;

using ::testing::Ne;

...

  EXPECT_CALL(foo, InRange(Ne(0), _))

      .With(Lt());

```

says that the first argument of `InRange()` must not be 0, and must be

less than the second argument.

The expression inside `With()` must be a matcher of type

`Matcher<tr1::tuple<A1, ..., An> >`, where `A1`, ..., `An` are the

types of the function arguments.

You can also write `AllArgs(m)` instead of `m` inside `.With()`. The

two forms are equivalent, but `.With(AllArgs(Lt()))` is more readable

than `.With(Lt())`.

You can use `Args<k1, ..., kn>(m)` to match the `n` selected arguments

(as a tuple) against `m`. For example,

```

using ::testing::_;

using ::testing::AllOf;

using ::testing::Args;

using ::testing::Lt;

...

  EXPECT_CALL(foo, Blah(_, _, _))

      .With(AllOf(Args<0, 1>(Lt()), Args<1, 2>(Lt())));

```

says that `Blah()` will be called with arguments `x`, `y`, and `z` where

`x < y < z`.

As a convenience and example, Google Mock provides some matchers for

2-tuples, including the `Lt()` matcher above. See the [CheatSheet](V1_7_CheatSheet.md) for

the complete list.

Note that if you want to pass the arguments to a predicate of your own

(e.g. `.With(Args<0, 1>(Truly(&MyPredicate)))`), that predicate MUST be

written to take a `tr1::tuple` as its argument; Google Mock will pass the `n`

selected arguments as _one_ single tuple to the predicate.

## Using Matchers as Predicates ##

Have you noticed that a matcher is just a fancy predicate that also

knows how to describe itself? Many existing algorithms take predicates

as arguments (e.g. those defined in STL's `<algorithm>` header), and

it would be a shame if Google Mock matchers are not allowed to