Metadata-Version: 1.1
Name: pytest-mock
Version: 0.11.0
Summary: Thin-wrapper around the mock package for easier use with py.test
Home-page: https://github.com/pytest-dev/pytest-mock/
Author: Bruno Oliveira
Author-email: nicoddemus@gmail.com
License: LGPL
Description: ===========
        pytest-mock
        ===========
        
        This plugin installs a ``mocker`` fixture which is a thin-wrapper around the patching API
        provided by the excellent `mock <http://pypi.python.org/pypi/mock>`_ package,
        but with the benefit of not having to worry about undoing patches at the end
        of a test:
        
        .. code-block:: python
        
         
            def test_unix_fs(mocker):
                mocker.patch('os.remove')
                UnixFS.rm('file')
                os.remove.assert_called_once_with('file')
                
        
        .. Using PNG badges because PyPI doesn't support SVG
        
        |python| |version| |downloads| |ci| |appveyor| |coverage|
        
        .. |version| image:: http://img.shields.io/pypi/v/pytest-mock.png
          :target: https://pypi.python.org/pypi/pytest-mock
          
        .. |downloads| image:: http://img.shields.io/pypi/dm/pytest-mock.png
          :target: https://pypi.python.org/pypi/pytest-mock
        
        .. |ci| image:: http://img.shields.io/travis/pytest-dev/pytest-mock.png
          :target: https://travis-ci.org/pytest-dev/pytest-mock
        
        .. |appveyor| image:: https://ci.appveyor.com/api/projects/status/pid1t7iuwhkm9eh6/branch/master?svg=true
          :target: https://ci.appveyor.com/project/pytestbot/pytest-mock
        
        .. |coverage| image:: http://img.shields.io/coveralls/pytest-dev/pytest-mock.png
          :target: https://coveralls.io/r/pytest-dev/pytest-mock
          
        .. |python| image:: https://img.shields.io/pypi/pyversions/pytest-mock.svg
          :target: https://pypi.python.org/pypi/pytest-mock/
        
        Usage
        =====
        
        The ``mocker`` fixture has the same API as
        `mock.patch <http://www.voidspace.org.uk/python/mock/patch.html#patch-decorators>`_, 
        supporting the same arguments:
        
        .. code-block:: python
        
            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 <https://docs.python.org/3/library/unittest.mock.html#unittest.mock.Mock>`_; *New in version 0.5*
        * `MagicMock <https://docs.python.org/3/library/unittest.mock.html#unittest.mock.MagicMock>`_; *New in version 0.5*
        * `PropertyMock <https://docs.python.org/3/library/unittest.mock.html#unittest.mock.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:
        
        .. code-block:: python
        
            def test_context_manager(mocker):
                a = A()
                with mocker.patch.object(a, 'doIt', return_value=True, autospec=True):
                    assert a.doIt() == True
        
        .. code-block:: console
        
            ================================== 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.
        
        .. code-block:: python
        
            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.
        
        .. code-block:: python
        
            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:
        
        .. code-block:: ini
        
            [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 <http://pip-installer.org/>`_:
        
        .. code-block:: console
            
            $ pip install pytest-mock
        
        Changelog
        =========
        
        Please consult the `changelog page`_.
        
        .. _changelog page: https://github.com/pytest-dev/pytest-mock/blob/master/CHANGELOG.rst
                
        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:
        
        .. code-block:: python
        
            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:
        
        .. code-block:: python
        
            @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;
        
Keywords: pytest mock
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Software Development :: Testing
