| 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.4.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 3.4 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 |
| |
| ### 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 |
| |
| Choosing a TR1 Tuple Library |
| ---------------------------- |
| Google Mock uses the C++ Technical Report 1 (TR1) tuple library |
| heavily. Unfortunately TR1 tuple is not yet widely available with all |
| compilers. The good news is that Google Test 1.4.0+ implements a |
| subset of TR1 tuple that's enough for Google Mock's need. Google Mock |
| will automatically use that implementation when the compiler doesn't |
| provide TR1 tuple. |
| |
| Usually you don't need to care about which tuple library Google Test |
| and Google Mock use. However, if your project already uses TR1 tuple, |
| you need to tell Google Test and Google Mock to use the same TR1 tuple |
| library the rest of your project uses (this requirement is new in |
| Google Test 1.4.0 and Google Mock 1.2.0, so you may need to take care |
| of it when upgrading from an earlier version), or the two tuple |
| implementations will clash. To do that, add |
| |
| -DGTEST_USE_OWN_TR1_TUPLE=0 |
| |
| to the compiler flags while compiling Google Test, Google Mock, and |
| your tests. |
| |
| If you want to use Boost's TR1 tuple library with Google Mock, please |
| refer to the Boost website (http://www.boost.org/) for how to obtain |
| it and set it up. |
| |
| 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. |
| |
| 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. |
| |
| 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 |
| |
| 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! |