9.3 Usage


9.3 Usage

Test classes are created by subclassing TestCase . The simplest approach is to override the method runTest( ) , as shown in Example 9-1.

Example 9-1. Simple unit test for the class Book

"""Unit test for book.py"""

import book

import unittest

class  BookTests  (unittest.TestCase):

   def  runTest  (self):

      """Test book creation"""

      book1 = book.Book( "Cosmos", "Carl Sagan" )

      self.  assertEqual  ( "Cosmos", book1.title ) 

This example creates the test class BookTests . The test method runTest( ) creates a Book and uses the assertEqual( ) test assert method to verify its attributes. Test methods customarily contain a label similar to the example's Test book creation . This test description is printed if the test fails.

The class Book tested by BookTests is given in Example 9-2.

Example 9-2. Simple unit test for the class Book

class  Book  :

   title = ""

   author = ""

   def  __init_  _  (self, title, author):

      self.title = title

      self.author = author 

Unit tests may be run from the command line using unittests.py as a test runner. The argument specifies the Python module name, class name, and method name of the test to run. Example 9-3 demonstrates running BookTests this way and shows the result.

Example 9-3. Results of running BookTests
 $ python unittest.py booktests.BookTests.runTest



Ran 1 test in 0.000s


For this command to work as shown, the module unittests.py must be present in the Python search path specified by the environment variable $PYTHONPATH .

Making BookTests fail by changing the test assert statement to self.assertEqual ( " Bad", book1.title ) demonstrates PyUnit's test failure reporting, as shown in Example 9-4.

Example 9-4. BookTests failure
 $ python unittest.py booktests.BookTests.runTest



FAIL: Test book creation


Traceback (most recent call last):

  File "/cygdrive/c/work/UnitTestFrameworks/Python/example1/booktests.


line 11, in runTest

    self.assertEqual( "Bad", book1.title )

  File "/cygdrive/c/work/UnitTestFrameworks/Python/example1/unittest.


line 302, in failUnlessEqual

    raise self.failureException, \

AssertionError: 'Bad' != 'Cosmos'


Ran 1 test in 0.000s

FAILED (failures=1) 

The failure report includes the test description Test book creation , as well as the specific assert condition that failed.

Rather than overriding runTest( ) , it is far more common to create uniquely named test methods. This allows building test classes with multiple test methods. Example 9-5 shows BookTests redesigned this way.

Example 9-5. Redesigned BookTest

"""Unit test for book.py"""

import book

import unittest

class  BookTests  (unittest.TestCase):

   def  testCreateBook  (self):

      """Test book creation"""

      book1 = book.Book( "Cosmos", "Carl Sagan" )

      self.assertEqual( "Cosmos", book1.title )

if __name__ == '__main_  _':

   unittest.main( ) 

The additional two lines of code at the end allow the test to be run directly without using unittest.py , as shown in Example 9-6. All methods that have names starting with test are found and run.

Example 9-6. Running BookTest directly
 $ python booktests.py



Ran 1 test in 0.000s


With this approach, multiple test methods can be added to a test class. If they share objects, test fixture behavior should be implemented using the setUp() and tearDown( ) methods. Example 9-7 shows the test fixture LibraryTests .

Example 9-7. . The test class LibraryTests

"""Unit test for library.py"""

import book

import library

import unittest

class  LibraryTests  (unittest.TestCase):

   def  setUp  (self):

      self.library = library.Library( )

      book1 = book.Book( "Cosmos", "Carl Sagan" )

      self.library.addBook( book1 )

      book2 = book.Book( "Contact", "Carl Sagan" )

      self.library.addBook( book2 )

   def  tearDown  (self):

      self.library.dispose( )

   def  testGetNumBooks  (self):

      """Test getting number of books"""

      self.  assert_  ( self.library.getNumBooks( )==2 )

   def  testGetBook  (self):

      """Test getting a book from library"""

      book2 = self.library.getBook( "Cosmos" )

      self.assertNotEqual( None, book2, "Book not found" ) 

The setUp( ) method creates a Library and adds two Book s to it, and tearDown( ) disposes of the Library . The test method testGetNumBooks( ) uses the test assert method assert_() to check the library's size . This is the most generic type of test assert, as it simply checks whether its argument evaluates to true .

Example 9-8 shows the Library class that is tested by LibraryTest .

Example 9-8. The Library class

class  NonexistentBookError  (Exception):

   """Exception thrown for missing book"""


class  Library  :

   """A library"""

   def  __init_  _  (self):

      self._  _books = dict( )

   def  dispose  (self):

      self._  _books.clear( )

   def  addBook  (self, book):

      """Add a book"""

      self._  _books[book.title] = book

   def  getBook  (self, title):

      """Find a book by title"""

      return self._  _books.get(title)

   def  removeBook  (self, title):

      """Remove a book"""

      if self._  _books.has_key(title):

         self._  _books.pop(title)


         raise NonexistentBookError

   def  getNumBooks  (self):

      """Get number of books"""

      return len(self._  _books) 

