[docs] [issue28911] Clarify the behaviour of assert_called_once_with

[Arne de Laat]

New submission from Arne de Laat:

The name assert_called_once_with and the current method documentation can be interpreted to mean that it asserts that there is precisely one call matching the given signature, regardless of the total number of calls. However, the method first checks that there is precisely one call, and then checks if that call has a signature matching the provided signature.

Additionally, the assert_any_call method documentation references assert_called_once_with in a way that enforces the possible misinterpretation: "… assert_called_with and assert_called_once_with that only pass if the call is the most recent one". This may lead to the interpretation that there must be only one call with the given signature and  that it must be the most recent one, it must in fact be the only one.

In the mock examples documentation there is an important sentence that clarifies the actual functionality: "you can use the assert_called_once_with method that also asserts that the call_count is one".

The example provided in the method documentation also does not satisfactorily address the ambiguity, because it only calls the mock with one call signature. By changing the call signature of the second call (and in the assert) in the example the purpose of the method becomes clearer.

----------
assignee: docs at python
components: Documentation, Tests
files: assert_once_with_doc.patch
keywords: patch
messages: 282740
nosy: 153957, docs at python
priority: normal
severity: normal
status: open
title: Clarify the behaviour of assert_called_once_with
type: enhancement
versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7
Added file: http://bugs.python.org/file45803/assert_once_with_doc.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue28911>
_______________________________________