classification
Title: Improve unittest basic example in the doc
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: docs@python, eric.araujo, ezio.melotti, michael.foord, ncoghlan, notizblock, orsenthil, python-dev, rhettinger, zach.ware
Priority: low Keywords: easy, patch

Created on 2011-03-11 18:15 by ezio.melotti, last changed 2015-03-24 10:55 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
issue-11468.patch notizblock, 2011-07-05 10:47 documentation update for unittest review
Messages (15)
msg130598 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-03-11 18:15
The current example[0] uses assertTrue(element in self.seq) but it would be better to use assertIn instead.  The whole example could be changed to something simpler that uses only the assertTrue/assertEqual/assertRaises methods correctly, e.g.:

import unittest

class TestStringMethods(unittest.TestCase):

    def test_upper(self):
        self.assertEqual('foo'.upper(), 'FOO')

    def test_isupper(self):
        self.assertTrue('FOO'.isupper())
        self.assertFalse('Foo'.isupper())

    def test_split(self):
        s = 'hello world'
        self.assertEqual(s.split(), ['hello', 'world'])
        # check that s.split fails when the separator is not a string
        with self.assertRaises(TypeError):
            s.split(2)

if __name__ == '__main__':
    unittest.main()

[0]: http://docs.python.org/py3k/library/unittest.html#basic-example
msg130680 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-03-12 14:59
LGTM.
msg139844 - (view) Author: Florian Preinstorfer (notizblock) Date: 2011-07-05 10:47
I tried to implement the improvements suggested by Ezio Melotti and updated the documentation accordingly.
msg140538 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2011-07-17 22:05
I would be +1 if the basic example also highlights setUp and tearDown methods. Those are useful ones for a new comer to know via an example snippet and not just with explanation.
msg140585 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-18 14:21
I think there’s value in accepting the current patch as really basic example, and then see if the section about setting up and tearing down also has a very simple example.
msg149334 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-12-12 17:19
I'll be updating this example shortly, but it is intentional that it include only assertEqual, assertTrue, and assertRaises.  Those three are the minimum necessary to get up and running (which is the whole point of the BASIC example).
msg149342 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-12-12 18:21
The patch includes only assertEqual, assertTrue, and assertRaises and, except a s/functions/methods/ in the first line, looks good to me.
msg149347 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-12-12 18:38
Ezio, please leave this one for me.
msg178040 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-12-24 09:00
I think `self.assertRaises(TypeError, s.split, 2)` looks simpler. In any case two examples for assertRaises needed, simple inlined and more complicated use as context manager.
msg178041 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-12-24 09:02
Given that this is a basic example, it's not necessary to introduce both the forms of assertRaises.
I personally find the context manager form more readable, and I prefer it to the regular one even if it takes two lines instead of one.
msg219244 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-05-27 21:48
FWIW, I'm going to test some other module (math or somesuch) rather than the built-in string methods.  The normal use of unittest is to import both the unittest module and the module under test.  I want to show that pattern (which is somewhat different from doctests where the tests are typically in the same file as the code being tested).
msg238466 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2015-03-18 19:13
Raymond, in the meanwhile can the proposed patch be applied?
I don't think it's necessary to show that you need to import a module in order to test its functions.  Using modules also has the disadvantage that people might not know what result to expect if they are not familiar with the functions of that module (e.g. the only functions that return True/False in the math module seem to be isfinite/isnan/isinf), whereas everyone should know basic string methods.
msg238491 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2015-03-19 06:10
Yes, go ahead an apply this patch.
msg239108 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-03-24 10:52
New changeset 4a2a5fddbab3 by Ezio Melotti in branch '2.7':
#11468: improve unittest basic example.  Initial patch by Florian Preinstorfer.
https://hg.python.org/cpython/rev/4a2a5fddbab3

New changeset 010e33b37feb by Ezio Melotti in branch '3.4':
#11468: improve unittest basic example.  Initial patch by Florian Preinstorfer.
https://hg.python.org/cpython/rev/010e33b37feb

New changeset d6791e4026f1 by Ezio Melotti in branch 'default':
#11468: merge with 3.4.
https://hg.python.org/cpython/rev/d6791e4026f1
msg239109 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2015-03-24 10:55
I tweaked the wording a bit, added a link to the section about setUp/tearDown, and applied it on all the 3 branches.
Thanks for the patch Florian!
History
Date User Action Args
2015-03-24 10:55:55ezio.melottisetstatus: open -> closed
resolution: fixed
messages: + msg239109

stage: patch review -> resolved
2015-03-24 10:52:52python-devsetnosy: + python-dev
messages: + msg239108
2015-03-19 06:10:17rhettingersetassignee: rhettinger -> ezio.melotti
messages: + msg238491
2015-03-18 19:13:00ezio.melottisetmessages: + msg238466
2014-05-27 21:48:30rhettingersetmessages: + msg219244
2014-05-27 17:17:19zach.waresetnosy: + zach.ware
2014-05-27 12:55:10berker.peksagsetversions: + Python 3.5, - Python 3.3
2014-05-27 12:29:16ezio.melottilinkissue21589 superseder
2013-05-28 18:41:01serhiy.storchakasetnosy: - serhiy.storchaka
stage: commit review -> patch review

versions: + Python 3.4, - Python 3.2
2012-12-24 09:02:52ezio.melottisetmessages: + msg178041
2012-12-24 09:00:09serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg178040
2012-10-26 10:29:56berker.peksagsetnosy: - berker.peksag
2011-12-12 18:38:31rhettingersetmessages: + msg149347
2011-12-12 18:21:51ezio.melottisetstage: needs patch -> commit review
messages: + msg149342
versions: - Python 3.1
2011-12-12 17:19:04rhettingersetassignee: docs@python -> rhettinger
messages: + msg149334
2011-12-12 16:47:58berker.peksagsetnosy: + berker.peksag
2011-07-18 14:21:32eric.araujosetmessages: + msg140585
2011-07-17 22:05:11orsenthilsetnosy: + orsenthil
messages: + msg140538
2011-07-05 10:47:42notizblocksetfiles: + issue-11468.patch

nosy: + notizblock
messages: + msg139844

keywords: + patch
2011-03-12 14:59:47eric.araujosetnosy: rhettinger, ncoghlan, ezio.melotti, eric.araujo, michael.foord, docs@python
messages: + msg130680
2011-03-11 18:15:41ezio.melotticreate