[Python-bugs-list] [ python-Feature Requests-767592 ] unittest docs don't suggest "unittest.main()"

[SourceForge.net]

Feature Requests item #767592, was opened at 2003-07-08 17:40
Message generated for change (Tracker Item Submitted) made by Item Submitter
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=355470&aid=767592&group_id=5470

Category: Documentation
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Andrew Bennetts (spiv)
Assigned to: Nobody/Anonymous (nobody)
Summary: unittest docs don't suggest "unittest.main()"

Initial Comment:
By far the most common use of the unittest module I've
seen is simply:

1. Define one or more classes that subclass
unittest.TestCase.  Give them methods that are named
"test_foo".

2. Put "if __name__ == '__main__': unittest.main()" at
the bottom of the module.

Nowhere do the unittest standard library docs make it
clear this is the easiest, and most common, way to use
the unittest module.

The "Organizing test code" section completely fails to
mention this, even though I think this should be the
first thing described.  Instead, it helpfully lists all
sorts of ways to use test suites that you rarely, if
ever, need in practice.  Mention of unittest.main() is
buried several sections later, and is very brief.

I suggest opening "Organizing test code" with a
complete working example demonstrating typical use, e.g.:

---
import unittest

class TestArithmetic(unittest.TestCase):
    def test_addition(self):
        self.failUnlessEqual(1+2, 3)

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

It's a trivial example, but it could work wonders.  I
usually recommend the diveintopython.org docs on
unittest (http://diveintopython.org/roman_divein.html)
due to the state of the official unittest docs.

Thanks!

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=355470&aid=767592&group_id=5470