The Tor Browser / file revision

 =========================

  Mock Library Comparison

 =========================

 .. testsetup::

     def assertEqual(a, b):

         assert a == b, ("%r != %r" % (a, b))

     def assertRaises(Exc, func):

         try:

             func()

         except Exc:

             return

         assert False, ("%s not raised" % Exc)

     sys.modules['somemodule'] = somemodule = mock.Mock(name='somemodule')

     class SomeException(Exception):

         some_method = method1 = method2 = None

     some_other_object = SomeObject = SomeException

 A side-by-side comparison of how to accomplish some basic tasks with mock and

 some other popular Python mocking libraries and frameworks.

 These are:

 * `flexmock <http://pypi.python.org/pypi/flexmock>`_

 * `mox <http://pypi.python.org/pypi/mox>`_

 * `Mocker <http://niemeyer.net/mocker>`_

 * `dingus <http://pypi.python.org/pypi/dingus>`_

 * `fudge <http://pypi.python.org/pypi/fudge>`_

 Popular python mocking frameworks not yet represented here include

 `MiniMock <http://pypi.python.org/pypi/MiniMock>`_.

 `pMock <http://pmock.sourceforge.net/>`_ (last release 2004 and doesn't import

 in recent versions of Python) and

 `python-mock <http://python-mock.sourceforge.net/>`_ (last release 2005) are

 intentionally omitted.

 .. note::

     A more up to date, and tested for all mock libraries (only the mock

     examples on this page can be executed as doctests) version of this

     comparison is maintained by Gary Bernhardt:

     * `Python Mock Library Comparison

       <http://garybernhardt.github.com/python-mock-comparison/>`_

 This comparison is by no means complete, and also may not be fully idiomatic

 for all the libraries represented. *Please* contribute corrections, missing

 comparisons, or comparisons for additional libraries to the `mock issue

 tracker <https://code.google.com/p/mock/issues/list>`_.

 This comparison page was originally created by the `Mox project

 <https://code.google.com/p/pymox/wiki/MoxComparison>`_ and then extended for

 `flexmock and mock <http://has207.github.com/flexmock/compare.html>`_ by

 Herman Sheremetyev. Dingus examples written by `Gary Bernhadt

 <http://garybernhardt.github.com/python-mock-comparison/>`_. fudge examples

 provided by `Kumar McMillan <http://farmdev.com/>`_.

 .. note::

     The examples tasks here were originally created by Mox which is a mocking

     *framework* rather than a library like mock. The tasks shown naturally

     exemplify tasks that frameworks are good at and not the ones they make

     harder. In particular you can take a `Mock` or `MagicMock` object and use

     it in any way you want with no up-front configuration. The same is also

     true for Dingus.

     The examples for mock here assume version 0.7.0.

 Simple fake object

 ~~~~~~~~~~~~~~~~~~

 .. doctest::

     >>> # mock

     >>> my_mock = mock.Mock()

     >>> my_mock.some_method.return_value = "calculated value"

     >>> my_mock.some_attribute = "value"

     >>> assertEqual("calculated value", my_mock.some_method())

     >>> assertEqual("value", my_mock.some_attribute)

 ::

     # Flexmock

     mock = flexmock(some_method=lambda: "calculated value", some_attribute="value")

     assertEqual("calculated value", mock.some_method())

     assertEqual("value", mock.some_attribute)

     # Mox

     mock = mox.MockAnything()

     mock.some_method().AndReturn("calculated value")

     mock.some_attribute = "value"

     mox.Replay(mock)

     assertEqual("calculated value", mock.some_method())

     assertEqual("value", mock.some_attribute)

     # Mocker

     mock = mocker.mock()

     mock.some_method()

     mocker.result("calculated value")

     mocker.replay()

     mock.some_attribute = "value"

     assertEqual("calculated value", mock.some_method())

     assertEqual("value", mock.some_attribute)

 ::

     >>> # Dingus

     >>> my_dingus = dingus.Dingus(some_attribute="value",

     ...                           some_method__returns="calculated value")

     >>> assertEqual("calculated value", my_dingus.some_method())

     >>> assertEqual("value", my_dingus.some_attribute)

 ::

     >>> # fudge

     >>> my_fake = (fudge.Fake()

     ...            .provides('some_method')

     ...            .returns("calculated value")

     ...            .has_attr(some_attribute="value"))

     ...

     >>> assertEqual("calculated value", my_fake.some_method())

     >>> assertEqual("value", my_fake.some_attribute)

 Simple mock

 ~~~~~~~~~~~

 .. doctest::

     >>> # mock

     >>> my_mock = mock.Mock()

     >>> my_mock.some_method.return_value = "value"

     >>> assertEqual("value", my_mock.some_method())

     >>> my_mock.some_method.assert_called_once_with()

 ::

     # Flexmock

     mock = flexmock()

     mock.should_receive("some_method").and_return("value").once

     assertEqual("value", mock.some_method())

     # Mox

     mock = mox.MockAnything()

     mock.some_method().AndReturn("value")

     mox.Replay(mock)

     assertEqual("value", mock.some_method())

     mox.Verify(mock)

     # Mocker

     mock = mocker.mock()

     mock.some_method()

     mocker.result("value")

     mocker.replay()

     assertEqual("value", mock.some_method())

     mocker.verify()

 ::

     >>> # Dingus

     >>> my_dingus = dingus.Dingus(some_method__returns="value")

     >>> assertEqual("value", my_dingus.some_method())

     >>> assert my_dingus.some_method.calls().once()

 ::

     >>> # fudge

     >>> @fudge.test

     ... def test():

     ...     my_fake = (fudge.Fake()

     ...                .expects('some_method')

     ...                .returns("value")

     ...                .times_called(1))

     ...

     >>> test()

     Traceback (most recent call last):

     ...

     AssertionError: fake:my_fake.some_method() was not called

 Creating partial mocks

 ~~~~~~~~~~~~~~~~~~~~~~

 .. doctest::

     >>> # mock

     >>> SomeObject.some_method = mock.Mock(return_value='value')

     >>> assertEqual("value", SomeObject.some_method())

 ::

     # Flexmock

     flexmock(SomeObject).should_receive("some_method").and_return('value')

     assertEqual("value", mock.some_method())

     # Mox

     mock = mox.MockObject(SomeObject)

     mock.some_method().AndReturn("value")

     mox.Replay(mock)

     assertEqual("value", mock.some_method())

     mox.Verify(mock)

     # Mocker

     mock = mocker.mock(SomeObject)

     mock.Get()

     mocker.result("value")

     mocker.replay()

     assertEqual("value", mock.some_method())

     mocker.verify()

 ::

     >>> # Dingus

     >>> object = SomeObject

     >>> object.some_method = dingus.Dingus(return_value="value")

     >>> assertEqual("value", object.some_method())

 ::

     >>> # fudge

     >>> fake = fudge.Fake().is_callable().returns("<fudge-value>")

     >>> with fudge.patched_context(SomeObject, 'some_method', fake):

     ...     s = SomeObject()

     ...     assertEqual("<fudge-value>", s.some_method())

     ...

 Ensure calls are made in specific order

 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .. doctest::

     >>> # mock

     >>> my_mock = mock.Mock(spec=SomeObject)

     >>> my_mock.method1()

     <Mock name='mock.method1()' id='...'>

     >>> my_mock.method2()

     <Mock name='mock.method2()' id='...'>

     >>> assertEqual(my_mock.mock_calls, [call.method1(), call.method2()])

 ::

     # Flexmock

     mock = flexmock(SomeObject)

     mock.should_receive('method1').once.ordered.and_return('first thing')

     mock.should_receive('method2').once.ordered.and_return('second thing')

     # Mox

     mock = mox.MockObject(SomeObject)

     mock.method1().AndReturn('first thing')

     mock.method2().AndReturn('second thing')

     mox.Replay(mock)

     mox.Verify(mock)

     # Mocker

     mock = mocker.mock()

     with mocker.order():

         mock.method1()

         mocker.result('first thing')

         mock.method2()

         mocker.result('second thing')

         mocker.replay()

         mocker.verify()

 ::

     >>> # Dingus

     >>> my_dingus = dingus.Dingus()

     >>> my_dingus.method1()

     <Dingus ...>

     >>> my_dingus.method2()

     <Dingus ...>

     >>> assertEqual(['method1', 'method2'], [call.name for call in my_dingus.calls])

 ::

     >>> # fudge

     >>> @fudge.test

     ... def test():

     ...     my_fake = (fudge.Fake()

     ...                .remember_order()

     ...                .expects('method1')

     ...                .expects('method2'))

     ...     my_fake.method2()

     ...     my_fake.method1()

     ...

     >>> test()

     Traceback (most recent call last):

     ...

     AssertionError: Call #1 was fake:my_fake.method2(); Expected: #1 fake:my_fake.method1(), #2 fake:my_fake.method2(), end

 Raising exceptions

 ~~~~~~~~~~~~~~~~~~

 .. doctest::

     >>> # mock

     >>> my_mock = mock.Mock()

     >>> my_mock.some_method.side_effect = SomeException("message")

     >>> assertRaises(SomeException, my_mock.some_method)

 ::

     # Flexmock

     mock = flexmock()

     mock.should_receive("some_method").and_raise(SomeException("message"))

     assertRaises(SomeException, mock.some_method)

     # Mox

     mock = mox.MockAnything()

     mock.some_method().AndRaise(SomeException("message"))

     mox.Replay(mock)

     assertRaises(SomeException, mock.some_method)

     mox.Verify(mock)

     # Mocker

     mock = mocker.mock()

     mock.some_method()

     mocker.throw(SomeException("message"))

     mocker.replay()

     assertRaises(SomeException, mock.some_method)

     mocker.verify()

 ::

     >>> # Dingus

     >>> my_dingus = dingus.Dingus()

     >>> my_dingus.some_method = dingus.exception_raiser(SomeException)

     >>> assertRaises(SomeException, my_dingus.some_method)

 ::

     >>> # fudge

     >>> my_fake = (fudge.Fake()

     ...            .is_callable()

     ...            .raises(SomeException("message")))

     ...

     >>> my_fake()

     Traceback (most recent call last):

     ...

     SomeException: message

 Override new instances of a class

 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .. doctest::

     >>> # mock

     >>> with mock.patch('somemodule.Someclass') as MockClass:

     ...     MockClass.return_value = some_other_object

     ...     assertEqual(some_other_object, somemodule.Someclass())

     ...

 ::

     # Flexmock

     flexmock(some_module.SomeClass, new_instances=some_other_object)

     assertEqual(some_other_object, some_module.SomeClass())

     # Mox

     # (you will probably have mox.Mox() available as self.mox in a real test)

     mox.Mox().StubOutWithMock(some_module, 'SomeClass', use_mock_anything=True)

     some_module.SomeClass().AndReturn(some_other_object)

     mox.ReplayAll()

     assertEqual(some_other_object, some_module.SomeClass())

     # Mocker

     instance = mocker.mock()

     klass = mocker.replace(SomeClass, spec=None)

     klass('expected', 'args')

     mocker.result(instance)

 ::

     >>> # Dingus

     >>> MockClass = dingus.Dingus(return_value=some_other_object)

     >>> with dingus.patch('somemodule.SomeClass', MockClass):

     ...     assertEqual(some_other_object, somemodule.SomeClass())

     ...

 ::

     >>> # fudge

     >>> @fudge.patch('somemodule.SomeClass')

     ... def test(FakeClass):

     ...     FakeClass.is_callable().returns(some_other_object)

     ...     assertEqual(some_other_object, somemodule.SomeClass())

     ...

     >>> test()

 Call the same method multiple times

 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .. note::

     You don't need to do *any* configuration to call `mock.Mock()` methods

     multiple times. Attributes like `call_count`, `call_args_list` and

     `method_calls` provide various different ways of making assertions about

     how the mock was used.

 .. doctest::

     >>> # mock

     >>> my_mock = mock.Mock()

     >>> my_mock.some_method()

     <Mock name='mock.some_method()' id='...'>

     >>> my_mock.some_method()

     <Mock name='mock.some_method()' id='...'>

     >>> assert my_mock.some_method.call_count >= 2

 ::

     # Flexmock # (verifies that the method gets called at least twice)

     flexmock(some_object).should_receive('some_method').at_least.twice

     # Mox

     # (does not support variable number of calls, so you need to create a new entry for each explicit call)

     mock = mox.MockObject(some_object)

     mock.some_method(mox.IgnoreArg(), mox.IgnoreArg())

     mock.some_method(mox.IgnoreArg(), mox.IgnoreArg())

     mox.Replay(mock)

     mox.Verify(mock)

     # Mocker

     # (TODO)

 ::

     >>> # Dingus

     >>> my_dingus = dingus.Dingus()

     >>> my_dingus.some_method()

     <Dingus ...>

     >>> my_dingus.some_method()

     <Dingus ...>

     >>> assert len(my_dingus.calls('some_method')) == 2

 ::

     >>> # fudge

     >>> @fudge.test

     ... def test():

     ...     my_fake = fudge.Fake().expects('some_method').times_called(2)

     ...     my_fake.some_method()

     ...

     >>> test()

     Traceback (most recent call last):

     ...

     AssertionError: fake:my_fake.some_method() was called 1 time(s). Expected 2.

 Mock chained methods

 ~~~~~~~~~~~~~~~~~~~~

 .. doctest::

     >>> # mock

     >>> my_mock = mock.Mock()

     >>> method3 = my_mock.method1.return_value.method2.return_value.method3

     >>> method3.return_value = 'some value'

     >>> assertEqual('some value', my_mock.method1().method2().method3(1, 2))

     >>> method3.assert_called_once_with(1, 2)

 ::

     # Flexmock

     # (intermediate method calls are automatically assigned to temporary fake objects

     # and can be called with any arguments)

     flexmock(some_object).should_receive(

         'method1.method2.method3'

     ).with_args(arg1, arg2).and_return('some value')

     assertEqual('some_value', some_object.method1().method2().method3(arg1, arg2))

 ::

     # Mox

     mock = mox.MockObject(some_object)

     mock2 = mox.MockAnything()

     mock3 = mox.MockAnything()

     mock.method1().AndReturn(mock1)

     mock2.method2().AndReturn(mock2)

     mock3.method3(arg1, arg2).AndReturn('some_value')

     self.mox.ReplayAll()

     assertEqual("some_value", some_object.method1().method2().method3(arg1, arg2))

     self.mox.VerifyAll()

     # Mocker

     # (TODO)

 ::

     >>> # Dingus

     >>> my_dingus = dingus.Dingus()

     >>> method3 = my_dingus.method1.return_value.method2.return_value.method3

     >>> method3.return_value = 'some value'

     >>> assertEqual('some value', my_dingus.method1().method2().method3(1, 2))

     >>> assert method3.calls('()', 1, 2).once()

 ::

     >>> # fudge

     >>> @fudge.test

     ... def test():

     ...     my_fake = fudge.Fake()

     ...     (my_fake

     ...      .expects('method1')

     ...      .returns_fake()

     ...      .expects('method2')

     ...      .returns_fake()

     ...      .expects('method3')

     ...      .with_args(1, 2)

     ...      .returns('some value'))

     ...     assertEqual('some value', my_fake.method1().method2().method3(1, 2))

     ...

     >>> test()

 Mocking a context manager

 ~~~~~~~~~~~~~~~~~~~~~~~~~

 Examples for mock, Dingus and fudge only (so far):

 .. doctest::

     >>> # mock

     >>> my_mock = mock.MagicMock()

     >>> with my_mock:

     ...     pass

     ...

     >>> my_mock.__enter__.assert_called_with()

     >>> my_mock.__exit__.assert_called_with(None, None, None)

 ::

     >>> # Dingus (nothing special here; all dinguses are "magic mocks")

     >>> my_dingus = dingus.Dingus()

     >>> with my_dingus:

     ...     pass

     ...

     >>> assert my_dingus.__enter__.calls()

     >>> assert my_dingus.__exit__.calls('()', None, None, None)

 ::

     >>> # fudge

     >>> my_fake = fudge.Fake().provides('__enter__').provides('__exit__')

     >>> with my_fake:

     ...     pass

     ...

 Mocking the builtin open used as a context manager

 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Example for mock only (so far):

 .. doctest::

     >>> # mock

     >>> my_mock = mock.MagicMock()

     >>> with mock.patch('__builtin__.open', my_mock):

     ...     manager = my_mock.return_value.__enter__.return_value

     ...     manager.read.return_value = 'some data'

     ...     with open('foo') as h:

     ...         data = h.read()

     ...

     >>> data

     'some data'

     >>> my_mock.assert_called_once_with('foo')

 *or*:

 .. doctest::

     >>> # mock

     >>> with mock.patch('__builtin__.open') as my_mock:

     ...     my_mock.return_value.__enter__ = lambda s: s

     ...     my_mock.return_value.__exit__ = mock.Mock()

     ...     my_mock.return_value.read.return_value = 'some data'

     ...     with open('foo') as h:

     ...         data = h.read()

     ...

     >>> data

     'some data'

     >>> my_mock.assert_called_once_with('foo')

 ::

     >>> # Dingus

     >>> my_dingus = dingus.Dingus()

     >>> with dingus.patch('__builtin__.open', my_dingus):

     ...     file_ = open.return_value.__enter__.return_value

     ...     file_.read.return_value = 'some data'

     ...     with open('foo') as h:

     ...         data = f.read()

     ...

     >>> data

     'some data'

     >>> assert my_dingus.calls('()', 'foo').once()

 ::

     >>> # fudge

     >>> from contextlib import contextmanager

     >>> from StringIO import StringIO

     >>> @contextmanager

     ... def fake_file(filename):

     ...     yield StringIO('sekrets')

     ...

     >>> with fudge.patch('__builtin__.open') as fake_open:

     ...     fake_open.is_callable().calls(fake_file)

     ...     with open('/etc/password') as f:

     ...         data = f.read()

     ...

     fake:__builtin__.open

     >>> data

     'sekrets'