pytest-mock

This plugin installs a mocker fixture which is a thin-wrapper around the patching API provided by the excellent mock package, but with the benefit of not having to worry about undoing patches at the end of a test:

def test_unix_fs(mocker):
    mocker.patch('os.remove')
    UnixFS.rm('file')
    os.remove.assert_called_once_with('file')

Usage

The mocker fixture has the same API as mock.patch, supporting the same arguments:

def test_foo(mocker):
    # all valid calls
    mocker.patch('os.remove')
    mocker.patch.object(os, 'listdir', autospec=True)
    mocked_isfile = mocker.patch('os.path.isfile')

The supported methods are:

• mocker.patch: see http://www.voidspace.org.uk/python/mock/patch.html#patch.
• mocker.patch.object: see http://www.voidspace.org.uk/python/mock/patch.html#patch-object.
• mocker.patch.multiple: see http://www.voidspace.org.uk/python/mock/patch.html#patch-multiple.
• mocker.patch.dict: see http://www.voidspace.org.uk/python/mock/patch.html#patch-dict.
• mocker.stopall(): stops all active patches up to this point.
• mocker.resetall(): calls reset_mock() in all mocked objects up to this point. New in version 0.9

Some objects from the mock module are accessible directly from mocker so you don't have to import it:

• Mock; New in version 0.5
• MagicMock; New in version 0.5
• PropertyMock; New in version 0.11

Note

Although mocker's API is intentionally the same as mock.patch's, its uses as context managers and function decorators are not supported. The purpose of this plugin is to make the use of context managers and function decorators for mocking unnecessary. Indeed, trying to use the functionality in mocker in this manner can lead to non-intuitive errors:

def test_context_manager(mocker):
    a = A()
    with mocker.patch.object(a, 'doIt', return_value=True, autospec=True):
        assert a.doIt() == True

================================== FAILURES ===================================
____________________________ test_context_manager _____________________________
in test_context_manager
    with mocker.patch.object(a, 'doIt', return_value=True, autospec=True):
E   AttributeError: __exit__

Spy

New in version 0.6

The spy acts exactly like the original method in all cases, except it allows use of mock features with it, like retrieving call count.

From version 0.7 onward it also works for class and static methods. Originally it was only safe to use with instance methods.

def test_spy(mocker):
    class Foo(object):
        def bar(self):
            return 42

    foo = Foo()
    mocker.spy(foo, 'bar')
    assert foo.bar() == 42
    assert foo.bar.call_count == 1

Stub

New in version 0.6

The stub is a mock object that accepts any arguments and is useful to test callbacks, for instance.

def test_stub(mocker):
    def foo(on_something):
        on_something('foo', 'bar')

    stub = mocker.stub()

    foo(stub)
    stub.assert_called_once_with('foo', 'bar')

Improved reporting of mock call assertion errors

New in version 0.10

This plugin monkeypatches the mock library to improve pytest output for failures of mock call assertions like Mock.assert_called_with(). This is probably safe, but if you encounter any problems this feature can be disabled in your pytest.ini file:

[pytest]
mock_traceback_monkeypatch = false

Note

Prior to version 0.4.0, the mocker fixture was named mock. This was changed because naming the fixture mock conflicts with the actual mock module, which made using it awkward when access to both the module and the plugin were required within a test.

The old fixture mock still works, but its use is discouraged and will be removed in version 1.0.

Requirements

• Python 2.6+, Python 3.4+
• pytest
• mock (for Python 2)

Install

Install using pip:

$ pip install pytest-mock

Changelog

Please consult the changelog page.

Why bother with a plugin?

There are a number of different patch usages in the standard mock API, but IMHO they don't scale very well when you have more than one or two patches to apply.

It may lead to an excessive nesting of with statements, breaking the flow of the test:

import mock

def test_unix_fs():
    with mock.patch('os.remove'):
        UnixFS.rm('file')
        os.remove.assert_called_once_with('file')

        with mock.patch('os.listdir'):
            assert UnixFS.ls('dir') == expected
            # ...

    with mock.patch('shutil.copy'):
        UnixFS.cp('src', 'dst')
        # ...

One can use patch as a decorator to improve the flow of the test:

@mock.patch('os.remove')
@mock.patch('os.listdir')
@mock.patch('shutil.copy')
def test_unix_fs(mocked_copy, mocked_listdir, mocked_remove):
    UnixFS.rm('file')
    os.remove.assert_called_once_with('file')

    assert UnixFS.ls('dir') == expected
    # ...

    UnixFS.cp('src', 'dst')
    # ...

But this poses a few disadvantages:

• test functions must receive the mock objects as parameter, even if you don't plan to access them directly; also, order depends on the order of the decorated patch functions;
• receiving the mocks as parameters doesn't mix nicely with pytest's approach of naming fixtures as parameters, or pytest.mark.parametrize;
• you can't easily undo the mocking during the test execution;