classification
Title: UnitTest docs should have a single list of assertions
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: docs@python, ezio.melotti, kushal.das, michael.foord, ntoll, python-dev, roysmith, terry.reedy, wiggin15
Priority: normal Keywords: patch

Created on 2013-09-11 15:45 by roysmith, last changed 2016-01-12 09:04 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
issue19006.diff ezio.melotti, 2016-01-01 05:04 Doc patch against default. review
Messages (10)
msg197492 - (view) Author: Roy Smith (roysmith) Date: 2013-09-11 15:45
http://docs.python.org/2/library/unittest.html#assert-methods

The docs say, "The TestCase class provides a number of methods to check for and report failures, such as", and then when you scroll a couple of screens down, there's another list, "There are also other methods used to perform more specific checks, such as".  These should be merged into a single list.  There's nothing fundamentally different about the two lists and breaking them into two parts just makes it harder to find what you want.
msg197495 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-09-11 16:10
> There's nothing fundamentally different about the two lists

I made that division because the ones in the first table are the most common and widely used, and are quite general too.
The second table contains assert methods about catching exceptions and warnings, and, while still common, they are different from the first group. 
The third table has additional assertions that are quite specific and not used too often, and many of these have been added later on.
There's also a fourth table with additional type-specific assertions, but they shouldn't be used directly.

Also note that the list of methods is different on 3.x, even though I kept the same division on all the branches.

> These should be merged into a single list.

Having a table with all the assert methods would indeed provide a better overview, but it would be quite a big table (25 assert methods on 3.4, excluding the type-specific ones) and might make navigation more difficult while scrolling through the methods.  Something could be done to make clear that there are other tables down below though (e.g. adding links or using sub-sections with an index).
msg197503 - (view) Author: Roy Smith (roysmith) Date: 2013-09-11 19:28
Adding a note that there are more methods in the tables below would be useful.  Otherwise, you assume you've seen them all when you've read the first table.

I agree that the assertions about exceptions and warnings belong in a different group, but I don't see any fundamental reason to put assertGreater in a different table from assertEqual.
msg197504 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-09-11 19:41
One reason is that if I list all those assert methods first and keep the assertRaises/Warns in a separate group, they will be pushed way down, and people might miss them.
I'll try to prepare a patch that adds links to the other tables and/or changes the wording to make it clear that there are more assert methods.
msg197624 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-09-13 18:41
I like the current division, but agree that
  The TestCase class provides a number of methods to check for and
  report failures, such as:

is slightly misleading. I would change it to
  The TestCase class provides a number of methods to check for and
  report failures. The most commonly used are:
  ...<table>
  More are listed in the Regex, Comparisons, and Type-specific tables.

where each of Regex, Comparisons, and Type-specific link to their respective tables. (Repaint the link names if you wish ;-).
msg197627 - (view) Author: Roy Smith (roysmith) Date: 2013-09-13 18:46
The new text suggested by terry.reedy works for me.
msg257272 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2016-01-01 05:04
Here's a patch.
msg257440 - (view) Author: Kushal Das (kushal.das) * (Python committer) Date: 2016-01-04 04:55
The patch looks good to me. Commit :)
msg258084 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-01-12 09:04
New changeset ddb8fa84a119 by Ezio Melotti in branch '2.7':
#19006: fix wording in unittest docs.
https://hg.python.org/cpython/rev/ddb8fa84a119

New changeset 84f34e8685de by Ezio Melotti in branch '3.5':
#19006: fix wording in unittest docs.
https://hg.python.org/cpython/rev/84f34e8685de

New changeset 86c8d65d188f by Ezio Melotti in branch 'default':
#19006: merge with 3.5.
https://hg.python.org/cpython/rev/86c8d65d188f
msg258085 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2016-01-12 09:04
Fixed, thanks for the review!
History
Date User Action Args
2016-01-12 09:04:50ezio.melottisetstatus: open -> closed
resolution: fixed
messages: + msg258085

stage: commit review -> resolved
2016-01-12 09:04:05python-devsetnosy: + python-dev
messages: + msg258084
2016-01-04 04:55:59kushal.dassetmessages: + msg257440
2016-01-01 05:04:18ezio.melottisetfiles: + issue19006.diff
versions: + Python 3.5, Python 3.6, - Python 3.3, Python 3.4
messages: + msg257272

assignee: docs@python -> ezio.melotti
keywords: + patch
stage: commit review
2015-10-02 08:23:19ntollsetnosy: + kushal.das, ntoll
2015-09-29 15:48:32wiggin15setnosy: + wiggin15
2013-09-13 18:46:42roysmithsetmessages: + msg197627
2013-09-13 18:41:49terry.reedysetnosy: + terry.reedy
messages: + msg197624
2013-09-11 19:41:06ezio.melottisetmessages: + msg197504
2013-09-11 19:28:28roysmithsetmessages: + msg197503
2013-09-11 16:10:16ezio.melottisetversions: + Python 3.3, Python 3.4
nosy: + ezio.melotti, michael.foord

messages: + msg197495

type: enhancement
2013-09-11 15:45:35roysmithcreate