googletest/googlemock/docs/design.md

# gMock - a Framework for Writing and Using C++ Mock Classes

<!--#include file="under-construction-banner.md"-->

**Status:** Draft \
**Tiny URL:** http://go/gmockdesign \
**Author:** Zhanyong Wan (who/wan)

<!-- GOOGLETEST_CM0035 DO NOT DELETE -->

(To participate in discussions on gMock, please subscribe to
[opensource-gmock](https://groups.google.com/a/google.com/group/opensource-gmock/subscribe).
Past discussions can be viewed
[here](https://groups.google.com/a/google.com/group/opensource-gmock/topics) and
[here](https://mailman.corp.google.com/pipermail/c-mock-dev/).)

(The slides for my gMock preview talk can be found here:
[ppt](http://wiki.corp.google.com/twiki/pub/Main/WanTalks/0706-beijing-gmock-preview.ppt).)

## Objective

[Mock objects](http://en.wikipedia.org/wiki/Mock_object) are simulated objects
that mimic real objects in controlled ways. They are useful for driving the
design of a system, and for testing some other object when it's difficult to use
real objects in a test.

While the idea of mocks applies to all objected-oriented languages, writing them
in C++ has many practical difficulties, due to the lack of support for
reflection in the language, the complexity and irregularity of C++, and the lack
of adequate tools. As an unfortunate result, C++ programmers often avoid writing
mocks, resulting in big, monolithic classes in production, and slow, brittle,
and difficult-to-maintain tests.

We believe that a good framework can make it much more pleasant to write and use
mocks in C++. Such a tool would help people write more
[small](https://wiki.corp.google.com/twiki/bin/view/Main/GoogleTestDefinitions)
tests that are quick, robust, and precise. Perhaps more importantly,
incorporating mocks early and often in the design process helps people discover
the role interfaces in the system and thus often leads to
[better designs](http://www.jmock.org/oopsla2004.pdf).

We plan to develop *gMock* as a generic framework for creating and using mock
classes in C++. We would encourage people to *use gMock as a design tool as much
as a testing tool*.

### Goals of gMock

*   **Supporting all interfaces:** A user should be able to use gMock to create
    a mock class for any C++ interface (i.e. a class whose methods are virtual).
    In particular, interface templates should be supported, and there should be
    no restriction on the types of the parameters - `const` parameters, pointer
    parameters, reference parameters, reference-to-`const` parameters, and etc
    should all be allowed.

    gMock can also be used to mock a "loose" interface (i.e. the set of
    operations a template class or template function expects its type argument
    to support). This is useful for testing code that uses the
    ["high-performance dependency injection"](https://engdoc.corp.google.com/eng/doc/tott/episodes/33.md)
    technique.

*   **Precise specification of the intention:** gMock should enable a user to
    precisely specify the intended behavior of a mock object, and how its
    methods are expected to be called (in what order, with what arguments, etc).
    In particular, it should not force the user to over-specify the problem
    (which results in brittle tests that break when unrelated changes to the
    code are made), or to under-specify the problem (which results in tests that
    continue to pass when they shouldn't).

*   **Intuitive and declarative syntax:** A declarative syntax fosters thinking
    at the right abstraction level, and makes the code readable and less
    error-prone. Therefore gMock should provide intuitive and declarative syntax
    for:

    1.  creating a mock class, and
    2.  controlling the behavior of a mock object. When the two goals conflict,
        the latter takes precedence, as it usually needs to be done many more
        times than the former.

*   **Extensible:** No framework can be expected to cover all users' needs.
    Therefore, gMock shouldn't tie the users to whatever it provides. Instead, a
    user should be able to easily extend the framework to accomplish more
    advanced tasks.

*   **Helpful error messages:** Bad error messages are a sure-fire way to
    frustrate the users and drive them away. Therefore, gMock should generate
    clear and sensible messages

    1.  when the code fails to compile - this can be hard as lots of templates
        have to be used in the implementation, but we should try our best; and
    2.  when a user-supplied expectation fails. This also applies to
        user-defined extensions, given that the user has done a good job
        implementing the extensions.

*   **Easy to learn:** We want gMock to make people's life easier, not harder.
    It defeats our purpose if the framework is complex and difficult to learn.

*   **Easily automatable:** The design of gMock should make the process of
    creating a mock class from an interface fairly mechanical, and thus doable
    by the automated
    [mock class generator](https://wiki.corp.google.com/twiki/bin/view/Main/MockClassGeneratorDev).

*   **Working in Google's environment:** While we may be interested in open
    sourcing gMock later, our primary goal is to serve Google. Therefore gMock
    must work well in our environment. In particular, it must not use
    exceptions, and should work well with
    [gUnit](https://wiki.corp.google.com/twiki/bin/view/Main/GUnitGuide).

### Non-goals

*   **Mocking non-virtual methods:** gMock is a source-level tool that works
    with standard compilers and linkers. It doesn't attempt to swap the object
    code of a mock class and that of a real class on-the-fly. Therefore, only
    virtual methods and template arguments can be mocked by gMock.
*   **Supporting arbitrary number of parameters:** Due to limitations of the C++
    language, there will be a practical limit on the number of parameters a mock
    function can have. Support for more parameters can be added as needed.
*   **Supporting non-Linux platforms:** The initial implementation may not run
    on Windows or Mac OS. We have limited resources and need to make sure that
    Linux users are served first. However, we'll try to avoid doing things that
    will make porting gMock to non-Linux platforms difficult.
*   **Special support for particular projects:** gMock is a generic framework
    that makes mocking easy for *all* Google C++ projects. It should not contain
    logic that's useful only to a small number of projects.

## Background

### Terminology

Different people often use "mock" to mean different things. This document
borrows the terminology popularized by
<a href="http://www.martinfowler.com/articles/mocksArentStubs.html">Martin
Fowler</a>:

*   **Dummy** objects are passed around but never actually used. Usually they
    are just used to fill parameter lists.
*   **Fake** objects actually have working implementations, but usually take
    some shortcut (perhaps to make the operations less expensive), which makes
    them not suitable for production.
*   **Stubs** provide canned answers to calls made during the test, usually not
    responding at all to anything outside what's programmed in for the test.
*   **Mocks** are objects pre-programmed with expectations which form a
    specification of the calls they are expected to receive.

### Fakes vs Mocks

Many people are not clear about the difference between a fake and a mock, and
use the terms interchangeably. However, to understand why we need gMock and what
it will deliver, it's crucial to distinguish the two.

Compared with a fake, a mock object is "dumb" and usually doesn't have a working
implementation. However, it allows the user to control its behavior and set
expectations on the calls it will receive. For example, you can tell a mock
object that its `Foo()` method will be called twice with an argument that's
greater than 10, and it should return 12 and 14 respectively.

It may seem that mocks are not very useful compared to fakes, but the Java
community has shown this perception to be wrong. The ability to control a mock
object's behavior and specify the expected interaction between it and the code
under test makes it far more flexible and useful than a fake in designing and
testing a software system.

While fake classes have to be crafted with domain knowledge, mock classes can
actually be created mechanically - with suitable support from a framework. In
more dynamic languages like Java, C#, and Python, there are tools that create
mock objects on the fly without any user intervention. In C++, this cannot be
done within the language itself. However, a framework can make the task much
easier for a user, and the
[mock class generator](https://wiki.corp.google.com/twiki/bin/view/Main/MockClassGeneratorDev)
will make the process automated to a large extent.

### C++ Mocking at Google

To our knowledge, no tool or library is used at Google to facilitate the
creation of mock classes. As a result, people have been writing mock classes
manually. Such classes are typically tedious to create, and lack functionalities
for effective mocking. As a result, people are often frustrated and decided to
avoid mock classes.

As a rough estimate, as of 3/15/2007, the number of existing C++ mock classes in
our source tree is:

```shell
$ gsearch -f="\.(h|cc|cpp)$" -a -c "^\s*class\s+(Mock\w*|\w+Mock)\s*[:{]"
748
```

while the number of all C++ classes is:

```shell
$ gsearch -f="\.(h|cc|cpp)$" -a -c "^\s*class\s+\w+\s*[:{]"
188488
```

Roughly 1 out of every 250 C++ classes has a corresponding mock class. Clearly
this is not enough.

### Situation outside Google

The situation of using C++ mocks outside of Google is not a lot brighter either.
Although there is an open-source framework
([mockpp](http://mockpp.sourceforge.net/)) for writing mock classes, it is
overly complex and has limited functionalities. As a result, it doesn't have a
large following.

### Existing Mock Frameworks

A good mock framework takes years of hard work and actual use in the field to
mature. Therefore, it pays hugely to learn from existing mock frameworks: what
they can and cannot do, why they are the way they are, how they have evolved,
what lessons their creators have learned, and what they intend to do next, etc.

We studied some well-known mock frameworks for Java
([Mock Objects](http://www.mockobjects.com),
[EasyMock](http://www.easymock.org), [jMock 1](http://www.jmock.org), and
[jMock 2](http://cvs.jmock.codehaus.org/browse/~raw,r=1.3/jmock/website/content/cheat-sheet.html))
and for C++ ([mockpp](http://mockpp.sourceforge.net/)). Our conclusion is:

*   Mock Objects is the most primitive of the four. It provides some basic
    constructs for a user to set expected arguments and return values, but not
    much beyond that.
*   EasyMock makes the simple case very easy, but isn't flexible enough to
    handle more advanced usage well. Often the users are forced to either
    over-specify or under-specify their intention, resulting in brittle or
    imprecise tests.
*   jMock 1 and 2 share the same design philosophy, but have incompatible
    syntaxes. They allow a user to precisely specify the intention of the test
    in most cases, and can be easily extended by the user to handle more complex
    situations.
*   mockpp is a mixed bag of constructs from the above three. It doesn't have a
    coherent design philosophy, and doesn't address C++'s specific requirements
    well. It is more complex, redundant, and difficult to learn and use than we
    would like.

### Our Plan

We believe that jMock is the most interesting and promising of the four. Its
creators have been aggressively experimenting with new ideas and designs, and
have produced many iterations before the current form. They have also documented
their experience and lessons in developing jMock in
[two](http://www.jmock.org/oopsla2004.pdf)
[papers](http://mockobjects.com/files/evolving_an_edsl.ooplsa2006.pdf), which
contain many valuable insights.

Therefore, the design of gMock is heavily influenced by jMock. Many constructs
will be directly ported from jMock. Meanwhile, we'll revisit various design
decisions in C++'s context to make sure that we take advantages of C++ strengths
and avoid its weaknesses. We will also address some challenges that are unique
to C++.

## Overview

### Why a Framework

Mock objects serve two distinct purposes in designing and testing a software
system:

1.  They implement the same interfaces as the real classes and provide canned
    responses, allowing code that uses them to compile and run; and
2.  They can verify that the actual interaction between them and the code under
    test matches what the user expects (for example, the right functions are
    called, in the right order, with the right arguments, etc).

Without a framework, a user could manually implement mock functions to return
answers that are either pre-defined or computed using simplified logic. To
verify that the interaction that actually happens matches the expectation, a
user would typically let the mock functions record the interaction in some way,
and inspect the record in the end. This poor man's approach leaves several
things to be desired:

1.  Writing a mock class manually is not easy, and often viewed as a burden to
    be avoided.
2.  Different tests use a mock class in different ways. Therefore, it is often
    impractical to provide a working fake implementation that is useful for all
    tests.
3.  Describing what the interaction should be by inspecting what really has
    happened is round-about and unnatural. It obscure the intention of the test
    author, and results in tests that are hard to read and understand.
4.  It is often too late to check how the interaction went after it has
    finished. Much better is to report a failure at the exact moment an
    expectation is violated. This gives the user a chance to check the context
    of the failure (the stack trace, the variables, etc) before important
    information is lost.

The purpose of gMock is to address the above problems. In particular, it will:

1.  make the task of writing a mock class much easier by hiding the low-level
    mechanism from the user;
1.  let the user of a mock class, rather than its creator, specify the intended
    responses;
1.  let the user specify the intended interaction in a clear and direct syntax;
    and
1.  catch violations to the specification as soon as they arise.

### gMock's Expressiveness

The Java community's years of experience using mocks shows that a mock framework
should enable a user to directly specify the following properties of the
interaction between a mock object and its surrounding code:

*   How many times will a function be called?
*   What arguments will be used?
*   In what order will the calls be made?
*   What should the functions return?
*   What side effects (if any) should the calls incur?

Also, it's important to be able to loosen the constraints when necessary to
prevent brittle tests. For example,

*   If the test doesn't care about how many times a function will be called, the
    test writer should be able to make that clear;
*   If the exact value of an argument doesn't matter, the user should be able to
    say so;
*   If only a subset of the calls need to happen in a strict order, the user
    should be allowed to specify a partial order.

### Architecture of gMock

gMock is a C++ library that will be linked into a user's test code. It consists
of the following components (the syntax used in the code samples is
*tentative*):

1.  **Function mockers:** A family of template classes will be provided for the
    user to mock functions with different arities. For example, a field of type

    ```
    FunctionMocker<int(bool, const string&)>
    ```

    will be used to mock a function with signature

    ```
      virtual int Foo(bool, const string&);
    ```

1.  **Specification builder:** This provides a syntax for the user to specify
    the expected arguments and responses of a mock function. For example, to say
    that `Foo()` will be called exactly twice with arguments `true` and a string
    that contains `"hello"`, and will return 10 and 12 respectively, the user
    can write:

    ```
    EXPECT_CALL(mock_object, Foo(Eq(true), HasSubstring("hello"))
      .Times(2)
      .WillOnce(Return(10))
      .WillOnce(Return(12))
    ```

1.  **Cardinalities, matchers, and actions:** A collection of pre-defined
    *cardinalities* (e.g. `2`), argument *matchers* (e.g. `Eq()` and
    `HasSubstring()`), and stub *actions* (e.g. `Return()`) will enable the user
    to precisely specify the intended interaction in most cases. When this set
    is inadequate, the user can easily define new cardinalities, matchers, and
    actions.

1.  **Specification interpreter:** An underlying interpreter will verify that
    the actual calls made to the mock object conform to the user's expectations.

gMock helps a user in two kinds of activities: *writing* mock classes and
*using* them in tests. When writing a mock class, a user employs the function
mockers (#1); when using a mock class, the user relies on #2 and #3 to specify
the expected interaction between the mock object and the code under test. As the
test runs and the mock functions are invoked, the specification interpreter (#4)
verifies that the actual interaction matches the expectation, and fails the test
when the two don't match.

## Detailed Design

### Implementing a Mock

This section explains how a user would implement a mock class using gMock. The
final syntax may be slightly different to what's presented here, but the overall
idea should remain the same.

The goal of the design is to allow mocking functions that take 0 or more
arguments, functions that are overloaded on the number/types of parameters,
const methods, and methods that are overloaded on the const-ness of this object.

#### Using macros

The easiest way to define a mock class is to use the `MOCK_METHOD` macro.
Specifically, to mock an interface

```cpp
class FooInterface {
  ...
  virtual R Method(A1 a1, A2 a2, ..., Am am) = 0;
  virtual S ConstMethod(B1 b1, B2 b2, ..., Bn bn) = 0;
};
```

one would simply write

```cpp
class MockFoo : public FooInterface {
  ...
  MOCK_METHOD(R, Method, (A1 a1, A2 a2, ..., Am am), (override));
  MOCK_METHOD(S, ConstMethod, (B1 b1, B2 b2, ..., Bn bn), (const, override));
};
```

#### Using no macro

The user can also choose to implement a mock class without using the macros.

For each function to be mocked that is not overloaded, the user should define a
**function mocker** member variable and implement the function by forwarding the
call to the function mocker, which knows how to respond to the given arguments.

A user specifies the mock function's default behavior and expectations on it by
calling the *mock spec function* in an `ON_CALL()` or `EXPECT_CALL()` statement.

Now let's see the concrete syntax. To mock a function that takes no argument:

```cpp
class AbcInterface {
  ...
  virtual R Foo() = 0;
};
```

a user would write:

```cpp
class MockAbc : public AbcInterface {
  ...
  // Mock Foo().  Implements AbcInterface::Foo().
  virtual R Foo() { return gmock_Foo.Invoke(); }

  FunctionMocker<R()> gmock_Foo;
};
```

To mock a function that takes some arguments:

```cpp
  virtual R Bar(A1 a1, A2 a2);
```

a user would write:

```cpp
  virtual R Bar(A1 a1, A2 a2) { return gmock_Bar.Invoke(a1, a2); }

  FunctionMocker<R(A1, A2)> gmock_Bar;
```

To mock a `const` method:

```cpp
  virtual R Baz(A1 a1) const;
```

a user would write:

```cpp
  virtual R Baz(A1 a1) const { return gmock_Baz.Invoke(a1); }

  mutable FunctionMocker<R(A1)> gmock_Baz;
```

Mocking overloaded functions is a little bit more involved. For each overloaded
version, the user needs to define an overloaded mock controller function, e.g.

```cpp
  virtual R Bar(A a) { return gmock_Bar_1.Invoke(a); }
  MockSpec<R(A)>& gmock_Bar(Matcher<A> a) {
     return gmock_Bar_1.With(a);
  }

  virtual R Bar(B b, C c) { return gmock_Bar_2.Invoke(b, c); }
  MockSpec<R(B, C)>& gmock_Bar(Matcher<B> b, Matcher<C> c) {
     return gmock_Bar_2.With(b, c);
  }
 private:
  FunctionMocker<R(A)> gmock_Bar_1;
  FunctionMocker<R(B, C)> gmock_Bar_2;
```

If a method is overloaded on the const-ness of this object, the user can
distinguish between the two overloaded versions by using a const- vs non-const-
reference to the mock object. The `Const()` function provided by gMock can be
used to get a const reference to an object conveniently:

```cpp
template <typename T>
inline const T& Const(const T& x) { return x; }
```

### Syntax for Setting Default Actions and Expectations

For each mock function, there are two interesting properties for a user to
specify:

1.  the **default action**: what the function should do by default when invoked,
    and
2.  the **expectations**: how the function will be called in a particular test.

While the default actions of a mock class usually don't change from test to
test, a user typically sets different expectations in different tests.

The following syntax is proposed for setting the default action of and the
expectations on a mock function:

```cpp
ON_CALL(mock-object, method(argument-matchers))
  .With(multi-argument-matcher) ?
  .WillByDefault(action);
```

The `ON_CALL()` statement defines what a mock function should do when its
arguments match the given matchers (unless the user overrides the behavior in
`EXPECT_CALL()`). The `With()` clause is optional. The `WillByDefault()` clause
must appear exactly once.

```cpp
EXPECT_CALL(mock-object, method(argument-matchers))
  .With(multi-argument-matcher) ?
  .Times(cardinality) ?
  .InSequence(sequences) *
  .WillOnce(action) *
  .WillRepeatedly(action) ?
  .RetiresOnSaturation(); ?
```

The `EXPECT_CALL()` statement says that the mock function should be called the
given number of times (`cardinality`), in the order determined by the
`sequences`, and with arguments that satisfy the given `matchers`. When it is
called, it will perform the given `action`. In this statement, all clauses are
optional and you can repeat `WillOnce()` any number of times. When no action is
specified, the default action defined by `ON_CALL()` will be taken.

For non-overloaded methods, '(argument-matchers)' may be omitted:

```cpp
ON_CALL(mock-object, method)
  .With(multi-argument-matcher) ?
  .WillByDefault(action);

EXPECT_CALL(mock-object, method)
  .With(multi-argument-matcher) ?
  …cardinality and actions…
```

This allows test writers to omit the parameter list and match any call to the
method. Doing so eases the burden on test maintainers when refactoring method
signatures. The 'With()' clause is still optional when the parameter list is
omitted.

We make `ON_CALL()` and `EXPECT_CALL()` macros such that we can tell the mock
object the file name and line number of a rule, which can be used to produce
better error messages at run time. When running a test inside Emacs and an
expectation is violated, the user can jump to the expectation by hitting
`<return>` on the message.

#### Argument Matchers

An `argument-matcher` can be any of the following:

```cpp
Void(), Eq(value), Ge(value), Gt(value), Le(value), Lt(value), Ne(value),
HasSubstring(string), SubstringOf(string),
Same(value), Anything(), Any<type>(), Not(argument-matcher), AnyOf(argument-matchers), AllOf(argument-matchers)
```

In addition, a user can define custom matchers by implementing the
`MatcherImplInterface<type>` interface (TBD).

#### Multi-argument Matchers

Matchers in the previous section match one argument at a time. Sometimes it's
necessary to check all arguments together. This is when multi-argument matchers
are needed:

```cpp
Eq(), Ge(), Gt(), Le(), Lt(), Ne(),
HasSubstring(), SubstringOf(),
Same(), AnyThings(), Not(multi-argument-matcher), AnyOf(multi-argument-matchers), AllOf(multi-argument-matchers)
```

When there are multiple `WithArguments()` clauses in a rule, all of them have to
be satisfied for the rule to match a call.

A user can define new multi-argument matchers by implementing the
`MatcherImplInterface<std::tuple<type1, ..., type_n> >` interface (TBD).

#### Actions

```cpp
Return(), Return(value), DoDefault(), Fail(string),
SetArgPointee<N>(value), DoAll(actions), ...
```

The version of `Return()` that takes no argument is for mocking `void`-returning
functions. The clauses are all statically typed, so a user won't be able to
mistakenly use `Return()` when the mocked function has a non-void return type,
or to use `Return(value)` when the function returns `void`.

On consecutive calls that match a given expectation, actions specified in
multiple `WillOnce()` clauses in the expectation will be used in the order they
are presented. After all `WillOnce()` clauses have been exhausted, the action
specified by `WillRepeatedly()` will always be used. If there is no
`WillRepeatedly()`, the default action defined by `ON_CALL()` will be taken.

When side effects need to be mocked (e.g. changing a field or a global variable,
calling a function of a class-typed argument, and so on), users can define a
custom action by implementing the `ActionImplInterface<return-type(type1, ...,
type-n)>` interface (TBD).

#### Cardinalities

A cardinality tells how many times a function is expected to be called. The
number doesn't have to be always exact, as we don't want to over-specify the
behavior and result in brittle tests.

```cpp
integer, AtLeast(n), AtMost(n), Between(m, n), AnyNumber()
```

This set can be extended by the user implementing the `CardinalityImplInterface`
interface (TBD).

If no cardinality is specified in an `EXPECT_CALL()` statement, gMock will infer
it this way:

*   If there are n `WillOnce()` clauses but no `WillRepeatedly()`, the
    cardinality is n;
*   If there are n `WillOnce()` clauses and a `WillRepeatedly()`, the
    cardinality is `AtLeast(n)`.

#### Sequences

Often we want to specify the order in which mock functions are called. However,
we may not want to specify a total order as that may lead to flaky tests that
will be broken by unrelated changes. For this reason, gMock allows the user to
specify a partial order on the calls by organizing them into *sequences*.

Basically, a sequence is a chain of expectations that have to happen in the
order they are defined. Sequences are identified by their names. For example,
the following defines a sequence named `"a"`, which contains two expectations
where the first has to happen before the second:

```cpp
  Sequence a;

  EXPECT_CALL(mock_foo, Func1(Anything()))
     .Times(1)
     .InSequence(a);

  EXPECT_CALL(mock_bar, Func2(Eq(2)))
     .Times(3)
     .InSequence(a);
```

Note that expectations in the same sequence don't have to be on the same object
or same function, as the above example shows.

An expectation can belong to any number of sequences, in which case all order
constraints have to be honored. For convenience, we allow `InSequence()` to take
multiple sequences. In the following example, the first expectation must be
matched before the second and the third, but we don't care about the relative
order of the latter two:

```cpp
  Sequence a, b;

  EXPECT_CALL(mock_foo, Func1(Anything()))
     .Times(1)
     .InSequence(a, b);

  EXPECT_CALL(mock_bar, Func2(Eq(2)))
     .Times(AnyNumber())
     .InSequence(a);

  EXPECT_CALL(mock_bar, Func2(Eq(5)))
     .Times(AnyNumber())
     .InSequence(b);
```

For convenience, we allow an expectation to contain multiple `InSequence()`
clauses, in which case their arguments will be joined. For example, another way
to write the first expectation in the above example is:

```cpp
  EXPECT_CALL(mock_foo, Func1(Anything()))
     .Times(1)
     .InSequence(a)
     .InSequence(b);
```

A common scenario is that the user wants all expectations to match in the strict
order they are defined. Instead of letting the user put `InSequence()` in every
expectation, we provide the following short-hand:

```cpp
  {
     InSequence s;

     EXPECT_CALL(...)...;
     EXPECT_CALL(...)...;
     ...
  }
```

In the above snippet, when the variable `s` is constructed, gMock will generate
a unique new sequence and automatically put each `EXPECT_CALL()` in the scope of
`s` into this sequence. The result is that this group of expectations must match
in the strict order.

The user can also use an existing sequence like this:

```cpp
  Sequence a;
  ...
  {
     InSequence s(a);

     EXPECT_CALL(...)...;
     EXPECT_CALL(...)...;
     ...
  }
```

This can be useful if an existing sequence needs to be extended.

#### Examples

```cpp
EXPECT_CALL(mock_goat, Eat(Eq(5), Anything()))
  .WillOnce(Return(false));
```

The mock goat will be told to `Eat()` 5 of something exactly once; the method
should return `false`.

```cpp
EXPECT_CALL(mock_goat, Drink(HasSubstring("milk")))
  .Times(1);
```

The mock goat will be told to `Drink()` something that contains milk once; the
method should perform its default action when invoked.

```cpp
EXPECT_CALL(mock_elephant, Eat(Same(mock_goat)))
  .Times(0);
```

The mock elephant should never be told to `Eat()` the poor mock goat, which
would be a terrible thing.

```cpp
Sequence a;

EXPECT_CALL(mock_elephant, Eat(Anything()))
  .InSequence(a)
  .WillOnce(Return(true));

EXPECT_CALL(mock_elephant, Walk(Ge(5)))
  .Times(AtLeast(1))
  .InSequence(a)
  .WillOnce(Return(2));
```

The mock elephant will be told to `Eat()` something; after that it will be told
to `Walk()` >= 5 meters at least once; the `Walk()` method should return 2 the
first time, and should do the default action in future calls.

#### Syntax Checking

We will use a combination of compile-time and run-time checks to catch syntax
errors. In particular, the spelling and types of the individual clauses will
(obviously) be done by the C++ compiler, while we'll enforce the order and
counts of the clauses via run-time checks.

Please note that technically it is possible to do the latter checks at compile
time too, and that is the approach of jMock and Mockpp. For the designer of an
embedded domain-specific language (EDSL), it is appealing to leverage the
compiler of the hosting language (C++ in this case) to parse code in the EDSL
and catch errors in it as much as possible. It is also an interesting exercise
in pushing the envelope of EDSL implementation techniques.

However, while we initially wanted to go with jMock's approach, we now think
it's better to defer such checks to run time. The reasons are:

1.  Doing the checks at run time *significantly* reduces the number of template
    classes and simplifies the implementation. This is not only a benefit for
    the author and maintainer of gMock, but also makes it much easier for a user
    to learn gMock. New and existing users will have to read the gMock header
    files from time to time, so it's important to keep the public interface
    small. As an example of what happens when the API is not kept small, try to
    read the header files of Mockpp - you will find a plethora of template
    classes that reference each other, and it's very difficult to tell what
    different roles they play.
1.  The jMock approach enables the IDE to automatically suggest the next clause
    when a user is writing an expectation statement and thus makes it trivial to
    write syntactically correct expectations. Unfortunately, such benefit is
    merely theoretic for most C++ users, as C++ is such a complex language that
    most IDEs do a poor job at understanding the user's source code and
    suggesting auto-completion.
1.  C++ templates generate horrible, horrible compiler errors that often baffle
    even experienced programmers. By enforcing the syntax at compile time, we
    subject gMock's users to the mercy of the C++ compiler, which will generate
    lengthy and cryptic errors when a user makes a small mistake in the syntax.
    It would be much better for us to generate the errors at run time, as we can
    control the messages and choose plain and clear language that guides the
    user to fix the problem.
1.  The default action and expectation statements in gMock are *declarative*,
    and typically each of them will be executed once during the test (not to be
    confused with a rule *matching* an invocation multiple times). Therefore
    there should be little concern that a syntax error is not caught because the
    statement is never actually executed.

### Formal Semantics

The previous section presented the syntax and informally explained the meanings
of various clauses. To avoid ambiguities and make sure we all have the same
understanding on the meaning of a complete test using mock objects, we need to
define the semantics of gMock more strictly.

For an expectation rule to match an actual invocation, three types of
constraints have to be satisfied at the same time:

1.  the order constraints (does the call occur in the right order?),
2.  the cardinality constraints (can the rule accept more invocations?), and
3.  the argument constraints (do all arguments satisfy their matchers?).

As the designer of gMock, we need to decide in which order these constraints
should be applied and how to resolve ambiguities. Our goal is to choose a
semantics that is easy to understand and allows the user to easily express
properties useful for writing tests.

Given that gMock borrows heavily from jMock, naturally one would try to adopt
jMock's semantics. I couldn't find a documentation on that unfortunately. The
following semantics is based on my reverse-engineering jMock and what I think is
reasonable. It differs from the jMock semantics in several important regards.
The exact differences and the rationale behind our decision can be found on the
c-mock-dev [archive](https://g.corp.google.com/group/c-mock-dev-archive) and are
not repeated here.

The proposed semantics can be summarized by two simple principles:

1.  **The orders are sacred**: under no circumstance can an expectation in a
    sequence to match before all expectations that appear earlier in the same
    sequence have been satisfied; and
2.  **Earlier rules take precedence:** when multiple rules can match an
    invocation without violating the order constraints, the one defined the
    earliest wins.

To define the semantics formally, we will use the following terminology:

*   An `ON_CALL()` statement defines a **default action**.
*   An `EXPECT_CALL()` statement defines an **expectation**.
*   An expectation is **active** iff it still can be used to match invocations.
    Otherwise it is **retired**. Initially, all expectations are active.
*   An expectation X is an **immediate pre-requisite** of another expectation Y
    iff there exists a sequence S where X and Y are both in S, X is defined
    before Y, and there is no expectation in S between X and Y.
*   An expectation X is a **pre-requisite** of another expectation Y iff there
    exists a list X[0] = X, X[1], ..., X[n] = Y, where X[i] is an immediate
    pre-requisite of X[i+1] for all i.
*   An expectation (or its cardinality constraint) is said to be **satisfied**
    iff it has reached its minimum number of allowed invocations.
*   An expectation (or its cardinality constraint) is said to be **saturated**
    iff it has reached its maximum number of allowed invocations. A saturated
    expectation by definition must be satisfied, but not vice versa.

After the user has set the default action and the expectations, when a mock
function is called, the following algorithm (in pseudo code) will be used to
find the matching expectation and the matching action:

```cpp
void TryToDoDefault(FunctionMocker& m, const Arguments& args) {
  if (m has a default action for arguments args) {
     perform the default action;
  } else {
     raise error("No action is specified.");
  }
}

void OnInvocation(FunctionMocker& m, const Arguments& args) {
  for_each (active expectation e on function m in the order
                the expectations are defined) {
     if (all pre-requisites of e are satisfied &&
          args match e's argument matchers) {
        // We found a match!

        if (e.is_saturated)
          raise error("Invocation upper bound exceeded.");

        e.invocation_count++;
        retire all prerequisites of e;

        if (e.retires_on_saturation && e.is_saturated)
          e.is_active = false;

        if (e has more action left) {
          a = e.get_next_action();
          perform a;
        } else {
          TryToDoDefault(m, args);
        }
        return;
     }
  }

  TryToDoDefault(m, args);
}
```

To find the default action for the given arguments, we look through all
`ON_CALL()` rules for the mock function, and pick the first one where all
argument matchers are satisfied, if any.

Since C++ exceptions are disabled in `google3`, **we will abort the current
process when gMock raises an error**. We cannot just return from the current
function like what gUnit does, as the mock functions will be called from the
production code under test, and we don't have the luxury to change the
production code at each call site to propagate the error. This is unfortunate,
but I don't see a better solution without enabling exceptions.

The real implementation will be more sophisticated in order to get a decent
performance (e.g. we'll memoize and use other tricks), but the end result must
match the above reference implementation.

**Note:** If you carefully inspect the algorithm, you should convince yourself
that an expectation whose cardinality is `0` has no effect whatsoever, as it is
always satisfied and saturated. This means that you can write such an
expectation, but it won't affect your test in any way. Indeed, this is jMock's
behavior, and jMock's documentation suggests to use `Never()` (jMock's
equivalent of the `0` cardinality) for documentation purpose only.

This bothers me as it contradicts with what one would naturally expect. When I
see

```cpp
  EXPECT_CALL(mock_foo, Bar(Eq(5)))
     .Times(0);
```

I would think that it will be an error if `mock_foo.Bar(5)` is ever called, and
gMock will catch this error at run time. However, jMock tells me that it will
not try to enforce this, and I should treat the statement as if it doesn't
exist.

I propose to give `Times(0)` a semantics that I think is more intuitive. Namely,
we should treat

```cpp
  EXPECT_CALL(mock-object, method(argument-matchers))
     .WithArguments(multi-argument-matcher)
     .Times(0)
     .InSequence(sequences);
```

as if it were

```cpp
  EXPECT_CALL(mock-object, method(argument-matchers))
     .WithArguments(multi-argument-matcher)
     .Times(AnyNumber())
     .InSequence(sequences)
     .WillOnce(Fail("Unexpected call."));
```

I don't like making this a special case, but the other choice seems worse.

**Note:** If a call doesn't match any explicitly written `EXPECT_CALL()`
statement, gMock will perform the default action (as long as it exists) instead
of raising an "unexpected call" error. If you want to assert that a function
should never be called, you must explicitly write an `EXPECT_CALL()` with a `0`
cardinality. This design is picked to allow modular tests:

An interface may contain many methods. Typically, each test will be interested
in only a small number of them, as we favor small and focused tests. Such a test
shouldn't start to fail when the code under test is modified to call functions
not interesting to the test. If no `EXPECT_CALL()` were to mean "no call is
allowed", we would have to say

```cpp
  EXPECT_CALL(mock_foo, UninterestingMethod(Anything()))
     .Times(AnyNumber());
```

for **every** method we do **not** care about. It can be very tedious. Worse,
when we add methods to the interface or remove methods from it, we have to
update every existing test. Clearly this isn't modular and won't scale.

#### Examples

If you are not interested in whether a function will be called or not, you just
don't say anything about it. If the function is called, its default action will
be performed.

If you want to make sure that a function is never called, say it explicitly:

```cpp
  EXPECT_CALL(mock_foo, Bar).Times(0);
  // or:
  EXPECT_CALL(mock_foo, Bar(Anything())).Times(0);
```

If you expect certain calls to a function and want to ignore the rest, just
specify the calls you are explicitly expecting:

```cpp
  EXPECT_CALL(mock_foo, Bar(Eq(1)))
     .WillOnce(Return(2));
  EXPECT_CALL(mock_foo, Bar(Eq(2)))
     .Times(AtMost(5))
     .WillRepeatedly(Return(3));
```

If you expect certain calls to a function and don't want to allow any other
calls to it, just add a `Times(0)` expectation **after** the normal
expectations:

```cpp
  EXPECT_CALL(mock_foo, Bar(Eq(1)))
     .WillOnce(Return(2));
  EXPECT_CALL(mock_foo, Bar(Eq(2)))
     .Times(AtMost(5))
     .WillRepeatedly(Return(3));

  // Any call to mock_foo.Bar() that doesn't match the above rules
  // will be an error.
  EXPECT_CALL(mock_foo, Bar(Anything()))
     .Times(0);
```

Here's one complete example:

```cpp
  ON_CALL(mock_foo, Bar(Anything()))
     .WillByDefault(Return(1));

  Sequence x;

  EXPECT_CALL(mock_foo, Bar(Ne('a')))     // Expectation #1
     .InSequence(x)
     .WillOnce(Return(2))
     .WillRepeatedly(Return(3));

  EXPECT_CALL(mock_foo, Bar(Anything()))  // Expectation #2
     .Times(AnyNumber())
     .InSequence(x);

  mock_foo.Bar('b');  // Matches expectation #1; returns 2.
  mock_foo.Bar('c');  // Matches expectation #1; returns 3.
  mock_foo.Bar('b');  // Matches expectation #1; returns 3.
  mock_foo.Bar('a');  // Matches expectation #2; returns 1.

  // Now that expectation #2 has been used, expectation #1 becomes
  // inactive (remember that the order is sacred), even though it's not
  // yet saturated.

  mock_foo.Bar('b');  // Matches expectation #2, returns 1.
```

Another one:

```cpp
  Sequence a, b;

  EXPECT_CALL(mock_foo, Func1(Void()))      // #1
     .Times(1)
     .InSequence(a);

  EXPECT_CALL(mock_bar, Func2(Anything())   // #2
     .Times(AtLeast(1))
     .InSequence(   b);

  EXPECT_CALL(mock_foo, Func3(Eq(0)))  // #3
     .Times(AtMost(2))
     .InSequence(a, b);

  EXPECT_CALL(mock_foo, Func3(Anything()))      // #4
     .InSequence(a);

  // The order constraints can be illustrated as
  //
  //    #1 < #3 < #4
  //    #2 < #3

  mock_foo.Func1();  // Matches #1
  // Now #1 is saturated but not retired.
  // If Func1() is called again here, it will be an upper-bound error.

  // It would be an error to call mock_foo.Func3(0) here, as #2 is its
  // pre-requisite and hasn't been satisfied.

  mock_bar.Func2(1);  // Matches #2, which is now satisfied.

  mock_foo.Func3(1);
  // Matches #4.  This causes all of #4's remaining pre-requisites (#2
  // and #3) to become inactive.  Note that #3 is trivially satisfied
  // as that AtMost(2) doesn't require it to match any invocation.
```

Yet another one:

```cpp
EXPECT_CALL(mock_foo, Func(Eq(1)))       // #1
  .WillOnce(Return(2))
  .RetiresOnSaturation();

EXPECT_CALL(mock_foo, Func(Anything()))  // #2
  .WillOnce(Return(3));

mock_foo.Func(1);  // Matches #1.
// Now #1 is satisfied, saturated, and retired.

mock_foo.Func(1);  // Matches #2.
// Since #1 is retired now, it doesn't participate in matching function
// calls.  Otherwise this would cause an upper-bound-exceeded failure.
```

### Verifying that All Expectations Are Satisfied

During a test, gMock will verify that each invocation to a mock function matches
one of the expectation rules. However, at the end of a test, we will want to
verify that *all expectations for the mock function have been satisfied*. This
is done by the destructor of the `FunctionMocker<...>` class:

### Life of a Mock

Now let's put the pieces together and see the complete process of using mock
objects in a test. Typically, the user should do it in the following order:

*   **C:** *Constructs* the mock objects;
*   **B:** Set their default **behaviors** using `ON_CALL()`;
*   **E:** Set **expectations** on them using `EXPECT_CALL()`;
*   **I:** Exercise the production code, which will **invoke** methods of the
    mock objects;
*   **D:** *Destructs* the mock objects, which will cause gMock to verify that
    all expectations are satisfied.

Usually, the user can do step 1 and 2 during the set-up phase of the test, step
3 and 4 in the test function body, and step 5 in the tear-down phase.

If the user performs a step out of sequence (e.g. an `EXPECT_CALL()` is
encountered after the mock function is already been called by the test and
before `Verify()` is called), the behavior is **undefined**. gMock will try to
print a friendly error message, but doesn't guarantee to catch all possible
violations, and the initial version may not implement this error check at all.

Valid sequences of using a mock object can be described using the regular
expression

```none
CB*E*I*D
```

### Typing of Argument Matchers

Argument matchers in gMock are statically typed. If we don't provide automatic
conversion between matchers of "compatible" types, the user experience will be
rather unpleasant. Covariance and contravariance are two common schemes for
imposing a sub-typing relation between types. Our observation is that neither
works for matchers in general, and gMock must leave the decision to individual
matcher authors.

#### Background: How Argument Matchers Work

In gMock, argument matchers are used to determine if the actual arguments in a
function invocation match the test writer's expectation. Conceptually, a matcher
for arguments of type `T` implements the following interface:

```cpp
class Matcher<T> {
  virtual bool Matches(T x) = 0;
};
```

For a method with argument type `T`:

```cpp
virtual void Func(T x);
```

its mock will be declared as something like (the actual declaration will be more
complicated but the idea remains the same):

```cpp
void Func(Matcher<T>* x);
```

When the mock `Func()` is invoked with an argument value `v`, which has type
`T`, `Matches(v)` will be called to determine if it's a match.

#### Need for Sub-typing

A straightforward way to mock a method with parameter types `T1`, `T2`, ..., and
`Tn` is to use a list of matchers of type `Matcher<T1>`, `Matcher<T2>`, ..., and
`Matcher<Tn>`. However, this simplistic approach has a usability problem.
Suppose we have a series of functions and their mocks:

```cpp
void Func1(char a);
void Func1(Matcher<char>* a);

void Func2(const char a);
void Func2(Matcher<const char>* a);

void Func3(char& a);
void Func3(Matcher<char&>* a);

void Func4(const char& a);
void Func4(Matcher<const char&>* a);

void Func5(char* a);
void Func5(Matcher<char*>* a);

void Func6(const char* a);
void Func6(Matcher<const char*>* a);
```

(note that `Func2()` has a `const` parameter. Since argument matchers are not
allowed to modify the arguments in any case, technically we could use a
`Matcher<char>` in the mock of `Func2()`. However, we want to make sure that a
user can define the mock using a `Matcher<const char>` too, as this makes the
task of the mock class generator easier.) and some simple, pre-defined matcher
factories:

```cpp
// Matches if the argument equals the given value x.
Matcher<T>* Eq(T x);

// Matches if the argument has the same identify as the
// given object x.
Matcher<T&>* Same(T& x);
```

then a user might be surprised when trying to use these mocks:

```cpp
  Func1('a');       // Invokes the real method.  This works fine.
  Func1(Eq('a'));  // Invokes the mock method.  This works fine too.

  Func2('a');       // Invokes the real method.  This works fine.
  Func2(Eq('a'));  // Compiler ERROR - surprise!!!  Why can't I say that
                         // the argument, which is a const char, should be equal
                         // to 'a'?

  char a = 'a';
  Func3(a);       // Invokes the real method.  This works fine.
  Func3(Same(a));  // Fine.  The argument should reference the variable a.
  Func3(Eq('a'));  // Compiler ERROR - surprise!!!  Why can't I say that
                         // the argument, which is a char&, should have a value
                         // 'a', which is a char?

  const char b = 'b';
  Func4(b);       // Fine.
  Func4(Same(b));  // Fine.  The argument should reference the variable b.
  Func4(Eq(b));  // Compiler ERROR - surprise!!!  Why can't I say that
                         // the argument, which is a const char&, should have
                         // a value equal to b, which is a const char?
  Func4(Same(a));  // Compiler ERROR - surprise!!!  Why can't I say that
                         // the argument, which is a const char&, should reference
                         // a, which is a char?

  char* p = NULL;
  Func5(p);       // Fine.
  Func5(Eq(p));  // Fine.

  Func6("a");       // Fine.
  Func6(Eq("a"));  // Fine.
  Func6(Eq(p));  // Compiler ERROR - surprise!!!  Why can't I say that
                         // the argument, which is a const char*, should point
                         // to where p, which is a char*, points to?
```

(In Java, this issue isn't nearly as severe, as Java has neither reference nor
`const`. Lucky them.)

The compiler errors can be worked around using explicit template instantiating
in most cases, but require more dirty hacks in some others:

```cpp
  // The following works:
  Func2(Eq<const char>('a'));
  Func4(Eq<const char&>(b));
  Func4(Same<const char>(a));
  Func6(Eq<const char*>(p));

  // but this doesn't:
  Func3(Eq<char&>('a'));  // Compiler ERROR!

  // You have to use a temporary variable, and pray that it's not
  // accidentally changed before the actual invocation occurs.
  // No, you cannot make the temporary variable const - that won't
  // compile.
  char temp = 'a';
  Func3(Eq<char&>(temp));
```

Having to use these tricks all the time is a big bummer and makes the tests
harder to read. The author of Mockpp either chose to ignore this problem, or
wasn't aware of it, but I don't think that's a good solution.

To give the user a satisfying experience, I believe we should provide automatic
conversions between matchers of "compatible" types when it makes sense (i.e. we
should establish a sub-typing relation between matcher types). The challenges
are:

1.  Deciding when "it makes sense",
1.  Making sure the conversions are neither too restricted nor too liberal,
1.  Making it possible for the user to understand the compiler errors when
    automatic conversions cannot be done,
1.  Making the rules easy to learn and remember, and
1.  Implementing it.

#### Covariant or Contravariant?

We already know that making the matchers **invariant** (i.e. no auto-conversion
between matcher types) doesn't work, but what about **covariant** (`Matcher<A>`
can be used as `Matcher<B>` as long as `A` can be used as `B`) or
**contravariant** (`Matcher<A>` can be used as `Matcher<B>` as long as `B` can
be used as `A`)? Would one of them work?

It's easy to see that covariance doesn't work in general, as it requires a
matcher expecting a sub-type value to inspect a super-type value. What if the
matcher needs to look at a field that's only present in the sub-type?

On the surface level, it seems that contravariance is what we need: if type `B`
can be implicitly converted to type `A`, then given an argument of type `B`, we
can convert it to type `A` and then ask a `Matcher<A>` whether the converted
value matches. This means that we can use a `Matcher<A>` in place of a
`Matcher<B>`.

For example, given a class hierarchy and some (real and mock) functions that use
the classes:

```cpp
class Father { ... };

class Son : public Father {
 public:
  ...
  // New method not present in Father:
  virtual bool PropertyFoo() const;
};

class Grandson : public Son { ... };

void InviteFather(Father* obj);
void InviteFather(Matcher<Father*>* m);

void InviteGrandson(Grandson* obj);
void InviteGrandson(Matcher<Grandson*>* m);
```

we can expect to write the following:

```cpp
// Matches if the argument's PropertyFoo() method returns true.
Matcher<Son*>* HasFoo() { ... }

// The compiler should reject this as a Father object doesn't have
// the PropertyFoo() method:
//
//  InviteFather(HasFoo());

// This should work, as a Grandson object is also a Son object and
// has the PropertyFoo() method.
InviteGrandson(HasFoo());
```

In the latter case, the actual argument (of type `Grandson*`) will be implicitly
converted to a `Son*` and then passed to the matcher.

However, things are not always so simple. Take the example of the equality
matcher, `Func5()`, and `Func6()` we saw earlier:

```cpp
// Matches if the argument equals the given value x.
Matcher<T>* Eq(T x);

void Func5(char* a);
void Func5(Matcher<char*>* a);

void Func6(const char* a);
void Func6(Matcher<const char*>* a);
```

By making matchers contravariant, we have

```cpp
  // Remember that a char* can be implicitly converted to a const char*.

  Func5(Eq("a"));  // Compiles, but we DON'T want it to!!!  The user is
                         // trying to say that the actual argument (a char*)
                         // can be "a", and we should catch this error.

  char* p = ...;
  Func6(Eq(p));  // Still a compiler ERROR, as a const char* cannot be
                         // implicitly converted to a char*, which Eq(p) expects.
```

Clearly this isn't what we want. In fact, we want `Eq(value)` to be covariant:

```cpp
  char* p = ...;

  Func5(p);
  Func5(Eq(p));
  // Func5("a");        // The compiler will reject this,
  // Func5(Eq("a"));  // and thus should reject this too.

  Func6("a");
  Func6(Eq("a"));
  Func6(p);           // The compiler accepts this,
  Func6(Eq(p));      // and thus should accept this too.
```

In another example:

```cpp
void InviteSon(Son* obj);
void InviteSon(Matcher<Son*> m);

Father* father = ...;
Grandson* grandson = ...;

InviteSon(grandson);         // The compiler accepts this,
InviteSon(Eq(grandson));    // and thus should accept this too.

// InviteSon(father);       // The compiler will reject this,
// InviteSon(Eq(father));  // and thus should reject this too.
```

So, what was the problem? The key insight here is that *one size doesn't fit
all*. While some matchers should be contravariant (like `HasFoo()`), some should
be covariant (like `Eq(value)` and `Same(object)`). *The decision has to be left
to the individual matcher authors. gMock should not impose a global policy on
all the matchers.*

#### Implementing Automatic Type Conversion

In C++, you have several options if you want to make one class `A` act like
another class `B`:

1.  Derive `A` from `B`;
1.  In class `B`, define a public single-parameter constructor `B::B(const A&)`
    (don't make it `explicit`);
1.  In class `A`, define a type-conversion operator for type `B`.

Each of these approaches has its limitations:

*   #1 is most straightforward and requires the least amount of work. However,
    it means that an `A` object will contain all the members of `B`. It may not
    work for you if you want to be able to auto-convert `A` to multiple classes,
    and it certainly won't work if you want to convert `A` to an infinite number
    of other classes.
*   #2 requires you to be able to edit the implementation of `B`. This is not
    always possible, for example, when `B` is a class defined in a standard
    library and you are a user of that library. It's a closed approach, meaning
    that only the owner of `B` can decide which classes can be converted to `B`.
*   #3 requires more work to implement typically, but doesn't have the problems
    of #1 and #2. In particular, you can define a template type-conversion
    operator to convert `A` to an infinite number of other classes of your
    choice.

Also, remember that the compiler will only automatically insert one level of
type conversion on your behalf. For example, if `A` can be implicitly converted
to `B`, which can be implicitly converted to `C`, and you have a function
expecting a `C`, you cannot give the function an `A` without explicit casting,
unless `A` can be implicitly converted to `C` too.

gMock defines the `Matcher<T>` interface, which a user cannot modify. When
defining a polymorphic matcher (e.g. `Eq(value)`), a user needs to make it
behave like a (potentially infinite) number of matchers of different types. This
means that the last implementation technique should be used.

### Comparison with Mockpp and jMock

See GMockVsMockppAndJMock.

## Project

This design doc describes the project "[gMock](http://p?p=6164) - a framework
for writing C++ mock classes" in PDB.

## Code Location

This is a new project, so no existing file is expected to be touched. The
implementation is added in directory `//depot/google3/testing/base`.

## Group Members

ZhanyongWan : spending 60% of his time on this.

## Caveats

We considered existing solutions, but don't think they would work well enough
for Google. For details, please refer to MockppStudy.

TODO:

*   Explain why we pick the EDSL-style syntax.

## Documentation Plan

In additional to this design doc, a user's guide, an FAQ, and a codelab will
also be written.

## Testing Plan

gMock will be thoroughly tested on Linux using gUnit.

## Work Estimates

*   **Inspecting existing solutions:** The goal is to understand how other
    people have approached this problem, what they did well, and what did
    poorly. In addition to studying solutions for C++ (mockpp), we will also
    study solutions for Java (jMock and EasyMock). **3 weeks.**
*   **Initial design and prototyping:** Come up with a design tailored to C++'s
    specifics and Google's unique requirements, taking into account lessons
    learned from other solutions. **3 weeks.**
*   **Soliciting feedback on the design:** Listen to `testing-technology`,
    `testing-grouplet`, `c-users`, `c-mock-dev`, and `gunit-users`; revise the
    design based on the feedback. **3 weeks.**
*   **Initial implementation:** **6 weeks.**
*   **Documentation:** Write the user's guide and a codelab. **3 weeks.**
*   **Company-wide roll-out:** Implement a process for promoting and tracking
    adoption. **1 week.**
*   **Customer support, incremental improvements, and maintenance:** **On-going
    effort.**

## Potential Patents

We'll know whether there will be patentable inventions when we have a more
concrete design and prototype. At that time, we should talk to Google's
[patent counsel](mailto:patents@google.com).

## Things that Don't Apply

### Security Considerations

This is an internal library for writing (unit) tests, and will not be used in
production. Therefore there is no security concern.

### Privacy Considerations

gMock will not touch any user data. Therefore there is no concern about user
privacy.

### Standards

There is no existing standard in creating C++ mocks.

### Logging Plan

This is an internal library and will not handle any user request. Therefore
there is no plan for logging.

### Monitoring Plan

This is an internal library and will not run on our production servers.
Therefore no monitoring is required.

### Internationalization Plan

gMock is not visible to external users, so there is no plan to internationalize
it.

### Billing Plan and Tax Plan

gMock is an internal library and doesn't involve money, so there is no billing
plan or tax plan.

### Launch Plans

gMock will not launch externally as a Google property. However, we may later
decide to open source it.

## References

*   [jMock 1 cheat sheet](https://wiki.corp.google.com/twiki/bin/view/Main/JMockOneCheatSheet) -
    I compiled this from the downloaded jMock 1 source code.
*   [jMock 1 JavaDoc](http://www.corp.google.com/~wan/jmock1/javadoc/) - I built
    this locally. The one on http://jmock.org can be slow and may change.
*   [jMock 2 cheat sheet](http://www.jmock.org/cheat-sheet.html) - as found on
    http://jmock.org.
*   [jMock 2 cheat sheet](https://wiki.corp.google.com/twiki/bin/view/Main/JMockTwoCheatSheet) -
    I compiled this from the jMock 2 source code in CVS as of 3/21.
*   [jMock 2 JavaDoc](http://www.corp.google.com/~wan/jmock2/javadoc) - I
    generated this locally from the jMock 2 source code in CVS as of 3/21. No
    official jMock 2 JavaDoc is available yet, as the library hasn't been
    released.
*   [mockpp cheat sheet](https://wiki.corp.google.com/twiki/bin/view/Main/MockppCheatSheet) -
    I compiled this from the mockpp source code.
*   [mockpp API docs](http://mockpp.sourceforge.net/api-doc/index.html) -
    external.

## Acknowledgments

This design doc contains many ideas from PiotrKaminski. We'd also like to thank
the following people for contributing ideas to this project:

JoeWalnes, CraigSilverstein, JeffreyYasskin, KeithRay, MikeBland.