Issue #17015: When it has a spec, a Mock object now inspects its signature when matching calls, so that arguments can be matched positionally or by name.

1 files changed, 14 insertions, 0 deletions

diff --git a/Doc/library/unittest.mock-examples.rst b/Doc/library/unittest.mock-examples.rst
index 0cbb5ae..36926cd 100644
--- a/Doc/library/unittest.mock-examples.rst
+++ b/Doc/library/unittest.mock-examples.rst
@@ -277,6 +277,20 @@ instantiate the class in those tests.
        ...
     AttributeError: object has no attribute 'old_method'
 
+Using a specification also enables a smarter matching of calls made to the
+mock, regardless of whether some parameters were passed as positional or
+named arguments::
+
+   >>> def f(a, b, c): pass
+   ...
+   >>> mock = Mock(spec=f)
+   >>> mock(1, 2, 3)
+   <Mock name='mock()' id='140161580456576'>
+   >>> mock.assert_called_with(a=1, b=2, c=3)
+
+If you want this smarter matching to also work with method calls on the mock,
+you can use :ref:`auto-speccing <auto-speccing>`.
+
 If you want a stronger form of specification that prevents the setting
 of arbitrary attributes as well as the getting of them then you can use
 `spec_set` instead of `spec`.