This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: [doc] TextTestRunner documentation improvements
Type: behavior Stage:
Components: Documentation, Tests Versions: Python 3.11, Python 3.10, Python 3.9
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: Julian, docs@python, ezio.melotti, iritkatriel, michael.foord, techtonik, terry.reedy
Priority: normal Keywords: easy

Created on 2011-03-03 18:25 by techtonik, last changed 2022-04-11 14:57 by admin.

Messages (8)
msg129988 - (view) Author: anatoly techtonik (techtonik) Date: 2011-03-03 18:25
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()
msg130084 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-03-04 23:17
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(
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?
msg130085 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-03-04 23:26
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.
msg130086 - (view) Author: Michael Foord (michael.foord) * (Python committer) Date: 2011-03-04 23:28
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.)
msg130089 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-03-05 00:08
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.
msg130093 - (view) Author: Michael Foord (michael.foord) * (Python committer) Date: 2011-03-05 00:21
TextTestRunner was more meant to be an *example* of a test runner. It just turned out to be the only one and widely used.
msg130177 - (view) Author: anatoly techtonik (techtonik) Date: 2011-03-06 16:24
Something to think about for future examples.
msg408022 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-12-08 14:47
The run method is documented now, but most of the above points are still true.
Date User Action Args
2022-04-11 14:57:13adminsetgithub: 55594
2021-12-08 14:47:37iritkatrielsetassignee: michael.foord ->

title: TextTestRunner methods are not documented -> [doc] TextTestRunner documentation improvements
keywords: + easy
nosy: + iritkatriel
versions: + Python 3.9, Python 3.10, Python 3.11, - Python 2.7, Python 3.4, Python 3.5
messages: + msg408022
2014-07-02 22:41:57terry.reedylinkissue11389 superseder
2014-06-27 20:54:38BreamoreBoysettype: behavior
versions: + Python 3.5, - Python 3.2, Python 3.3
2012-09-12 11:52:32Juliansetnosy: + Julian
2012-09-11 22:54:54ezio.melottisetnosy: + ezio.melotti

versions: + Python 3.4, - Python 3.1
2011-03-15 16:59:39michael.foordsetassignee: docs@python -> michael.foord
nosy: terry.reedy, techtonik, michael.foord, docs@python
2011-03-06 16:24:42techtoniksetnosy: terry.reedy, techtonik, michael.foord, docs@python
messages: + msg130177
2011-03-05 00:21:43michael.foordsetnosy: terry.reedy, techtonik, michael.foord, docs@python
messages: + msg130093
2011-03-05 00:08:18terry.reedysetnosy: terry.reedy, techtonik, michael.foord, docs@python
messages: + msg130089
2011-03-04 23:28:03michael.foordsetnosy: terry.reedy, techtonik, michael.foord, docs@python
messages: + msg130086
2011-03-04 23:26:20terry.reedysetnosy: terry.reedy, techtonik, michael.foord, docs@python
messages: + msg130085
2011-03-04 23:17:01terry.reedysetnosy: + terry.reedy, michael.foord

messages: + msg130084
versions: + Python 3.1, Python 2.7, Python 3.2, Python 3.3, - Python 2.6
2011-03-03 18:25:33techtonikcreate