Title: Improve recipes and howtos for the unittest.mock
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.10, Python 3.9
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: docs@python, dougharris, eppeters, miss-islington, rhettinger, xtreak
Priority: normal Keywords: patch

Created on 2021-03-04 16:43 by eppeters, last changed 2021-03-05 01:39 by rhettinger.

Pull Requests
URL Status Linked Edit
PR 24752 merged eppeters, 2021-03-04 16:51
PR 24758 merged miss-islington, 2021-03-04 23:39
Messages (8)
msg388102 - (view) Author: Eddie Peters (eppeters) * Date: 2021-03-04 16:43
The unittest.mock library is very useful and very powerful, but it is not "very easy to use." Docs are useful and important, or we wouldn't be here in a documentation issue.

I have watched several of the most experienced Python programmers I know struggle with various aspects of mock, including basic usage. I have sat with frustrated developers who have used mocking utilities in other languages but had little Python experience, and they were surprised by some mock behaviors and just couldn't get things "right" until they were helped by someone with all the tiny little healed-over cuts from lots of mock usage.

Again, mock is great, but maybe if I have these opinions, I should contribute to making mock more intuitive. That's true. For now, though, the documentation contains this little line in the opening paragraphs that is unnecessary and can only make new mock users feel bad about having trouble: "Mock is very easy to use and is designed for use with unittest."

I propose we remove the opinion "Mock is very easy to use" and change this line to "Mock is designed for use with unittest." The rest of the paragraph flows just fine without this:

"Mock is very easy to use and is designed for use with unittest. Mock is based on the ‘action -> assertion’ pattern instead of ‘record -> replay’ used by many mocking frameworks."
msg388108 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python committer) Date: 2021-03-04 17:17
I don't have any opinion on removing the part of the sentence. It will be helpful if you can list the scenarios where you feel document is lacking so that it can be improved. One area I have found to be little tricky is patching the correct object during testing which has a section and needs some understanding of Python's import mechanism. The other was about setting return value properly for nested attributes.

Mock has a lot of features and has a wide range of API so listing places where you feel some of the things are not clear will help in improving them.
msg388109 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-03-04 17:19
+1 for the OP's suggestion.
msg388110 - (view) Author: Doug Harris (dougharris) Date: 2021-03-04 17:53
+1 on this documentation change.

@xtreak yes, patching the correct object has bit me a couple times.

The pattern that I work with the most is when mocking calls to external services and APIs. I want to test my code that, say, sends email or sends user information to a partner, but without actual HTTP calls. Whenever I add a new test that does this, I need to rethink exactly what the sequence of mocked objects, calls, and returns will be.

The HOWTO section of the official Python docs has nothing on unittest or mock. Perhaps something there... (makes note to think about drafting something).
msg388138 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-03-04 23:39
New changeset 2122e486307d5577cb5fb5e7cfd24095695bc7e9 by Eddie Peters in branch 'master':
bpo-43400: Remove "easy to use" from mock docs (GH-24752)
msg388139 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-03-05 00:35
New changeset 0dd4cb944b497dc6bd0b3763e461d72e9a7b6490 by Miss Islington (bot) in branch '3.9':
bpo-43400: Remove "easy to use" from mock docs (GH-24752) (GH-24758)
msg388141 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python committer) Date: 2021-03-05 01:15
Mock has a section on getting started that has several recipes but it's not under howto section. Perhaps this page could be updated if you want to make a PR :

There is also a section on where to patch :

I admit it also bites me few times and I have to do trial and error to get the right patch object.
msg388143 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-03-05 01:39
Renaming this issue to reflect a shift in focus towards broader improvements to the documentation.
Date User Action Args
2021-03-05 01:39:19rhettingersetassignee: rhettinger ->
2021-03-05 01:39:12rhettingersettitle: Remove "Mock is very easy to use" from unittest.mock documentation -> Improve recipes and howtos for the unittest.mock
messages: + msg388143
versions: - Python 3.6, Python 3.7, Python 3.8
2021-03-05 01:15:38xtreaksetmessages: + msg388141
2021-03-05 00:35:54rhettingersetmessages: + msg388139
2021-03-04 23:39:52rhettingersetassignee: docs@python -> rhettinger
2021-03-04 23:39:40miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request23530
2021-03-04 23:39:36rhettingersetmessages: + msg388138
2021-03-04 17:53:03dougharrissetnosy: + dougharris
messages: + msg388110
2021-03-04 17:19:31rhettingersetnosy: + rhettinger
messages: + msg388109
2021-03-04 17:17:41xtreaksetnosy: + xtreak
messages: + msg388108
2021-03-04 16:51:53eppeterssetkeywords: + patch
stage: patch review
pull_requests: + pull_request23522
2021-03-04 16:43:58eppeterscreate