<commit_before>==========
 Examples
==========

.. testsetup::

    import os, sys, unittest
    if not os.getcwd() in sys.path:
        sys.path.append(os.getcwd())

    from mock import Mock, sentinel, patch

    class SomeClass(object):
        static_method = None
        class_method = None

    class Test(unittest.TestCase):
        def testSomething(self):
            pass
    self = Test('testSomething')


For comprehensive examples, see the unit tests included in the full source
distribution.


Mock Examples
=============

Mock Patching Methods
---------------------

``Mock`` is callable. If it is called then it sets a ``called`` attribute to
``True``.

This example tests that calling ``method`` results in a call to ``something``:

.. doctest::

    >>> from mock import Mock
    >>> class ProductionClass(object):
    ...     def method(self):
    ...         self.something()
    ...     def something(self):
    ...         pass
    ...
    >>> real = ProductionClass()
    >>> real.something = Mock()
    >>> real.method()
    >>> real.something.called
    True

If you want to catch the arguments to make assertions about them this
information, and more, is exposed:

.. 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.

If the mock has only been called once then you can use
:method:`Mock.assert_called_once_with`:

.. doctest::

    >>> real = ProductionClass()
    >>> real.something = Mock()
    >>> 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
:method:`Mock.assert_called_with`:

.. doctest::

    >>> mock = Mock(return_value=None)
    >>> mock(1, 2, 3)
    >>> mock.assert_called_with(1, 2, 3)


Mock for Method Calls on an Object
----------------------------------

::

    def test_closer_closes_something(self):
        real = ProductionClass()
        mock = Mock()

        real.closer(mock)

        self.assertTrue(mock.close.called, "closer didn't close something")

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 ``called`` will be ``False``.

As ``close`` is a mock object is has all the attributes from the previous
example.


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.

::

    def test_closer_closes_something(self):
        real = ProductionClass()
        mock = Mock(spec=['close'])

        real.closer(mock)

        self.assertTrue(mock.close.called, "closer didn't close something")


If ``closer`` calls any methods on ``mock`` *other* than close, then an
``AttributeError`` will be raised.


Tracking all Method 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
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.method()
    <mock.Mock object at 0x...>
    >>> mock.Property.method(10, x=53)
    <mock.Mock object at 0x...>
    >>> mock.method_calls
    [('method', (), {}), ('Property.method', (10,), {'x': 53})]
    >>>

If you make an assertion about ``method_calls`` and any unexpected methods
have been called, then the assertion will fail.


Setting Return Values and Attributes
------------------------------------

Setting the return values on a mock object is trivially easy:

.. doctest::

    >>> mock = Mock()
    >>> mock.return_value = 3
    >>> mock()
    3

Of course you can do the same for methods on the mock:

.. doctest::

    >>> mock = Mock()
    >>> mock.method.return_value = 3
    >>> mock.method()
    3

If you need an attribute setting on your mock, just do it:

.. doctest::

    >>> mock = Mock()
    >>> mock.x = 3
    >>> mock.x
    3

Sometimes you want to mock up a more complex situation, like for example
``mock.connection.cursor().execute("SELECT 1")``:


.. doctest::

    >>> mock = Mock()
    >>> cursor = mock.connection.cursor.return_value
    >>> cursor.execute.return_value = None
    >>>
    >>> mock.connection.cursor().execute("SELECT 1")
    >>> mock.method_calls
    [('connection.cursor', (), {})]
    >>> cursor.method_calls
    [('execute', ('SELECT 1',), {})]


Creating a Mock from an Existing Object
---------------------------------------

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
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 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
instantiate the class in those tests.

.. doctest::

    >>> mock = Mock(spec=SomeClass)
    >>>
    >>> mock.old_method()
    Traceback (most recent call last):
       ...
    AttributeError: object has no attribute 'old_method'


Patch Decorator Examples
========================

A common need in tests is to patch a class attribute or a module attribute,
for example patching a builtin or patching a class in a module to test that it
is instantiated. Modules and classes are effectively global, so patching on
them has to be undone after the test or the patch will persist into other
tests and cause hard to diagnose problems.

The ``patch`` and ``patch.object`` decorators provide a convenient way of
doing this.

``patch.object`` patches attributes on objects within the scope of a function
they decorate:

.. doctest::

    >>> mock = Mock()

    >>> @patch.object(SomeClass, 'class_method', mock)
    ... def test():
    ...     SomeClass.class_method()
    ...
    >>> test()

    >>> self.assertTrue(mock.called, "class_method not called")

The decorator is applied to a function (called ``test`` above). The patching
only applies inside the body of the function. You have to call the function
explicitly, this can be useful as the test function can take arguments and be
used to implement several tests, it can also return values.

They can be stacked to perform multiple simultaneous patches:

.. doctest::

    >>> mock1 = Mock()
    >>> mock2 = Mock()

    >>> @patch.object(SomeClass, 'class_method', mock1)
    ... @patch.object(SomeClass, 'static_method', mock2)
    ... def test():
    ...     SomeClass.class_method()
    ...     SomeClass.static_method()
    ...
    >>> test()

    >>> self.assertTrue(mock1.called, "class_method not called")
    >>> self.assertTrue(mock2.called, "static_method not called")

If you are patching a module (including ``__builtin__``) then use ``patch``
instead of ``patch.object``:

