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

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

The supported methods are:

Also, as a convenience, these names from the mock module are accessible directly from mocker:

It is also possible to use mocking functionality from fixtures of other scopes using the appropriate fixture:

  • class_mocker

  • module_mocker

  • package_mocker

  • session_mocker


The mocker.spy object acts exactly like the original method in all cases, except the spy also tracks function/method calls, return values and exceptions raised.

def test_spy_method(mocker):
    class Foo(object):
        def bar(self, v):
            return v * 2

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

    assert spy.spy_return == 42

def test_spy_function(mocker):
    # mymodule declares `myfunction` which just returns 42
    import mymodule

    spy = mocker.spy(mymodule, "myfunction")
    assert mymodule.myfunction() == 42
    assert spy.call_count == 1
    assert spy.spy_return == 42

The object returned by mocker.spy is a MagicMock object, so all standard checking functions are available (like assert_called_once_with or call_count in the examples above).

In addition, spy objects contain two extra attributes:

  • spy_return: contains the returned value of the spied function.

  • spy_exception: contain the last exception value raised by the spied function/method when it was last called, or None if no exception was raised.

Besides functions and normal methods, mocker.spy also works for class and static methods.

As of version 3.0.0, mocker.spy also works with async def functions.


In versions earlier than 2.0, the attributes were called return_value and side_effect respectively, but due to incompatibilities with unittest.mock they had to be renamed (see #175 for details).

As of version 3.10, spying can be also selectively stopped.

def test_with_unspy(mocker):
    class Foo:
        def bar(self):
            return 42

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

mocker.stop() can also be used by mocker.patch calls.


The stub is a mock object that accepts any arguments and is useful to test callbacks. It may receive an optional name that is shown in its repr, useful for debugging.

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

    stub = mocker.stub(name='on_something_stub')

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

See also

async_stub method, which actually the same as stub but makes async stub.