diff -Nru python-mock-0.7.2/debian/changelog python-mock-1.0.1/debian/changelog --- python-mock-0.7.2/debian/changelog 2011-08-23 11:13:44.000000000 +0000 +++ python-mock-1.0.1/debian/changelog 2014-07-19 14:57:19.000000000 +0000 @@ -1,3 +1,75 @@ +python-mock (1.0.1-3ubuntu1) precise; urgency=low + + * No-change backport to precise + + -- Lars Butler (larsbutler) Sat, 19 Jul 2014 14:56:56 +0000 + +python-mock (1.0.1-3) unstable; urgency=medium + + * Team upload. + * d/patches/python3.4_compat.patch: Fix FTBFS with Python 3.4. + (Closes: #739890) (LP: #1283742) + * d/control: Bump Standards-Version with no other changes necessary. + + -- Barry Warsaw Wed, 26 Feb 2014 15:39:36 -0500 + +python-mock (1.0.1-2) unstable; urgency=low + + [ Michael Fladischer ] + * Upload to unstable. + * Remove temporary fix for PKG-INFO. + + [ Jakub Wilk ] + * Use canonical URIs for Vcs-* fields. + + -- Michael Fladischer Wed, 08 May 2013 07:45:16 +0200 + +python-mock (1.0.1-1) experimental; urgency=low + + [ Michael Fladischer] + * New upstream release. + * Fix upstream name, contact and year in d/copyright. + + [ Thomas Goirand ] + * Uploading to experimental. + + -- Thomas Goirand Thu, 14 Feb 2013 21:43:58 +0800 + +python-mock (0.8.0-3) unstable; urgency=low + + * Team upload. + * debian/control: python-mock-doc needs to Break/Replace + python-mock (<< 0.7.2) to ensure clean upgrades from squeeze + to wheezy. Thanks to Andreas Beckmann (Closes: #694296). + + -- Andrew Starr-Bochicchio Fri, 30 Nov 2012 17:02:02 -0500 + +python-mock (0.8.0-2) unstable; urgency=low + + * Add mock.egg-info/PKG-INFO to d/clean to allow two builds in a row + (Closes: #671252). + * Run tests during build (Closes: #667554). + - Add patch for python3 unittests. + - B-D on python-unittest2 for python2.x. + - Add override for dh_auto_test. + * Exclude SOURCES.txt and add temporary fix for Metadata-Version in + PKG-INFO. + * Change order of my name. + * Update years in d/copyright. + * Use DEP5 1.0 format URL. + * Drop d/s/local-options from SVN. + + -- Michael Fladischer Mon, 04 Jun 2012 20:34:13 +0200 + +python-mock (0.8.0-1) unstable; urgency=low + + * Team upload. + * New upstream release + * debian/control + - bump Standards-Version to 3.9.3 (no changes needed) + + -- Sandro Tosi Wed, 04 Apr 2012 23:08:09 +0200 + python-mock (0.7.2-1) unstable; urgency=low * New upstream release. (Closes: #617799) diff -Nru python-mock-0.7.2/debian/clean python-mock-1.0.1/debian/clean --- python-mock-0.7.2/debian/clean 2011-08-23 11:09:54.000000000 +0000 +++ python-mock-1.0.1/debian/clean 2012-05-31 07:29:44.000000000 +0000 @@ -1,3 +1,4 @@ *.pyc **/*.pyc +mock.egg-info/PKG-INFO mock.egg-info/SOURCES.txt diff -Nru python-mock-0.7.2/debian/control python-mock-1.0.1/debian/control --- python-mock-0.7.2/debian/control 2011-08-23 10:19:56.000000000 +0000 +++ python-mock-1.0.1/debian/control 2014-02-26 20:41:10.000000000 +0000 @@ -3,19 +3,20 @@ Priority: extra Maintainer: Debian Python Modules Team Uploaders: David Watson , - Fladischer Michael + Michael Fladischer Build-Depends: debhelper (>= 8), python-all (>= 2.6.6-3~), python-setuptools, + python-unittest2, python3-all (>= 3.1.2-12~), python3-setuptools Build-Depends-Indep: libjs-jquery, python-sphinx (>= 1.0.7+dfsg-1~) -Standards-Version: 3.9.2 +Standards-Version: 3.9.5 X-Python-Version: >= 2.4 X-Python3-Version: >= 3.0 Homepage: http://www.voidspace.org.uk/python/mock/ -Vcs-Svn: svn://svn.debian.org/python-modules/packages/python-mock/trunk/ -Vcs-Browser: http://svn.debian.org/viewsvn/python-modules/packages/python-mock/trunk/ +Vcs-Svn: svn://anonscm.debian.org/python-modules/packages/python-mock/trunk/ +Vcs-Browser: http://anonscm.debian.org/viewvc/python-modules/packages/python-mock/trunk/ Package: python-mock Architecture: all @@ -47,6 +48,8 @@ Section: doc Architecture: all Depends: ${misc:Depends}, ${sphinxdoc:Depends} +Breaks: python-mock (<< 0.7.2) +Replaces: python-mock (<< 0.7.2) Description: Mocking and Testing Library (Documentation) mock provides a core mock.Mock class that is intended to reduce the need to create a host of trivial stubs throughout your test suite. diff -Nru python-mock-0.7.2/debian/copyright python-mock-1.0.1/debian/copyright --- python-mock-0.7.2/debian/copyright 2011-07-07 06:49:43.000000000 +0000 +++ python-mock-1.0.1/debian/copyright 2013-01-24 14:28:31.000000000 +0000 @@ -1,14 +1,14 @@ -Format: http://anonscm.debian.org/viewvc/dep/web/deps/dep5.mdwn?view=markup&pathrev=174 -Upstream-Name: anyjson -Upstream-Contact: Rune Halvorsen +Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ +Upstream-Name: mock +Upstream-Contact: Michael Foord Source: http://www.voidspace.org.uk/python/mock/ Files: * -Copyright: 2003-2009, Michael Foord +Copyright: 2003-2012, Michael Foord License: BSD-mock Files: debian/* -Copyright: 2011, Fladischer Michael +Copyright: 2012-2013, Michael Fladischer 2009, David Watson License: BSD-mock diff -Nru python-mock-0.7.2/debian/patches/python3.2_tests.patch python-mock-1.0.1/debian/patches/python3.2_tests.patch --- python-mock-0.7.2/debian/patches/python3.2_tests.patch 1970-01-01 00:00:00.000000000 +0000 +++ python-mock-1.0.1/debian/patches/python3.2_tests.patch 2012-06-04 18:33:49.000000000 +0000 @@ -0,0 +1,29 @@ +Description: Allow tests to be run with python3 (>= 3.2). +Author: Michael Fladischer +Last-Update: 2012-05-30 +Forwarded: no + +--- a/setup.py ++++ b/setup.py +@@ -7,7 +7,7 @@ + from mock import __version__ + + import os +- ++import sys + + NAME = 'mock' + MODULES = ['mock'] +@@ -66,7 +66,10 @@ + except ImportError: + from distutils.core import setup + else: +- params['tests_require'] = ['unittest2'] +- params['test_suite'] = 'unittest2.collector' ++ if sys.version_info >= (3,): ++ params['test_suite'] = 'tests' ++ else: ++ params['tests_require'] = ['unittest2'] ++ params['test_suite'] = 'unittest2.collector' + + setup(**params) diff -Nru python-mock-0.7.2/debian/patches/python3.4_compat.patch python-mock-1.0.1/debian/patches/python3.4_compat.patch --- python-mock-0.7.2/debian/patches/python3.4_compat.patch 1970-01-01 00:00:00.000000000 +0000 +++ python-mock-1.0.1/debian/patches/python3.4_compat.patch 2014-02-26 20:41:10.000000000 +0000 @@ -0,0 +1,35 @@ +Description: With Python 3.4, some builtins are now introspectable but + don't have the full compliment of attributes. Ignore + AttributeErrors when accessing such attributes. +Author: Barry Warsaw +Bug-Debian: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=739890 +Bug-Ubuntu: https://bugs.launchpad.net/ubuntu/+source/python-mock/+bug/1283742 +Forwarded: no + +--- a/mock.py ++++ b/mock.py +@@ -218,12 +218,21 @@ + funcopy.__name__ = func.__name__ + funcopy.__doc__ = func.__doc__ + #funcopy.__dict__.update(func.__dict__) +- funcopy.__module__ = func.__module__ ++ try: ++ funcopy.__module__ = func.__module__ ++ except AttributeError: ++ pass + if not inPy3k: + funcopy.func_defaults = func.func_defaults + return +- funcopy.__defaults__ = func.__defaults__ +- funcopy.__kwdefaults__ = func.__kwdefaults__ ++ try: ++ funcopy.__defaults__ = func.__defaults__ ++ except AttributeError: ++ pass ++ try: ++ funcopy.__kwdefaults__ = func.__kwdefaults__ ++ except AttributeError: ++ pass + + + def _callable(obj): diff -Nru python-mock-0.7.2/debian/patches/series python-mock-1.0.1/debian/patches/series --- python-mock-0.7.2/debian/patches/series 1970-01-01 00:00:00.000000000 +0000 +++ python-mock-1.0.1/debian/patches/series 2014-02-26 20:41:10.000000000 +0000 @@ -0,0 +1,2 @@ +python3.2_tests.patch +python3.4_compat.patch diff -Nru python-mock-0.7.2/debian/rules python-mock-1.0.1/debian/rules --- python-mock-0.7.2/debian/rules 2011-08-23 11:09:54.000000000 +0000 +++ python-mock-1.0.1/debian/rules 2013-05-08 05:57:02.000000000 +0000 @@ -37,6 +37,7 @@ $$py -B setup.py install --skip-build --root debian/python3-mock \ --install-layout deb; \ done + rm debian/python*-mock/usr/lib/python*/*-packages/mock*.egg-info/SOURCES.txt .PHONY: override_dh_installchangelogs override_dh_installchangelogs: @@ -48,6 +49,15 @@ .PHONY: override_dh_clean override_dh_clean: - rm -rf docs/.build + rm -rf docs/.build tests/__pycache__ __pycache__ dh_clean +.PHONY: override_dh_auto_test +override_dh_auto_test: +ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS))) + set -e; \ + for py in $(PYVERS) $(PY3VERS); do \ + $$py setup.py test ; \ + done +endif + diff -Nru python-mock-0.7.2/docs/changelog.txt python-mock-1.0.1/docs/changelog.txt --- python-mock-0.7.2/docs/changelog.txt 2011-05-30 18:34:24.000000000 +0000 +++ python-mock-1.0.1/docs/changelog.txt 2012-11-05 21:25:26.000000000 +0000 @@ -1,48 +1,378 @@ -TODO and Limitations -==================== - .. currentmodule:: mock -Contributions, bug reports and comments welcomed! +CHANGELOG +========= -Feature requests and bug reports are handled on the issue tracker: +2012/11/5 Version 1.0.1 +----------------------- - * `mock module issue tracker `_ +* Functions decorated with `patch` variants have a `__wrapped__` attribute + pointing to the original function. This brings compatibility with the + default behaviour in Python 3.3 (due to a new feature in `functools.wraps`). -When mocking a class with ``patch``, passing in ``spec=True``, the mock class -has an instance created from the same spec. Should this be the default -behaviour for mocks anyway (mock return values inheriting the spec from their -parent), or should it be controlled by an additional keyword argument -(``inherit``) to the Mock constructor? - -Interaction of magic methods with spec, wraps. For example, should spec cause -all methods to be wrapped with mocksignature perhaps? (or another keyword -argument perhaps?) - -Should magic method calls (including `__call__`?) be tracked in `method_calls`? - -Could take a patch keyword argument and auto-do the patching in the -constructor and unpatch in the destructor. This would be useful in itself, but -violates TOOWTDI and would be unsafe for IronPython (non-deterministic calling -of destructors). Destructors aren't called *anyway* where there are cycles, but -a weak reference with a callback can be used to get round this. - -``Mock`` has several attributes. This makes it unsuitable for mocking objects -that use these attribute names. A way round this would be to provide ``start`` -and ``stop`` (or similar) methods that *hide* these attributes when needed. -(`_name` is a mock attribute that will be not-uncommon, but it is accessed -externally on mocks when building `method_calls` names and so can't be changed -to a double underscore name.) - -If a patch is started using `patch.start` and then not stopped correctly, due -to a bug in the test code, then the unpatching is not done. Using weak -references it would be possible to detect and fix this when the patch object -itself is garbage collected. This is tricky to get right though. +Note that due to changes in `tox`, `mock` is no longer tested with Python 2.4. +The compatibility code has not been removed so it probably still works, but +tests are no longer run. -CHANGELOG -========= +2012/10/07 Version 1.0.0 +------------------------ + +No changes since 1.0.0 beta 1. This version has feature parity with +`unittest.mock +`_ +in Python 3.3. + +Full list of changes since 0.8: + +* `mocksignature`, along with the `mocksignature` argument to `patch`, removed +* Support for deleting attributes (accessing deleted attributes will raise an + `AttributeError`) +* Added the `mock_open` helper function for mocking the builtin `open` +* `__class__` is assignable, so a mock can pass an `isinstance` check without + requiring a spec +* Addition of `PropertyMock`, for mocking properties +* `MagicMocks` made unorderable by default (in Python 3). The comparison + methods (other than equality and inequality) now return `NotImplemented` +* Propagate traceback info to support subclassing of `_patch` by other + libraries +* `create_autospec` works with attributes present in results of `dir` that + can't be fetched from the object's class. Contributed by Konstantine Rybnikov +* Any exceptions in an iterable `side_effect` will be raised instead of + returned +* In Python 3, `create_autospec` now supports keyword only arguments +* Added `patch.stopall` method to stop all active patches created by `start` +* BUGFIX: calling `MagicMock.reset_mock` wouldn't reset magic method mocks +* BUGFIX: calling `reset_mock` on a `MagicMock` created with autospec could + raise an exception +* BUGFIX: passing multiple spec arguments to patchers (`spec` , `spec_set` and + `autospec`) had unpredictable results, now it is an error +* BUGFIX: using `spec=True` *and* `create=True` as arguments to patchers could + result in using `DEFAULT` as the spec. Now it is an error instead +* BUGFIX: using `spec` or `autospec` arguments to patchers, along with + `spec_set=True` did not work correctly +* BUGFIX: using an object that evaluates to False as a spec could be ignored +* BUGFIX: a list as the `spec` argument to a patcher would always result in a + non-callable mock. Now if `__call__` is in the spec the mock is callable + + +2012/07/13 Version 1.0.0 beta 1 +-------------------------------- + +* Added `patch.stopall` method to stop all active patches created by `start` +* BUGFIX: calling `MagicMock.reset_mock` wouldn't reset magic method mocks +* BUGFIX: calling `reset_mock` on a `MagicMock` created with autospec could + raise an exception + + +2012/05/04 Version 1.0.0 alpha 2 +-------------------------------- + +* `PropertyMock` attributes are now standard `MagicMocks` +* `create_autospec` works with attributes present in results of `dir` that + can't be fetched from the object's class. Contributed by Konstantine Rybnikov +* Any exceptions in an iterable `side_effect` will be raised instead of + returned +* In Python 3, `create_autospec` now supports keyword only arguments + + +2012/03/25 Version 1.0.0 alpha 1 +-------------------------------- + +The standard library version! + +* `mocksignature`, along with the `mocksignature` argument to `patch`, removed +* Support for deleting attributes (accessing deleted attributes will raise an + `AttributeError`) +* Added the `mock_open` helper function for mocking the builtin `open` +* `__class__` is assignable, so a mock can pass an `isinstance` check without + requiring a spec +* Addition of `PropertyMock`, for mocking properties +* `MagicMocks` made unorderable by default (in Python 3). The comparison + methods (other than equality and inequality) now return `NotImplemented` +* Propagate traceback info to support subclassing of `_patch` by other + libraries +* BUGFIX: passing multiple spec arguments to patchers (`spec` , `spec_set` and + `autospec`) had unpredictable results, now it is an error +* BUGFIX: using `spec=True` *and* `create=True` as arguments to patchers could + result in using `DEFAULT` as the spec. Now it is an error instead +* BUGFIX: using `spec` or `autospec` arguments to patchers, along with + `spec_set=True` did not work correctly +* BUGFIX: using an object that evaluates to False as a spec could be ignored +* BUGFIX: a list as the `spec` argument to a patcher would always result in a + non-callable mock. Now if `__call__` is in the spec the mock is callable + + +2012/02/13 Version 0.8.0 +------------------------ + +The only changes since 0.8rc2 are: + +* Improved repr of :data:`sentinel` objects +* :data:`ANY` can be used for comparisons against :data:`call` objects +* The return value of `MagicMock.__iter__` method can be set to + any iterable and isn't required to be an iterator + +Full List of changes since 0.7: + +mock 0.8.0 is the last version that will support Python 2.4. + +* Addition of :attr:`~Mock.mock_calls` list for *all* calls (including magic + methods and chained calls) +* :func:`patch` and :func:`patch.object` now create a :class:`MagicMock` + instead of a :class:`Mock` by default +* The patchers (`patch`, `patch.object` and `patch.dict`), plus `Mock` and + `MagicMock`, take arbitrary keyword arguments for configuration +* New mock method :meth:`~Mock.configure_mock` for setting attributes and + return values / side effects on the mock and its attributes +* New mock assert methods :meth:`~Mock.assert_any_call` and + :meth:`~Mock.assert_has_calls` +* Implemented :ref:`auto-speccing` (recursive, lazy speccing of mocks with + mocked signatures for functions/methods), as the `autospec` argument to + `patch` +* Added the :func:`create_autospec` function for manually creating + 'auto-specced' mocks +* :func:`patch.multiple` for doing multiple patches in a single call, using + keyword arguments +* Setting :attr:`~Mock.side_effect` to an iterable will cause calls to the mock + to return the next value from the iterable +* New `new_callable` argument to `patch` and `patch.object` allowing you to + pass in a class or callable object (instead of `MagicMock`) that will be + called to replace the object being patched +* Addition of :class:`NonCallableMock` and :class:`NonCallableMagicMock`, mocks + without a `__call__` method +* Addition of :meth:`~Mock.mock_add_spec` method for adding (or changing) a + spec on an existing mock +* Protocol methods on :class:`MagicMock` are magic mocks, and are created + lazily on first lookup. This means the result of calling a protocol method is + a `MagicMock` instead of a `Mock` as it was previously +* Addition of :meth:`~Mock.attach_mock` method +* Added :data:`ANY` for ignoring arguments in :meth:`~Mock.assert_called_with` + calls +* Addition of :data:`call` helper object +* Improved repr for mocks +* Improved repr for :attr:`Mock.call_args` and entries in + :attr:`Mock.call_args_list`, :attr:`Mock.method_calls` and + :attr:`Mock.mock_calls` +* Improved repr for :data:`sentinel` objects +* `patch` lookup is done at use time not at decoration time +* In Python 2.6 or more recent, `dir` on a mock will report all the dynamically + created attributes (or the full list of attributes if there is a spec) as + well as all the mock methods and attributes. +* Module level :data:`FILTER_DIR` added to control whether `dir(mock)` filters + private attributes. `True` by default. +* `patch.TEST_PREFIX` for controlling how patchers recognise test methods when + used to decorate a class +* Support for using Java exceptions as a :attr:`~Mock.side_effect` on Jython +* `Mock` call lists (`call_args_list`, `method_calls` & `mock_calls`) are now + custom list objects that allow membership tests for "sub lists" and have + a nicer representation if you `str` or `print` them +* Mocks attached as attributes or return values to other mocks have calls + recorded in `method_calls` and `mock_calls` of the parent (unless a name is + already set on the child) +* Improved failure messages for `assert_called_with` and + `assert_called_once_with` +* The return value of the :class:`MagicMock` `__iter__` method can be set to + any iterable and isn't required to be an iterator +* Added the Mock API (`assert_called_with` etc) to functions created by + :func:`mocksignature` +* Tuples as well as lists can be used to specify allowed methods for `spec` & + `spec_set` arguments +* Calling `stop` on an unstarted patcher fails with a more meaningful error + message +* Renamed the internal classes `Sentinel` and `SentinelObject` to prevent abuse +* BUGFIX: an error creating a patch, with nested patch decorators, won't leave + patches in place +* BUGFIX: `__truediv__` and `__rtruediv__` not available as magic methods on + mocks in Python 3 +* BUGFIX: `assert_called_with` / `assert_called_once_with` can be used with + `self` as a keyword argument +* BUGFIX: when patching a class with an explicit spec / spec_set (not a + boolean) it applies "spec inheritance" to the return value of the created + mock (the "instance") +* BUGFIX: remove the `__unittest` marker causing traceback truncation +* Removal of deprecated `patch_object` +* Private attributes `_name`, `_methods`, '_children', `_wraps` and `_parent` + (etc) renamed to reduce likelihood of clash with user attributes. +* Added license file to the distribution + + +2012/01/10 Version 0.8.0 release candidate 2 +-------------------------------------------- + +* Removed the `configure` keyword argument to `create_autospec` and allow + arbitrary keyword arguments (for the `Mock` constructor) instead +* Fixed `ANY` equality with some types in `assert_called_with` calls +* Switched to a standard Sphinx theme (compatible with + `readthedocs.org `_) + + +2011/12/29 Version 0.8.0 release candidate 1 +-------------------------------------------- + +* `create_autospec` on the return value of a mocked class will use `__call__` + for the signature rather than `__init__` +* Performance improvement instantiating `Mock` and `MagicMock` +* Mocks used as magic methods have the same type as their parent instead of + being hardcoded to `MagicMock` + +Special thanks to Julian Berman for his help with diagnosing and improving +performance in this release. + + +2011/10/09 Version 0.8.0 beta 4 +------------------------------- + +* `patch` lookup is done at use time not at decoration time +* When attaching a Mock to another Mock as a magic method, calls are recorded + in mock_calls +* Addition of `attach_mock` method +* Renamed the internal classes `Sentinel` and `SentinelObject` to prevent abuse +* BUGFIX: various issues around circular references with mocks (setting a mock + return value to be itself etc) + + +2011/08/15 Version 0.8.0 beta 3 +------------------------------- + +* Mocks attached as attributes or return values to other mocks have calls + recorded in `method_calls` and `mock_calls` of the parent (unless a name is + already set on the child) +* Addition of `mock_add_spec` method for adding (or changing) a spec on an + existing mock +* Improved repr for `Mock.call_args` and entries in `Mock.call_args_list`, + `Mock.method_calls` and `Mock.mock_calls` +* Improved repr for mocks +* BUGFIX: minor fixes in the way `mock_calls` is worked out, + especially for "intermediate" mocks in a call chain + + +2011/08/05 Version 0.8.0 beta 2 +------------------------------- + +* Setting `side_effect` to an iterable will cause calls to the mock to return + the next value from the iterable +* Added `assert_any_call` method +* Moved `assert_has_calls` from call lists onto mocks +* BUGFIX: `call_args` and all members of `call_args_list` are two tuples of + `(args, kwargs)` again instead of three tuples of `(name, args, kwargs)` + + +2011/07/25 Version 0.8.0 beta 1 +------------------------------- + +* `patch.TEST_PREFIX` for controlling how patchers recognise test methods when + used to decorate a class +* `Mock` call lists (`call_args_list`, `method_calls` & `mock_calls`) are now + custom list objects that allow membership tests for "sub lists" and have + an `assert_has_calls` method for unordered call checks +* `callargs` changed to *always* be a three-tuple of `(name, args, kwargs)` +* Addition of `mock_calls` list for *all* calls (including magic methods and + chained calls) +* Extension of `call` object to support chained calls and `callargs` for better + comparisons with or without names. `call` object has a `call_list` method for + chained calls +* Added the public `instance` argument to `create_autospec` +* Support for using Java exceptions as a `side_effect` on Jython +* Improved failure messages for `assert_called_with` and + `assert_called_once_with` +* Tuples as well as lists can be used to specify allowed methods for `spec` & + `spec_set` arguments +* BUGFIX: Fixed bug in `patch.multiple` for argument passing when creating + mocks +* Added license file to the distribution + + +2011/07/16 Version 0.8.0 alpha 2 +-------------------------------- + +* `patch.multiple` for doing multiple patches in a single call, using keyword + arguments +* New `new_callable` argument to `patch` and `patch.object` allowing you to + pass in a class or callable object (instead of `MagicMock`) that will be + called to replace the object being patched +* Addition of `NonCallableMock` and `NonCallableMagicMock`, mocks without a + `__call__` method +* Mocks created by `patch` have a `MagicMock` as the `return_value` where a + class is being patched +* `create_autospec` can create non-callable mocks for non-callable objects. + `return_value` mocks of classes will be non-callable unless the class has + a `__call__` method +* `autospec` creates a `MagicMock` without a spec for properties and slot + descriptors, because we don't know the type of object they return +* Removed the "inherit" argument from `create_autospec` +* Calling `stop` on an unstarted patcher fails with a more meaningful error + message +* BUGFIX: an error creating a patch, with nested patch decorators, won't leave + patches in place +* BUGFIX: `__truediv__` and `__rtruediv__` not available as magic methods on + mocks in Python 3 +* BUGFIX: `assert_called_with` / `assert_called_once_with` can be used with + `self` as a keyword argument +* BUGFIX: autospec for functions / methods with an argument named self that + isn't the first argument no longer broken +* BUGFIX: when patching a class with an explicit spec / spec_set (not a + boolean) it applies "spec inheritance" to the return value of the created + mock (the "instance") +* BUGFIX: remove the `__unittest` marker causing traceback truncation + + +2011/06/14 Version 0.8.0 alpha 1 +-------------------------------- + +mock 0.8.0 is the last version that will support Python 2.4. + +* The patchers (`patch`, `patch.object` and `patch.dict`), plus `Mock` and + `MagicMock`, take arbitrary keyword arguments for configuration +* New mock method `configure_mock` for setting attributes and return values / + side effects on the mock and its attributes +* In Python 2.6 or more recent, `dir` on a mock will report all the dynamically + created attributes (or the full list of attributes if there is a spec) as + well as all the mock methods and attributes. +* Module level `FILTER_DIR` added to control whether `dir(mock)` filters + private attributes. `True` by default. Note that `vars(Mock())` can still be + used to get all instance attributes and `dir(type(Mock())` will still return + all the other attributes (irrespective of `FILTER_DIR`) +* `patch` and `patch.object` now create a `MagicMock` instead of a `Mock` by + default +* Added `ANY` for ignoring arguments in `assert_called_with` calls +* Addition of `call` helper object +* Protocol methods on `MagicMock` are magic mocks, and are created lazily on + first lookup. This means the result of calling a protocol method is a + MagicMock instead of a Mock as it was previously +* Added the Mock API (`assert_called_with` etc) to functions created by + `mocksignature` +* Private attributes `_name`, `_methods`, '_children', `_wraps` and `_parent` + (etc) renamed to reduce likelihood of clash with user attributes. +* Implemented auto-speccing (recursive, lazy speccing of mocks with mocked + signatures for functions/methods) + + Limitations: + + - Doesn't mock magic methods or attributes (it creates MagicMocks, so the + magic methods are *there*, they just don't have the signature mocked nor + are attributes followed) + - Doesn't mock function / method attributes + - Uses object traversal on the objects being mocked to determine types - so + properties etc may be triggered + - The return value of mocked classes (the 'instance') has the same call + signature as the class __init__ (as they share the same spec) + + You create auto-specced mocks by passing `autospec=True` to `patch`. + + Note that attributes that are None are special cased and mocked without a + spec (so any attribute / method can be used). This is because None is + typically used as a default value for attributes that may be of some other + type, and as we don't know what type that may be we allow all access. + + Note that the `autospec` option to `patch` obsoletes the `mocksignature` + option. + +* Added the `create_autospec` function for manually creating 'auto-specced' + mocks +* Removal of deprecated `patch_object` + 2011/05/30 Version 0.7.2 ------------------------ @@ -174,7 +504,7 @@ returns the type of the spec) * Default numeric value for MagicMock is 1 rather than zero (because the MagicMock bool defaults to True and 0 is False) -* Improved failure message for :meth:`Mock.assert_called_with` when the mock +* Improved failure message for :meth:`~Mock.assert_called_with` when the mock has not been called at all * Adding the following to the set of supported magic methods: @@ -334,3 +664,74 @@ ------------------------- Initial release. + + +TODO and Limitations +==================== + +Contributions, bug reports and comments welcomed! + +Feature requests and bug reports are handled on the issue tracker: + + * `mock issue tracker `_ + +`wraps` is not integrated with magic methods. + +`patch` could auto-do the patching in the constructor and unpatch in the +destructor. This would be useful in itself, but violates TOOWTDI and would be +unsafe for IronPython & PyPy (non-deterministic calling of destructors). +Destructors aren't called in CPython where there are cycles, but a weak +reference with a callback can be used to get round this. + +`Mock` has several attributes. This makes it unsuitable for mocking objects +that use these attribute names. A way round this would be to provide methods +that *hide* these attributes when needed. In 0.8 many, but not all, of these +attributes are renamed to gain a `_mock` prefix, making it less likely that +they will clash. Any outstanding attributes that haven't been modified with +the prefix should be changed. + +If a patch is started using `patch.start` and then not stopped correctly then +the unpatching is not done. Using weak references it would be possible to +detect and fix this when the patch object itself is garbage collected. This +would be tricky to get right though. + +When a `Mock` is created by `patch`, arbitrary keywords can be used to set +attributes. If `patch` is created with a `spec`, and is replacing a class, then +a `return_value` mock is created. The keyword arguments are not applied to the +child mock, but could be. + +When mocking a class with `patch`, passing in `spec=True` or `autospec=True`, +the mock class has an instance created from the same spec. Should this be the +default behaviour for mocks anyway (mock return values inheriting the spec +from their parent), or should it be controlled by an additional keyword +argument (`inherit`) to the Mock constructor? `create_autospec` does this, so +an additional keyword argument to Mock is probably unnecessary. + +The `mocksignature` argument to `patch` with a non `Mock` passed into +`new_callable` will *probably* cause an error. Should it just be invalid? + +Note that `NonCallableMock` and `NonCallableMagicMock` still have the unused +(and unusable) attributes: `return_value`, `side_effect`, `call_count`, +`call_args` and `call_args_list`. These could be removed or raise errors on +getting / setting. They also have the `assert_called_with` and +`assert_called_once_with` methods. Removing these would be pointless as +fetching them would create a mock (attribute) that could be called without +error. + +Some outstanding technical debt. The way autospeccing mocks function +signatures was copied and modified from `mocksignature`. This could all be +refactored into one set of functions instead of two. The way we tell if +patchers are started and if a patcher is being used for a `patch.multiple` +call are both horrible. There are now a host of helper functions that should +be rationalised. (Probably time to split mock into a package instead of a +module.) + +Passing arbitrary keyword arguments to `create_autospec`, or `patch` with +`autospec`, when mocking a *function* works fine. However, the arbitrary +attributes are set on the created mock - but `create_autospec` returns a +real function (which doesn't have those attributes). However, what is the use +case for using autospec to create functions with attributes that don't exist +on the original? + +`mocksignature`, plus the `call_args_list` and `method_calls` attributes of +`Mock` could all be deprecated. diff -Nru python-mock-0.7.2/docs/compare.txt python-mock-1.0.1/docs/compare.txt --- python-mock-0.7.2/docs/compare.txt 2011-03-21 21:25:31.000000000 +0000 +++ python-mock-1.0.1/docs/compare.txt 2011-12-31 16:33:30.000000000 +0000 @@ -5,9 +5,6 @@ .. testsetup:: - import sys - import mock - def assertEqual(a, b): assert a == b, ("%r != %r" % (a, b)) @@ -243,10 +240,10 @@ >>> # mock >>> my_mock = mock.Mock(spec=SomeObject) >>> my_mock.method1() - + >>> my_mock.method2() - - >>> assertEqual(my_mock.method_calls, [('method1',), ('method2',)]) + + >>> assertEqual(my_mock.mock_calls, [call.method1(), call.method2()]) :: @@ -378,7 +375,10 @@ assertEqual(some_other_object, some_module.SomeClass()) # Mocker - # (TODO) + instance = mocker.mock() + klass = mocker.replace(SomeClass, spec=None) + klass('expected', 'args') + mocker.result(instance) :: @@ -414,9 +414,9 @@ >>> # mock >>> my_mock = mock.Mock() >>> my_mock.some_method() - + >>> my_mock.some_method() - + >>> assert my_mock.some_method.call_count >= 2 :: diff -Nru python-mock-0.7.2/docs/conf.py python-mock-1.0.1/docs/conf.py --- python-mock-0.7.2/docs/conf.py 2011-05-30 09:57:24.000000000 +0000 +++ python-mock-1.0.1/docs/conf.py 2012-01-11 12:03:47.000000000 +0000 @@ -25,13 +25,38 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.doctest', 'sphinx.ext.autodoc'] +extensions = ['sphinx.ext.doctest'] -html_theme = 'basic' +doctest_global_setup = """ +import os +import sys +import mock +from mock import * # yeah, I know :-/ +import unittest2 +import __main__ + +if os.getcwd() not in sys.path: + sys.path.append(os.getcwd()) + +# keep a reference to __main__ +sys.modules['__main'] = __main__ + +class ProxyModule(object): + def __init__(self): + self.__dict__ = globals() + +sys.modules['__main__'] = ProxyModule() +""" + +doctest_global_cleanup = """ +sys.modules['__main__'] = sys.modules['__main'] +""" + +html_theme = 'nature' html_theme_options = {} # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +#templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.txt' @@ -41,7 +66,7 @@ # General substitutions. project = u'Mock' -copyright = u'2007-2011, Michael Foord & the mock team' +copyright = u'2007-2012, Michael Foord & the mock team' # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. @@ -88,7 +113,7 @@ # The style sheet to use for HTML and HTML Help pages. A file of that name # must exist either in Sphinx' static/ path, or in one of the custom paths # given in html_static_path. -html_style = 'adctheme.css' +#html_style = 'adctheme.css' # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -109,7 +134,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +#html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff -Nru python-mock-0.7.2/docs/examples.txt python-mock-1.0.1/docs/examples.txt --- python-mock-0.7.2/docs/examples.txt 2011-05-30 19:51:53.000000000 +0000 +++ python-mock-1.0.1/docs/examples.txt 2012-04-24 00:24:08.000000000 +0000 @@ -1,3 +1,5 @@ +.. _further-examples: + ================== Further Examples ================== @@ -6,8 +8,6 @@ .. testsetup:: - import sys, unittest2 - from mock import MagicMock, Mock, patch from datetime import date BackendProvider = Mock() @@ -28,35 +28,12 @@ out = unittest2.TestCase.run(self, result) assert result.wasSuccessful() - def configure_mock(mock, **kwargs): - if mock is None: - mock = Mock() - for arg, val in sorted(kwargs.items(), key=lambda entry: len(entry[0].split('.'))): - args = arg.split('.') - final = args.pop() - obj = mock - for entry in args: - obj = getattr(obj, entry) - setattr(obj, final, val) - return mock - - class Call(object): - def __init__(self, name=None): - self.name = name - - def __call__(self, *args, **kwargs): - if self.name is None: - return (args, kwargs) - return (self.name, args, kwargs) - - def __getattr__(self, attr): - if self.name is None: - return Call(attr) - name = '%s.%s' % (self.name, attr) - return Call(name) + from mock import inPy3k + - call = Call() +For comprehensive examples, see the unit tests included in the full source +distribution. Here are some more examples for some slightly more advanced scenarios than in the :ref:`getting started ` guide. @@ -66,7 +43,7 @@ ===================== Mocking chained calls is actually straightforward with mock once you -understand the :attr:`Mock.return_value` attribute. When a mock is called for +understand the :attr:`~Mock.return_value` attribute. When a mock is called for the first time, or you fetch its `return_value` before it has been called, a new `Mock` is created. @@ -77,7 +54,7 @@ >>> mock = Mock() >>> mock().foo(a=2, b=3) - + >>> mock.return_value.foo.assert_called_with(a=2, b=3) From here it is a simple step to configure and then make assertions about @@ -96,34 +73,32 @@ ... # more code Assuming that `BackendProvider` is already well tested, how do we test -`method()`? Specifically, we want to test that the code section ``# more -code`` uses the response object in the correct way. +`method()`? Specifically, we want to test that the code section `# more +code` uses the response object in the correct way. As this chain of calls is made from an instance attribute we can monkey patch the `backend` attribute on a `Something` instance. In this particular case we are only interested in the return value from the final call to `start_call` so we don't have much configuration to do. Let's assume the object it returns is 'file-like', so we'll ensure that our response object -uses the builtin ``file`` as its `spec`. +uses the builtin `file` as its `spec`. To do this we create a mock instance as our mock backend and create a mock response object for it. To set the response as the return value for that final `start_call` we could do this: - ``mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response``. + `mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response`. -Here's how we might do it in a slightly nicer way. We start by creating our -initial mocks: +We can do that in a slightly nicer way using the :meth:`~Mock.configure_mock` +method to directly set the return value for us: .. doctest:: >>> something = Something() >>> mock_response = Mock(spec=file) >>> mock_backend = Mock() - >>> get_endpoint = mock_backend.get_endpoint - >>> create_call = get_endpoint.return_value.create_call - >>> start_call = create_call.return_value.start_call - >>> start_call.return_value = mock_response + >>> config = {'get_endpoint.return_value.create_call.return_value.start_call.return_value': mock_response} + >>> mock_backend.configure_mock(**config) With these we monkey patch the "mock backend" in place and can make the real call: @@ -133,15 +108,16 @@ >>> something.backend = mock_backend >>> something.method() -Keeping references to the intermediate methods makes our assertions easier, -and also makes the code less ugly. +Using :attr:`~Mock.mock_calls` we can check the chained call with a single +assert. A chained call is several calls in one line of code, so there will be +several entries in `mock_calls`. We can use :meth:`call.call_list` to create +this list of calls for us: .. doctest:: - >>> get_endpoint.assert_called_with('foobar') - >>> create_call.assert_called_with('spam', 'eggs') - >>> start_call.assert_called_with() - >>> # make assertions on mock_response about how it is used + >>> chained = call.get_endpoint('foobar').create_call('spam', 'eggs').start_call() + >>> call_list = chained.call_list() + >>> assert mock_backend.mock_calls == call_list Partial mocking @@ -185,64 +161,55 @@ Calls to the date constructor are recorded in the `mock_date` attributes (`call_count` and friends) which may also be useful for your tests. +An alternative way of dealing with mocking dates, or other builtin classes, +is discussed in `this blog entry +`_. -Mocking open -============ -Using `open` as a context manager is a great way to ensure your file handles are -closed properly and is becoming common:: +Mocking a Generator Method +========================== - with open('/some/path', 'w') as f: - f.write('something') +A Python generator is a function or method that uses the `yield statement +`_ to +return a series of values when iterated over [#]_. -The issue is that even if you mock out the call to `open` it is the -*returned object* that is used as a context manager (and has `__enter__` and -`__exit__` called). +A generator method / function is called to return the generator object. It is +the generator object that is then iterated over. The protocol method for +iteration is `__iter__ +`_, so we can +mock this using a `MagicMock`. -So first the topic of creating a mock object that can be called, with the -return value able to act as a context manager. The easiest way of doing this -is to use the new :class:`MagicMock`, which -is preconfigured to be able to act as a context manger. As an added bonus -we'll use the spec argument to ensure that the mocked object can only be used -in the same ways a real file could be used (attempting to access a method or -attribute not on the `file` will raise an ``AttributeError``): +Here's an example class with an "iter" method implemented as a generator: .. doctest:: - >>> mock_open = Mock() - >>> mock_open.return_value = MagicMock(spec=file) + >>> class Foo(object): + ... def iter(self): + ... for i in [1, 2, 3]: + ... yield i + ... + >>> foo = Foo() + >>> list(foo.iter()) + [1, 2, 3] -In terms of configuring our mock this is all that needs to be done. In fact it -could be constructed with a one liner: ``mock_open = -Mock(return_value=MagicMock(spec=file))``. -So what is the best way of patching the builtin ``open`` function? One way -would be to globally patch ``__builtin__.open``. So long as you are sure that -none of the other code being called also accesses ``open`` this is perfectly -reasonable. It does make some people nervous however. By default we can't -patch the ``open`` name in the module where it is used, because ``open`` -doesn't exist as an attribute in that namespace. ``patch`` refuses to patch -attributes that don't exist because that is a great way of having tests that -pass but code that is horribly broken (your code can access attributes that -only exist during your tests!). ``patch`` *will* however create (and then -remove again) non-existent attributes if you tell it that you are really sure -you know what you're doing. +How would we mock this class, and in particular its "iter" method? -By passing ``create=True`` into ``patch`` we can just patch the ``open`` -function in the module under test instead of patching it globally: +To configure the values returned from the iteration (implicit in the call to +`list`), we need to configure the object returned by the call to `foo.iter()`. .. doctest:: - >>> open_name = '%s.open' % __name__ - >>> with patch(open_name, create=True) as mock_open: - ... mock_open.return_value = MagicMock(spec=file) - ... - ... with open('/some/path', 'w') as f: - ... f.write('something') - ... - - >>> file_handle = mock_open.return_value.__enter__.return_value - >>> file_handle.write.assert_called_with('something') + >>> mock_foo = MagicMock() + >>> mock_foo.iter.return_value = iter([1, 2, 3]) + >>> list(mock_foo.iter()) + [1, 2, 3] + +.. [#] There are also generator expressions and more `advanced uses + `_ of generators, but we aren't + concerned about them here. A very good introduction to generators and how + powerful they are is: `Generator Tricks for Systems Programmers + `_. Applying the same patch to every test method @@ -326,7 +293,7 @@ patch out methods with a mock that having to create a real function becomes a nuisance. -If you pass ``mocksignature=True`` to patch then it does the patching with a +If you pass `autospec=True` to patch then it does the patching with a *real* function object. This function object has the same signature as the one it is replacing, but delegates to a mock under the hood. You still get your mock auto-created in exactly the same way as before. What it means though, is @@ -341,7 +308,7 @@ ... def foo(self): ... pass ... - >>> with patch.object(Foo, 'foo', mocksignature=True) as mock_foo: + >>> with patch.object(Foo, 'foo', autospec=True) as mock_foo: ... mock_foo.return_value = 'foo' ... foo = Foo() ... foo.foo() @@ -349,36 +316,10 @@ 'foo' >>> mock_foo.assert_called_once_with(foo) -If we don't use `mocksignature=True` then the unbound method is patched out +If we don't use `autospec=True` then the unbound method is patched out with a Mock instance instead, and isn't called with `self`. -Mocking Properties -================== - -A few people have asked about `mocking properties -`_, specifically -tracking when properties are fetched from objects or even having side effects -when properties are fetched. - -You can already do this by subclassing :class:`Mock` and providing your own -property. Delegating to another mock is one way to record the property being -accessed whilst still able to control things like return values: - -.. doctest:: - - >>> mock_foo = Mock(return_value='fish') - >>> class MyMock(Mock): - ... @property - ... def foo(self): - ... return mock_foo() - ... - >>> mock = MyMock() - >>> mock.foo - 'fish' - >>> mock_foo.assert_called_once_with() - - Checking multiple calls with mock ================================= @@ -406,11 +347,8 @@ Both `assert_called_with` and `assert_called_once_with` make assertions about the *most recent* call. If your mock is going to be called several times, and -you want to make assertions about *all* those calls, the API is not quite so -nice. - -All of the calls, in order, are stored in `call_args_list` as tuples of -(positional args, keyword args). +you want to make assertions about *all* those calls you can use +:attr:`~Mock.call_args_list`: .. doctest:: @@ -419,58 +357,18 @@ >>> mock(4, 5, 6) >>> mock() >>> mock.call_args_list - [((1, 2, 3), {}), ((4, 5, 6), {}), ((), {})] - + [call(1, 2, 3), call(4, 5, 6), call()] -Because it stores positional args *and* keyword args, even if they are empty, -the list is overly verbose which makes for ugly tests. It turns out that I do -this rarely enough that I've never got around to improving it. One of the new -features in 0.7.0 helps with this. The tuples of (positional, keyword) -arguments are now custom objects that allow for 'soft comparisons' -(implemented by Konrad Delong). This allows you to omit empty positional or -keyword arguments from tuples you compare against. +The :data:`call` helper makes it easy to make assertions about these calls. You +can build up a list of expected calls and compare it to `call_args_list`. This +looks remarkably similar to the repr of the `call_args_list`: .. doctest:: - >>> mock.call_args_list - [((1, 2, 3), {}), ((4, 5, 6), {}), ((), {})] - >>> expected = [((1, 2, 3),), ((4, 5, 6),), ()] + >>> expected = [call(1, 2, 3), call(4, 5, 6), call()] >>> mock.call_args_list == expected True -This is an improvement, but still not as nice as `assert_called_with`. Here's -a helper function that pops the last argument of the call args list and -decrements the call count. This allows you to make asserts as a series of -calls to `assert_called_with` followed by a `pop_last_call`. - -.. doctest:: - - >>> def pop_last_call(mock): - ... if not mock.call_count: - ... raise AssertionError("Cannot pop last call: call_count is 0") - ... mock.call_args_list.pop() - ... try: - ... mock.call_args = mock.call_args_list[-1] - ... except IndexError: - ... mock.call_args = None - ... mock.called = False - ... mock.call_count -=1 - ... - >>> mock = Mock(return_value=None) - >>> mock(1, foo='bar') - >>> mock(2, foo='baz') - >>> mock(3, foo='spam') - >>> mock.assert_called_with(3, foo='spam') - >>> pop_last_call(mock) - >>> mock.assert_called_with(2, foo='baz') - >>> pop_last_call(mock) - >>> mock.assert_called_once_with(1, foo='bar') - -The calls to `assert_called_with` are made in reverse order to the actual -calls. Your final call can be a call to `assert_called_once_with`, that -ensures there were no extra calls you weren't expecting. You could, if you -wanted, extend the function to take args and kwargs and do the assert for you. - Coping with mutable arguments ============================= @@ -541,7 +439,7 @@ ... >>> new_mock.assert_called_with(set([6])) >>> new_mock.call_args - ((set([6]),), {}) + call(set([6])) `copy_call_args` is called with the mock that will be called. It returns a new mock that we do the assertion on. The `side_effect` function makes a copy of @@ -562,13 +460,73 @@ >>> mock(set([6])) >>> mock(set()) Traceback (most recent call last): - ... + ... AssertionError +An alternative approach is to create a subclass of `Mock` or `MagicMock` that +copies (using `copy.deepcopy +`_) the arguments. +Here's an example implementation: + +.. doctest:: + + >>> from copy import deepcopy + >>> class CopyingMock(MagicMock): + ... def __call__(self, *args, **kwargs): + ... args = deepcopy(args) + ... kwargs = deepcopy(kwargs) + ... return super(CopyingMock, self).__call__(*args, **kwargs) + ... + >>> c = CopyingMock(return_value=None) + >>> arg = set() + >>> c(arg) + >>> arg.add(1) + >>> c.assert_called_with(set()) + >>> c.assert_called_with(arg) + Traceback (most recent call last): + ... + AssertionError: Expected call: mock(set([1])) + Actual call: mock(set([])) + >>> c.foo + + +When you subclass `Mock` or `MagicMock` all dynamically created attributes, +and the `return_value` will use your subclass automatically. That means all +children of a `CopyingMock` will also have the type `CopyingMock`. + + +Raising exceptions on attribute access +====================================== + +You can use :class:`PropertyMock` to mimic the behaviour of properties. This +includes raising exceptions when an attribute is accessed. + +Here's an example raising a `ValueError` when the 'foo' attribute is accessed: + +.. doctest:: + + >>> m = MagicMock() + >>> p = PropertyMock(side_effect=ValueError) + >>> type(m).foo = p + >>> m.foo + Traceback (most recent call last): + .... + ValueError + +Because every mock object has its own type, a new subclass of whichever mock +class you're using, all mock objects are isolated from each other. You can +safely attach properties (or other descriptors or whatever you want in fact) +to `type(mock)` without affecting other mock objects. + Multiple calls with different effects ===================================== +.. note:: + + In mock 1.0 the handling of iterable `side_effect` was changed. Any + exceptions in the iterable will be raised instead of returned. + Handling code that needs to behave differently on subsequent calls during the test can be tricky. For example you may have a function that needs to raise an exception the first time it is called but returns a response on the second @@ -589,7 +547,7 @@ >>> mock = Mock(side_effect=side_effect) >>> mock('first') Traceback (most recent call last): - ... + ... Exception: boom >>> mock('second') 'response' @@ -610,7 +568,7 @@ >>> mock = Mock(side_effect=side_effect) >>> mock('first') Traceback (most recent call last): - ... + ... Exception: boom >>> mock('second') 'response' @@ -672,7 +630,6 @@ >>> assert mymodule.Foo is original - Mocking a dictionary with MagicMock =================================== @@ -680,7 +637,7 @@ access to it whilst having it still behave like a dictionary. We can do this with :class:`MagicMock`, which will behave like a dictionary, -and using :data:`Mock.side_effect` to delegate dictionary access to a real +and using :data:`~Mock.side_effect` to delegate dictionary access to a real underlying dictionary that is under our control. When the `__getitem__` and `__setitem__` methods of our `MagicMock` are called @@ -688,7 +645,7 @@ the case of `__setitem__` the value too). We can also control what is returned. After the `MagicMock` has been used we can use attributes like -:data:`Mock.call_args_list` to assert about how the dictionary was used: +:data:`~Mock.call_args_list` to assert about how the dictionary was used: .. doctest:: @@ -736,7 +693,7 @@ 3 >>> mock['d'] Traceback (most recent call last): - ... + ... KeyError: 'd' >>> mock['b'] = 'fish' >>> mock['d'] = 'eggs' @@ -751,95 +708,80 @@ .. doctest:: >>> mock.__getitem__.call_args_list - [(('a',), {}), (('c',), {}), (('d',), {}), (('b',), {}), (('d',), {})] + [call('a'), call('c'), call('d'), call('b'), call('d')] >>> mock.__setitem__.call_args_list - [(('b', 'fish'), {}), (('d', 'eggs'), {})] + [call('b', 'fish'), call('d', 'eggs')] >>> my_dict {'a': 1, 'c': 3, 'b': 'fish', 'd': 'eggs'} -Less verbose configuration of mock objects -========================================== +Mock subclasses and their attributes +==================================== -If you have a mock object, particularly one created for you by `patch -`_, -setting up attributes and return values for methods takes one line for every -aspect of configuration. - -A feature I'm considering for mock 0.8.0 is an api for `making configuring -mocks less verbose `_. As -is the way of these things, it is easy to prototype this first with a function -that you can use right now. - -`configure_mock` is a function that takes a `Mock() -`_ -instance along with keyword arguments for attributes of the mock you want to -set. For example, to set `mock.foo` to 3 and `mock.bar` to None, you call: +There are various reasons why you might want to subclass `Mock`. One reason +might be to add helper methods. Here's a silly example: .. doctest:: - >>> mock = Mock() - >>> configure_mock(mock, foo=3, bar=None) - - >>> mock.foo - 3 - >>> print mock.bar - None + >>> class MyMock(MagicMock): + ... def has_been_called(self): + ... return self.called + ... + >>> mymock = MyMock(return_value=None) + >>> mymock + + >>> mymock.has_been_called() + False + >>> mymock() + >>> mymock.has_been_called() + True -`return_value` and `side_effect` can be used to set them directly on the main -mock *anyway* as they are just attributes. +The standard behaviour for `Mock` instances is that attributes and the return +value mocks are of the same type as the mock they are accessed on. This ensures +that `Mock` attributes are `Mocks` and `MagicMock` attributes are `MagicMocks` +[#]_. So if you're subclassing to add helper methods then they'll also be +available on the attributes and return value mock of instances of your +subclass. .. doctest:: - >>> mock = Mock() - >>> configure_mock(mock, side_effect=KeyError) - - >>> mock() - Traceback (most recent call last): - ... - KeyError + >>> mymock.foo + + >>> mymock.foo.has_been_called() + False + >>> mymock.foo() + + >>> mymock.foo.has_been_called() + True -This is fine for directly setting attributes, but what if you want to -configure the return values or side effects of child mocks? How about using -standard dotted notation to specify these. Instead of normal keyword arguments -you'll need to build a dictionary of arguments and pass them in with `**`. The -function could also create a mock for us if we pass in `None`: +Sometimes this is inconvenient. For example, `one user +`_ is subclassing mock to +created a `Twisted adaptor +`_. +Having this applied to attributes too actually causes errors. + +`Mock` (in all its flavours) uses a method called `_get_child_mock` to create +these "sub-mocks" for attributes and return values. You can prevent your +subclass being used for attributes by overriding this method. The signature is +that it takes arbitrary keyword arguments (`**kwargs`) which are then passed +onto the mock constructor: .. doctest:: - >>> args = {'foo.baz.return_value': 'fish', 'foo.side_effect': - ... RuntimeError, 'side_effect': KeyError, 'foo.bar': 3} - ... - >>> mock = configure_mock(None, **args) - >>> mock.foo.bar - 3 - >>> mock() - Traceback (most recent call last): - ... - KeyError - >>> mock.foo.baz() - 'fish' - >>> mock.foo() - Traceback (most recent call last): - ... - RuntimeError - -If you have any opinions on this then please comment on the issue. - -A minimal implementation of `configure_mock` that you can start using now is:: - - def configure_mock(mock, **kwargs): - if mock is None: - mock = Mock() - for arg, val in sorted(kwargs.items(), - key=lambda entry: len(entry[0].split('.'))): - args = arg.split('.') - final = args.pop() - obj = mock - for entry in args: - obj = getattr(obj, entry) - setattr(obj, final, val) - return mock + >>> class Subclass(MagicMock): + ... def _get_child_mock(self, **kwargs): + ... return MagicMock(**kwargs) + ... + >>> mymock = Subclass() + >>> mymock.foo + + >>> assert isinstance(mymock, Subclass) + >>> assert not isinstance(mymock.foo, Subclass) + >>> assert not isinstance(mymock(), Subclass) + +.. [#] An exception to this rule are the non-callable mocks. Attributes use the + callable variant because otherwise non-callable mocks couldn't have callable + methods. Mocking imports with patch.dict @@ -878,7 +820,7 @@ ... import fooble ... fooble.blob() ... - + >>> assert 'fooble' not in sys.modules >>> mock.blob.assert_called_once_with() @@ -894,7 +836,7 @@ ... from fooble import blob ... blob.blip() ... - + >>> mock.blob.blip.assert_called_once_with() With slightly more work you can also mock package imports: @@ -907,159 +849,109 @@ ... from package.module import fooble ... fooble() ... - + >>> mock.module.fooble.assert_called_once_with() -Unfortunately it seems that using `patch.dict` as a test *decorator* on -`sys.modules` interferes with the way `nosetests -`_ collects tests. -`nosetests` does some manipulation of `sys.modules` (along with `sys.path` -manipulation) and using `patch.dict` with `sys.modules` can cause it to not -find tests. Using `patch.dict` as a context manager, or using the -:ref:`start-and-stop`, work around this by taking a reference to `sys.modules` -inside the test rather than at import time. (Using `patch.dict` as a decorator -takes a *reference* to `sys.modules` at import time, it doesn't do the -patching until the test is executed though.) - Tracking order of calls and less verbose call assertions ======================================================== The :class:`Mock` class allows you to track the *order* of method calls on -your mock objects through the :attr:`Mock.method_calls` attribute. This +your mock objects through the :attr:`~Mock.method_calls` attribute. This doesn't allow you to track the order of calls between separate mock objects, -however we can use `method_calls` to achieve the same effect. +however we can use :attr:`~Mock.mock_calls` to achieve the same effect. -Because mocks track calls to child mocks in `method_calls`, and accessing an +Because mocks track calls to child mocks in `mock_calls`, and accessing an arbitrary attribute of a mock creates a child mock, we can create our separate mocks from a parent one. Calls to those child mock will then all be recorded, -in order, in the `method_calls` of the parent: +in order, in the `mock_calls` of the parent: .. doctest:: >>> manager = Mock() - >>> mock_foo = manager.foo >>> mock_bar = manager.bar >>> mock_foo.something() - + >>> mock_bar.other.thing() - - - >>> manager.method_calls - [('foo.something', (), {}), ('bar.other.thing', (), {})] - -Using the "soft comparisons" feature of mock 0.7.0 we can make the final -assertion about the expected calls less verbose: - -.. doctest:: - - >>> expected_calls = [('foo.something',), ('bar.other.thing',)] - >>> manager.method_calls == expected_calls - True - -To make them even less verbose I would like to add a new `call` object to mock -0.8.0. You can see the issues I expect to work on for 0.8.0 in the `issues -list `_. - -`call` would look something like this:: - - class Call(object): - def __init__(self, name=None): - self.name = name - - def __call__(self, *args, **kwargs): - if self.name is None: - return (args, kwargs) - return (self.name, args, kwargs) - - def __getattr__(self, attr): - if self.name is None: - return Call(attr) - name = '%s.%s' % (self.name, attr) - return Call(name) + - call = Call() + >>> manager.mock_calls + [call.foo.something(), call.bar.other.thing()] -You can then use it like this: +We can then assert about the calls, including the order, by comparing with +the `mock_calls` attribute on the manager mock: .. doctest:: - >>> mock = Mock(return_value=None) - >>> mock(1, 2, 3) - >>> mock(a=3, b=6) - >>> mock.call_args_list == [call(1, 2, 3), call(a=3, b=6)] - True - - >>> mock = Mock() - >>> mock.foo(1, 2 ,3) - - >>> mock.bar.baz(a=3, b=6) - - >>> mock.method_calls == [call.foo(1, 2, 3), call.bar.baz(a=3, b=6)] + >>> expected_calls = [call.foo.something(), call.bar.other.thing()] + >>> manager.mock_calls == expected_calls True -And for good measure, the first example (tracking order of calls between -mocks) using the new `call` object for assertions: +If `patch` is creating, and putting in place, your mocks then you can attach +them to a manager mock using the :meth:`~Mock.attach_mock` method. After +attaching calls will be recorded in `mock_calls` of the manager. .. doctest:: - >>> manager = Mock() - - >>> mock_foo = manager.foo - >>> mock_bar = manager.bar - - >>> mock_foo.something() - - >>> mock_bar.other.thing() - - - >>> manager.method_calls == [call.foo.something(), call.bar.other.thing()] - True - - -Matching any argument in assertions -=================================== - -Sometimes you may need to make assertions about *some* of the arguments in a -call to mock, but either not care about some of the arguments or want to pull -them individually out of :attr:`Mock.call_args` and make more complex -assertions on them. - -To ignore certain arguments you can pass in objects that compare equal to -*everything*. Calls to :meth:`Mock.assert_called_with` and -:meth:`Mock.assert_called_once_with` will then succeed no matter what was -passed in. - -Here's an example implementation: + >>> manager = MagicMock() + >>> with patch('mymodule.Class1') as MockClass1: + ... with patch('mymodule.Class2') as MockClass2: + ... manager.attach_mock(MockClass1, 'MockClass1') + ... manager.attach_mock(MockClass2, 'MockClass2') + ... MockClass1().foo() + ... MockClass2().bar() + ... + + + >>> manager.mock_calls + [call.MockClass1(), + call.MockClass1().foo(), + call.MockClass2(), + call.MockClass2().bar()] + +If many calls have been made, but you're only interested in a particular +sequence of them then an alternative is to use the +:meth:`~Mock.assert_has_calls` method. This takes a list of calls (constructed +with the :data:`call` object). If that sequence of calls are in +:attr:`~Mock.mock_calls` then the assert succeeds. .. doctest:: - >>> class _ANY(object): - ... def __eq__(self, other): - ... return True - ... - >>> ANY = _ANY() - -And an example of using it: + >>> m = MagicMock() + >>> m().foo().bar().baz() + + >>> m.one().two().three() + + >>> calls = call.one().two().three().call_list() + >>> m.assert_has_calls(calls) + +Even though the chained call `m.one().two().three()` aren't the only calls that +have been made to the mock, the assert still succeeds. + +Sometimes a mock may have several calls made to it, and you are only interested +in asserting about *some* of those calls. You may not even care about the +order. In this case you can pass `any_order=True` to `assert_has_calls`: .. doctest:: - >>> mock = Mock(return_value=None) - >>> mock('foo', bar=object()) - >>> mock.assert_called_once_with('foo', bar=ANY) + >>> m = MagicMock() + >>> m(1), m.two(2, 3), m.seven(7), m.fifty('50') + (...) + >>> calls = [call.fifty('50'), call(1), call.seven(7)] + >>> m.assert_has_calls(calls, any_order=True) More complex argument matching ============================== -Using the same basic concept as the `ANY` pattern above we can implement -matchers to do more complex assertions on objects used as arguments to mocks. +Using the same basic concept as `ANY` we can implement matchers to do more +complex assertions on objects used as arguments to mocks. Suppose we expect some object to be passed to a mock that by default compares equal based on object identity (which is the Python default for user -defined classes). To use :meth:`Mock.assert_called_with` we would need to pass +defined classes). To use :meth:`~Mock.assert_called_with` we would need to pass in the exact same object. If we are only interested in some of the attributes of this object then we can create a matcher that will check these attributes for us. @@ -1077,9 +969,9 @@ >>> mock(Foo(1, 2)) >>> mock.assert_called_with(Foo(1, 2)) Traceback (most recent call last): - ... - AssertionError: Expected: ((<__main__.Foo object at 0x...>,), {}) - Called with: ((<__main__.Foo object at 0x...>,), {}) + ... + AssertionError: Expected: call(<__main__.Foo object at 0x...>) + Actual call: call(<__main__.Foo object at 0x...>) A comparison function for our `Foo` class might look something like this: @@ -1126,7 +1018,7 @@ >>> match_wrong = Matcher(compare, Foo(3, 4)) >>> mock.assert_called_with(match_wrong) Traceback (most recent call last): - ... + ... AssertionError: Expected: ((,), {}) Called with: ((,), {}) @@ -1138,3 +1030,34 @@ that may be useful here, in the form of its equality matcher (`hamcrest.library.integration.match_equality `_). + + +Less verbose configuration of mock objects +========================================== + +This recipe, for easier configuration of mock objects, is now part of `Mock`. +See the :meth:`~Mock.configure_mock` method. + + +Matching any argument in assertions +=================================== + +This example is now built in to mock. See :data:`ANY`. + + +Mocking Properties +================== + +This example is now built in to mock. See :class:`PropertyMock`. + + +Mocking open +============ + +This example is now built in to mock. See :func:`mock_open`. + + +Mocks without some attributes +============================= + +This example is now built in to mock. See :ref:`deleting-attributes`. diff -Nru python-mock-0.7.2/docs/getting-started.txt python-mock-1.0.1/docs/getting-started.txt --- python-mock-0.7.2/docs/getting-started.txt 2011-05-29 21:02:20.000000000 +0000 +++ python-mock-1.0.1/docs/getting-started.txt 2012-04-13 19:42:45.000000000 +0000 @@ -8,13 +8,6 @@ .. testsetup:: - import os, sys - if not os.getcwd() in sys.path: - sys.path.append(os.getcwd()) - - import unittest - from mock import Mock, sentinel, patch - class SomeClass(object): static_method = None class_method = None @@ -25,125 +18,93 @@ sys.modules['module'] = package.module -For comprehensive examples, see the unit tests included in the full source -distribution. - - Using Mock ========== Mock Patching Methods --------------------- -``Mock`` objects can be used for: +Common uses for :class:`Mock` objects include: * Patching methods * Recording method calls on objects +You might want to replace a method on an object to check that +it is called with the correct arguments by another part of the system: + .. doctest:: - >>> from mock import Mock >>> real = SomeClass() - >>> real.method = Mock() + >>> real.method = MagicMock(name='method') >>> real.method(3, 4, 5, key='value') - + + +Once our mock has been used (`real.method` in this example) it has methods +and attributes that allow you to make assertions about how it has been used. + +.. note:: -Once the mock has been used it has methods and attributes that allow you to -make assertions about how it has been used. + In most of these examples the :class:`Mock` and :class:`MagicMock` classes + are interchangeable. As the `MagicMock` is the more capable class it makes + a sensible one to use by default. -`Mock` objects are callable. If they are called then the ``called`` attribute is -set to `True`. +Once the mock has been called its :attr:`~Mock.called` attribute is set to +`True`. More importantly we can use the :meth:`~Mock.assert_called_with` or +:meth:`~Mock.assert_called_once_with` method to check that it was called with +the correct arguments. -This example tests that calling ``method`` results in a call to ``something``: +This example tests that calling `ProductionClass().method` results in a call to +the `something` method: .. doctest:: - >>> from mock import Mock + >>> from mock import MagicMock >>> class ProductionClass(object): ... def method(self): - ... self.something() - ... def something(self): + ... self.something(1, 2, 3) + ... def something(self, a, b, c): ... pass ... >>> real = ProductionClass() - >>> real.something = Mock() - >>> real.method() - >>> real.something.called - True - -If you want access to the actual arguments the mock was called with, for example -to make assertions about the arguments themselves, then this information is -available. - -.. doctest:: - - >>> real = ProductionClass() - >>> real.something = Mock() - >>> real.method() - >>> real.something.call_count - 1 - >>> args, kwargs = (), {} - >>> assert real.something.call_args == (args, kwargs) - >>> assert real.something.call_args_list == [(args, kwargs)] - -Checking ``call_args_list`` tests how many times the mock was called, and the -arguments for each call, in a single assertion. - -From 0.7.0 you can omit empty args and keyword args, which makes comparisons -less verbose: - -.. doctest:: - - >>> real = ProductionClass() - >>> real.something = Mock() - >>> real.method() - >>> assert real.something.call_args == () - >>> assert real.something.call_args_list == [()] - -If the mock has only been called once then you can use -:meth:`Mock.assert_called_once_with`: - -.. doctest:: - - >>> real = ProductionClass() - >>> real.something = Mock() + >>> real.something = MagicMock() >>> real.method() - >>> real.something.assert_called_once_with() - -If you don't care how many times an object has been called, but are just -interested in the most recent call, then you can use -:meth:`Mock.assert_called_with`: - -.. doctest:: + >>> real.something.assert_called_once_with(1, 2, 3) - >>> mock = Mock(return_value=None) - >>> mock(1, 2, 3) - >>> mock.assert_called_with(1, 2, 3) Mock for Method Calls on an Object ---------------------------------- +In the last example we patched a method directly on an object to check that it +was called correctly. Another common use case is to pass an object into a +method (or some part of the system under test) and then check that it is used +in the correct way. + +The simple `ProductionClass` below has a `closer` method. If it is called with +an object then it calls `close` on it. + .. doctest:: >>> class ProductionClass(object): ... def closer(self, something): ... something.close() ... + +So to test it we need to pass in an object with a `close` method and check +that it was called correctly. + +.. doctest:: + >>> real = ProductionClass() >>> mock = Mock() >>> real.closer(mock) >>> mock.close.assert_called_with() - We don't have to do any work to provide the 'close' method on our mock. Accessing close creates it. So, if 'close' hasn't already been called then -accessing it in the test will create it, but :meth:`Mock.assert_called_with` +accessing it in the test will create it, but :meth:`~Mock.assert_called_with` will raise a failure exception. -As ``close`` is a mock object is has all the attributes from the previous -example. - Mocking Classes --------------- @@ -154,8 +115,9 @@ by looking at the return value of the mocked class. In the example below we have a function `some_function` that instantiates `Foo` -and calls a method on it. We can mock out the class `Foo`, and configure the -behaviour of the `Foo` instance by configuring the `mock.return_value`. +and calls a method on it. The call to `patch` replaces the class `Foo` with a +mock. The `Foo` instance is the result of calling the mock, so it is configured +by modifying the mock :attr:`~Mock.return_value`. .. doctest:: @@ -179,97 +141,43 @@ .. doctest:: - >>> mock = Mock(name='foo') + >>> mock = MagicMock(name='foo') >>> mock - + >>> mock.method - - - -Limiting Available Methods --------------------------- - -The disadvantage of the approach above is that *all* method access creates a -new mock. This means that you can't tell if any methods were called that -shouldn't have been. There are two ways round this. The first is by -restricting the methods available on your mock. - -.. doctest:: - - >>> mock = Mock(spec=['close']) - >>> real.closer(mock) - >>> mock.close.assert_called_with() - >>> mock.foo - Traceback (most recent call last): - ... - AttributeError: Mock object has no attribute 'foo' - -If ``closer`` calls any methods on ``mock`` *other* than close, then an -``AttributeError`` will be raised. - -When you use `spec` it is still possible to set arbitrary attributes on the mock -object. For a stronger form that only allows you to *set* attributes that are in -the spec you can use `spec_set` instead: - -.. doctest:: - - >>> mock = Mock(spec=['close']) - >>> mock.foo = 3 - >>> mock.foo - 3 - >>> mock = Mock(spec_set=['close']) - >>> mock.foo = 3 - Traceback (most recent call last): - ... - AttributeError: Mock object has no attribute 'foo' - -Mock objects that use a class or an instance as a `spec` or `spec_set` are able -to pass `isintance` tests: - -.. doctest:: + - >>> mock = Mock(spec=SomeClass) - >>> isinstance(mock, SomeClass) - True - >>> mock = Mock(spec_set=SomeClass()) - >>> isinstance(mock, SomeClass) - True -Tracking all Method Calls -------------------------- +Tracking all Calls +------------------ -An alternative way to verify that only the expected methods have been accessed -is to use the ``method_calls`` attribute of the mock. This records all calls +Often you want to track more than a single call to a method. The +:attr:`~Mock.mock_calls` attribute records all calls to child attributes of the mock - and also to their children. -This is useful if you have a mock where you expect an attribute method to be -called. You could access the attribute directly, but ``method_calls`` provides -a convenient way of looking at all method calls: - .. doctest:: - >>> mock = Mock() + >>> mock = MagicMock() >>> mock.method() - - >>> mock.Property.method(10, x=53) - - >>> mock.method_calls - [('method', (), {}), ('Property.method', (10,), {'x': 53})] + + >>> mock.attribute.method(10, x=53) + + >>> mock.mock_calls + [call.method(), call.attribute.method(10, x=53)] -If you make an assertion about ``method_calls`` and any unexpected methods -have been called, then the assertion will fail. +If you make an assertion about `mock_calls` and any unexpected methods +have been called, then the assertion will fail. This is useful because as well +as asserting that the calls you expected have been made, you are also checking +that they were made in the right order and with no additional calls: -Again, from 0.7.0, empty arguments and keyword arguments can be omitted for -less verbose comparisons: +You use the :data:`call` object to construct lists for comparing with +`mock_calls`: .. doctest:: - >>> mock = Mock() - >>> mock.method1() - - >>> mock.method2() - - >>> assert mock.method_calls == [('method1',), ('method2',)] + >>> expected = [call.method(), call.attribute.method(10, x=53)] + >>> mock.mock_calls == expected + True Setting Return Values and Attributes @@ -311,19 +219,83 @@ 3 Sometimes you want to mock up a more complex situation, like for example -``mock.connection.cursor().execute("SELECT 1")``: +`mock.connection.cursor().execute("SELECT 1")`. If we wanted this call to +return a list, then we have to configure the result of the nested call. + +We can use :data:`call` to construct the set of calls in a "chained call" like +this for easy assertion afterwards: .. doctest:: >>> mock = Mock() >>> cursor = mock.connection.cursor.return_value - >>> cursor.execute.return_value = None + >>> cursor.execute.return_value = ['foo'] >>> mock.connection.cursor().execute("SELECT 1") - >>> mock.method_calls - [('connection.cursor', (), {})] - >>> cursor.method_calls - [('execute', ('SELECT 1',), {})] + ['foo'] + >>> expected = call.connection.cursor().execute("SELECT 1").call_list() + >>> mock.mock_calls + [call.connection.cursor(), call.connection.cursor().execute('SELECT 1')] + >>> mock.mock_calls == expected + True + +It is the call to `.call_list()` that turns our call object into a list of +calls representing the chained calls. + + + +Raising exceptions with mocks +----------------------------- + +A useful attribute is :attr:`~Mock.side_effect`. If you set this to an +exception class or instance then the exception will be raised when the mock +is called. + +.. doctest:: + + >>> mock = Mock(side_effect=Exception('Boom!')) + >>> mock() + Traceback (most recent call last): + ... + Exception: Boom! + + +Side effect functions and iterables +----------------------------------- + +`side_effect` can also be set to a function or an iterable. The use case for +`side_effect` as an iterable is where your mock is going to be called several +times, and you want each call to return a different value. When you set +`side_effect` to an iterable every call to the mock returns the next value +from the iterable: + +.. doctest:: + + >>> mock = MagicMock(side_effect=[4, 5, 6]) + >>> mock() + 4 + >>> mock() + 5 + >>> mock() + 6 + + +For more advanced use cases, like dynamically varying the return values +depending on what the mock is called with, `side_effect` can be a function. +The function will be called with the same arguments as the mock. Whatever the +function returns is what the call returns: + +.. doctest:: + + >>> vals = {(1, 2): 1, (2, 3): 2} + >>> def side_effect(*args): + ... return vals[args] + ... + >>> mock = MagicMock(side_effect=side_effect) + >>> mock(1, 2) + 1 + >>> mock(2, 3) + 2 Creating a Mock from an Existing Object @@ -331,13 +303,13 @@ One problem with over use of mocking is that it couples your tests to the implementation of your mocks rather than your real code. Suppose you have a -class that implements ``some_method``. In a test for another class, you -provide a mock of this object that *also* provides ``some_method``. If later -you refactor the first class, so that it no longer has ``some_method`` - then +class that implements `some_method`. In a test for another class, you +provide a mock of this object that *also* provides `some_method`. If later +you refactor the first class, so that it no longer has `some_method` - then your tests will continue to pass even though your code is now broken! -``Mock`` allows you to provide an object as a specification for the mock, -using the ``spec`` keyword argument. Accessing methods / attributes on the +`Mock` allows you to provide an object as a specification for the mock, +using the `spec` keyword argument. Accessing methods / attributes on the mock that don't exist on your specification object will immediately raise an attribute error. If you change the implementation of your specification, then tests that use that class will start failing immediately without you having to @@ -351,53 +323,11 @@ ... AttributeError: object has no attribute 'old_method' -Again, if you want a stronger form of specification that prevents the setting +If you want a stronger form of specification that prevents the setting of arbitrary attributes as well as the getting of them then you can use `spec_set` instead of `spec`. -Raising exceptions with mocks ------------------------------ - -A useful attribute is `side_effect`. If you set -this to an exception class or instance then the exception will be raised when -the mock is called. If you set it to a callable then it will be called whenever -the mock is called. This allows you to do things like return members of a -sequence from repeated calls: - - -.. doctest:: - - >>> mock = Mock() - >>> mock.side_effect = Exception('Boom!') - >>> mock() - Traceback (most recent call last): - ... - Exception: Boom! - - >>> results = [1, 2, 3] - >>> def side_effect(*args, **kwargs): - ... return results.pop() - ... - >>> mock.side_effect = side_effect - >>> mock(), mock(), mock() - (3, 2, 1) - - -Sentinel -======== - -``sentinel`` is a useful object for providing unique objects in your tests: - -.. doctest:: - - >>> from mock import sentinel - >>> real = SomeClass() - >>> real.method = Mock() - >>> real.method.return_value = sentinel.return_value - >>> real.method() - - Patch Decorators ================ @@ -442,22 +372,19 @@ ... >>> test() -If you are patching a module (including ``__builtin__``) then use ``patch`` -instead of ``patch.object``: +If you are patching a module (including `__builtin__`) then use `patch` +instead of `patch.object`: .. doctest:: - >>> mock = Mock() - >>> mock.return_value = sentinel.file_handle - >>> @patch('__builtin__.open', mock) - ... def test(): - ... return open('filename', 'r') + >>> mock = MagicMock(return_value = sentinel.file_handle) + >>> with patch('__builtin__.open', mock): + ... handle = open('filename', 'r') ... - >>> handle = test() >>> mock.assert_called_with('filename', 'r') >>> assert handle == sentinel.file_handle, "incorrect file handle returned" -The module name can be 'dotted', in the form ``package.module`` if needed: +The module name can be 'dotted', in the form `package.module` if needed: .. doctest:: @@ -468,14 +395,11 @@ ... >>> test() -If you don't want to call the decorated test function yourself, you can add -`apply` as a decorator on top, this calls it immediately. - A nice pattern is to actually decorate test methods themselves: .. doctest:: - >>> class MyTest(unittest.TestCase): + >>> class MyTest(unittest2.TestCase): ... @patch.object(SomeClass, 'attribute', sentinel.attribute) ... def test_something(self): ... self.assertEqual(SomeClass.attribute, sentinel.attribute) @@ -485,12 +409,12 @@ >>> assert SomeClass.attribute == original If you want to patch with a Mock, you can use `patch` with only one argument -(or ``patch.object`` with two arguments). The mock will be created for you and +(or `patch.object` with two arguments). The mock will be created for you and passed into the test function / method: .. doctest:: - >>> class MyTest(unittest.TestCase): + >>> class MyTest(unittest2.TestCase): ... @patch.object(SomeClass, 'static_method') ... def test_something(self, mock_method): ... SomeClass.static_method() @@ -502,7 +426,7 @@ .. doctest:: - >>> class MyTest(unittest.TestCase): + >>> class MyTest(unittest2.TestCase): ... @patch('package.module.ClassName1') ... @patch('package.module.ClassName2') ... def test_something(self, MockClass2, MockClass1): @@ -549,5 +473,7 @@ As an alternative `patch`, `patch.object` and `patch.dict` can be used as -class decorators. When used in this way it is the same as applying the decorator -indvidually to every method whose name starts with "test". +class decorators. When used in this way it is the same as applying the +decorator indvidually to every method whose name starts with "test". + +For some more advanced examples, see the :ref:`further-examples` page. diff -Nru python-mock-0.7.2/docs/helpers.txt python-mock-1.0.1/docs/helpers.txt --- python-mock-0.7.2/docs/helpers.txt 1970-01-01 00:00:00.000000000 +0000 +++ python-mock-1.0.1/docs/helpers.txt 2012-04-13 15:58:42.000000000 +0000 @@ -0,0 +1,583 @@ +========= + Helpers +========= + +.. currentmodule:: mock + +.. testsetup:: + + mock.FILTER_DIR = True + from pprint import pprint as pp + original_dir = dir + def dir(obj): + print pp(original_dir(obj)) + + import urllib2 + __main__.urllib2 = urllib2 + +.. testcleanup:: + + dir = original_dir + mock.FILTER_DIR = True + + + +call +==== + +.. function:: call(*args, **kwargs) + + `call` is a helper object for making simpler assertions, for comparing + with :attr:`~Mock.call_args`, :attr:`~Mock.call_args_list`, + :attr:`~Mock.mock_calls` and :attr: `~Mock.method_calls`. `call` can also be + used with :meth:`~Mock.assert_has_calls`. + + .. doctest:: + + >>> m = MagicMock(return_value=None) + >>> m(1, 2, a='foo', b='bar') + >>> m() + >>> m.call_args_list == [call(1, 2, a='foo', b='bar'), call()] + True + +.. method:: call.call_list() + + For a call object that represents multiple calls, `call_list` + returns a list of all the intermediate calls as well as the + final call. + +`call_list` is particularly useful for making assertions on "chained calls". A +chained call is multiple calls on a single line of code. This results in +multiple entries in :attr:`~Mock.mock_calls` on a mock. Manually constructing +the sequence of calls can be tedious. + +:meth:`~call.call_list` can construct the sequence of calls from the same +chained call: + +.. doctest:: + + >>> m = MagicMock() + >>> m(1).method(arg='foo').other('bar')(2.0) + + >>> kall = call(1).method(arg='foo').other('bar')(2.0) + >>> kall.call_list() + [call(1), + call().method(arg='foo'), + call().method().other('bar'), + call().method().other()(2.0)] + >>> m.mock_calls == kall.call_list() + True + +.. _calls-as-tuples: + +A `call` object is either a tuple of (positional args, keyword args) or +(name, positional args, keyword args) depending on how it was constructed. When +you construct them yourself this isn't particularly interesting, but the `call` +objects that are in the :attr:`Mock.call_args`, :attr:`Mock.call_args_list` and +:attr:`Mock.mock_calls` attributes can be introspected to get at the individual +arguments they contain. + +The `call` objects in :attr:`Mock.call_args` and :attr:`Mock.call_args_list` +are two-tuples of (positional args, keyword args) whereas the `call` objects +in :attr:`Mock.mock_calls`, along with ones you construct yourself, are +three-tuples of (name, positional args, keyword args). + +You can use their "tupleness" to pull out the individual arguments for more +complex introspection and assertions. The positional arguments are a tuple +(an empty tuple if there are no positional arguments) and the keyword +arguments are a dictionary: + +.. doctest:: + + >>> m = MagicMock(return_value=None) + >>> m(1, 2, 3, arg='one', arg2='two') + >>> kall = m.call_args + >>> args, kwargs = kall + >>> args + (1, 2, 3) + >>> kwargs + {'arg2': 'two', 'arg': 'one'} + >>> args is kall[0] + True + >>> kwargs is kall[1] + True + + >>> m = MagicMock() + >>> m.foo(4, 5, 6, arg='two', arg2='three') + + >>> kall = m.mock_calls[0] + >>> name, args, kwargs = kall + >>> name + 'foo' + >>> args + (4, 5, 6) + >>> kwargs + {'arg2': 'three', 'arg': 'two'} + >>> name is m.mock_calls[0][0] + True + + +create_autospec +=============== + +.. function:: create_autospec(spec, spec_set=False, instance=False, **kwargs) + + Create a mock object using another object as a spec. Attributes on the + mock will use the corresponding attribute on the `spec` object as their + spec. + + Functions or methods being mocked will have their arguments checked to + ensure that they are called with the correct signature. + + If `spec_set` is `True` then attempting to set attributes that don't exist + on the spec object will raise an `AttributeError`. + + If a class is used as a spec then the return value of the mock (the + instance of the class) will have the same spec. You can use a class as the + spec for an instance object by passing `instance=True`. The returned mock + will only be callable if instances of the mock are callable. + + `create_autospec` also takes arbitrary keyword arguments that are passed to + the constructor of the created mock. + +See :ref:`auto-speccing` for examples of how to use auto-speccing with +`create_autospec` and the `autospec` argument to :func:`patch`. + + +ANY +=== + +.. data:: ANY + +Sometimes you may need to make assertions about *some* of the arguments in a +call to mock, but either not care about some of the arguments or want to pull +them individually out of :attr:`~Mock.call_args` and make more complex +assertions on them. + +To ignore certain arguments you can pass in objects that compare equal to +*everything*. Calls to :meth:`~Mock.assert_called_with` and +:meth:`~Mock.assert_called_once_with` will then succeed no matter what was +passed in. + +.. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock('foo', bar=object()) + >>> mock.assert_called_once_with('foo', bar=ANY) + +`ANY` can also be used in comparisons with call lists like +:attr:`~Mock.mock_calls`: + +.. doctest:: + + >>> m = MagicMock(return_value=None) + >>> m(1) + >>> m(1, 2) + >>> m(object()) + >>> m.mock_calls == [call(1), call(1, 2), ANY] + True + + + +FILTER_DIR +========== + +.. data:: FILTER_DIR + +`FILTER_DIR` is a module level variable that controls the way mock objects +respond to `dir` (only for Python 2.6 or more recent). The default is `True`, +which uses the filtering described below, to only show useful members. If you +dislike this filtering, or need to switch it off for diagnostic purposes, then +set `mock.FILTER_DIR = False`. + +With filtering on, `dir(some_mock)` shows only useful attributes and will +include any dynamically created attributes that wouldn't normally be shown. +If the mock was created with a `spec` (or `autospec` of course) then all the +attributes from the original are shown, even if they haven't been accessed +yet: + +.. doctest:: + + >>> dir(Mock()) + ['assert_any_call', + 'assert_called_once_with', + 'assert_called_with', + 'assert_has_calls', + 'attach_mock', + ... + >>> import urllib2 + >>> dir(Mock(spec=urllib2)) + ['AbstractBasicAuthHandler', + 'AbstractDigestAuthHandler', + 'AbstractHTTPHandler', + 'BaseHandler', + ... + +Many of the not-very-useful (private to `Mock` rather than the thing being +mocked) underscore and double underscore prefixed attributes have been +filtered from the result of calling `dir` on a `Mock`. If you dislike this +behaviour you can switch it off by setting the module level switch +`FILTER_DIR`: + +.. doctest:: + + >>> import mock + >>> mock.FILTER_DIR = False + >>> dir(mock.Mock()) + ['_NonCallableMock__get_return_value', + '_NonCallableMock__get_side_effect', + '_NonCallableMock__return_value_doc', + '_NonCallableMock__set_return_value', + '_NonCallableMock__set_side_effect', + '__call__', + '__class__', + ... + +Alternatively you can just use `vars(my_mock)` (instance members) and +`dir(type(my_mock))` (type members) to bypass the filtering irrespective of +`mock.FILTER_DIR`. + + +mock_open +========= + +.. function:: mock_open(mock=None, read_data=None) + + A helper function to create a mock to replace the use of `open`. It works + for `open` called directly or used as a context manager. + + The `mock` argument is the mock object to configure. If `None` (the + default) then a `MagicMock` will be created for you, with the API limited + to methods or attributes available on standard file handles. + + `read_data` is a string for the `read` method of the file handle to return. + This is an empty string by default. + +Using `open` as a context manager is a great way to ensure your file handles +are closed properly and is becoming common:: + + with open('/some/path', 'w') as f: + f.write('something') + +The issue is that even if you mock out the call to `open` it is the +*returned object* that is used as a context manager (and has `__enter__` and +`__exit__` called). + +Mocking context managers with a :class:`MagicMock` is common enough and fiddly +enough that a helper function is useful. + +.. doctest:: + + >>> from mock import mock_open + >>> m = mock_open() + >>> with patch('__main__.open', m, create=True): + ... with open('foo', 'w') as h: + ... h.write('some stuff') + ... + >>> m.mock_calls + [call('foo', 'w'), + call().__enter__(), + call().write('some stuff'), + call().__exit__(None, None, None)] + >>> m.assert_called_once_with('foo', 'w') + >>> handle = m() + >>> handle.write.assert_called_once_with('some stuff') + +And for reading files: + +.. doctest:: + + >>> with patch('__main__.open', mock_open(read_data='bibble'), create=True) as m: + ... with open('foo') as h: + ... result = h.read() + ... + >>> m.assert_called_once_with('foo') + >>> assert result == 'bibble' + + +.. _auto-speccing: + +Autospeccing +============ + +Autospeccing is based on the existing `spec` feature of mock. It limits the +api of mocks to the api of an original object (the spec), but it is recursive +(implemented lazily) so that attributes of mocks only have the same api as +the attributes of the spec. In addition mocked functions / methods have the +same call signature as the original so they raise a `TypeError` if they are +called incorrectly. + +Before I explain how auto-speccing works, here's why it is needed. + +`Mock` is a very powerful and flexible object, but it suffers from two flaws +when used to mock out objects from a system under test. One of these flaws is +specific to the `Mock` api and the other is a more general problem with using +mock objects. + +First the problem specific to `Mock`. `Mock` has two assert methods that are +extremely handy: :meth:`~Mock.assert_called_with` and +:meth:`~Mock.assert_called_once_with`. + +.. doctest:: + + >>> mock = Mock(name='Thing', return_value=None) + >>> mock(1, 2, 3) + >>> mock.assert_called_once_with(1, 2, 3) + >>> mock(1, 2, 3) + >>> mock.assert_called_once_with(1, 2, 3) + Traceback (most recent call last): + ... + AssertionError: Expected to be called once. Called 2 times. + +Because mocks auto-create attributes on demand, and allow you to call them +with arbitrary arguments, if you misspell one of these assert methods then +your assertion is gone: + +.. code-block:: pycon + + >>> mock = Mock(name='Thing', return_value=None) + >>> mock(1, 2, 3) + >>> mock.assret_called_once_with(4, 5, 6) + +Your tests can pass silently and incorrectly because of the typo. + +The second issue is more general to mocking. If you refactor some of your +code, rename members and so on, any tests for code that is still using the +*old api* but uses mocks instead of the real objects will still pass. This +means your tests can all pass even though your code is broken. + +Note that this is another reason why you need integration tests as well as +unit tests. Testing everything in isolation is all fine and dandy, but if you +don't test how your units are "wired together" there is still lots of room +for bugs that tests might have caught. + +`mock` already provides a feature to help with this, called speccing. If you +use a class or instance as the `spec` for a mock then you can only access +attributes on the mock that exist on the real class: + +.. doctest:: + + >>> import urllib2 + >>> mock = Mock(spec=urllib2.Request) + >>> mock.assret_called_with + Traceback (most recent call last): + ... + AttributeError: Mock object has no attribute 'assret_called_with' + +The spec only applies to the mock itself, so we still have the same issue +with any methods on the mock: + +.. code-block:: pycon + + >>> mock.has_data() + + >>> mock.has_data.assret_called_with() + +Auto-speccing solves this problem. You can either pass `autospec=True` to +`patch` / `patch.object` or use the `create_autospec` function to create a +mock with a spec. If you use the `autospec=True` argument to `patch` then the +object that is being replaced will be used as the spec object. Because the +speccing is done "lazily" (the spec is created as attributes on the mock are +accessed) you can use it with very complex or deeply nested objects (like +modules that import modules that import modules) without a big performance +hit. + +Here's an example of it in use: + +.. doctest:: + + >>> import urllib2 + >>> patcher = patch('__main__.urllib2', autospec=True) + >>> mock_urllib2 = patcher.start() + >>> urllib2 is mock_urllib2 + True + >>> urllib2.Request + + +You can see that `urllib2.Request` has a spec. `urllib2.Request` takes two +arguments in the constructor (one of which is `self`). Here's what happens if +we try to call it incorrectly: + +.. doctest:: + + >>> req = urllib2.Request() + Traceback (most recent call last): + ... + TypeError: () takes at least 2 arguments (1 given) + +The spec also applies to instantiated classes (i.e. the return value of +specced mocks): + +.. doctest:: + + >>> req = urllib2.Request('foo') + >>> req + + +`Request` objects are not callable, so the return value of instantiating our +mocked out `urllib2.Request` is a non-callable mock. With the spec in place +any typos in our asserts will raise the correct error: + +.. doctest:: + + >>> req.add_header('spam', 'eggs') + + >>> req.add_header.assret_called_with + Traceback (most recent call last): + ... + AttributeError: Mock object has no attribute 'assret_called_with' + >>> req.add_header.assert_called_with('spam', 'eggs') + +In many cases you will just be able to add `autospec=True` to your existing +`patch` calls and then be protected against bugs due to typos and api +changes. + +As well as using `autospec` through `patch` there is a +:func:`create_autospec` for creating autospecced mocks directly: + +.. doctest:: + + >>> import urllib2 + >>> mock_urllib2 = create_autospec(urllib2) + >>> mock_urllib2.Request('foo', 'bar') + + +This isn't without caveats and limitations however, which is why it is not +the default behaviour. In order to know what attributes are available on the +spec object, autospec has to introspect (access attributes) the spec. As you +traverse attributes on the mock a corresponding traversal of the original +object is happening under the hood. If any of your specced objects have +properties or descriptors that can trigger code execution then you may not be +able to use autospec. On the other hand it is much better to design your +objects so that introspection is safe [#]_. + +A more serious problem is that it is common for instance attributes to be +created in the `__init__` method and not to exist on the class at all. +`autospec` can't know about any dynamically created attributes and restricts +the api to visible attributes. + +.. doctest:: + + >>> class Something(object): + ... def __init__(self): + ... self.a = 33 + ... + >>> with patch('__main__.Something', autospec=True): + ... thing = Something() + ... thing.a + ... + Traceback (most recent call last): + ... + AttributeError: Mock object has no attribute 'a' + +There are a few different ways of resolving this problem. The easiest, but +not necessarily the least annoying, way is to simply set the required +attributes on the mock after creation. Just because `autospec` doesn't allow +you to fetch attributes that don't exist on the spec it doesn't prevent you +setting them: + +.. doctest:: + + >>> with patch('__main__.Something', autospec=True): + ... thing = Something() + ... thing.a = 33 + ... + +There is a more aggressive version of both `spec` and `autospec` that *does* +prevent you setting non-existent attributes. This is useful if you want to +ensure your code only *sets* valid attributes too, but obviously it prevents +this particular scenario: + +.. doctest:: + + >>> with patch('__main__.Something', autospec=True, spec_set=True): + ... thing = Something() + ... thing.a = 33 + ... + Traceback (most recent call last): + ... + AttributeError: Mock object has no attribute 'a' + +Probably the best way of solving the problem is to add class attributes as +default values for instance members initialised in `__init__`. Note that if +you are only setting default attributes in `__init__` then providing them via +class attributes (shared between instances of course) is faster too. e.g. + +.. code-block:: python + + class Something(object): + a = 33 + +This brings up another issue. It is relatively common to provide a default +value of `None` for members that will later be an object of a different type. +`None` would be useless as a spec because it wouldn't let you access *any* +attributes or methods on it. As `None` is *never* going to be useful as a +spec, and probably indicates a member that will normally of some other type, +`autospec` doesn't use a spec for members that are set to `None`. These will +just be ordinary mocks (well - `MagicMocks`): + +.. doctest:: + + >>> class Something(object): + ... member = None + ... + >>> mock = create_autospec(Something) + >>> mock.member.foo.bar.baz() + + +If modifying your production classes to add defaults isn't to your liking +then there are more options. One of these is simply to use an instance as the +spec rather than the class. The other is to create a subclass of the +production class and add the defaults to the subclass without affecting the +production class. Both of these require you to use an alternative object as +the spec. Thankfully `patch` supports this - you can simply pass the +alternative object as the `autospec` argument: + +.. doctest:: + + >>> class Something(object): + ... def __init__(self): + ... self.a = 33 + ... + >>> class SomethingForTest(Something): + ... a = 33 + ... + >>> p = patch('__main__.Something', autospec=SomethingForTest) + >>> mock = p.start() + >>> mock.a + + +.. note:: + + An additional limitation (currently) with `autospec` is that unbound + methods on mocked classes *don't* take an "explicit self" as the first + argument - so this usage will fail with `autospec`. + + .. doctest:: + + >>> class Foo(object): + ... def foo(self): + ... pass + ... + >>> Foo.foo(Foo()) + >>> MockFoo = create_autospec(Foo) + >>> MockFoo.foo(MockFoo()) + Traceback (most recent call last): + ... + TypeError: () takes exactly 1 argument (2 given) + + The reason is that its very hard to tell the difference between functions, + unbound methods and staticmethods across Python 2 & 3 and the alternative + implementations. This restriction may be fixed in future versions. + + +------ + +.. [#] This only applies to classes or already instantiated objects. Calling + a mocked class to create a mock instance *does not* create a real instance. + It is only attribute lookups - along with calls to `dir` - that are done. A + way round this problem would have been to use `getattr_static + `_, + which can fetch attributes without triggering code execution. Descriptors + like `classmethod` and `staticmethod` *need* to be fetched correctly though, + so that their signatures can be mocked correctly. diff -Nru python-mock-0.7.2/docs/index.txt python-mock-1.0.1/docs/index.txt --- python-mock-0.7.2/docs/index.txt 2011-05-30 19:39:33.000000000 +0000 +++ python-mock-1.0.1/docs/index.txt 2012-10-07 23:39:29.000000000 +0000 @@ -4,16 +4,19 @@ .. currentmodule:: mock -:Author: `Michael Foord `_ -:Co-maintainer: `Konrad Delong `_ +:Author: `Michael Foord + `_ :Version: |release| -:Date: 2011/05/30 +:Date: 2012/10/07 :Homepage: `Mock Homepage`_ :Download: `Mock on PyPI`_ -:Documentation: `PDF Documentation `_ +:Documentation: `PDF Documentation + `_ :License: `BSD License`_ -:Support: `Mailing list (testing-in-python@lists.idyll.org) `_ -:Issue tracker: `Google code project `_ +:Support: `Mailing list (testing-in-python@lists.idyll.org) + `_ +:Issue tracker: `Google code project + `_ .. _Mock Homepage: http://www.voidspace.org.uk/python/mock/ .. _BSD License: http://www.voidspace.org.uk/python/license.shtml @@ -26,37 +29,45 @@ .. index:: introduction -mock is a Python module that provides a core :class:`Mock` class. It removes -the need to create a host of stubs throughout your test suite. After -performing an action, you can make assertions about which methods / attributes -were used and arguments they were called with. You can also specify return -values and set needed attributes in the normal way. - -The mock module also provides a :func:`patch` decorator that handles -patching module and class level attributes within the scope of a test, along -with :const:`sentinel` for creating unique objects. See the `quick guide`_ for -some examples of how to use :class:`Mock`, :class:`MagicMock` and :func:`patch`. +mock is a library for testing in Python. It allows you to replace parts of +your system under test with mock objects and make assertions about how they +have been used. + +mock is now part of the Python standard library, available as `unittest.mock +`_ +in Python 3.3 onwards. + +mock provides a core :class:`Mock` class removing the need to create a host +of stubs throughout your test suite. After performing an action, you can make +assertions about which methods / attributes were used and arguments they were +called with. You can also specify return values and set needed attributes in +the normal way. + +Additionally, mock provides a :func:`patch` decorator that handles patching +module and class level attributes within the scope of a test, along with +:const:`sentinel` for creating unique objects. See the `quick guide`_ for +some examples of how to use :class:`Mock`, :class:`MagicMock` and +:func:`patch`. Mock is very easy to use and is designed for use with `unittest `_. Mock is based on the 'action -> assertion' pattern instead of `'record -> replay'` used by many mocking frameworks. -mock is tested on Python versions 2.4-2.7 and Python 3. +mock is tested on Python versions 2.4-2.7, Python 3 plus the latest versions of +Jython and PyPy. .. testsetup:: - import sys class ProductionClass(object): def method(self, *args): pass - test_module = sys.modules['test_module'] = ProductionClass + module = sys.modules['module'] = ProductionClass ProductionClass.ClassName1 = ProductionClass ProductionClass.ClassName2 = ProductionClass - from mock import Mock, patch, MagicMock API Documentation @@ -67,9 +78,9 @@ mock patch + helpers sentinel magicmock - mocksignature User Guide @@ -83,18 +94,19 @@ compare changelog + .. index:: installing Installing ========== -The current version is |release|. Mock is still experimental; the API may -change (although we are moving towards a 1.0 release when the API will -stabilise). If you find bugs or have suggestions for improvements / extensions +The current version is |release|. Mock is stable and widely used. If you do +find any bugs, or have suggestions for improvements / extensions then please contact us. * `mock on PyPI `_ -* `mock documentation as PDF `_ +* `mock documentation as PDF + `_ * `Google Code Home & Mercurial Repository `_ .. index:: repository @@ -124,22 +136,22 @@ Quick Guide =========== -:class:`Mock` objects create all attributes and methods as you access them and store -details of how they have been used. You can configure them, to specify return -values or limit what attributes are available, and then make assertions about -how they have been used: +:class:`Mock` and :class:`MagicMock` objects create all attributes and +methods as you access them and store details of how they have been used. You +can configure them, to specify return values or limit what attributes are +available, and then make assertions about how they have been used: .. doctest:: - >>> from mock import Mock - >>> real = ProductionClass() - >>> real.method = Mock(return_value=3) - >>> real.method(3, 4, 5, key='value') + >>> from mock import MagicMock + >>> thing = ProductionClass() + >>> thing.method = MagicMock(return_value=3) + >>> thing.method(3, 4, 5, key='value') 3 - >>> real.method.assert_called_with(3, 4, 5, key='value') + >>> thing.method.assert_called_with(3, 4, 5, key='value') -:attr:`side_effect` allows you to perform side effects, return different -values or raise an exception when a mock is called: +:attr:`side_effect` allows you to perform side effects, including raising an +exception when a mock is called: .. doctest:: @@ -148,18 +160,22 @@ Traceback (most recent call last): ... KeyError: 'foo' - >>> values = [1, 2, 3] - >>> def side_effect(): - ... return values.pop() + + >>> values = {'a': 1, 'b': 2, 'c': 3} + >>> def side_effect(arg): + ... return values[arg] ... >>> mock.side_effect = side_effect + >>> mock('a'), mock('b'), mock('c') + (1, 2, 3) + >>> mock.side_effect = [5, 4, 3, 2, 1] >>> mock(), mock(), mock() - (3, 2, 1) + (5, 4, 3) Mock has many other ways you can configure it and control its behaviour. For -example the ``spec`` argument configures the mock to take its specification from -another object. Attempting to access attributes or methods on the mock that -don't exist on the spec will fail with an ``AttributeError``. +example the `spec` argument configures the mock to take its specification +from another object. Attempting to access attributes or methods on the mock +that don't exist on the spec will fail with an `AttributeError`. The :func:`patch` decorator / context manager makes it easy to mock classes or objects in a module under test. The object you specify will be replaced with a @@ -168,14 +184,14 @@ .. doctest:: >>> from mock import patch - >>> @patch('test_module.ClassName1') - ... @patch('test_module.ClassName2') - ... def test(MockClass2, MockClass1): - ... test_module.ClassName1() - ... test_module.ClassName2() + >>> @patch('module.ClassName2') + ... @patch('module.ClassName1') + ... def test(MockClass1, MockClass2): + ... module.ClassName1() + ... module.ClassName2() - ... assert MockClass1 is test_module.ClassName1 - ... assert MockClass2 is test_module.ClassName2 + ... assert MockClass1 is module.ClassName1 + ... assert MockClass2 is module.ClassName2 ... assert MockClass1.called ... assert MockClass2.called ... @@ -186,7 +202,7 @@ When you nest patch decorators the mocks are passed in to the decorated function in the same order they applied (the normal *python* order that decorators are applied). This means from the bottom up, so in the example - above the mock for `test_module.ClassName2` is passed in first. + above the mock for `module.ClassName1` is passed in first. With `patch` it matters that you patch objects in the namespace where they are looked up. This is normally straightforward, but for a quick guide @@ -197,12 +213,11 @@ .. doctest:: - >>> with patch.object(ProductionClass, 'method') as mock_method: - ... mock_method.return_value = None - ... real = ProductionClass() - ... real.method(1, 2, 3) + >>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method: + ... thing = ProductionClass() + ... thing.method(1, 2, 3) ... - >>> mock_method.assert_called_with(1, 2, 3) + >>> mock_method.assert_called_once_with(1, 2, 3) There is also :func:`patch.dict` for setting values in a dictionary just @@ -224,7 +239,6 @@ .. doctest:: - >>> from mock import MagicMock >>> mock = MagicMock() >>> mock.__str__.return_value = 'foobarbaz' >>> str(mock) @@ -232,8 +246,8 @@ >>> mock.__str__.assert_called_with() Mock allows you to assign functions (or other Mock instances) to magic methods -and they will be called appropriately. The MagicMock class is just a Mock -variant that has all of the magic methods pre-created for you (well - all the +and they will be called appropriately. The `MagicMock` class is just a Mock +variant that has all of the magic methods pre-created for you (well, all the useful ones anyway). The following is an example of using magic methods with the ordinary Mock @@ -242,52 +256,73 @@ .. doctest:: >>> mock = Mock() - >>> mock.__str__ = Mock() - >>> mock.__str__.return_value = 'wheeeeee' + >>> mock.__str__ = Mock(return_value='wheeeeee') >>> str(mock) 'wheeeeee' -:func:`mocksignature` is a useful companion to Mock and patch. It creates -copies of functions that delegate to a mock, but have the same signature as the -original function. This ensures that your mocks will fail in the same way as -your production code if they are called incorrectly: +For ensuring that the mock objects in your tests have the same api as the +objects they are replacing, you can use :ref:`auto-speccing `. +Auto-speccing can be done through the `autospec` argument to patch, or the +:func:`create_autospec` function. Auto-speccing creates mock objects that +have the same attributes and methods as the objects they are replacing, and +any functions and methods (including constructors) have the same call +signature as the real object. + +This ensures that your mocks will fail in the same way as your production +code if they are used incorrectly: .. doctest:: - >>> from mock import mocksignature + >>> from mock import create_autospec >>> def function(a, b, c): ... pass ... - >>> function2 = mocksignature(function) - >>> function2.mock.return_value = 'fishy' - >>> function2(1, 2, 3) + >>> mock_function = create_autospec(function, return_value='fishy') + >>> mock_function(1, 2, 3) 'fishy' - >>> function2.mock.assert_called_with(1, 2, 3) - >>> function2('wrong arguments') + >>> mock_function.assert_called_once_with(1, 2, 3) + >>> mock_function('wrong arguments') Traceback (most recent call last): ... TypeError: () takes exactly 3 arguments (1 given) -`mocksignature` can also be used on classes, where it copies the signature of +`create_autospec` can also be used on classes, where it copies the signature of the `__init__` method, and on callable objects where it copies the signature of the `__call__` method. + .. index:: references .. index:: articles References ========== -Articles and blog entries on testing with Mock: +Articles, blog entries and other stuff related to testing with Mock: +* `Imposing a No DB Discipline on Django unit tests + `_ +* `mock-django: tools for mocking the Django ORM and models + `_ * `PyCon 2011 Video: Testing with mock `_ -* `Mocking Django `_ +* `Mock objects in Python + `_ +* `Python: Injecting Mock Objects for Powerful Testing + `_ +* `Python Mock: How to assert a substring of logger output + `_ +* `Mocking Django `_ +* `Mocking dates and other classes that can't be modified + `_ * `Mock recipes `_ * `Mockity mock mock - some love for the mock module `_ +* `Coverage and Mock (with django) + `_ * `Python Unit Testing with Mock `_ * `Getting started with Python Mock `_ +* `Smart Parameter Checks with mock + `_ * `Python mock testing techniques and tools `_ * `How To Test Django Template Tags @@ -305,10 +340,10 @@ ===== Mock uses `unittest2 `_ for its own -test suite. In order to run it, use the ``unit2`` script that comes with -``unittest2`` module on a checkout of the source repository: +test suite. In order to run it, use the `unit2` script that comes with +`unittest2` module on a checkout of the source repository: - ``unit2 discover`` + `unit2 discover` If you have `setuptools `_ as well as unittest2 you can run: @@ -333,7 +368,12 @@ Documentation for older versions of mock: -* `mock 0.6.0 `_ +* `mock 0.8 `_ +* `mock 0.7 `_ +* `mock 0.6 `_ + +Docs from the in-development version of `mock` can be found at +`mock.readthedocs.org `_. Terminology @@ -348,13 +388,14 @@ allows for *post-mortem* examination. This is what I call the "action -> assertion" [#]_ pattern of testing. -I'm not however a fan of this "statically typed mocking terminology" promulgated -by `Martin Fowler `_. It -confuses usage patterns with implementation and prevents you from using natural -terminology when discussing mocking. +I'm not however a fan of this "statically typed mocking terminology" +promulgated by `Martin Fowler +`_. It confuses usage +patterns with implementation and prevents you from using natural terminology +when discussing mocking. I much prefer duck typing, if an object used in your test suite looks like a -mock object and quacks like a mock object then its fine to call it a mock no +mock object and quacks like a mock object then it's fine to call it a mock, no matter what the implementation looks like. This terminology is perhaps more useful in less capable languages where diff -Nru python-mock-0.7.2/docs/magicmock.txt python-mock-1.0.1/docs/magicmock.txt --- python-mock-0.7.2/docs/magicmock.txt 2011-05-29 22:14:55.000000000 +0000 +++ python-mock-1.0.1/docs/magicmock.txt 2012-03-18 01:04:22.000000000 +0000 @@ -1,9 +1,6 @@ .. currentmodule:: mock -.. testsetup:: - - from mock import Mock, MagicMock, patch .. _magic-methods: @@ -48,27 +45,26 @@ [] One use case for this is for mocking objects used as context managers in a -``with`` statement: +`with` statement: .. doctest:: >>> mock = Mock() - >>> mock.__enter__ = Mock() - >>> mock.__exit__ = Mock() - >>> mock.__exit__.return_value = False - >>> with mock: - ... pass + >>> mock.__enter__ = Mock(return_value='foo') + >>> mock.__exit__ = Mock(return_value=False) + >>> with mock as m: + ... assert m == 'foo' ... >>> mock.__enter__.assert_called_with() >>> mock.__exit__.assert_called_with(None, None, None) -Calls to magic methods do not (yet) appear in :attr:`Mock.method_calls`. -This may change in a future release. +Calls to magic methods do not appear in :attr:`~Mock.method_calls`, but they +are recorded in :attr:`~Mock.mock_calls`. .. note:: - If you use the ``spec`` keyword argument to create a mock then attempting to - set a magic method that isn't in the spec will raise an AttributeError. + If you use the `spec` keyword argument to create a mock then attempting to + set a magic method that isn't in the spec will raise an `AttributeError`. The full list of supported magic methods is: @@ -83,7 +79,7 @@ * Context manager: ``__enter__`` and ``__exit__`` * Unary numeric methods: ``__neg__``, ``__pos__`` and ``__invert__`` * The numeric methods (including right hand and in-place variants): - ``__add__``, ``__sub__``, ``__mul__``, ``__div__``, ``__truediv__``, + ``__add__``, ``__sub__``, ``__mul__``, ``__div__``, ``__floordiv__``, ``__mod__``, ``__divmod__``, ``__lshift__``, ``__rshift__``, ``__and__``, ``__xor__``, ``__or__``, and ``__pow__`` * Numeric conversion methods: ``__complex__``, ``__int__``, ``__float__``, @@ -96,6 +92,7 @@ The following methods are supported in Python 2 but don't exist in Python 3: * ``__unicode__``, ``__long__``, ``__oct__``, ``__hex__`` and ``__nonzero__`` +* ``__truediv__`` and ``__rtruediv__`` The following methods are supported in Python 3 but don't exist in Python 2: @@ -112,16 +109,30 @@ Magic Mock ========== +There are two `MagicMock` variants: `MagicMock` and `NonCallableMagicMock`. + + .. class:: MagicMock(*args, **kw) ``MagicMock`` is a subclass of :class:`Mock` with default implementations of most of the magic methods. You can use ``MagicMock`` without having to configure the magic methods yourself. - If you use the ``spec`` argument then *only* magic methods that exist in - the spec will be created. + The constructor parameters have the same meaning as for :class:`Mock`. + + If you use the `spec` or `spec_set` arguments then *only* magic methods + that exist in the spec will be created. + + +.. class:: NonCallableMagicMock(*args, **kw) -The magic methods are setup with ``Mock`` objects, so you can configure them + A non-callable version of `MagicMock`. + + The constructor parameters have the same meaning as for + :class:`MagicMock`, with the exception of `return_value` and + `side_effect` which have no meaning on a non-callable mock. + +The magic methods are setup with `MagicMock` objects, so you can configure them and use them in the usual way: .. doctest:: @@ -141,6 +152,10 @@ Methods and their defaults: +* ``__lt__``: NotImplemented +* ``__gt__``: NotImplemented +* ``__le__``: NotImplemented +* ``__ge__``: NotImplemented * ``__int__`` : 1 * ``__contains__`` : False * ``__len__`` : 1 @@ -175,9 +190,9 @@ >>> object() in mock False -The two equality method, `__eq__` and `__ne__`, are special (changed in 0.7.2). -They do the default equality comparison on identity, using a side effect, unless -you change their return value to return something else: +The two equality method, `__eq__` and `__ne__`, are special (changed in +0.7.2). They do the default equality comparison on identity, using a side +effect, unless you change their return value to return something else: .. doctest:: @@ -190,6 +205,30 @@ >>> mock == 3 True +In `0.8` the `__iter__` also gained special handling implemented with a +side effect. The return value of `MagicMock.__iter__` can be any iterable +object and isn't required to be an iterator: + +.. doctest:: + + >>> mock = MagicMock() + >>> mock.__iter__.return_value = ['a', 'b', 'c'] + >>> list(mock) + ['a', 'b', 'c'] + >>> list(mock) + ['a', 'b', 'c'] + +If the return value *is* an iterator, then iterating over it once will consume +it and subsequent iterations will result in an empty list: + +.. doctest:: + + >>> mock.__iter__.return_value = iter(['a', 'b', 'c']) + >>> list(mock) + ['a', 'b', 'c'] + >>> list(mock) + [] + ``MagicMock`` has all of the supported magic methods configured except for some of the obscure and obsolete ones. You can still set these up if you want. diff -Nru python-mock-0.7.2/docs/mocksignature.txt python-mock-1.0.1/docs/mocksignature.txt --- python-mock-0.7.2/docs/mocksignature.txt 2011-03-21 21:24:58.000000000 +0000 +++ python-mock-1.0.1/docs/mocksignature.txt 1970-01-01 00:00:00.000000000 +0000 @@ -1,203 +0,0 @@ -mocksignature -============= - -.. currentmodule:: mock - -A problem with using mock objects to replace real objects in your tests is that -:class:`Mock` can be *too* flexible. Your code can treat the mock objects in -any way and you have to manually check that they were called correctly. If your -code calls functions or methods with the wrong number of arguments then mocks -don't complain. - -The solution to this is ``mocksignature``, which creates functions with the -same signature as the original, but delegating to a mock. You can interrogate -the mock in the usual way to check it has been called with the *right* -arguments, but if it is called with the wrong number of arguments it will -raise a ``TypeError`` in the same way your production code would. - -Another advantage is that your mocked objects are real functions, which can -be useful when your code uses -`inspect `_ or depends on functions -being functions. - -.. function:: mocksignature(func, mock=None, skipfirst=False) - - Create a new function with the same signature as `func` that delegates - to `mock`. If `skipfirst` is True the first argument is skipped, useful - for methods where `self` needs to be omitted from the new function. - - If you don't pass in a `mock` then one will be created for you. - - The mock is set as the `mock` attribute of the returned function for easy - access. - - `mocksignature` can also be used with classes. It copies the signature of - the `__init__` method. - - When used with callable objects (instances) it copies the signature of the - `__call__` method. - -``mocksignature`` will work out if it is mocking the signature of a method on -an instance or a method on a class and do the "right thing" with the ``self`` -argument in both cases. - -Because of a limitation in the way that arguments are collected by functions -created by ``mocksignature`` they are *always* passed as positional arguments -(including defaults) and not keyword arguments. - -Example use ------------ - -Basic use -~~~~~~~~~ - -.. doctest:: - - >>> from mock import mocksignature, Mock - >>> def function(a, b, c=None): - ... pass - ... - >>> mock = Mock() - >>> function = mocksignature(function, mock) - >>> function() - Traceback (most recent call last): - ... - TypeError: () takes at least 2 arguments (0 given) - >>> mock.return_value = 'some value' - >>> function(1, 2, 'foo') - 'some value' - >>> function.mock.assert_called_with(1, 2, 'foo') - - -Keyword arguments -~~~~~~~~~~~~~~~~~ - -Note that arguments to functions created by ``mocksignature`` are always passed -in to the underlying mock by position even when called with keywords: - -.. doctest:: - - >>> from mock import mocksignature - >>> def function(a, b, c=None): - ... pass - ... - >>> function = mocksignature(function) - >>> function.mock.return_value = None - >>> function(1, 2) - >>> function.mock.assert_called_with(1, 2, None) - - -Mocking methods and self -~~~~~~~~~~~~~~~~~~~~~~~~ - -When you use ``mocksignature`` to replace a method on a class then ``self`` -will be included in the method signature - and you will need to include -the instance when you do your asserts: - -.. doctest:: - - >>> from mock import mocksignature - >>> class SomeClass(object): - ... def method(self, a, b, c=None): - ... pass - ... - >>> SomeClass.method = mocksignature(SomeClass.method) - >>> SomeClass.method.mock.return_value = None - >>> instance = SomeClass() - >>> instance.method() - Traceback (most recent call last): - ... - TypeError: () takes at least 4 arguments (1 given) - >>> instance.method(1, 2, 3) - >>> instance.method.mock.assert_called_with(instance, 1, 2, 3) - -When you use ``mocksignature`` on instance methods ``self`` isn't included: - -.. doctest:: - - >>> from mock import mocksignature - >>> class SomeClass(object): - ... def method(self, a, b, c=None): - ... pass - ... - >>> instance = SomeClass() - >>> instance.method = mocksignature(instance.method) - >>> instance.method.mock.return_value = None - >>> instance.method(1, 2, 3) - >>> instance.method.mock.assert_called_with(1, 2, 3) - - -mocksignature with classes -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When used with a class `mocksignature` copies the signature of the `__init__` -method. - -.. doctest:: - - >>> from mock import mocksignature - >>> class Something(object): - ... def __init__(self, foo, bar): - ... pass - ... - >>> MockSomething = mocksignature(Something) - >>> instance = MockSomething(10, 9) - >>> assert instance is MockSomething.mock.return_value - >>> MockSomething.mock.assert_called_with(10, 9) - >>> MockSomething() - Traceback (most recent call last): - ... - TypeError: () takes at least 2 arguments (0 given) - -Because the object returned by `mocksignature` is a function rather than a -`Mock` you lose the other capabilities of `Mock`, like dynamic attribute -creation. - -mocksignature with callable objects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When used with a callable object `mocksignature` copies the signature of the -`__call__` method. - -.. doctest:: - - >>> from mock import mocksignature - >>> class Something(object): - ... def __call__(self, spam, eggs): - ... pass - ... - >>> something = Something() - >>> mock_something = mocksignature(something) - >>> result = mock_something(10, 9) - >>> mock_something.mock.assert_called_with(10, 9) - >>> mock_something() - Traceback (most recent call last): - ... - TypeError: () takes at least 2 arguments (0 given) - -Because the object returned by `mocksignature` is a function rather than a -`Mock` you lose the other capabilities of `Mock`, like dynamic attribute -creation. - -mocksignature argument to patch -------------------------------- - -``mocksignature`` is available as a keyword argument to :func:`patch` or -:func:`patch.object`. It can be used with functions / methods / classes and -callable objects. - -.. doctest:: - - >>> from mock import patch - >>> class SomeClass(object): - ... def method(self, a, b, c=None): - ... pass - ... - >>> @patch.object(SomeClass, 'method', mocksignature=True) - ... def test(mock_method): - ... instance = SomeClass() - ... mock_method.return_value = None - ... instance.method(1, 2) - ... mock_method.assert_called_with(instance, 1, 2, None) - ... - >>> test() diff -Nru python-mock-0.7.2/docs/mock.txt python-mock-1.0.1/docs/mock.txt --- python-mock-0.7.2/docs/mock.txt 2011-03-21 21:24:58.000000000 +0000 +++ python-mock-1.0.1/docs/mock.txt 2012-04-21 00:43:53.000000000 +0000 @@ -1,27 +1,30 @@ -================ - The Mock Class -================ +The Mock Class +============== .. currentmodule:: mock .. testsetup:: - import os, sys - if not os.getcwd() in sys.path: - sys.path.append(os.getcwd()) - from mock import Mock, sentinel, DEFAULT - class SomeClass: pass -``Mock`` is a flexible mock object intended to replace the use of stubs and + +`Mock` is a flexible mock object intended to replace the use of stubs and test doubles throughout your code. Mocks are callable and create attributes as new mocks when you access them [#]_. Accessing the same attribute will always return the same mock. Mocks record how you use them, allowing you to make assertions about what your code has done to them. -The :func:`mock.patch` decorators makes it easy to temporarily replace classes -in a particular module with a Mock object. +:class:`MagicMock` is a subclass of `Mock` with all the magic methods +pre-created and ready to use. There are also non-callable variants, useful +when you are mocking out objects that aren't callable: +:class:`NonCallableMock` and :class:`NonCallableMagicMock` + +The :func:`patch` decorators makes it easy to temporarily replace classes +in a particular module with a `Mock` object. By default `patch` will create +a `MagicMock` for you. You can specify an alternative class of `Mock` using +the `new_callable` argument to `patch`. + .. index:: side_effect .. index:: return_value @@ -29,7 +32,501 @@ .. index:: name .. index:: spec -.. autoclass:: Mock +.. class:: Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, **kwargs) + + Create a new `Mock` object. `Mock` takes several optional arguments + that specify the behaviour of the Mock object: + + * `spec`: This can be either a list of strings or an existing object (a + class or instance) that acts as the specification for the mock object. If + you pass in an object then a list of strings is formed by calling dir on + the object (excluding unsupported magic attributes and methods). + Accessing any attribute not in this list will raise an `AttributeError`. + + If `spec` is an object (rather than a list of strings) then + :attr:`__class__` returns the class of the spec object. This allows mocks + to pass `isinstance` tests. + + * `spec_set`: A stricter variant of `spec`. If used, attempting to *set* + or get an attribute on the mock that isn't on the object passed as + `spec_set` will raise an `AttributeError`. + + * `side_effect`: A function to be called whenever the Mock is called. See + the :attr:`~Mock.side_effect` attribute. Useful for raising exceptions or + dynamically changing return values. The function is called with the same + arguments as the mock, and unless it returns :data:`DEFAULT`, the return + value of this function is used as the return value. + + Alternatively `side_effect` can be an exception class or instance. In + this case the exception will be raised when the mock is called. + + If `side_effect` is an iterable then each call to the mock will return + the next value from the iterable. If any of the members of the iterable + are exceptions they will be raised instead of returned. + + A `side_effect` can be cleared by setting it to `None`. + + * `return_value`: The value returned when the mock is called. By default + this is a new Mock (created on first access). See the + :attr:`return_value` attribute. + + * `wraps`: Item for the mock object to wrap. If `wraps` is not None then + calling the Mock will pass the call through to the wrapped object + (returning the real result and ignoring `return_value`). Attribute access + on the mock will return a Mock object that wraps the corresponding + attribute of the wrapped object (so attempting to access an attribute + that doesn't exist will raise an `AttributeError`). + + If the mock has an explicit `return_value` set then calls are not passed + to the wrapped object and the `return_value` is returned instead. + + * `name`: If the mock has a name then it will be used in the repr of the + mock. This can be useful for debugging. The name is propagated to child + mocks. + + Mocks can also be called with arbitrary keyword arguments. These will be + used to set attributes on the mock after it is created. See the + :meth:`configure_mock` method for details. + + + .. method:: assert_called_with(*args, **kwargs) + + This method is a convenient way of asserting that calls are made in a + particular way: + + .. doctest:: + + >>> mock = Mock() + >>> mock.method(1, 2, 3, test='wow') + + >>> mock.method.assert_called_with(1, 2, 3, test='wow') + + + .. method:: assert_called_once_with(*args, **kwargs) + + Assert that the mock was called exactly once and with the specified + arguments. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock('foo', bar='baz') + >>> mock.assert_called_once_with('foo', bar='baz') + >>> mock('foo', bar='baz') + >>> mock.assert_called_once_with('foo', bar='baz') + Traceback (most recent call last): + ... + AssertionError: Expected to be called once. Called 2 times. + + + .. method:: assert_any_call(*args, **kwargs) + + assert the mock has been called with the specified arguments. + + The assert passes if the mock has *ever* been called, unlike + :meth:`assert_called_with` and :meth:`assert_called_once_with` that + only pass if the call is the most recent one. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock(1, 2, arg='thing') + >>> mock('some', 'thing', 'else') + >>> mock.assert_any_call(1, 2, arg='thing') + + + .. method:: assert_has_calls(calls, any_order=False) + + assert the mock has been called with the specified calls. + The `mock_calls` list is checked for the calls. + + If `any_order` is False (the default) then the calls must be + sequential. There can be extra calls before or after the + specified calls. + + If `any_order` is True then the calls can be in any order, but + they must all appear in :attr:`mock_calls`. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock(1) + >>> mock(2) + >>> mock(3) + >>> mock(4) + >>> calls = [call(2), call(3)] + >>> mock.assert_has_calls(calls) + >>> calls = [call(4), call(2), call(3)] + >>> mock.assert_has_calls(calls, any_order=True) + + + .. method:: reset_mock() + + The reset_mock method resets all the call attributes on a mock object: + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock('hello') + >>> mock.called + True + >>> mock.reset_mock() + >>> mock.called + False + + This can be useful where you want to make a series of assertions that + reuse the same object. Note that `reset_mock` *doesn't* clear the + return value, :attr:`side_effect` or any child attributes you have + set using normal assignment. Child mocks and the return value mock + (if any) are reset as well. + + + .. method:: mock_add_spec(spec, spec_set=False) + + Add a spec to a mock. `spec` can either be an object or a + list of strings. Only attributes on the `spec` can be fetched as + attributes from the mock. + + If `spec_set` is `True` then only attributes on the spec can be set. + + + .. method:: attach_mock(mock, attribute) + + Attach a mock as an attribute of this one, replacing its name and + parent. Calls to the attached mock will be recorded in the + :attr:`method_calls` and :attr:`mock_calls` attributes of this one. + + + .. method:: configure_mock(**kwargs) + + Set attributes on the mock through keyword arguments. + + Attributes plus return values and side effects can be set on child + mocks using standard dot notation and unpacking a dictionary in the + method call: + + .. doctest:: + + >>> mock = Mock() + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock.configure_mock(**attrs) + >>> mock.method() + 3 + >>> mock.other() + Traceback (most recent call last): + ... + KeyError + + The same thing can be achieved in the constructor call to mocks: + + .. doctest:: + + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock = Mock(some_attribute='eggs', **attrs) + >>> mock.some_attribute + 'eggs' + >>> mock.method() + 3 + >>> mock.other() + Traceback (most recent call last): + ... + KeyError + + `configure_mock` exists to make it easier to do configuration + after the mock has been created. + + + .. method:: __dir__() + + `Mock` objects limit the results of `dir(some_mock)` to useful results. + For mocks with a `spec` this includes all the permitted attributes + for the mock. + + See :data:`FILTER_DIR` for what this filtering does, and how to + switch it off. + + + .. method:: _get_child_mock(**kw) + + Create the child mocks for attributes and return value. + By default child mocks will be the same type as the parent. + Subclasses of Mock may want to override this to customize the way + child mocks are made. + + For non-callable mocks the callable variant will be used (rather than + any custom subclass). + + + .. attribute:: called + + A boolean representing whether or not the mock object has been called: + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock.called + False + >>> mock() + >>> mock.called + True + + .. attribute:: call_count + + An integer telling you how many times the mock object has been called: + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock.call_count + 0 + >>> mock() + >>> mock() + >>> mock.call_count + 2 + + + .. attribute:: return_value + + Set this to configure the value returned by calling the mock: + + .. doctest:: + + >>> mock = Mock() + >>> mock.return_value = 'fish' + >>> mock() + 'fish' + + The default return value is a mock object and you can configure it in + the normal way: + + .. doctest:: + + >>> mock = Mock() + >>> mock.return_value.attribute = sentinel.Attribute + >>> mock.return_value() + + >>> mock.return_value.assert_called_with() + + `return_value` can also be set in the constructor: + + .. doctest:: + + >>> mock = Mock(return_value=3) + >>> mock.return_value + 3 + >>> mock() + 3 + + + .. attribute:: side_effect + + This can either be a function to be called when the mock is called, + or an exception (class or instance) to be raised. + + If you pass in a function it will be called with same arguments as the + mock and unless the function returns the :data:`DEFAULT` singleton the + call to the mock will then return whatever the function returns. If the + function returns :data:`DEFAULT` then the mock will return its normal + value (from the :attr:`return_value`. + + An example of a mock that raises an exception (to test exception + handling of an API): + + .. doctest:: + + >>> mock = Mock() + >>> mock.side_effect = Exception('Boom!') + >>> mock() + Traceback (most recent call last): + ... + Exception: Boom! + + Using `side_effect` to return a sequence of values: + + .. doctest:: + + >>> mock = Mock() + >>> mock.side_effect = [3, 2, 1] + >>> mock(), mock(), mock() + (3, 2, 1) + + The `side_effect` function is called with the same arguments as the + mock (so it is wise for it to take arbitrary args and keyword + arguments) and whatever it returns is used as the return value for + the call. The exception is if `side_effect` returns :data:`DEFAULT`, + in which case the normal :attr:`return_value` is used. + + .. doctest:: + + >>> mock = Mock(return_value=3) + >>> def side_effect(*args, **kwargs): + ... return DEFAULT + ... + >>> mock.side_effect = side_effect + >>> mock() + 3 + + `side_effect` can be set in the constructor. Here's an example that + adds one to the value the mock is called with and returns it: + + .. doctest:: + + >>> side_effect = lambda value: value + 1 + >>> mock = Mock(side_effect=side_effect) + >>> mock(3) + 4 + >>> mock(-8) + -7 + + Setting `side_effect` to `None` clears it: + + .. doctest:: + + >>> from mock import Mock + >>> m = Mock(side_effect=KeyError, return_value=3) + >>> m() + Traceback (most recent call last): + ... + KeyError + >>> m.side_effect = None + >>> m() + 3 + + + .. attribute:: call_args + + This is either `None` (if the mock hasn't been called), or the + arguments that the mock was last called with. This will be in the + form of a tuple: the first member is any ordered arguments the mock + was called with (or an empty tuple) and the second member is any + keyword arguments (or an empty dictionary). + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> print mock.call_args + None + >>> mock() + >>> mock.call_args + call() + >>> mock.call_args == () + True + >>> mock(3, 4) + >>> mock.call_args + call(3, 4) + >>> mock.call_args == ((3, 4),) + True + >>> mock(3, 4, 5, key='fish', next='w00t!') + >>> mock.call_args + call(3, 4, 5, key='fish', next='w00t!') + + `call_args`, along with members of the lists :attr:`call_args_list`, + :attr:`method_calls` and :attr:`mock_calls` are :data:`call` objects. + These are tuples, so they can be unpacked to get at the individual + arguments and make more complex assertions. See + :ref:`calls as tuples `. + + + .. attribute:: call_args_list + + This is a list of all the calls made to the mock object in sequence + (so the length of the list is the number of times it has been + called). Before any calls have been made it is an empty list. The + :data:`call` object can be used for conveniently constructing lists of + calls to compare with `call_args_list`. + + .. doctest:: + + >>> mock = Mock(return_value=None) + >>> mock() + >>> mock(3, 4) + >>> mock(key='fish', next='w00t!') + >>> mock.call_args_list + [call(), call(3, 4), call(key='fish', next='w00t!')] + >>> expected = [(), ((3, 4),), ({'key': 'fish', 'next': 'w00t!'},)] + >>> mock.call_args_list == expected + True + + Members of `call_args_list` are :data:`call` objects. These can be + unpacked as tuples to get at the individual arguments. See + :ref:`calls as tuples `. + + + .. attribute:: method_calls + + As well as tracking calls to themselves, mocks also track calls to + methods and attributes, and *their* methods and attributes: + + .. doctest:: + + >>> mock = Mock() + >>> mock.method() + + >>> mock.property.method.attribute() + + >>> mock.method_calls + [call.method(), call.property.method.attribute()] + + Members of `method_calls` are :data:`call` objects. These can be + unpacked as tuples to get at the individual arguments. See + :ref:`calls as tuples `. + + + .. attribute:: mock_calls + + `mock_calls` records *all* calls to the mock object, its methods, magic + methods *and* return value mocks. + + .. doctest:: + + >>> mock = MagicMock() + >>> result = mock(1, 2, 3) + >>> mock.first(a=3) + + >>> mock.second() + + >>> int(mock) + 1 + >>> result(1) + + >>> expected = [call(1, 2, 3), call.first(a=3), call.second(), + ... call.__int__(), call()(1)] + >>> mock.mock_calls == expected + True + + Members of `mock_calls` are :data:`call` objects. These can be + unpacked as tuples to get at the individual arguments. See + :ref:`calls as tuples `. + + + .. attribute:: __class__ + + Normally the `__class__` attribute of an object will return its type. + For a mock object with a `spec` `__class__` returns the spec class + instead. This allows mock objects to pass `isinstance` tests for the + object they are replacing / masquerading as: + + .. doctest:: + + >>> mock = Mock(spec=3) + >>> isinstance(mock, int) + True + + `__class__` is assignable to, this allows a mock to pass an + `isinstance` check without forcing you to use a spec: + + .. doctest:: + + >>> mock = Mock() + >>> mock.__class__ = dict + >>> isinstance(mock, dict) + True + +.. class:: NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, **kwargs) + + A non-callable version of `Mock`. The constructor parameters have the same + meaning of `Mock`, with the exception of `return_value` and `side_effect` + which have no meaning on a non-callable mock. Mock objects that use a class or an instance as a `spec` or `spec_set` are able to pass `isintance` tests: @@ -43,59 +540,81 @@ >>> isinstance(mock, SomeClass) True +The `Mock` classes have support for mocking magic methods. See :ref:`magic +methods ` for the full details. -Methods -======= - -.. method:: Mock.assert_called_with(*args, **kwargs) +The mock classes and the :func:`patch` decorators all take arbitrary keyword +arguments for configuration. For the `patch` decorators the keywords are +passed to the constructor of the mock being created. The keyword arguments +are for configuring attributes of the mock: - This method is a convenient way of asserting that calls are made in a - particular way: +.. doctest:: - .. doctest:: + >>> m = MagicMock(attribute=3, other='fish') + >>> m.attribute + 3 + >>> m.other + 'fish' - >>> mock = Mock() - >>> mock.method(1, 2, 3, test='wow') - - >>> mock.method.assert_called_with(1, 2, 3, test='wow') +The return value and side effect of child mocks can be set in the same way, +using dotted notation. As you can't use dotted names directly in a call you +have to create a dictionary and unpack it using `**`: +.. doctest:: -.. method:: Mock.assert_called_once_with(*args, **kwargs) + >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> mock = Mock(some_attribute='eggs', **attrs) + >>> mock.some_attribute + 'eggs' + >>> mock.method() + 3 + >>> mock.other() + Traceback (most recent call last): + ... + KeyError + + +.. class:: PropertyMock(*args, **kwargs) + + A mock intended to be used as a property, or other descriptor, on a class. + `PropertyMock` provides `__get__` and `__set__` methods so you can specify + a return value when it is fetched. - Assert that the mock was called exactly once and with the specified - arguments. + Fetching a `PropertyMock` instance from an object calls the mock, with + no args. Setting it calls the mock with the value being set. .. doctest:: - >>> mock = Mock(return_value=None) - >>> mock('foo', bar='baz') - >>> mock.assert_called_once_with('foo', bar='baz') - >>> mock('foo', bar='baz') - >>> mock.assert_called_once_with('foo', bar='baz') - Traceback (most recent call last): - ... - AssertionError: Expected to be called once. Called 2 times. - - -.. method:: Mock.reset_mock() - - The reset_mock method resets all the call attributes on a mock object: - - .. doctest:: + >>> class Foo(object): + ... @property + ... def foo(self): + ... return 'something' + ... @foo.setter + ... def foo(self, value): + ... pass + ... + >>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_foo: + ... mock_foo.return_value = 'mockity-mock' + ... this_foo = Foo() + ... print this_foo.foo + ... this_foo.foo = 6 + ... + mockity-mock + >>> mock_foo.mock_calls + [call(), call(6)] + +Because of the way mock attributes are stored you can't directly attach a +`PropertyMock` to a mock object. Instead you can attach it to the mock type +object: - >>> mock = Mock(return_value=None) - >>> mock('hello') - >>> mock.called - True - >>> mock.reset_mock() - >>> mock.called - False +.. doctest:: - This can be useful where you want to make a series of assertions that - reuse the same object. Note that ``reset`` *doesn't* clear the return - value, ``side_effect`` or any child attributes. Attributes you have set - using normal assignment are also left in place. Child mocks and the return - value mock (if any) are reset as well. + >>> m = MagicMock() + >>> p = PropertyMock(return_value=3) + >>> type(m).foo = p + >>> m.foo + 3 + >>> p.assert_called_once_with() .. index:: __call__ @@ -105,236 +624,213 @@ ======= Mock objects are callable. The call will return the value set as the -:attr:`Mock.return_value` attribute. The default return value is a new Mock +:attr:`~Mock.return_value` attribute. The default return value is a new Mock object; it is created the first time the return value is accessed (either explicitly or by calling the Mock) - but it is stored and the same one returned each time. -Calls made to the object will be recorded in the attributes_. - -If :attr:`Mock.side_effect` is set then it will be called after the call has -been recorded but before any value is returned. - +Calls made to the object will be recorded in the attributes +like :attr:`~Mock.call_args` and :attr:`~Mock.call_args_list`. -Attributes -========== +If :attr:`~Mock.side_effect` is set then it will be called after the call has +been recorded, so if `side_effect` raises an exception the call is still +recorded. -.. attribute:: Mock.called +The simplest way to make a mock raise an exception when called is to make +:attr:`~Mock.side_effect` an exception class or instance: - A boolean representing whether or not the mock object has been called: - - .. doctest:: +.. doctest:: - >>> mock = Mock(return_value=None) - >>> mock.called - False - >>> mock() - >>> mock.called - True + >>> m = MagicMock(side_effect=IndexError) + >>> m(1, 2, 3) + Traceback (most recent call last): + ... + IndexError + >>> m.mock_calls + [call(1, 2, 3)] + >>> m.side_effect = KeyError('Bang!') + >>> m('two', 'three', 'four') + Traceback (most recent call last): + ... + KeyError: 'Bang!' + >>> m.mock_calls + [call(1, 2, 3), call('two', 'three', 'four')] + +If `side_effect` is a function then whatever that function returns is what +calls to the mock return. The `side_effect` function is called with the +same arguments as the mock. This allows you to vary the return value of the +call dynamically, based on the input: -.. attribute:: Mock.call_count +.. doctest:: - An integer telling you how many times the mock object has been called: + >>> def side_effect(value): + ... return value + 1 + ... + >>> m = MagicMock(side_effect=side_effect) + >>> m(1) + 2 + >>> m(2) + 3 + >>> m.mock_calls + [call(1), call(2)] - .. doctest:: +If you want the mock to still return the default return value (a new mock), or +any set return value, then there are two ways of doing this. Either return +`mock.return_value` from inside `side_effect`, or return :data:`DEFAULT`: - >>> mock = Mock(return_value=None) - >>> mock.call_count - 0 - >>> mock() - >>> mock() - >>> mock.call_count - 2 +.. doctest:: + >>> m = MagicMock() + >>> def side_effect(*args, **kwargs): + ... return m.return_value + ... + >>> m.side_effect = side_effect + >>> m.return_value = 3 + >>> m() + 3 + >>> def side_effect(*args, **kwargs): + ... return DEFAULT + ... + >>> m.side_effect = side_effect + >>> m() + 3 -.. attribute:: Mock.return_value +To remove a `side_effect`, and return to the default behaviour, set the +`side_effect` to `None`: - Set this to configure the value returned by calling the mock: +.. doctest:: - .. doctest:: + >>> m = MagicMock(return_value=6) + >>> def side_effect(*args, **kwargs): + ... return 3 + ... + >>> m.side_effect = side_effect + >>> m() + 3 + >>> m.side_effect = None + >>> m() + 6 + +The `side_effect` can also be any iterable object. Repeated calls to the mock +will return values from the iterable (until the iterable is exhausted and +a `StopIteration` is raised): - >>> mock = Mock() - >>> mock.return_value = 'fish' - >>> mock() - 'fish' +.. doctest:: - The default return value is a mock object and you can configure it in the - normal way: + >>> m = MagicMock(side_effect=[1, 2, 3]) + >>> m() + 1 + >>> m() + 2 + >>> m() + 3 + >>> m() + Traceback (most recent call last): + ... + StopIteration - .. doctest:: +If any members of the iterable are exceptions they will be raised instead of +returned: - >>> mock = Mock() - >>> mock.return_value.attribute = sentinel.Attribute - >>> mock.return_value() - - >>> mock.return_value.assert_called_with() +.. doctest:: - `return_value` can also be set in the constructor: + >>> iterable = (33, ValueError, 66) + >>> m = MagicMock(side_effect=iterable) + >>> m() + 33 + >>> m() + Traceback (most recent call last): + ... + ValueError + >>> m() + 66 - .. doctest:: - >>> mock = Mock(return_value=3) - >>> mock.return_value - 3 - >>> mock() - 3 +.. _deleting-attributes: +Deleting Attributes +=================== -.. attribute:: Mock.side_effect +Mock objects create attributes on demand. This allows them to pretend to be +objects of any type. +You may want a mock object to return `False` to a `hasattr` call, or raise an +`AttributeError` when an attribute is fetched. You can do this by providing +an object as a `spec` for a mock, but that isn't always convenient. - This can either be a function to be called when the mock is called, or an - exception (class or instance) to be raised. +You "block" attributes by deleting them. Once deleted, accessing an attribute +will raise an `AttributeError`. - If you pass in a function it will be called with same arguments as the - mock and unless the function returns the :data:`DEFAULT` singleton the - call to the mock will then return whatever the function returns. If the - function returns :data:`DEFAULT` then the mock will return its normal - value (from the :attr:`Mock.return_value`. +.. doctest:: - An example of a mock that raises an exception (to test exception handling of - an API): + >>> mock = MagicMock() + >>> hasattr(mock, 'm') + True + >>> del mock.m + >>> hasattr(mock, 'm') + False + >>> del mock.f + >>> mock.f + Traceback (most recent call last): + ... + AttributeError: f - .. doctest:: - >>> mock = Mock() - >>> mock.side_effect = Exception('Boom!') - >>> mock() - Traceback (most recent call last): - ... - Exception: Boom! +Attaching Mocks as Attributes +============================= - Using ``side_effect`` to return a sequence of values: +When you attach a mock as an attribute of another mock (or as the return +value) it becomes a "child" of that mock. Calls to the child are recorded in +the :attr:`~Mock.method_calls` and :attr:`~Mock.mock_calls` attributes of the +parent. This is useful for configuring child mocks and then attaching them to +the parent, or for attaching mocks to a parent that records all calls to the +children and allows you to make assertions about the order of calls between +mocks: - .. doctest:: +.. doctest:: - >>> mock = Mock() - >>> results = [1, 2, 3] - >>> def side_effect(*args, **kwargs): - ... return results.pop() - ... - >>> mock.side_effect = side_effect - >>> mock(), mock(), mock() - (3, 2, 1) - - The `side_effect` function is called with the same arguments as the mock (so - it is wise for it to take arbitrary args and keyword arguments) and - whatever it returns is used as the return value for the call. The - exception is if `side_effect` returns :data:`DEFAULT`, in which case the - normal :attr:`Mock.return_value` is used. + >>> parent = MagicMock() + >>> child1 = MagicMock(return_value=None) + >>> child2 = MagicMock(return_value=None) + >>> parent.child1 = child1 + >>> parent.child2 = child2 + >>> child1(1) + >>> child2(2) + >>> parent.mock_calls + [call.child1(1), call.child2(2)] - .. doctest:: +The exception to this is if the mock has a name. This allows you to prevent +the "parenting" if for some reason you don't want it to happen. - >>> mock = Mock(return_value=3) - >>> def side_effect(*args, **kwargs): - ... return DEFAULT - ... - >>> mock.side_effect = side_effect - >>> mock() - 3 +.. doctest:: - `side_effect` can be set in the constructor. Here's an example that adds one - to the value the mock is called with and returns it: + >>> mock = MagicMock() + >>> not_a_child = MagicMock(name='not-a-child') + >>> mock.attribute = not_a_child + >>> mock.attribute() + + >>> mock.mock_calls + [] + +Mocks created for you by :func:`patch` are automatically given names. To +attach mocks that have names to a parent you use the :meth:`~Mock.attach_mock` +method: - .. doctest:: +.. doctest:: - >>> side_effect = lambda value: value + 1 - >>> mock = Mock(side_effect=side_effect) - >>> mock(3) - 4 - >>> mock(-8) - -7 - -.. attribute:: Mock.call_args - - This is either ``None`` (if the mock hasn't been called), or the arguments - that the mock was last called with. This will be in the form of a tuple: - the first member is any ordered arguments the mock was called with (or an - empty tuple) and the second member is any keyword arguments (or an empty - dictionary). - - .. doctest:: - - >>> mock = Mock(return_value=None) - >>> print mock.call_args - None - >>> mock() - >>> mock.call_args - ((), {}) - >>> mock.call_args == () - True - >>> mock(3, 4) - >>> mock.call_args - ((3, 4), {}) - >>> mock.call_args == ((3, 4),) - True - >>> mock(3, 4, 5, key='fish', next='w00t!') - >>> mock.call_args - ((3, 4, 5), {'key': 'fish', 'next': 'w00t!'}) - - The tuple is lenient when comparing against tuples with empty - elements skipped. This can make tests less verbose: - - .. doctest:: - - >>> mock = Mock(return_value=None) - >>> mock() - >>> mock.call_args == () - True - -.. attribute:: Mock.call_args_list - - This is a list of all the calls made to the mock object in sequence (so - the length of the list is the number of times it has been called). Before - any calls have been made it is an empty list. Its elements compare - "softly" when positional arguments or keyword arguments are skipped: - - .. doctest:: - - >>> mock = Mock(return_value=None) - >>> mock() - >>> mock(3, 4) - >>> mock(key='fish', next='w00t!') - >>> mock.call_args_list - [((), {}), ((3, 4), {}), ((), {'key': 'fish', 'next': 'w00t!'})] - >>> expected = [(), ((3, 4),), ({'key': 'fish', 'next': 'w00t!'},)] - >>> mock.call_args_list == expected - True - - -.. attribute:: Mock.method_calls - - As well as tracking calls to themselves, mocks also track calls to methods - and attributes, and *their* methods and attributes: - - .. doctest:: - - >>> mock = Mock() - >>> mock.method() - - >>> mock.property.method.attribute() - - >>> mock.method_calls - [('method', (), {}), ('property.method.attribute', (), {})] - - The tuples in method_calls compare equal even if empty positional and - keyword arguments are skipped. - - .. doctest:: - - >>> mock = Mock() - >>> mock.method() - - >>> mock.method(1, 2) - - >>> mock.method(a="b") - - >>> mock.method_calls == [('method',), ('method', (1, 2)), - ... ('method', {"a": "b"})] - True + >>> thing1 = object() + >>> thing2 = object() + >>> parent = MagicMock() + >>> with patch('__main__.thing1', return_value=None) as child1: + ... with patch('__main__.thing2', return_value=None) as child2: + ... parent.attach_mock(child1, 'child1') + ... parent.attach_mock(child2, 'child2') + ... child1('one') + ... child2('two') + ... + >>> parent.mock_calls + [call.child1('one'), call.child2('two')] -The ``Mock`` class has support for mocking magic methods. See :ref:`magic -methods ` for the full details. ----- diff -Nru python-mock-0.7.2/docs/patch.txt python-mock-1.0.1/docs/patch.txt --- python-mock-0.7.2/docs/patch.txt 2011-05-30 19:46:32.000000000 +0000 +++ python-mock-1.0.1/docs/patch.txt 2012-06-10 19:37:55.000000000 +0000 @@ -7,13 +7,6 @@ .. testsetup:: - import os, sys - if not os.getcwd() in sys.path: - sys.path.append(os.getcwd()) - - from mock import Mock, sentinel, patch - import unittest2 - class SomeClass(object): static_method = None class_method = None @@ -28,6 +21,11 @@ super(unittest2.TestCase, self).run(result) assert result.wasSuccessful() +.. testcleanup:: + + patch.TEST_PREFIX = 'test' + + The patch decorators are used for patching objects only within the scope of the function they decorate. They automatically handle the unpatching for you, even if exceptions are raised. All of these functions can also be used in with @@ -42,44 +40,202 @@ `patch` is straightforward to use. The key is to do the patching in the right namespace. See the section `where to patch`_. -.. autofunction:: patch +.. function:: patch(target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) -.. note:: + `patch` acts as a function decorator, class decorator or a context + manager. Inside the body of the function or with statement, the `target` + is patched with a `new` object. When the function/with statement exits + the patch is undone. + + If `new` is omitted, then the target is replaced with a + :class:`MagicMock`. If `patch` is used as a decorator and `new` is + omitted, the created mock is passed in as an extra argument to the + decorated function. If `patch` is used as a context manager the created + mock is returned by the context manager. + + `target` should be a string in the form `'package.module.ClassName'`. The + `target` is imported and the specified object replaced with the `new` + object, so the `target` must be importable from the environment you are + calling `patch` from. The target is imported when the decorated function + is executed, not at decoration time. + + The `spec` and `spec_set` keyword arguments are passed to the `MagicMock` + if patch is creating one for you. + + In addition you can pass `spec=True` or `spec_set=True`, which causes + patch to pass in the object being mocked as the spec/spec_set object. + + `new_callable` allows you to specify a different class, or callable object, + that will be called to create the `new` object. By default `MagicMock` is + used. + + A more powerful form of `spec` is `autospec`. If you set `autospec=True` + then the mock with be created with a spec from the object being replaced. + All attributes of the mock will also have the spec of the corresponding + attribute of the object being replaced. Methods and functions being mocked + will have their arguments checked and will raise a `TypeError` if they are + called with the wrong signature. For mocks + replacing a class, their return value (the 'instance') will have the same + spec as the class. See the :func:`create_autospec` function and + :ref:`auto-speccing`. + + Instead of `autospec=True` you can pass `autospec=some_object` to use an + arbitrary object as the spec instead of the one being replaced. + + By default `patch` will fail to replace attributes that don't exist. If + you pass in `create=True`, and the attribute doesn't exist, patch will + create the attribute for you when the patched function is called, and + delete it again afterwards. This is useful for writing tests against + attributes that your production code creates at runtime. It is off by by + default because it can be dangerous. With it switched on you can write + passing tests against APIs that don't actually exist! + + Patch can be used as a `TestCase` class decorator. It works by + decorating each test method in the class. This reduces the boilerplate + code when your test methods share a common patchings set. `patch` finds + tests by looking for method names that start with `patch.TEST_PREFIX`. + By default this is `test`, which matches the way `unittest` finds tests. + You can specify an alternative prefix by setting `patch.TEST_PREFIX`. + + Patch can be used as a context manager, with the with statement. Here the + patching applies to the indented block after the with statement. If you + use "as" then the patched object will be bound to the name after the + "as"; very useful if `patch` is creating a mock object for you. - Patching a class replaces the class with a Mock *instance*. If the class - is instantiated in the code under test then it will be the `return_value` - of the mock that will be used. - - If the class is instantiated multiple times you could use - :attr:`Mock.side_effect` to return a new mock each time. Alternatively you - can set the `return_value` to be anything you want. + `patch` takes arbitrary keyword arguments. These will be passed to + the `Mock` (or `new_callable`) on construction. - To configure return values on methods of *instances* on the patched class - you must do this on the `return_value`. For example: + `patch.dict(...)`, `patch.multiple(...)` and `patch.object(...)` are + available for alternate use-cases. - .. doctest:: +`patch` as function decorator, creating the mock for you and passing it into +the decorated function: - >>> @patch('package.module.Class') - ... def test(MockClass): - ... instance = MockClass.return_value - ... instance.method.return_value = 'foo' - ... from package.module import Class - ... assert Class() is instance - ... assert Class().method() == 'foo' - ... - >>> test() +.. doctest:: + + >>> @patch('__main__.SomeClass') + ... def function(normal_argument, mock_class): + ... print mock_class is SomeClass + ... + >>> function(None) + True + + +Patching a class replaces the class with a `MagicMock` *instance*. If the +class is instantiated in the code under test then it will be the +:attr:`~Mock.return_value` of the mock that will be used. + +If the class is instantiated multiple times you could use +:attr:`~Mock.side_effect` to return a new mock each time. Alternatively you +can set the `return_value` to be anything you want. + +To configure return values on methods of *instances* on the patched class +you must do this on the `return_value`. For example: + +.. doctest:: + + >>> class Class(object): + ... def method(self): + ... pass + ... + >>> with patch('__main__.Class') as MockClass: + ... instance = MockClass.return_value + ... instance.method.return_value = 'foo' + ... assert Class() is instance + ... assert Class().method() == 'foo' + ... + +If you use `spec` or `spec_set` and `patch` is replacing a *class*, then the +return value of the created mock will have the same spec. + +.. doctest:: + + >>> Original = Class + >>> patcher = patch('__main__.Class', spec=True) + >>> MockClass = patcher.start() + >>> instance = MockClass() + >>> assert isinstance(instance, Original) + >>> patcher.stop() + +The `new_callable` argument is useful where you want to use an alternative +class to the default :class:`MagicMock` for the created mock. For example, if +you wanted a :class:`NonCallableMock` to be used: + +.. doctest:: + + >>> thing = object() + >>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing: + ... assert thing is mock_thing + ... thing() + ... + Traceback (most recent call last): + ... + TypeError: 'NonCallableMock' object is not callable + +Another use case might be to replace an object with a `StringIO` instance: + +.. doctest:: + + >>> from StringIO import StringIO + >>> def foo(): + ... print 'Something' + ... + >>> @patch('sys.stdout', new_callable=StringIO) + ... def test(mock_stdout): + ... foo() + ... assert mock_stdout.getvalue() == 'Something\n' + ... + >>> test() + +When `patch` is creating a mock for you, it is common that the first thing +you need to do is to configure the mock. Some of that configuration can be done +in the call to patch. Any arbitrary keywords you pass into the call will be +used to set attributes on the created mock: + +.. doctest:: + + >>> patcher = patch('__main__.thing', first='one', second='two') + >>> mock_thing = patcher.start() + >>> mock_thing.first + 'one' + >>> mock_thing.second + 'two' + +As well as attributes on the created mock attributes, like the +:attr:`~Mock.return_value` and :attr:`~Mock.side_effect`, of child mocks can +also be configured. These aren't syntactically valid to pass in directly as +keyword arguments, but a dictionary with these as keys can still be expanded +into a `patch` call using `**`: + +.. doctest:: + + >>> config = {'method.return_value': 3, 'other.side_effect': KeyError} + >>> patcher = patch('__main__.thing', **config) + >>> mock_thing = patcher.start() + >>> mock_thing.method() + 3 + >>> mock_thing.other() + Traceback (most recent call last): + ... + KeyError patch.object ============ -.. function:: patch.object(target, attribute, new=DEFAULT, spec=None, create=False, mocksignature=False, spec_set=None) +.. function:: patch.object(target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) patch the named member (`attribute`) on an object (`target`) with a mock object. - Arguments new, spec, create, mocksignature and spec_set have the same - meaning as for patch. + `patch.object` can be used as a decorator, class decorator or a context + manager. Arguments `new`, `spec`, `create`, `spec_set`, `autospec` and + `new_callable` have the same meaning as for `patch`. Like `patch`, + `patch.object` takes arbitrary keyword arguments for configuring the mock + object it creates. + + When used as a class decorator `patch.object` honours `patch.TEST_PREFIX` + for choosing which methods to wrap. You can either call `patch.object` with three arguments or two arguments. The three argument form takes the object to be patched, the attribute name and the @@ -98,26 +254,17 @@ ... >>> test() -``spec`` and ``create`` have the same meaning as for the patch decorator. - -``patch.object`` is also a context manager and can be used with ``with`` -statements in the same way as ``patch``. It can also be used as a class -decorator with same semantics as ``patch``. - -patch_object -============ - -.. deprecated:: 0.7 - This is the same as ``patch.object``. Use the renamed version. +`spec`, `create` and the other arguments to `patch.object` have the same +meaning as they do for `patch`. patch.dict ========== -.. function:: patch.dict(in_dict, values=(), clear=False) +.. function:: patch.dict(in_dict, values=(), clear=False, **kwargs) - Patch a dictionary and restore the dictionary to its original state after - the test. + Patch a dictionary, or dictionary like object, and restore the dictionary + to its original state after the test. `in_dict` can be a dictionary or a mapping like container. If it is a mapping then it must at least support getting, setting and deleting items @@ -127,15 +274,21 @@ will then be fetched by importing it. `values` can be a dictionary of values to set in the dictionary. `values` - can also be an iterable of ``(key, value)`` pairs. + can also be an iterable of `(key, value)` pairs. If `clear` is True then the dictionary will be cleared before the new values are set. -Like :func:`patch` and :func:`patch.object` ``patch.dict`` can be used as a -decorator or a context manager. It can be used to add members to a dictionary, -or simply let a test change a dictionary, and ensure the dictionary is restored -when the test ends. + `patch.dict` can also be called with arbitrary keyword arguments to set + values in the dictionary. + + `patch.dict` can be used as a context manager, decorator or class + decorator. When used as a class decorator `patch.dict` honours + `patch.TEST_PREFIX` for choosing which methods to wrap. + +`patch.dict` can be used to add members to a dictionary, or simply let a test +change a dictionary, and ensure the dictionary is restored when the test +ends. .. doctest:: @@ -153,13 +306,122 @@ newvalue >>> assert 'newkey' not in os.environ +Keywords can be used in the `patch.dict` call to set values in the dictionary: + +.. doctest:: + + >>> mymodule = MagicMock() + >>> mymodule.function.return_value = 'fish' + >>> with patch.dict('sys.modules', mymodule=mymodule): + ... import mymodule + ... mymodule.function('some', 'args') + ... + 'fish' + +`patch.dict` can be used with dictionary like objects that aren't actually +dictionaries. At the very minimum they must support item getting, setting, +deleting and either iteration or membership test. This corresponds to the +magic methods `__getitem__`, `__setitem__`, `__delitem__` and either +`__iter__` or `__contains__`. + +.. doctest:: + + >>> class Container(object): + ... def __init__(self): + ... self.values = {} + ... def __getitem__(self, name): + ... return self.values[name] + ... def __setitem__(self, name, value): + ... self.values[name] = value + ... def __delitem__(self, name): + ... del self.values[name] + ... def __iter__(self): + ... return iter(self.values) + ... + >>> thing = Container() + >>> thing['one'] = 1 + >>> with patch.dict(thing, one=2, two=3): + ... assert thing['one'] == 2 + ... assert thing['two'] == 3 + ... + >>> assert thing['one'] == 1 + >>> assert list(thing) == ['one'] + + +patch.multiple +============== + +.. function:: patch.multiple(target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) + + Perform multiple patches in a single call. It takes the object to be + patched (either as an object or a string to fetch the object by importing) + and keyword arguments for the patches:: + + with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'): + ... + + Use :data:`DEFAULT` as the value if you want `patch.multiple` to create + mocks for you. In this case the created mocks are passed into a decorated + function by keyword, and a dictionary is returned when `patch.multiple` is + used as a context manager. + + `patch.multiple` can be used as a decorator, class decorator or a context + manager. The arguments `spec`, `spec_set`, `create`, `autospec` and + `new_callable` have the same meaning as for `patch`. These arguments will + be applied to *all* patches done by `patch.multiple`. + + When used as a class decorator `patch.multiple` honours `patch.TEST_PREFIX` + for choosing which methods to wrap. + +If you want `patch.multiple` to create mocks for you, then you can use +:data:`DEFAULT` as the value. If you use `patch.multiple` as a decorator +then the created mocks are passed into the decorated function by keyword. + +.. doctest:: + + >>> thing = object() + >>> other = object() + + >>> @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) + ... def test_function(thing, other): + ... assert isinstance(thing, MagicMock) + ... assert isinstance(other, MagicMock) + ... + >>> test_function() + +`patch.multiple` can be nested with other `patch` decorators, but put arguments +passed by keyword *after* any of the standard arguments created by `patch`: + +.. doctest:: + + >>> @patch('sys.exit') + ... @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) + ... def test_function(mock_exit, other, thing): + ... assert 'other' in repr(other) + ... assert 'thing' in repr(thing) + ... assert 'exit' in repr(mock_exit) + ... + >>> test_function() + +If `patch.multiple` is used as a context manager, the value returned by the +context manger is a dictionary where created mocks are keyed by name: + +.. doctest:: + + >>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values: + ... assert 'other' in repr(values['other']) + ... assert 'thing' in repr(values['thing']) + ... assert values['thing'] is thing + ... assert values['other'] is other + ... + .. _start-and-stop: patch methods: start and stop ============================= -All three patchers have `start` and `stop` methods. These make it simpler to do +All the patchers have `start` and `stop` methods. These make it simpler to do patching in `setUp` methods or where you want to do multiple patches without nesting decorators or with statements. @@ -229,8 +491,44 @@ As an added bonus you no longer need to keep a reference to the `patcher` object. -In fact `start` and `stop` are just aliases for the context manager -`__enter__` and `__exit__` methods. +It is also possible to stop all patches which have been started by using +`patch.stopall`. + +.. function:: patch.stopall + + Stop all active patches. Only stops patches started with `start`. + + +TEST_PREFIX +=========== + +All of the patchers can be used as class decorators. When used in this way +they wrap every test method on the class. The patchers recognise methods that +start with `test` as being test methods. This is the same way that the +`unittest.TestLoader` finds test methods by default. + +It is possible that you want to use a different prefix for your tests. You can +inform the patchers of the different prefix by setting `patch.TEST_PREFIX`: + +.. doctest:: + + >>> patch.TEST_PREFIX = 'foo' + >>> value = 3 + >>> + >>> @patch('__main__.value', 'not three') + ... class Thing(object): + ... def foo_one(self): + ... print value + ... def foo_two(self): + ... print value + ... + >>> + >>> Thing().foo_one() + not three + >>> Thing().foo_two() + not three + >>> value + 3 Nesting Patch Decorators @@ -286,9 +584,9 @@ for patching to work you must ensure that you patch the name used by the system under test. -The basic principle is that you patch where an object is *used*, which is not -necessarily the same place as where it is defined. A couple of examples will -help to clarify this. +The basic principle is that you patch where an object is *looked up*, which +is not necessarily the same place as where it is defined. A couple of +examples will help to clarify this. Imagine we have a project that we want to test with the following structure:: @@ -310,14 +608,14 @@ ). In this case `some_function` will actually look up `SomeClass` in module b, where we have imported it. The patching should look like: - ``@patch('b.SomeClass')`` + `@patch('b.SomeClass')` However, consider the alternative scenario where instead of `from a import SomeClass` module b does `import a` and `some_function` uses `a.SomeClass`. Both of these import forms are common. In this case the class we want to patch is being looked up on the a module and so we have to patch `a.SomeClass` instead: - ``@patch('a.SomeClass')`` + `@patch('a.SomeClass')` Patching Descriptors and Proxy Objects diff -Nru python-mock-0.7.2/docs/sentinel.txt python-mock-1.0.1/docs/sentinel.txt --- python-mock-0.7.2/docs/sentinel.txt 2011-03-21 21:25:31.000000000 +0000 +++ python-mock-1.0.1/docs/sentinel.txt 2012-01-23 00:08:06.000000000 +0000 @@ -7,17 +7,11 @@ .. testsetup:: - import os, sys, unittest - if not os.getcwd() in sys.path: - sys.path.append(os.getcwd()) - - from mock import Mock, sentinel - class ProductionClass(object): def something(self): return self.method() - class Test(unittest.TestCase): + class Test(unittest2.TestCase): def testSomething(self): pass self = Test('testSomething') @@ -35,8 +29,8 @@ .. data:: DEFAULT - The ``DEFAULT`` object is a pre-created sentinel (actually - ``sentinel.DEFAULT``). It can be used by :attr:`Mock.side_effect` + The `DEFAULT` object is a pre-created sentinel (actually + `sentinel.DEFAULT`). It can be used by :attr:`~Mock.side_effect` functions to indicate that the normal return value should be used. @@ -59,6 +53,6 @@ >>> result = real.method() >>> assert result is sentinel.some_object >>> sentinel.some_object - + sentinel.some_object diff -Nru python-mock-0.7.2/docs/_static/adctheme.css python-mock-1.0.1/docs/_static/adctheme.css --- python-mock-0.7.2/docs/_static/adctheme.css 2011-03-21 21:24:58.000000000 +0000 +++ python-mock-1.0.1/docs/_static/adctheme.css 1970-01-01 00:00:00.000000000 +0000 @@ -1,757 +0,0 @@ -/** - * Sphinx stylesheet -- basic theme - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - */ - h3 { - color:#000000; - font-size: 17px; - margin-bottom:0.5em; - margin-top:2em; - } -/* -- main layout ----------------------------------------------------------- */ - -div.clearer { - clear: both; -} - -/* -- header ---------------------------------------------------------------- */ - -#header #title { - background:#29334F url(title_background.png) repeat-x scroll 0 0; - border-bottom:1px solid #B6B6B6; - height:25px; - overflow:hidden; -} -#headerButtons { - position: absolute; - list-style: none outside; - top: 26px; - left: 0px; - right: 0px; - margin: 0px; - padding: 0px; - border-top: 1px solid #2B334F; - border-bottom: 1px solid #EDEDED; - height: 20px; - font-size: 8pt; - overflow: hidden; - background-color: #D8D8D8; -} - -#headerButtons li { - background-repeat:no-repeat; - display:inline; - margin-top:0; - padding:0; -} - -.headerButton { - display: inline; - height:20px; -} - -.headerButton a { - text-decoration: none; - float: right; - height: 20px; - padding: 4px 15px; - border-left: 1px solid #ACACAC; - font-family:'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; - color: black; -} -.headerButton a:hover { - color: white; - background-color: #787878; - -} - -li#toc_button { - text-align:left; -} - -li#toc_button .headerButton a { - width:198px; - padding-top: 4px; - font-family:'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; - color: black; - float: left; - padding-left:15px; - border-right:1px solid #ACACAC; - background:transparent url(triangle_open.png) no-repeat scroll 4px 6px; -} - -li#toc_button .headerButton a:hover { - background-color: #787878; - color: white; -} - -li#page_buttons { -position:absolute; -right:0; -} - -#breadcrumbs { - color: black; - background-image:url(breadcrumb_background.png); - border-top:1px solid #2B334F; - bottom:0; - font-size:10px; - height:15px; - left:0; - overflow:hidden; - padding:3px 10px 0; - position:absolute; - right:0; - white-space:nowrap; - z-index:901; -} -#breadcrumbs a { - color: black; - text-decoration: none; -} -#breadcrumbs a:hover { - text-decoration: underline; -} -#breadcrumbs img { - padding-left: 3px; -} -/* -- sidebar --------------------------------------------------------------- */ -#sphinxsidebar { - position: absolute; - top: 84px; - bottom: 19px; - left: 0px; - width: 229px; - background-color: #E4EBF7; - border-right: 1px solid #ACACAC; - border-top: 1px solid #2B334F; - overflow-x: hidden; - overflow-y: auto; - padding: 0px 0px 0px 0px; - font-size:11px; -} - -div.sphinxsidebarwrapper { - padding: 10px 5px 0 10px; -} - -#sphinxsidebar li { - margin: 0px; - padding: 0px; - font-weight: normal; - margin: 0px 0px 7px 0px; - overflow: hidden; - text-overflow: ellipsis; - font-size: 11px; -} - -#sphinxsidebar ul { - list-style: none; - margin: 0px 0px 0px 0px; - padding: 0px 5px 0px 5px; -} - -#sphinxsidebar ul ul, -#sphinxsidebar ul.want-points { - list-style: square; -} - -#sphinxsidebar ul ul { - margin-top: 0; - margin-bottom: 0; -} - -#sphinxsidebar form { - margin-top: 10px; -} - -#sphinxsidebar input { - border: 1px solid #787878; - font-family: sans-serif; - font-size: 1em; -} - -img { - border: 0; -} - -#sphinxsidebar li.toctree-l1 a { - font-weight: bold; - color: #000; - text-decoration: none; -} - -#sphinxsidebar li.toctree-l2 a { - font-weight: bold; - color: #4f4f4f; - text-decoration: none; -} - -/* -- search page ----------------------------------------------------------- */ - -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} -#sphinxsidebar input.prettysearch {border:none;} -input.searchbutton { - float: right; -} -.search-wrapper {width: 100%; height: 25px;} -.search-wrapper input.prettysearch { border: none; width:200px; height: 16px; background: url(searchfield_repeat.png) center top repeat-x; border: 0px; margin: 0; padding: 3px 0 0 0; font: 11px "Lucida Grande", "Lucida Sans Unicode", Arial, sans-serif; } -.search-wrapper input.prettysearch { width: 184px; margin-left: 20px; *margin-top:-1px; *margin-right:-2px; *margin-left:10px; } -.search-wrapper .search-left { display: block; position: absolute; width: 20px; height: 19px; background: url(searchfield_leftcap.png) left top no-repeat; } -.search-wrapper .search-right { display: block; position: relative; left: 204px; top: -19px; width: 10px; height: 19px; background: url(searchfield_rightcap.png) right top no-repeat; } - -/* -- index page ------------------------------------------------------------ */ - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.3em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; - font-size: 90%; -} - -/* -- general index --------------------------------------------------------- */ - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -/* -- general body styles --------------------------------------------------- */ -.document { - border-top:1px solid #2B334F; - overflow:auto; - padding-left:2em; - padding-right:2em; - position:absolute; - z-index:1; - top:84px; - bottom:19px; - right:0; - left:230px; -} - -a.headerlink { - visibility: hidden; -} - -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink, -dt:hover > a.headerlink { - visibility: visible; -} - -div.body p.caption { - text-align: inherit; -} - -div.body td { - text-align: left; -} - -.field-list ul { - padding-left: 1em; -} - -.first { - margin-top: 0 !important; -} - -p.rubric { - margin-top: 30px; - font-weight: bold; -} - -/* -- sidebars -------------------------------------------------------------- */ - -/*div.sidebar { - margin: 0 0 0.5em 1em; - border: 1px solid #ddb; - padding: 7px 7px 0 7px; - background-color: #ffe; - width: 40%; - float: right; -} - -p.sidebar-title { - font-weight: bold; -} -*/ -/* -- topics ---------------------------------------------------------------- */ - -div.topic { - border: 1px solid #ccc; - padding: 7px 7px 0 7px; - margin: 10px 0 10px 0; -} - -p.topic-title { - font-size: 1.1em; - font-weight: bold; - margin-top: 10px; -} - -/* -- admonitions ----------------------------------------------------------- */ -.admonition { - border: 1px solid #a1a5a9; - background-color: #f7f7f7; - margin: 20px; - padding: 0px 8px 7px 9px; - text-align: left; -} -.warning { - background-color:#E8E8E8; - border:1px solid #111111; - margin:30px; -} -.admonition p { - font: 12px 'Lucida Grande', Geneva, Helvetica, Arial, sans-serif; - margin-top: 7px; - margin-bottom: 0px; -} - -div.admonition dt { - font-weight: bold; -} - -div.admonition dl { - margin-bottom: 0; -} - -p.admonition-title { - margin: 0px 10px 5px 0px; - font-weight: bold; - padding-top: 3px; -} - -div.body p.centered { - text-align: center; - margin-top: 25px; -} - -/* -- tables ---------------------------------------------------------------- */ - -table.docutils { - border-collapse: collapse; - border-top: 1px solid #919699; - border-left: 1px solid #919699; - border-right: 1px solid #919699; - font-size:12px; - padding:8px; - text-align:left; - vertical-align:top; -} - -table.docutils td, table.docutils th { - padding: 8px; - font-size: 12px; - text-align: left; - vertical-align: top; - border-bottom: 1px solid #919699; -} - -table.docutils th { - font-weight: bold; -} -/* This alternates colors in up to six table rows (light blue for odd, white for even)*/ -.docutils tr { - background: #F0F5F9; -} - -.docutils tr + tr { - background: #FFFFFF; -} - -.docutils tr + tr + tr { - background: #F0F5F9; -} - -.docutils tr + tr + tr + tr { - background: #FFFFFF; -} - -.docutils tr + tr + tr +tr + tr { - background: #F0F5F9; -} - -.docutils tr + tr + tr + tr + tr + tr { - background: #FFFFFF; -} - -.docutils tr + tr + tr + tr + tr + tr + tr { - background: #F0F5F9; -} - -table.footnote td, table.footnote th { - border: 0 !important; -} - -th { - text-align: left; - padding-right: 5px; -} - -/* -- other body styles ----------------------------------------------------- */ - -dl { - margin-bottom: 15px; -} - -dd p { - margin-top: 0px; - font-size: 12px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; - font-size: 12px; -} - -dt:target, .highlight { - background-color: #fbe54e; -} - -dl.glossary dt { - font-weight: bold; - font-size: 0.8em; -} - -dl.glossary dd { - font-size:12px; -} -.field-list ul { - vertical-align: top; - margin: 0; - padding-bottom: 0; - list-style: none inside; -} - -.field-list ul li { - margin-top: 0; -} - -.field-list p { - margin: 0; -} - -.refcount { - color: #060; -} - -.optional { - font-size: 1.3em; -} - -.versionmodified { - font-style: italic; -} - -.system-message { - background-color: #fda; - padding: 5px; - border: 3px solid red; -} - -.footnote:target { - background-color: #ffa -} - -/* -- code displays --------------------------------------------------------- */ - -pre { - overflow: auto; - background-color:#F1F5F9; - border:1px solid #C9D1D7; - border-spacing:0; - font-family:"Bitstream Vera Sans Mono",Monaco,"Lucida Console",Courier,Consolas,monospace; - font-size:11px; - padding: 10px; -} - -td.linenos pre { - padding: 5px 0px; - border: 0; - background-color: transparent; - color: #aaa; -} - -table.highlighttable { - margin-left: 0.5em; -} - -table.highlighttable td { - padding: 0 0.5em 0 0.5em; -} - -tt { - font-family:"Bitstream Vera Sans Mono",Monaco,"Lucida Console",Courier,Consolas,monospace; - -} - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1em; -} - -tt.descclassname { - background-color: transparent; -} - -tt.xref, a tt { - background-color: transparent; - font-weight: bold; -} - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - background-color: transparent; -} - -/* -- math display ---------------------------------------------------------- */ - -img.math { - vertical-align: middle; -} - -div.body div.math p { - text-align: center; -} - -span.eqno { - float: right; -} - -/* -- printout stylesheet --------------------------------------------------- */ - -@media print { - div.document, - div.documentwrapper, - div.bodywrapper { - margin: 0; - width: 100%; - } - - div.sphinxsidebar, - div.related, - div.footer, - #top-link { - display: none; - } -} - -body { - font-family:'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; -} - -dl.class dt { - padding: 3px; -/* border-top: 2px solid #999;*/ -} - -em.property { - font-style: normal; -} - -dl.class dd p { - margin-top: 6px; -} - -dl.class dd dl.exception dt { - padding: 3px; - background-color: #FFD6D6; - border-top: none; -} - -dl.class dd dl.method dt { - padding: 3px; - background-color: #e9e9e9; - border-top: none; - -} - -dl.function dt { - padding: 3px; - border-top: 2px solid #999; -} - -ul { -list-style-image:none; -list-style-position:outside; -list-style-type:square; -margin:0 0 0 30px; -padding:0 0 12px 6px; -} -#docstitle { - height: 36px; - background-image: url(header_sm_mid.png); - left: 0; - top: 0; - position: absolute; - width: 100%; -} -#docstitle p { - padding:7px 0 0 45px; - margin: 0; - color: white; - text-shadow:0 1px 0 #787878; - background: transparent url(documentation.png) no-repeat scroll 10px 3px; - height: 36px; - font-size: 15px; -} -#header { -height:45px; -left:0; -position:absolute; -right:0; -top:36px; -z-index:900; -} - -#header h1 { -font-size:10pt; -margin:0; -padding:5px 0 0 10px; -text-shadow:0 1px 0 #D5D5D5; -white-space:nowrap; -} - -h1 { --x-system-font:none; -color:#000000; -font-family:'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; -font-size:30px; -font-size-adjust:none; -font-stretch:normal; -font-style:normal; -font-variant:normal; -font-weight:bold; -line-height:normal; -margin-bottom:25px; -margin-top:1em; -} - -.footer { -border-top:1px solid #DDDDDD; -clear:both; -padding-top:9px; -width:100%; -font-size:10px; -} - -p { --x-system-font:none; -font-family:'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; -font-size:12px; -font-size-adjust:none; -font-stretch:normal; -font-style:normal; -font-variant:normal; -font-weight:normal; -line-height:normal; -margin-bottom:10px; -margin-top:0; -} - -h2 { -border-bottom:1px solid #919699; -color:#000000; -font-size:24px; -margin-top:2.5em; -padding-bottom:2px; -} - -a:link:hover { -color:#093D92; -text-decoration:underline; -} - -a:link { -color:#093D92; -text-decoration:none; -} - - -ol { -list-style-position:outside; -list-style-type:decimal; -margin:0 0 0 30px; -padding:0 0 12px 6px; -} -li { -margin-top:7px; -font-family:'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; -font-size:12px; -font-size-adjust:none; -font-stretch:normal; -font-style:normal; -font-variant:normal; -font-weight:normal; -line-height:normal; -} -li p { -margin-top:8px; -} \ No newline at end of file Binary files /tmp/zapgSFQ0Mb/python-mock-0.7.2/docs/_static/breadcrumb_background.png and /tmp/5MWMjkKy0R/python-mock-1.0.1/docs/_static/breadcrumb_background.png differ Binary files /tmp/zapgSFQ0Mb/python-mock-0.7.2/docs/_static/documentation.png and /tmp/5MWMjkKy0R/python-mock-1.0.1/docs/_static/documentation.png differ Binary files /tmp/zapgSFQ0Mb/python-mock-0.7.2/docs/_static/header_sm_mid.png and /tmp/5MWMjkKy0R/python-mock-1.0.1/docs/_static/header_sm_mid.png differ diff -Nru python-mock-0.7.2/docs/_static/mobile.css python-mock-1.0.1/docs/_static/mobile.css --- python-mock-0.7.2/docs/_static/mobile.css 2011-03-21 21:24:58.000000000 +0000 +++ python-mock-1.0.1/docs/_static/mobile.css 1970-01-01 00:00:00.000000000 +0000 @@ -1,17 +0,0 @@ -/* - * CSS adjustments (overrides) for mobile browsers that cannot handle - * fix-positioned div's very well. - * This makes long pages scrollable on mobile browsers. - */ - -#breadcrumbs { - display: none !important; -} - -.document { - bottom: inherit !important; -} - -#sphinxsidebar { - bottom: inherit !important; -} Binary files /tmp/zapgSFQ0Mb/python-mock-0.7.2/docs/_static/scrn1.png and /tmp/5MWMjkKy0R/python-mock-1.0.1/docs/_static/scrn1.png differ Binary files /tmp/zapgSFQ0Mb/python-mock-0.7.2/docs/_static/scrn2.png and /tmp/5MWMjkKy0R/python-mock-1.0.1/docs/_static/scrn2.png differ Binary files /tmp/zapgSFQ0Mb/python-mock-0.7.2/docs/_static/searchfield_leftcap.png and /tmp/5MWMjkKy0R/python-mock-1.0.1/docs/_static/searchfield_leftcap.png differ Binary files /tmp/zapgSFQ0Mb/python-mock-0.7.2/docs/_static/searchfield_repeat.png and /tmp/5MWMjkKy0R/python-mock-1.0.1/docs/_static/searchfield_repeat.png differ Binary files /tmp/zapgSFQ0Mb/python-mock-0.7.2/docs/_static/searchfield_rightcap.png and /tmp/5MWMjkKy0R/python-mock-1.0.1/docs/_static/searchfield_rightcap.png differ Binary files /tmp/zapgSFQ0Mb/python-mock-0.7.2/docs/_static/title_background.png and /tmp/5MWMjkKy0R/python-mock-1.0.1/docs/_static/title_background.png differ Binary files /tmp/zapgSFQ0Mb/python-mock-0.7.2/docs/_static/triangle_closed.png and /tmp/5MWMjkKy0R/python-mock-1.0.1/docs/_static/triangle_closed.png differ Binary files /tmp/zapgSFQ0Mb/python-mock-0.7.2/docs/_static/triangle_left.png and /tmp/5MWMjkKy0R/python-mock-1.0.1/docs/_static/triangle_left.png differ Binary files /tmp/zapgSFQ0Mb/python-mock-0.7.2/docs/_static/triangle_open.png and /tmp/5MWMjkKy0R/python-mock-1.0.1/docs/_static/triangle_open.png differ diff -Nru python-mock-0.7.2/docs/_templates/layout.html python-mock-1.0.1/docs/_templates/layout.html --- python-mock-0.7.2/docs/_templates/layout.html 2011-03-21 21:24:58.000000000 +0000 +++ python-mock-1.0.1/docs/_templates/layout.html 1970-01-01 00:00:00.000000000 +0000 @@ -1,146 +0,0 @@ -{% extends "basic/layout.html" %} -{%- block doctype -%} - -{%- endblock %} -{%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %} -{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %} -{%- block linktags %} - {%- if hasdoc('about') %} - - {%- endif %} - {%- if hasdoc('genindex') %} - - {%- endif %} - {%- if hasdoc('search') %} - - {%- endif %} - {%- if hasdoc('copyright') %} - - {%- endif %} - - {%- if parents %} - - {%- endif %} - {%- if next %} - - {%- endif %} - {%- if prev %} - - {%- endif %} - -{%- endblock %} -{%- block extrahead %} {% endblock %} -{%- block header %}{% endblock %} -{%- block relbar1 %} -
-

{{docstitle}}

-
- -{% endblock %} - -{%- block sidebar1 %} -{%- if not embedded %}{% if not theme_nosidebar|tobool %} -
-
- {%- block sidebarlogo %} - {%- if logo %} - - {%- endif %} - {%- endblock %} - {%- block sidebartoc %} - - {{ toctree() }} - {%- endblock %} - {%- block sidebarrel %} - {%- endblock %} - {%- block sidebarsourcelink %} - {%- if show_source and has_source and sourcename %} -

{{ _('This Page') }}

- - {%- endif %} - {%- endblock %} - {%- if customsidebar %} - {% include customsidebar %} - {%- endif %} - {%- block sidebarsearch %} - {%- if pagename != "search" %} - - - {%- endif %} - {%- endblock %} -
-
-{%- endif %}{% endif %} - -{% endblock %} -{%- block document %} -
- {%- if not embedded %}{% if not theme_nosidebar|tobool %} -
- {%- endif %}{% endif %} -
- {% block body %} {% endblock %} -
- {%- if not embedded %}{% if not theme_nosidebar|tobool %} -
- {%- endif %}{% endif %} -
-
-

{%- if hasdoc('copyright') %} - {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} -{%- else %} - {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} -{%- endif %} -{%- if last_updated %} - {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} -{%- endif %} -{%- if show_sphinx %} - {% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.{% endtrans %} -{%- endif %} -Theme: ADCtheme -

-
-{%- endblock %} -{%- block sidebar2 %}{% endblock %} -{%- block relbar2 %}{% endblock %} -{%- block footer %} - - -{%- endblock %} diff -Nru python-mock-0.7.2/html/changelog.html python-mock-1.0.1/html/changelog.html --- python-mock-0.7.2/html/changelog.html 2011-05-30 19:56:00.000000000 +0000 +++ python-mock-1.0.1/html/changelog.html 2012-11-05 21:36:08.000000000 +0000 @@ -2,17 +2,20 @@ + - TODO and Limitations — Mock v0.7.2 documentation - + CHANGELOG — Mock 1.0.1 documentation + + + - - - + + -
-

Mock v0.7.2 documentation

+
+

Navigation

+ +
+ +
+
+
+
+ +
+

CHANGELOG¶

+
+

2012/11/5 Version 1.0.1¶

+
    +
  • Functions decorated with patch variants have a __wrapped__ attribute +pointing to the original function. This brings compatibility with the +default behaviour in Python 3.3 (due to a new feature in functools.wraps).
    • +
+

Note that due to changes in tox, mock is no longer tested with Python 2.4. +The compatibility code has not been removed so it probably still works, but +tests are no longer run.

+
+
+

2012/10/07 Version 1.0.0¶

+

No changes since 1.0.0 beta 1. This version has feature parity with +unittest.mock +in Python 3.3.

+

Full list of changes since 0.8:

+
    +
  • mocksignature, along with the mocksignature argument to patch, removed
    • +
  • Support for deleting attributes (accessing deleted attributes will raise an +AttributeError)
    • +
  • Added the mock_open helper function for mocking the builtin open
    • +
  • __class__ is assignable, so a mock can pass an isinstance check without +requiring a spec
    • +
  • Addition of PropertyMock, for mocking properties
    • +
  • MagicMocks made unorderable by default (in Python 3). The comparison +methods (other than equality and inequality) now return NotImplemented
    • +
  • Propagate traceback info to support subclassing of _patch by other +libraries
    • +
  • create_autospec works with attributes present in results of dir that +can’t be fetched from the object’s class. Contributed by Konstantine Rybnikov
    • +
  • Any exceptions in an iterable side_effect will be raised instead of +returned
    • +
  • In Python 3, create_autospec now supports keyword only arguments
    • +
  • Added patch.stopall method to stop all active patches created by start
    • +
  • BUGFIX: calling MagicMock.reset_mock wouldn’t reset magic method mocks
    • +
  • BUGFIX: calling reset_mock on a MagicMock created with autospec could +raise an exception
    • +
  • BUGFIX: passing multiple spec arguments to patchers (spec , spec_set and +autospec) had unpredictable results, now it is an error
    • +
  • BUGFIX: using spec=True and create=True as arguments to patchers could +result in using DEFAULT as the spec. Now it is an error instead
    • +
  • BUGFIX: using spec or autospec arguments to patchers, along with +spec_set=True did not work correctly
    • +
  • BUGFIX: using an object that evaluates to False as a spec could be ignored
    • +
  • BUGFIX: a list as the spec argument to a patcher would always result in a +non-callable mock. Now if __call__ is in the spec the mock is callable
    • +
-