[doc] TextTestRunner documentation improvements

[techtonik]

BPO	11385
Nosy	@terryjreedy, @ezio-melotti, @voidspace, @Julian, @iritkatriel

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2011-03-03.18:25:33.377>
labels = ['easy', 'type-bug', '3.9', '3.10', '3.11', 'tests', 'docs']
title = '[doc] TextTestRunner documentation improvements'
updated_at = <Date 2021-12-08.14:47:37.110>
user = 'https://bugs.python.org/techtonik'

bugs.python.org fields:

activity = <Date 2021-12-08.14:47:37.110>
actor = 'iritkatriel'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Tests']
creation = <Date 2011-03-03.18:25:33.377>
creator = 'techtonik'
dependencies = []
files = []
hgrepos = []
issue_num = 11385
keywords = ['easy']
message_count = 8.0
messages = ['129988', '130084', '130085', '130086', '130089', '130093', '130177', '408022']
nosy_count = 7.0
nosy_names = ['terry.reedy', 'techtonik', 'ezio.melotti', 'michael.foord', 'docs@python', 'Julian', 'iritkatriel']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue11385'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

• gh-55594: Document unittest.TextTestRunner class and methods #142648

[techtonik]

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()

[terryjreedy]

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?

[terryjreedy]

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.

[voidspace]

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.)

[terryjreedy]

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.

[voidspace]

TextTestRunner was more meant to be an *example* of a test runner. It just turned out to be the only one and widely used.

[techtonik]

Something to think about for future examples.

[iritkatriel]

The run method is documented now, but most of the above points are still true.