329 lines
15 KiB
Plaintext
329 lines
15 KiB
Plaintext
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. Currently Google Mock only works
|
|
with Google Test (http://code.google.com/p/googletest/), although
|
|
eventually we plan to support other C++ testing frameworks. 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.2.1.
|
|
|
|
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
|
|
|
|
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 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. After that you have two options: either configure Boost as a system
|
|
library or modify the Google Mock project to point to your copy of Boost. The
|
|
former solution will let all your tests use the same copy of Boost while the
|
|
latter one will let each of your projects use its own copy of Boost. 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 configure Boost as a system library.
|
|
* 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\v_1_36_0\boost\tr1\tr1 and C:\boost\v_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\v_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!
|