.. doctest::

    >>> mock = Mock()
    >>> mock.return_value = sentinel.Handle
    >>> @patch('__builtin__.open', mock)<commit_msg>Changing more examples to doctests<commit_after>==========
 Examples
==========

.. testsetup::

    import os, sys, unittest
    if not os.getcwd() in sys.path:
        sys.path.append(os.getcwd())

    from mock import Mock, sentinel, patch

    class SomeClass(object):
        static_method = None
        class_method = None


For comprehensive examples, see the unit tests included in the full source
distribution.


Mock Examples
=============

Mock Patching Methods
---------------------

``Mock`` is callable. If it is called then it sets a ``called`` attribute to
``True``.

This example tests that calling ``method`` results in a call to ``something``:

.. doctest::

    >>> from mock import Mock
    >>> class ProductionClass(object):
    ...     def method(self):
    ...         self.something()
    ...     def something(self):
    ...         pass
    ...
    >>> real = ProductionClass()
    >>> real.something = Mock()
    >>> real.method()
    >>> real.something.called
    True

If you want to catch the arguments to make assertions about them this
information, and more, is exposed:

.. 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.

If the mock has only been called once then you can use
:method:`Mock.assert_called_once_with`:

.. doctest::

    >>> real = ProductionClass()
    >>> real.something = Mock()
    >>> 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
:method:`Mock.assert_called_with`:

.. doctest::

    >>> mock = Mock(return_value=None)
    >>> mock(1, 2, 3)
    >>> mock.assert_called_with(1, 2, 3)


Mock for Method Calls on an Object
----------------------------------

.. doctest::

    >>> class ProductionClass(object):
    ...     def closer(self, something):
    ...         something.close()
    ...
    >>> 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 :method:`Mock.assert_called_with`
will raise a failure exception.

As ``close`` is a mock object is has all the attributes from the previous
example.


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.


Tracking all Method 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
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.method()
    <mock.Mock object at 0x...>
    >>> mock.Property.method(10, x=53)
    <mock.Mock object at 0x...>
    >>> mock.method_calls
    [('method', (), {}), ('Property.method', (10,), {'x': 53})]
    >>>

If you make an assertion about ``method_calls`` and any unexpected methods
have been called, then the assertion will fail.




Setting Return Values and Attributes
------------------------------------

Setting the return values on a mock object is trivially easy:

.. doctest::

    >>> mock = Mock()
    >>> mock.return_value = 3
    >>> mock()
    3

Of course you can do the same for methods on the mock:

.. doctest::

    >>> mock = Mock()
    >>> mock.method.return_value = 3
    >>> mock.method()
    3

If you need an attribute setting on your mock, just do it:

.. doctest::

    >>> mock = Mock()
    >>> mock.x = 3
    >>> mock.x
    3

Sometimes you want to mock up a more complex situation, like for example
``mock.connection.cursor().execute("SELECT 1")``:


.. doctest::

    >>> mock = Mock()
    >>> cursor = mock.connection.cursor.return_value
    >>> cursor.execute.return_value = None
    >>>
    >>> mock.connection.cursor().execute("SELECT 1")
    >>> mock.method_calls
    [('connection.cursor', (), {})]
    >>> cursor.method_calls
    [('execute', ('SELECT 1',), {})]


Creating a Mock from an Existing Object
---------------------------------------

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
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 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
instantiate the class in those tests.

.. doctest::

    >>> mock = Mock(spec=SomeClass)
    >>>
    >>> mock.old_method()
    Traceback (most recent call last):
       ...
    AttributeError: object has no attribute 'old_method'


Patch Decorator Examples
========================

A common need in tests is to patch a class attribute or a module attribute,
for example patching a builtin or patching a class in a module to test that it
is instantiated. Modules and classes are effectively global, so patching on
them has to be undone after the test or the patch will persist into other
tests and cause hard to diagnose problems.

The ``patch`` and ``patch.object`` decorators provide a convenient way of
doing this.

``patch.object`` patches attributes on objects within the scope of a function
they decorate:

.. doctest::

    >>> mock = Mock()

    >>> @patch.object(SomeClass, 'class_method', mock)
    ... def test():
    ...     SomeClass.class_method()
    ...
    >>> test()
    >>> assert mock.called

The decorator is applied to a function (called ``test`` above). The patching
only applies inside the body of the function. You have to call the function
explicitly, this can be useful as the test function can take arguments and be
used to implement several tests, it can also return values.

They can be stacked to perform multiple simultaneous patches:

.. doctest::

    >>> mock1 = Mock()
    >>> mock2 = Mock()

    >>> @patch.object(SomeClass, 'class_method', mock1)
    ... @patch.object(SomeClass, 'static_method', mock2)
    ... def test():
    ...     SomeClass.class_method('foo')
    ...     SomeClass.static_method('bar')
    ...
    >>> test()
    >>> mock1.assert_called_once_with('foo')
    >>> mock2.assert_called_once_with('bar')

If you are patching a module (including ``__builtin__``) then use ``patch``
instead of ``patch.object``:

.. doctest::

    >>> mock = Mock()
    >>> mock.return_value = sentinel.Handle
    >>> @patch('__builtin__.open', mock)
{'fraction_non_alphanumeric': 0.1389280245022971, 'fraction_numerical': 0.003920367534456355, 'mean_word_length': 2.995594713656388, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 376, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4180061', 'n_tokens_mistral': 4576, 'n_tokens_neox': 4375, 'n_words': 1877}