Python unittest framework: Test description

Question

What's the best practice to provide the description of a test script in python?

Obviously I can put the comments below the test case, but wanted to know if there's any standard practice (any methods I should write) to provide the description of the test case (detailed information on what the test case is supposed to do)?

Is this how you would put the test description?:

Class TestFoo:
    def testfoo1():
    """
    test description:
    step1:
    step2: 
    """

Any suggestions/references would be appreciated.

Answer 1

The test method docstring is the standard place to put that information If you are using python's unittest module. unittest will use that docstring to format output, etc.

Answer 2

In the unittest framework, you have the shortDecription method:

shortDescription()

Returns a description of the test, or None if no description has been provided. The default implementation of this method returns the first line of the test method’s docstring, if available.

So, in fact, using the method docstring is a fine place. You may have to inherit from TestCase in your class declaration for the runner to work like that, though.

For best practice: name the test case (class) and the test methods in a concise but useful fashion which is sufficient for developers to have a high level idea of where something is going wrong, should that particular test fail. A prerequisite to this is each test method should only be testing one thing, rather than asserting on a whole bunch of different things.

With sensible test names, usually a docstring with "detailed information on what the test case is supposed to do" would not be necessary. If you have existing large tests which check many things, you may want to split them up into a bunch of smaller tests which each assert on one and only one individual thing.