Add Mock.assert_called()

Issue #26323: Add assert_called() and assert_called_once() methods to
unittest.mock.Mock.

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index 9a51194b8ac5021f6d9f9175cd1a71df7c77e9e1..c4dc4ed5663a4e4117cdcb320e2053722b7015de 100644 (file)
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -259,6 +259,34 @@ the *new_callable* argument to :func:`patch`.
     used to set attributes on the mock after it is created. See the
     :meth:`configure_mock` method for details.
 
+    .. method:: assert_called(*args, **kwargs)
+
+        Assert that the mock was called at least once.
+
+            >>> mock = Mock()
+            >>> mock.method()
+            <Mock name='mock.method()' id='...'>
+            >>> mock.method.assert_called()
+
+        .. versionadded:: 3.6
+
+    .. method:: assert_called_once(*args, **kwargs)
+
+        Assert that the mock was called exactly once.
+
+            >>> mock = Mock()
+            >>> mock.method()
+            <Mock name='mock.method()' id='...'>
+            >>> mock.method.assert_called_once()
+            >>> mock.method()
+            <Mock name='mock.method()' id='...'>
+            >>> mock.method.assert_called_once()
+            Traceback (most recent call last):
+            ...
+            AssertionError: Expected 'method' to have been called once. Called 2 times.
+
+        .. versionadded:: 3.6
+
 
     .. method:: assert_called_with(*args, **kwargs)
 

diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst
index 5c02b7df8b5e8e1f08785ede3a2d99b2143ce37c..3afe2d41f3016dd2092c3cfe63e1eaf47285a104 100644 (file)
--- a/Doc/whatsnew/3.6.rst
+++ b/Doc/whatsnew/3.6.rst
@@ -161,6 +161,18 @@ telnetlib
 Stéphane Wirtel in :issue:`25485`).
 
 
+unittest.mock
+-------------
+
+The :class:`~unittest.mock.Mock` class has the following improvements:
+
+* Two new methods, :meth:`Mock.assert_called()
+  <unittest.mock.Mock.assert_called>` and :meth:`Mock.assert_called_once()
+  <unittest.mock.Mock.assert_called_once>` to check if the mock object
+  was called.
+  (Contributed by Amit Saha in :issue:`26323`.)
+
+
 urllib.robotparser
 ------------------
 

diff --git a/Lib/unittest/mock.py b/Lib/unittest/mock.py
index 21f49fab1b2a7dfe5681961ef9bd98a9bf985971..50ff949c9033da42d2b3137487eccf77dcc8ef2f 100644 (file)
--- a/Lib/unittest/mock.py
+++ b/Lib/unittest/mock.py
@@ -772,6 +772,24 @@ class NonCallableMock(Base):
                    (self._mock_name or 'mock', self.call_count))
             raise AssertionError(msg)
 
+    def assert_called(_mock_self):
+        """assert that the mock was called at least once
+        """
+        self = _mock_self
+        if self.call_count == 0:
+            msg = ("Expected '%s' to have been called." %
+                   self._mock_name or 'mock')
+            raise AssertionError(msg)
+
+    def assert_called_once(_mock_self):
+        """assert that the mock was called only once.
+        """
+        self = _mock_self
+        if not self.call_count == 1:
+            msg = ("Expected '%s' to have been called once. Called %s times." %
+                   (self._mock_name or 'mock', self.call_count))
+            raise AssertionError(msg)
+
     def assert_called_with(_mock_self, *args, **kwargs):
         """assert that the mock was called with the specified arguments.
 

diff --git a/Lib/unittest/test/testmock/testmock.py b/Lib/unittest/test/testmock/testmock.py
index 2a6069f66a4045d62b768afc55b1caceea7503e0..b2d9acbc127391c01ee6e000624e98d7c888b05b 100644 (file)
--- a/Lib/unittest/test/testmock/testmock.py
+++ b/Lib/unittest/test/testmock/testmock.py
@@ -1222,6 +1222,27 @@ class MockTest(unittest.TestCase):
         with self.assertRaises(AssertionError):
             m.hello.assert_not_called()
 
+    def test_assert_called(self):
+        m = Mock()
+        with self.assertRaises(AssertionError):
+            m.hello.assert_called()
+        m.hello()
+        m.hello.assert_called()
+
+        m.hello()
+        m.hello.assert_called()
+
+    def test_assert_called_once(self):
+        m = Mock()
+        with self.assertRaises(AssertionError):
+            m.hello.assert_called_once()
+        m.hello()
+        m.hello.assert_called_once()
+
+        m.hello()
+        with self.assertRaises(AssertionError):
+            m.hello.assert_called_once()
+
     #Issue21256 printout of keyword args should be in deterministic order
     def test_sorted_call_signature(self):
         m = Mock()

diff --git a/Misc/ACKS b/Misc/ACKS
index 0a67f39d2dd240467172e5b4612d0c1864f8d105..a19e113fb22d11936bd68df0a8771fba6a434241 100644 (file)
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1267,6 +1267,7 @@ Bernt Røskar Brenna
 Constantina S.
 Patrick Sabin
 Sébastien Sablé
+Amit Saha
 Suman Saha
 Hajime Saitou
 George Sakkis

diff --git a/Misc/NEWS b/Misc/NEWS
index 45d8f2e2b6518d7f4dbc109afe66752c1ab9268c..1e87de899c3e7cabe8aab3fb32f0653c145a2e87 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -201,6 +201,9 @@ Core and Builtins
 Library
 -------
 
+- Issue #26323: Add Mock.assert_called() and Mock.assert_called_once()
+  methods to unittest.mock. Patch written by Amit Saha.
+
 - Issue #20589: Invoking Path.owner() and Path.group() on Windows now raise
   NotImplementedError instead of ImportError.