As an example, let's build a test for the createSnapshot() method in the snapshothelper.py module. The following paths assume a Windows system, so adjust the directory paths as appropriate if you are on Unix or Linux. Here is what the file (testsnapshothelper.py in the Chapter 10 directory) looks like:

import snapshothelper
import unittest
import os

class TestCreateSnapshot(unittest.TestCase):

    def setUp(self):
        import os
        os.chdir ('c:\snapshots')

    def tearDown(self):
        os.system('del *.snp')

    def testpython25snap(self):
        # make a snapshot of the Python25 directory
        snapshothelper.createSnapshot('c:\python25', 'python25snap.snp')
        assert 'python25snap.snp' in os.listdir(os.curdir), 'Snapshot not created!'

    def testprogramfilesdir(self):
        # make a snapshot of the Python25 directory
        snapshothelper.createSnapshot('c:\program files', 'programfilessnap.snp')
        assert 'programfilessnap.snp' in os.listdir(os.curdir), 'Snapshot not
        created!'

if __name__ == '__main__':
    unittest.main()

The first thing the program does is import the modules it is going to need:

import snapshothelper
import unittest
import os

Next, it initializes a class that is inherited from unittest.TestCase:

class TestCreateSnapshot(unittest.TestCase):

Two special methods are the first methods in the class. The setUp method is run at the beginning of each test method in the class, and the tearDown method is run at the end of each test method:

def setUp(self):
        import os
        os.chdir ('c:\snapshots')

    def tearDown(self):
        os.system('del *.snp')

Next are the test methods. Notice that each test methods begins with the word test. That's not just a naming convention — it tells the TestCase class that the method is a test method, to be run by the test runner.

Consider the first test method:

def testpython25snap(self):
        # make a snapshot of the Python25 directory
        snapshothelper.createSnapshot('c:\python25', 'python25snap.snp')
        assert 'python25snap.snp' in os.listdir(os.curdir), 'Snapshot not created!'

Notice it simply contains code to exercise the function under test, and then an assert statement verifying that the function executed correctly.

The next test method is structured much the same — it is to test that you can create a snapshot for the program files directory, which has a space in the directory name:

def testprogramfilesdir(self):
    # make a snapshot of the Python25 directory
    snapshothelper.createSnapshot('c:\program files', 'programfilessnap.snp')
    assert 'programfilessnap.snp' in os.listdir(os.curdir), 'Snapshot not created!'

Finally, the following lines of code, placed at the bottom of a test module, enable the tests to be run by simply executing the module:

if __name__ == '__main__':
    unittest.main()

Go ahead and run the example by typing the following from a command prompt at the directory where you downloaded the files for Chapter 10: python testsnapshothelper.py.

You should see errors similar to the following:

EE
======================================================================
ERROR: testprogramfilesdir (__main__.TestCreateSnapshot)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "testsnapshothelper.py", line 9, in setUp
    os.chdir ('c:\snapshots')
WindowsError: [Error 2] The system cannot find the file specified: 'c:\snapshots'

======================================================================

ERROR: testpython25snap (__main__.TestCreateSnapshot)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "testsnapshothelper.py", line 9, in setUp
    os.chdir ('c:\snapshots')
WindowsError: [Error 2] The system cannot find the file specified: 'c:\snapshots'

----------------------------------------------------------------------
Ran 2 tests in 0.009s

FAILED (errors=2)

Ah, we forgot to create the snapshots directory. You can see how the output of errors or failing tests is formatted, to help you troubleshoot the results of the test run.

Create the c:snapshots directory and run the test module again. You'll see the following:

Press [Enter] to continue....
Press [Enter] to continue....
----------------------------------------------------------------------
Ran 2 tests in 18.081s

OK

Note that after each function you were prompted to press Enter. That's not a behavior of the test framework; the function itself does that. The output indicates that all the tests passed, and how long it took to run the tests.

This first example shows the simplest way of running a doctest, by embedding docstrings inside a function itself:

def printname(firstname, lastname):
    """Print firstname and lastname

    >>> printname("Jim", "Knowlton")
    Jim Knowlton

>>> printname("John", "Doe")
    John Doe
    """
    print "%s %s" % (firstname, lastname)

def _test():
    import doctest
    doctest.testmod()

if __name__ == "__main__":
    _test()

This program defines a function printname, which takes a first name and a last name as parameters:

def printname(firstname, lastname):

This is followed by a comment (docstring) that shows the expected output of a test, written in the form of an interactive shell session:

"""Print firstname and lastname

    >>> printname("Jim", "Knowlton")
    Jim Knowlton
    >>> printname("John", "Doe")
    John Doe
    """

The next line is the actual functionality of the function, which prints the first name and last name, with a space in between:

print "%s %s" % (firstname, lastname)

The final block of code imports the doctest module and allows the doctests to be run when the module is executed:

def _test():
    import doctest
    doctest.testmod()

if __name__ == "__main__":
    _test()

This example shows how tests can be defined in a simple text file, separate from the module itself, and run.

The snapshottests.txt text file (simply copied and pasted from an interactive session) is as follows:

>>> def printname(firstname, lastname):
...     print firstname + " " + lastname
...
>>> printname("Jim", "Knowlton")
Jim Knowlton
>>> printname("Bob")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: printname() takes exactly 2 arguments (1 given)
>>> printname("William", "Jennings", "Bryan")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: printname() takes exactly 2 arguments (3 given)
>>>

Now let's look at the doctestexample2 module. It's very simple:

import doctest
doctest.testfile("snapshottests.txt")

As you can see, it is simply a matter of creating a text file from a Python interactive session and then creating a script that loads that text file (with the help of the testfile() function).

If the module is run from the command line with a -v option (for verbose), it generates the following output:

Trying:
    def printname(firstname, lastname):
        print firstname + " " + lastname
Expecting nothing
ok
Trying:
    printname("Jim", "Knowlton")
Expecting:
    Jim Knowlton
ok
Trying:
    printname("Bob")
Expecting:
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: printname() takes exactly 2 arguments (1 given)
ok
Trying:
    printname("William", "Jennings", "Bryan")

Expecting:
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: printname() takes exactly 2 arguments (3 given)
ok
1 items passed all tests:
   4 tests in snapshottests.txt
4 tests in 1 items.
4 passed and 0 failed.
Test passed.