[issue11385] TextTestRunner methods are not documented
New submission from anatoly techtonik <techtonik@gmail.com>: TextTestRunner has a run method, which is not documented. It is also is not clear how to add suite to TextTestRunner to be executed later by unittest.main() ---------- assignee: docs@python components: Documentation, Tests messages: 129988 nosy: docs@python, techtonik priority: normal severity: normal status: open title: TextTestRunner methods are not documented versions: Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11385> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: Doc issues should be 'tested' and reported against the latest versions. 2.6.6 doc is effectively the last 2.6 version. TextTextRunner is not completely undocumented. In 3.2
help(t.run) Help on function run in module unittest.runner:
run(self, test) Run the given test case or test suite. Searching on 'run(' finds near the top of the unittest chapter (2.7, 3.2): "A test runner is an object that provides a single method, run(), which accepts a TestCase or TestSuite object as a parameter, and returns a result object." I agree that the entry for TextTestRunner near the bottom should include one for .run, with at least the doc string, but maybe a backreference to the discussion near the top. It is not clear to me how TextTestRunner is expected to be used. Does unittest.main instantiate one, and call run, behind the scenes? ---------- nosy: +michael.foord, terry.reedy versions: +Python 2.7, Python 3.1, Python 3.2, Python 3.3 -Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11385> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: I also see that TextTestRunner has an attribute resultclass, which is TextTestResult. Is this intended to be ever changed? The docstring for TTRunner says "It prints out the names of tests as they are run, errors as they occur, and a summary of the results at the end of the test run." which seems to be what .main() does. The manual just has the less informative "A basic test runner implementation that outputs results to a stream." I prefer the former. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11385> _______________________________________
Michael Foord <michael@voidspace.org.uk> added the comment: Except the former is incorrect as the responsibility for printing results as they occur is with the TestResult and not the runner. I'll look at this and improve the docs for the runner. (And yes unittest.main() creates and uses a runner under the hood. It is frequently used directly by test frameworks as well though.) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11385> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: class unittest.TextTestRunner(stream=None, descriptions=True, verbosity=1, runnerclass=None, warnings=None) stream is documented, the others are not (except for some garbled text about warnings). "This class has a few configurable parameters, " is not helpful. It seems that TextTestRunner was meant to be a subclass of a documented TestRunner class (just as TextTestResult subclasses TestResult), except that is it not. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11385> _______________________________________
Michael Foord <michael@voidspace.org.uk> added the comment: TextTestRunner was more meant to be an *example* of a test runner. It just turned out to be the only one and widely used. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11385> _______________________________________
anatoly techtonik <techtonik@gmail.com> added the comment: Something to think about for future examples. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11385> _______________________________________
Changes by Michael Foord <michael@voidspace.org.uk>: ---------- assignee: docs@python -> michael.foord _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11385> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti versions: +Python 3.4 -Python 3.1 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11385> _______________________________________
Changes by Julian Berman <Julian+Python.org@GrayVines.com>: ---------- nosy: +Julian _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11385> _______________________________________
Changes by Mark Lawrence <breamoreboy@yahoo.co.uk>: ---------- type: -> behavior versions: +Python 3.5 -Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11385> _______________________________________
participants (6)
-
anatoly techtonik -
Ezio Melotti
-
Julian Berman
-
Mark Lawrence
-
Michael Foord
-
Terry J. Reedy