path: root/testing/gmock/README

Google C++ Mocking Framework
============================
http://code.google.com/p/googlemock/

Overview
--------
Google's framework for writing and using C++ mock classes on Linux,
Mac OS X, and Windows.  Inspired by jMock, EasyMock, and Hamcrest, and
designed with C++'s specifics in mind, it can help you derive better
designs of your system and write better tests.

Google Mock:

- provides a declarative syntax for defining mocks,
- can easily define partial (hybrid) mocks, which are a cross of real
  and mock objects,
- handles functions of arbitrary types and overloaded functions,
- comes with a rich set of matchers for validating function arguments,
- uses an intuitive syntax for controlling the behavior of a mock,
- does automatic verification of expectations (no record-and-replay
  needed),
- allows arbitrary (partial) ordering constraints on
  function calls to be expressed,
- lets a user extend it by defining new matchers and actions.
- does not use exceptions, and
- is easy to learn and use.

Please see the project page above for more information as well as mailing lists
for questions, discussions, and development. There is also an IRC channel on
OFTC (irc.oftc.net) #gtest available. Please join us!

Please note that code under scripts/generator/ is from the cppclean
project (http://code.google.com/p/cppclean/) and under the Apache
License, which is different from Google Mock's license.

Requirements
------------
Google Mock is not a testing framework itself. Instead, it needs a
testing framework for writing tests. It works with Google Test
(http://code.google.com/p/googletest/) out of the box. You can use
either the copy of Google Test that comes with Google Mock, or a
compatible version you already have.  This version of Google Mock
requires Google Test 1.3.0.

You can also easily configure Google Mock to work with another testing
framework of your choice; although it will still need Google Test as
an internal dependency.  Please read
http://code.google.com/p/googlemock/wiki/ForDummies#Using_Google_Mock_with_Any_Testing_Framework
for how to do it.

Google Mock depends on advanced C++ features and thus requires a more
modern compiler.  The following are needed to use Google Mock:

### Linux Requirements ###
These are the base requirements to build and use Google Mock from a source
package (as described below):
  * GNU-compatible Make or "gmake"
  * POSIX-standard shell
  * POSIX(-2) Regular Expressions (regex.h)
  * gcc 4.0 or newer, or gcc 3.4 or newer with the tr1 tuple library
    (from Boost or other vendors).

Furthermore, if you are building Google Mock from a VCS Checkout (also
described below), there are further requirements:
  * Automake version 1.9 or newer
  * Autoconf version 2.59 or newer
  * Libtool / Libtoolize
  * Python version 2.3 or newer

### Windows Requirements ###
  * Microsoft Visual C++ 8.0 SP1 or newer
  * An implementation of the tr1 tuple C++ library (You can get it for
    free from http://www.boost.org/.  We have verified that version
    1.36.0 works.  One caveat is this implementation exposes a bug in
    Visual C++'s <type_info> header when exceptions are disabled.
    Therefore your project must enable exceptions for this
    configuration to work.)

### Mac OS X Requirements ###
  * Mac OS X 10.4 Tiger or newer
  * Developer Tools Installed

Getting the Source
------------------
There are two primary ways of getting Google Mock's source code: you can
download a source release in your preferred archive format, or directly check
out the source from a Version Control System (VCS, we use Google Code's
Subversion hosting). The VCS checkout requires a few extra steps and some extra
software packages on your system, but lets you track development, and make
patches to contribute much more easily, so we highly encourage it.

### VCS Checkout: ###
The first step is to select whether you want to check out the main line of
development on Google Mock, or one of the released branches. The former will be
much more active and have the latest features, but the latter provides much
more stability and predictability. Choose whichever fits your needs best, and
proceed with the following Subversion commands:

  svn checkout http://googlemock.googlecode.com/svn/trunk/ gmock-svn

or for a release version X.Y.*'s branch:

  svn checkout http://googlemock.googlecode.com/svn/branches/release-X.Y/ \
    gmock-X.Y-svn

Next you will need to prepare the GNU Autotools build system, if you
are using Linux or Mac OS X. Enter the target directory of the
checkout command you used ('gmock-svn' or 'gmock-X.Y-svn' above) and
proceed with the following command:

  autoreconf -fvi

Once you have completed this step, you are ready to build the library. Note
that you should only need to complete this step once. The subsequent `make'
invocations will automatically re-generate the bits of the build system that
need to be changed.

If your system uses older versions of the autotools, the above command will
fail. You may need to explicitly specify a version to use. For instance, if you
have both GNU Automake 1.4 and 1.9 installed and `automake' would invoke the
1.4, use instead:

  AUTOMAKE=automake-1.9 ACLOCAL=aclocal-1.9 autoreconf -fvi

Make sure you're using the same version of automake and aclocal.

### Source Package: ###
Google Mock is also released in source packages which can be downloaded from
its Google Code download page[1]. Several different archive formats are
provided, but the only difference is the tools needed to extract their
contents, and the size of the resulting file. Download whichever you are most
comfortable with.

  [1] Google Mock Downloads: http://code.google.com/p/googlemock/downloads/list

Once downloaded expand the archive using whichever tools you prefer for that
type. This will always result in a new directory with the name "gmock-X.Y.Z"
which contains all of the source code. Here are some examples in Linux:

  tar -xvzf gmock-X.Y.Z.tar.gz
  tar -xvjf gmock-X.Y.Z.tar.bz2
  unzip gmock-X.Y.Z.zip

Building the Source
-------------------
### Linux and Mac OS X (without Xcode) ###
There are two primary options for building the source at this point: build it
inside the source code tree, or in a separate directory. We recommend building
in a separate directory as that tends to produce both more consistent results
and be easier to clean up should anything go wrong, but both patterns are
supported. The only hard restriction is that while the build directory can be
a subdirectory of the source directory, the opposite is not possible and will
result in errors. Once you have selected where you wish to build Google Mock,
create the directory if necessary, and enter it. The following steps apply for
either approach by simply substituting the shell variable SRCDIR with "." for
building inside the source directory, and the relative path to the source
directory otherwise.

  ${SRCDIR}/configure  # Standard GNU configure script, --help for more info

The default behavior of the configure script with respect to locating and using
Google Test is to first search for a 'gtest-config' in the system path, and
lacking this, build an internal copy of Google Test. You may optionally specify
a custom Google Test you wish to build Google Mock against, provided it is
a new enough version.

  # Configure against an installation in '/opt' with '/opt/bin/gtest-config'.
  ${SRCDIR}/configure --with-gtest=/opt

This can also be used to specify a Google Test which hasn't yet been installed.
However, it must have been configured and built as described in the Google Test
README before you configure Google Mock. To enable this feature, simply pass
the directory where you configured and built Google Test (which is not
necessarily its source directory) to Google Mock's configure script.

  # Configure against a build of Google Test in an arbitrary directory.
  ${SRCDIR}/configure --with-gtest=../../my_gtest_build

Finally, if you have a version of Google Test installed but for some reason
wish to forcibly prevent it from being used, we provide a special option.
Typically this is not needed as we fall back to the internal Google Test
packaged with Google Mock if an installed version is either unavailable or too
old to build Google Mock. When using the internally packaged Google Test, the
user does *not* need to configure or build it, that is automatically handled by
Google Mock's build system.

  # Force the use of the internally packaged Google Test, despite
  # 'gtest-config' being in your PATH.
  ${SRCDIR}/configure --disable-external-gtest

Once you have successfully configured Google Mock, the build steps are standard
for GNU-style OSS packages.

  make  # Standard makefile following GNU conventions
  make check  # Builds and runs all tests - all should pass

Other programs will only be able to use Google Mock's functionality if you
install it in a location which they can access, in Linux this is typically
under '/usr/local'. The following command will install all of the Google Mock
libraries, public headers, and utilities necessary for other programs and
libraries to leverage it. Note that if Google Mock was unable to find an
external Google Test to build against, it will also install the internally
packaged Google Test in order to allow the installed Google Mock to function
properly. This Google Test install will be fully functional, and if installed
will also be uninstalled by uninstalling Google Mock.

  sudo make install  # Not necessary, but allows use by other programs

Should you need to remove Google Mock from your system after having installed
it, run the following command, and it will back out its changes.  However, note
carefully that you must run this command on the *same* Google Mock build that
you ran the install from, or the results are not predictable.  If you install
Google Mock on your system, and are working from a VCS checkout, make sure you
run this *before* updating your checkout of the source in order to uninstall
the same version which you installed.

  sudo make uninstall  # Must be run against the exact same build as "install"

Your project can build against Google Mock and Google Test simply by leveraging
the 'gmock-config' script. This script can be invoked directly out of the
'scripts' subdirectory of the build tree, and it will be installed in the
binary directory specified during the 'configure'. Here are some examples of
its use, see 'gmock-config --help' for more detailed information.

  gmock-config --min-version=1.0 || echo "Insufficient Google Mock version."

  g++ $(gmock-config --cppflags --cxxflags) -o foo.o -c foo.cpp
  g++ $(gmock-config --ldflags --libs) -o foo foo.o

  # When using a built but not installed Google Mock:
  g++ $(../../my_gmock_build/scripts/gmock-config ...) ...

Note that when building your project against Google Mock, you are building
against Google Test as well. There is no need to configure Google Test
separately.

### Windows ###
The msvc/ directory contains VC++ 2005 projects for building Google
Mock and selected tests. In order to build Google Mock you must have
an implementation of TR1 tuple. One library that provides such
implementation is Boost. If you choose to use Boost, download it from
www.boost.org and install it on your system. Note that Boost TR1 tuple
is a header-only library, so the installation only involves unpacking
it to a suitable location - you don't need to compile it or download a
pre-compiled Boost binary.

Since Boost is quite large, you may prefer to only install the files
actually needed by Google Mock.  If so, you can download TR1 tuple
without other parts of Boost from
http://code.google.com/p/googlemock/downloads/list.

After that you have two options: either set up Boost globally or
modify the Google Mock project to point to your copy of Boost. The
former will let all your tests use the same Boost library while the
latter will allow each of your projects use its own copy. You can also
use a hybrid solution: your project settings will override the
system-wide one.

For example, if you unpacked boost v1.36.0 into C:\boost:
To set up Boost such that all projects can use it:
 * Assuming you are using the Visual Studio 2005 IDE, select Tools |
   Options | Projects And Solutions | VC++ Directories.
 * In the "Show directories for" drop-down select Include Files.  Add
   C:\boost\boost_1_36_0\boost\tr1\tr1 and C:\boost\boost_1_36_0 to the
   list of directories.

To configure your project to point to that version of Boost, replace
the value of the BoostDir user macro with C:\boost\boost_1_36_0 in the
msvc/gmock_config.vsprops file. You can use any text editor to edit
that file.

If you want to use a version of Google Test other then the one bundled with
Google Mock, change the value of the GTestDir macro in gmock_config.vsprop
to point to the new location.

After configuring Boost, just open msvc/gmock.sln and build the library and
tests. If you want to create your own project to use with Google Mock, you'll
have to configure it to use the gmock_config propety sheet. For that:
 * Open the Property Manager window (View | Other Windows | Property Manager)
 * Right-click on your project and select "Add Existing Property Sheet..."
 * Navigate to gmock_config.vsprops and select it.
 * In Project Properties | Configuration Properties | General | Additional
   Include Directories, type <path to Google Mock>/include.

TODO(wan@google.com): update the .vsprops and .vcproj files such that the
last step is unnecessary.

### Using GNU Make ###
The make/ directory contains a Makefile that you can use to build
Google Mock on systems where GNU make is available (e.g. Linux and Mac
OS X).  It doesn't try to build Google Mock's own tests.  Instead, it
just builds the Google Mock libraries and some sample tests.  You can
use it as a starting point for your own Makefile.

If the default settings are correct for your environment, the
following commands should succeed:

  cd ${SRCDIR}/make
  make
  ./gmock_test

If you see errors, try to tweak the contents of make/Makefile to make
them go away.  There are instructions in make/Makefile on how to do
it.

### Using Your Own Build System ###
If none of the build solutions we provide works for you, or if you
prefer your own build system, you just need to compile
${GTEST_SRCDIR}/src/gtest-all.cc (where GTEST_SRCDIR is the root of
the Google Test source tree) and src/gmock-all.cc into a library and
link your tests with it.  Assuming a Linux-like system and gcc,
something like the following will do:

  cd ${SRCDIR}
  g++ -I. -I./include -I${GTEST_SRCDIR} -I${GTEST_SRCDIR}/include \
    -c {GTEST_SRCDIR}/src/gtest-all.cc
  g++ -I. -I./include -I${GTEST_SRCDIR} -I${GTEST_SRCDIR}/include \
    -c src/gmock-all.cc
  ar -rv libgmock.a gtest-all.o gmock-all.o
  g++ -I. -I./include -I${GTEST_SRCDIR} -I${GTEST_SRCDIR}/include \
    path/to/your_test.cc libgmock.a -o your_test

On Windows, you'll also need to add the include path for the boost
headers to the compiler command line.  See
http://www.boost.org/doc/libs/1_36_0/doc/html/boost_tr1/usage.html for
how to do it.

Regenerating Source Files
-------------------------
Some of Google Mock's source files are generated from templates (not
in the C++ sense) using a script.  A template file is named FOO.pump,
where FOO is the name of the file it will generate.  For example, the
file include/gmock/gmock-generated-actions.h.pump is used to generate
gmock-generated-actions.h in the same directory.

Normally you don't need to worry about regenerating the source files,
unless you need to modify them (e.g. if you are working on a patch for
Google Mock).  In that case, you should modify the corresponding .pump
files instead and run the 'pump' script (for Pump is Useful for Meta
Programming) to regenerate them.  We are still working on releasing
the script and its documentation.  If you need it now, please email
googlemock@googlegroups.com such that we know to make it happen
sooner.

Happy testing!