The documentation for "unittest.TestCase" says "the standard implementation of the default 'methodName', runTest(), will run every method starting with 'test' as an individual test". However:

>>> from unittest import *
>>> class Test(TestCase):
...     def test_method(self): pass
... 
>>> t = Test()
>>> t.run()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/lib/python3.4/unittest/case.py", line 552, in run
    testMethod = getattr(self, self._testMethodName)
AttributeError: 'Test' object has no attribute 'runTest'

After further experimentation, I see that if my test method is called "runTest", it can be automatically discovered, but only if there are no other test- prefixed methods.

Perhaps you could drop the end of the second paragraph for TestCase, so that it just reads:

Each instance of TestCase will run a single base method: the method named "methodName".

I think the details about the test- prefix and counting results are covered elsewhere, and in most uses you wouldn't instantiate a TestCase yourself, so changing the method name is irrelevant.

Also, perhaps under "TestLoader.loadTestsFromTestCase" it should say:

If no methods with the usual name prefix are found, but the "runTest" method is implemented, there will be a single test case using that method.

Updated documentation following suggestion.

The patch seems reasonable to me

IMO hiding the existence of `runTest` would be best. It doesn't seem to make anything more flexible, and it complicates the documentation.

Do you mean pretending there is no default “methodName” value, or pretending that the runTest() method is not invoked by discovery?

I would have to check, but I think I have relied on the runTest() method being discovered in the past, when I did not think a more original test method name was useful. Though I agree that it makes the behaviour more complicated for little extra flexibility.

runTest is part of the current API. I think if we're going to hide it we should do so as part of a deprecation path. (I'm +1 on hiding it).

Le 28/10/2014 23:01, Robert Collins a écrit :
> 
> runTest is part of the current API. I think if we're going to hide
> it
we should do so as part of a deprecation path. (I'm +1 on hiding it).

We don't need a deprecation path to remove something from the
documentation, IMO. It wouldn't break any existing code, it would just
reduce the cognitive load for newcomers.

(and, while people may have chosen to use runTest, it doesn't mean they
need it in any way)

Removing stuff from the documentation would make it hard to understand what existing code means that uses runTest(). Isn’t this a case where you would add a big red “Deprecated since version . . .” warning instead? Maybe a comprimise would be to “hide” its documentation away in a separate deprecated section or something.

Le 29/10/2014 00:22, Martin Panter a écrit :
> 
> Martin Panter added the comment:
> 
> Removing stuff from the documentation would make it hard to
> understand
what existing code means that uses runTest(). Isn’t this a case where
you would add a big red “Deprecated since version . . .” warning
instead? Maybe a comprimise would be to “hide” its documentation away in
a separate deprecated section or something.

Well, I wasn't proposing a deprecation (although that can be done as
well, if we want). I was proposing that this detail be hidden. I don't
know if it would make existing software harder to understand. I don't
think I've ever seen an actively-maintained project that used runTest().

The simple way to hide it would be to stop documenting the TestCase
constructor and its signature. You aren't supposed to instantiate
TestCase yourself.

Constructing test case objects directly is part of the protocol, and its needed for framework and extension authors.

I've seen folk use runTest, but rarely enough that I think we could deprecate it. My argument is that while its supported we should be clear about when it should be used, and how.

Oh, one thought - in testtools we split out 'docs for test writers' and 'docs for framework folk'. That would facilitate getting runTest out of test writers face while still documenting it appropriately.

Related to that is my ongoing push to split the protocol so that these concerns are not intertwined the way they are today, but that needs to wait for the existing backlog to clear up :)

I'll apply the patch monday if there are no further comments before then.

> Oh, one thought - in testtools we split out 'docs for test writers' and
> 'docs for framework folk'. That would facilitate getting runTest out of
> test writers face while still documenting it appropriately.

This has already been discussed in the past, and IIRC there was consensus about giving unittest docs the same treatment.  I don't remember if there was an issue for this.

Updated patch with indentation fixed and new wording. I am just guessing the RST syntax based on the surrounding text, so please review :)

Updated patch, which applies to current tip of the default branch, and includes the formatting fix. Also including a version that applies to the 3.4 branch. Alternatively, if you patch the 3.4 branch it looks like merging to default automatically gives the correct result.

New changeset eefc157b3096 by Robert Collins in branch '3.4':
Issue #22153: Improve unittest docs. Patch from Martin Panter and evilzero.
https://hg.python.org/cpython/rev/eefc157b3096

New changeset 10f5a7fa26d5 by Robert Collins in branch '3.5':
Issue #22153: Improve unittest docs. Patch from Martin Panter and evilzero.
https://hg.python.org/cpython/rev/10f5a7fa26d5

New changeset 45bd2dadbd0d by Robert Collins in branch 'default':
Issue #22153: Improve unittest docs. Patch from Martin Panter and evilzero.
https://hg.python.org/cpython/rev/45bd2dadbd0d

Thanks for the update, it looks good to me. Applied to 3.4 and up. I'm not applying to 2.7 at this stage.