[issue11468] Improve unittest basic example in the doc
New submission from Ezio Melotti <ezio.melotti@gmail.com>: 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 ---------- assignee: docs@python components: Documentation keywords: easy messages: 130598 nosy: docs@python, eric.araujo, ezio.melotti, michael.foord, ncoghlan, rhettinger priority: low severity: normal stage: needs patch status: open title: Improve unittest basic example in the doc type: feature request versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: LGTM. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Florian Preinstorfer <nblock@archlinux.us> added the comment: I tried to implement the improvements suggested by Ezio Melotti and updated the documentation accordingly. ---------- keywords: +patch nosy: +notizblock Added file: http://bugs.python.org/file22576/issue-11468.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Senthil Kumaran <senthil@uthcode.com> added the comment: 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. ---------- nosy: +orsenthil _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- nosy: +berkerpeksag _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: 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). ---------- assignee: docs@python -> rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: The patch includes only assertEqual, assertTrue, and assertRaises and, except a s/functions/methods/ in the first line, looks good to me. ---------- stage: needs patch -> commit review versions: -Python 3.1 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: Ezio, please leave this one for me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- nosy: -berker.peksag _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Serhiy Storchaka added the comment: 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. ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Ezio Melotti added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- nosy: -serhiy.storchaka stage: commit review -> patch review versions: +Python 3.4 -Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- versions: +Python 3.5 -Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Changes by Zachary Ware <zachary.ware@gmail.com>: ---------- nosy: +zach.ware _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Raymond Hettinger added the comment: 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Ezio Melotti added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Raymond Hettinger added the comment: Yes, go ahead an apply this patch. ---------- assignee: rhettinger -> ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
Ezio Melotti added the comment: 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! ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________
participants (9)
-
Berker Peksag -
Ezio Melotti
-
Florian Preinstorfer
-
Raymond Hettinger
-
Roundup Robot
-
Senthil Kumaran
-
Serhiy Storchaka
-
Zachary Ware
-
Éric Araujo