Merge pull request #5 from nicoddemus/deprecate-mock

Deprecate mock in favor of mocker

README.rst

@@ -2,16 +2,16 @@
 pytest-mock
 ===========
 
-This plugin installs a ``mock`` fixture which is a thin-wrapper around the patching API 
+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(mock):
-        mock.patch('os.remove')
+    def test_unix_fs(mocker):
+        mocker.patch('os.remove')
         UnixFS.rm('file')
         os.remove.assert_called_once_with('file')
         
@@ -40,27 +40,38 @@ of a test:
 Usage
 =====
 
-The ``mock`` fixture has the same API as 
+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(mock):
+    def test_foo(mocker):
         # all valid calls
-        mock.patch('os.remove')
-        mock.patch.object(os, 'listdir', autospec=True)
-        mocked = mock.patch('os.path.isfile')
+        mocker.patch('os.remove')
+        mocker.patch.object(os, 'listdir', autospec=True)
+        mocked_isfile = mocker.patch('os.path.isfile')
     
 The supported methods are:
 
-* ``mock.patch``: see http://www.voidspace.org.uk/python/mock/patch.html#patch.
-* ``mock.patch.object``: see http://www.voidspace.org.uk/python/mock/patch.html#patch-object.
-* ``mock.patch.multiple``: see http://www.voidspace.org.uk/python/mock/patch.html#patch-multiple.
-* ``mock.patch.dict``: see http://www.voidspace.org.uk/python/mock/patch.html#patch-dict.
-* ``mock.stopall()``: stops all active patches at this point.
+* ``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 at this point.
 
 
+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
 ============
 

pytest_mock.py

@@ -68,11 +68,23 @@ def __call__(self, *args, **kwargs):
 
 
 @pytest.yield_fixture
-def mock():
+def mocker():
     """
     return an object that has the same interface to the `mock` module, but
     takes care of automatically undoing all patches after each test method.
     """
     result = MockFixture()
     yield result
-    result.stopall()
+    result.stopall()
+
+
+@pytest.yield_fixture
+def mock():
+    """
+    Same as "mocker", but kept only for backward compatibility.
+    """
+    import warnings
+    warnings.warn('"mock" fixture has been deprecated, use "mocker" instead',
+                  DeprecationWarning)
+    for m in mocker():
+        yield m

setup.py

@@ -9,7 +9,7 @@
 
 setup(
     name='pytest-mock',
-    version='0.3.0',
+    version='0.4.0',
     entry_points={
         'pytest11': ['pytest-mock = pytest_mock'],
     },

test_pytest_mock.py

@@ -3,6 +3,8 @@
 import pytest
 
 
+pytest_plugins = 'pytester'
+
 class UnixFS(object):
     """
     Wrapper to os functions to simulate a Unix file system, used for testing
@@ -19,7 +21,7 @@ def ls(cls, path):
 
 
 @pytest.fixture
-def check_unix_fs_mocked(tmpdir, mock):
+def check_unix_fs_mocked(tmpdir, mocker):
     """
     performs a standard test in a UnixFS, assuming that both `os.remove` and
     `os.listdir` have been mocked previously.
@@ -40,7 +42,7 @@ def check(mocked_rm, mocked_ls):
         assert UnixFS.ls(str(tmpdir)) == ['bar.txt']
         mocked_ls.assert_called_once_with(str(tmpdir))
 
-        mock.stopall()
+        mocker.stopall()
 
         assert UnixFS.ls(str(tmpdir)) == ['foo.txt']
         UnixFS.rm(str(file_name))
@@ -49,43 +51,63 @@ def check(mocked_rm, mocked_ls):
     return check
 
 
-def mock_using_patch_object(mock):
-    return mock.patch.object(os, 'remove'), mock.patch.object(os, 'listdir')
+def mock_using_patch_object(mocker):
+    return mocker.patch.object(os, 'remove'), mocker.patch.object(os, 'listdir')
 
 
-def mock_using_patch(mock):
-    return mock.patch('os.remove'), mock.patch('os.listdir')
+def mock_using_patch(mocker):
+    return mocker.patch('os.remove'), mocker.patch('os.listdir')
 
 
-def mock_using_patch_multiple(mock):
+def mock_using_patch_multiple(mocker):
     from pytest_mock import mock_module
 
-    r = mock.patch.multiple('os', remove=mock_module.DEFAULT,
-                            listdir=mock_module.DEFAULT)
+    r = mocker.patch.multiple('os', remove=mock_module.DEFAULT,
+                              listdir=mock_module.DEFAULT)
     return r['remove'], r['listdir']
 
 
 @pytest.mark.parametrize('mock_fs', [mock_using_patch_object, mock_using_patch,
                                      mock_using_patch_multiple],
 )
-def test_mock_patches(mock_fs, mock, check_unix_fs_mocked):
+def test_mock_patches(mock_fs, mocker, check_unix_fs_mocked):
     """
     Installs mocks into `os` functions and performs a standard testing of
     mock functionality. We parametrize different mock methods to ensure
     all (intended, at least) mock API is covered.
     """
-    mock_fs(mock)
-    mocked_rm, mocked_ls = mock_fs(mock)
+    # mock it twice on purpose to ensure we unmock it correctly later
+    mock_fs(mocker)
+    mocked_rm, mocked_ls = mock_fs(mocker)
     check_unix_fs_mocked(mocked_rm, mocked_ls)
 
 
-def test_mock_patch_dict(mock):
+def test_mock_patch_dict(mocker):
     """
     Testing
     :param mock:
     """
     x = {'original': 1}
-    mock.patch.dict(x, values=[('new', 10)], clear=True)
+    mocker.patch.dict(x, values=[('new', 10)], clear=True)
     assert x == {'new': 10}
-    mock.stopall()
+    mocker.stopall()
     assert x == {'original': 1}
+
+
+def test_mock_fixture_is_deprecated(testdir):
+    """
+    Test that a warning emitted when using deprecated "mock" fixture.
+    """
+    testdir.makepyfile('''
+        import warnings
+        import os
+        warnings.simplefilter('always')
+
+        def test_foo(mock, tmpdir):
+            mock.patch('os.listdir', return_value=['mocked'])
+            assert os.listdir(str(tmpdir)) == ['mocked']
+            mock.stopall()
+            assert os.listdir(str(tmpdir)) == []
+    ''')
+    result = testdir.runpytest('-s')
+    result.stderr.fnmatch_lines(['*"mock" fixture has been deprecated*'])