Library uses the Python dictionary object dict( ) to contain a collection of Book s. The module library.py also defines the exception class NonexistentBookError . This type of exception is thrown by the method removeBook( ) if it cannot find the Book to remove.

The failUnlessRaises() test assert method can be used to check for expected exception behavior, as shown in Example 9-9.

Example 9-9. Testing for an expected exception

   def  testRemoveNonexistentBook  (self):

      """Test expected exception from removing a nonexistent book"""

      self.  failUnlessRaises  (library.NonexistentBookError,

         self.library.removeBook, "Nonexistent" ) 

The arguments passed to failUnlessRaises( ) are an exception type, a callable object, and a variable argument list. In this example, the exception type is NonexistentBookError and the callable object is the function removeBook( ) . The object is called with the specified argument list. If an exception of the given exception type is thrown, the test passes . If no exception is thrown, or some other type of error occurs, the test fails.

Multiple tests may be aggregated using TestSuite . Example 9-10 adds a function named suite() to create a TestSuite containing LibraryTest 's test methods and changes the call to run the suite to unittest.main() .

Example 9-10. Creating and running a TestSuite

def  suite  ( ):

   suite = unittest.  TestSuite  ( )

   suite.  addTest  (LibraryTests("testGetNumBooks"))

   suite.  addTest  (LibraryTests("testGetBook"))

   suite.  addTest  (LibraryTests("testRemoveNonexistentBook"))

   return suite

if __name__ == '__main_  _':


Tests are added to a TestSuite using its addTest( ) method. It also has an addTests( ) method that allows multiple tests to be added at once.

PyUnit provides a convenience method, makeSuite() , which creates a TestSuite . It finds all methods named with a given prefix, such as test , and returns a suite containing them. Example 9-11 demonstrates makeSuite( ) .

Example 9-11. . Using makeSuite( ) to create a TestSuite

def  suite  ( ):

   suite = unittest.  makeSuite  (LibraryTests, "test")

   return suite 

It's often useful to create a module that builds TestSuite containing all the tests in each test class. Example 9-12 shows such a module, named alltests.py .

Example 9-12. Module to run all tests

import unittest

def  suite  ( ):

   modules_to_test = ('  booktests  ', '  librarytests  ')  alltests  = unittest.  TestSuite  ( )

   for module in map(__import_  _, modules_to_test):


   return  alltests  if __name__ == '__main_  _':


This example creates and runs a TestSuite named alltests that contains all the tests from booktests.py and librarytests.py .

Python includes a command-line interpreter for interactively running code. PyUnit tests can be run this way. Example 9-13 demonstrates using the interpreter to create and run a unit test.

Example 9-13. Running a test interactively
 $ python

>>> import unittest

>>> import librarytests

>>> runner = unittest.TextTestRunner( )

>>> test = librarytests.LibraryTests("testGetBook")

>>> runner.run(test)



Ran 1 test in 0.000s


<unittest._TextTestResult run=1 errors=0 failures=0> 

In this example, the modules unittest and librarytests are imported and a TextTestRunner is created. Next, a test containing the test method testGetBook( ) is created and run using the test runner.

A TestSuite can be created and run similarly, as shown in Example 9-14.

Example 9-14. Creating a TestSuite interactively
 >>> suite = unittest.makeSuite(librarytests.LibraryTests,'test')

>>> runner.run(suite)



Ran 5 tests in 0.001s


<unittest._TextTestResult run=5 errors=0 failures=0> 

Example 9-15 illustrates creating a test from BookTests and adding it to the TestSuite .

Example 9-15. Adding a test to the test suite
 >>> import booktests

>>> test2 = booktests.BookTests("testCreateBook")

>>> suite.addTest(test2)

>>> runner.run(suite)



Ran 6 tests in 0.001s


<unittest._TextTestResult run=6 errors=0 failures=0> 

The PyUnit GUI is implemented in the module unittestgui.py . It is not included with the standard Python libraries but is available in downloads from the PyUnit web site. It acts as a test runner, running test modules, classes, and methods, and displays a friendly green or red test results indicator, as well as failure details. It is shown in Figure 9-1.

Figure 9-1. The PyUnit GUI

The name of the test to run is entered at the top. The name can specify a module (e.g., librarytests ), a test class ( librarytests.LibraryTests ), or a test method ( librarytests.LibraryTests.testGetBook ). Except when a specific test method name is specified, all the methods in the module or class being tested that have names starting with test are run.