The first message of the longMessage docs is confusing:

https://docs.python.org/3/library/unittest.html#unittest.TestCase.longMessage

> If set to True then ....

This reads between the lines, that the default is False.

But that was long ago in Python2. In Python3 the default is True (which I prefer to the old default).

I think the docs should be like.

And the term "normal message" is not defined. For new comers the "normal message" is what I get if you don't change the default, not the behaviour of the Python2 version :-)

I think "normal message" should be replaced with "short message" or "diff message" .. I am unsure.

What do you think?

Replace existing description with

"This class attribute determines what happens when a custom failure message is passed as the msg argument to an assertXYY call that fails.  If True, the default, the custom message is appended to the end of the standard failure message.  If False, the custom message replaces the standard message.

The standard failure message for each *assert method* contains useful information about the objects involved.  For example the message from assertEqual shows the repr of the two unequal objects.  It is usually easier to augment rather than replace this message

The class setting can be overridden in individual test methods by assigning an instance attribute, self.longMessage, to True or False before calling the assert methods.

New in version 3.1."

Thank you for understanding my concern.



> The standard failure message for each *assert method* contains useful  
> information about the objects involved.  For example the message from 
> assertEqual shows the repr of the two unequal objects.  It is usually 
> easier to augment rather than replace this message

I think above is not needed.


> The class setting can be overridden in individual test methods by 
> assigning an instance attribute, self.longMessage, to True or False 
> before calling the assert methods.

I would add "the default value of the class gets reset before each test call". That is more explicit (I hope my text is what happens behind the scene)

Again, thank you, that you care.

Regards,
  Thomas Güttler

Hi, please review the updated documentation.

Thanks.

@Mariatta thank you very much. This update makes the docs easy to read and understand. Thank you :-)

New changeset 7eb4fe57492f by Guido van Rossum in branch '3.5':
Issue #26869: Document unittest.TestCase.longMessage. (Mariatta)
https://hg.python.org/cpython/rev/7eb4fe57492f

New changeset d7279d803d1d by Guido van Rossum in branch '3.6':
Issue #26869: Document unittest.TestCase.longMessage. (Mariatta) (3.5->3.6)
https://hg.python.org/cpython/rev/d7279d803d1d

New changeset c7c428350578 by Guido van Rossum in branch 'default':
Issue #26869: Document unittest.TestCase.longMessage. (Mariatta) (3.6->3.7)
https://hg.python.org/cpython/rev/c7c428350578

Done. Thanks!