Mock - Mocking and Testing Library

Date:Sep 29, 2018
Homepage:Mock Homepage
Download:Mock on PyPI
Documentation:Python Docs
License:BSD License
Support:Mailing list (
Issue tracker:Github Issues
Last sync:cb6aab1248c4aec4dd578bea717854505a6fb55d


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. However, if you are writing code that runs on multiple versions of Python the mock package is better, as you get the newest features from the latest release of Python available for all Pythons.

The mock package contains a rolling backport of the standard library mock code compatible with Python 2.6 and up, and 3.3 and up. Python 3.2 is supported by mock 1.3.0 and below - with pip no longer supporting 3.2, we cannot test against that version anymore.

Please see the standard library documentation for usage details.


The current version is 2.0.0. Mock is stable and widely used.

You can checkout the latest development version from Github repository with the following command:

git clone

You can install mock with pip:

pip install -U mock

Alternatively you can download the mock distribution from PyPI and after unpacking run:

python install

Bug Reports

Mock uses unittest2 for its own Issues with the backport process, such as compatibility with a particular Python, should be reported to the bug tracker. Feature requests and issues with Mock functionality should be reported to the Python bug tracker.

Python Changes

Python NEWS entries from cPython:


  • Issue #26323: Add Mock.assert_called() and Mock.assert_called_once() methods to unittest.mock. Patch written by Amit Saha.
  • Issue #22138: Fix mock.patch behavior when patching descriptors. Restore original values after patching. Patch contributed by Sean McCully.
  • Issue #24857: Comparing call_args to a long sequence now correctly returns a boolean result instead of raising an exception. Patch by A Kaptur.
  • Issue #23004: mock_open() now reads binary data correctly when the type of read_data is bytes. Initial patch by Aaron Hill.
  • Issue #21750: mock_open.read_data can now be read from each instance, as it could in Python 3.3.
  • Issue #18622: unittest.mock.mock_open().reset_mock would recurse infinitely. Patch from Nicola Palumbo and Laurent De Buyst.
  • Issue #23661: unittest.mock side_effects can now be exceptions again. This was a regression vs Python 3.4. Patch from Ignacio Rossi
  • Issue #23310: Fix MagicMock’s initializer to work with __methods__, just like configure_mock(). Patch by Kasia Jachim.
  • Issue #23568: Add rdivmod support to MagicMock() objects. Patch by Håkan Lövdahl.
  • Issue #23581: Add matmul support to MagicMock. Patch by Håkan Lövdahl.
  • Issue #23326: Removed __ne__ implementations. Since fixing default __ne__ implementation in issue #21408 they are redundant. * NOT BACKPORTED *
  • Issue #21270: We now override tuple methods in objects so that they can be used as normal call attributes.
  • Issue #21256: Printout of keyword args should be in deterministic order in a mock function call. This will help to write better doctests.
  • Issue #21262: New method assert_not_called for Mock. It raises AssertionError if the mock has been called.
  • Issue #21238: New keyword argument unsafe to Mock. It raises AttributeError incase of an attribute startswith assert or assret.
  • Issue #21239: patch.stopall() didn’t work deterministically when the same name was patched more than once.
  • Issue #21222: Passing name keyword argument to mock.create_autospec now works.
  • Issue #17826: setting an iterable side_effect on a mock function created by create_autospec now works. Patch by Kushal Das.
  • Issue #17826: setting an iterable side_effect on a mock function created by create_autospec now works. Patch by Kushal Das.
  • Issue #20968: unittest.mock.MagicMock now supports division. Patch by Johannes Baiter.
  • Issue #20189: unittest.mock now no longer assumes that any object for which it could get an inspect.Signature is a callable written in Python. Fix courtesy of Michael Foord.
  • Issue #17467: add readline and readlines support to mock_open in unittest.mock.
  • Issue #17015: When it has a spec, a Mock object now inspects its signature when matching calls, so that arguments can be matched positionally or by name.
  • Issue #15323: improve failure message of Mock.assert_called_once_with
  • Issue #14857: fix regression in references to PEP 3135 implicit __class__ closure variable (Reopens issue #12370)
  • Issue #14295: Add unittest.mock

Older Versions of Python

Version 1.0.1 is the last version compatible with Python < 2.6.

Maintainer Notes

Checkout from git (see Installing) and submit pull requests.

Committers can just push as desired: since all semantic development takes place in cPython, the backport process is as lightweight as we can make it.

mock is CI tested using Travis-CI on Python versions 2.6, 2.7, 3.3, 3.4, 3.5, nightly Python 3 builds, pypy, pypy3. Jython support is desired, if someone could contribute a patch to .travis.yml to support it that would be excellent.

NB: please use semver. Bump the major component on API breaks, minor on all non-bugfix changes, patch on bugfix only changes.

  1. tag -s, push –tags origin master
  2. sdist bdist_wheel upload -s

isinstance checks in cPython to type need to check ClassTypes. Code calling obj.isidentifier needs to change to _isidentifier(obj).

  1. Patch your git am with my patch.

  2. Install the applypatch-transform hook from tools/ to your .git hooks dir.

  3. Configure a pre-applypatch hook to test at least all the cPython versions we support on each patch that is applied. I use containers, and a sample script is in tools/pre-applypatch.

  4. Pull down the cPython git mirror:

  5. Export the new revisions since the Last sync at the top of this document:

    rm migrate-export
    git log --pretty="format:%H " $revs.. -- Lib/unittest/ \
      Lib/unittest/test/testmock/ > migrate-revs
    tac migrate-revs > migrate-sorted-revs
    for rev in $(< migrate-sorted-revs); do
          git format-patch -1 $rev -k --stdout >> migrate-export;
    echo NEW SYNC POINT: $(git rev-parse HEAD)
  6. Import into mock:

    git am -k --reject $path-to-cpython/migrate-export

    This will transform the patches automatically. Currently it will error on every NEWS change as I haven’t gotten around to making those patches automatic. Fixup any errors that occur. When the patch is ready, do a git add -u to update the index and then git am --continue to move onto the next patch. If the patch is inappropriate e.g. the patch removing __ne__ which would break older pythons, then either do git reset --hard; git am --skip to discard any partially applied changes and skip over it, or, if it has a NEWS entry thats worth preserving, edit it down to just that, with a note such as we have for the __ne__ patch, and continue on from there.

    The goal is that every patch work at all times.

  7. After the import is complete, update this document with the new sync point.

  8. Push to a personal branch and propose a PR to the main repo. This will make Travis-CI test it. If it works, push to the main repo.