Lib/unittest.py

   1 #!/usr/bin/env python
   2 '''
   3 Python unit testing framework, based on Erich Gamma's JUnit and Kent Beck's
   4 Smalltalk testing framework.
   5
   6 This module contains the core framework classes that form the basis of
   7 specific test cases and suites (TestCase, TestSuite etc.), and also a
   8 text-based utility class for running the tests and reporting the results
   9  (TextTestRunner).
  10
  11 Simple usage:
  12
  13     import unittest
  14
  15     class IntegerArithmenticTestCase(unittest.TestCase):
  16         def testAdd(self):  ## test method names begin 'test*'
  17             self.assertEquals((1 + 2), 3)
  18             self.assertEquals(0 + 1, 1)
  19         def testMultiply(self):
  20             self.assertEquals((0 * 10), 0)
  21             self.assertEquals((5 * 8), 40)
  22
  23     if __name__ == '__main__':
  24         unittest.main()
  25
  26 Further information is available in the bundled documentation, and from
  27
  28   http://docs.python.org/lib/module-unittest.html
  29
  30 Copyright (c) 1999-2003 Steve Purcell
  31 This module is free software, and you may redistribute it and/or modify
  32 it under the same terms as Python itself, so long as this copyright message
  33 and disclaimer are retained in their original form.
  34
  35 IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
  36 SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF
  37 THIS CODE, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  38 DAMAGE.
  39
  40 THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT
  41 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  42 PARTICULAR PURPOSE.  THE CODE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS,
  43 AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
  44 SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  45 '''
  46
  47 __author__ = "Steve Purcell"
  48 __email__ = "stephen_purcell at yahoo dot com"
  49 __version__ = "#Revision: 1.63 $"[11:-2]
  50
  51 import time
  52 import sys
  53 import traceback
  54 import os
  55 import types
  56
  57 ##############################################################################
  58 # Exported classes and functions
  59 ##############################################################################
  60 __all__ = ['TestResult', 'TestCase', 'TestSuite', 'TextTestRunner',
  61            'TestLoader', 'FunctionTestCase', 'main', 'defaultTestLoader']
  62
  63 # Expose obsolete functions for backwards compatibility
  64 __all__.extend(['getTestCaseNames', 'makeSuite', 'findTestCases'])
  65
  66
  67 ##############################################################################
  68 # Backward compatibility
  69 ##############################################################################
  70 if sys.version_info[:2] < (2, 2):
  71     False, True = 0, 1
  72     def isinstance(obj, clsinfo):
  73         import __builtin__
  74         if type(clsinfo) in (tuple, list):
  75             for cls in clsinfo:
  76                 if cls is type: cls = types.ClassType
  77                 if __builtin__.isinstance(obj, cls):
  78                     return 1
  79             return 0
  80         else: return __builtin__.isinstance(obj, clsinfo)
  81
  82
  83 ##############################################################################
  84 # Test framework core
  85 ##############################################################################
  86
  87 # All classes defined herein are 'new-style' classes, allowing use of 'super()'
  88 __metaclass__ = type
  89
  90 def _strclass(cls):
  91     return "%s.%s" % (cls.__module__, cls.__name__)
  92
  93 __unittest = 1
  94
  95 class TestResult:
  96     """Holder for test result information.
  97
  98     Test results are automatically managed by the TestCase and TestSuite
  99     classes, and do not need to be explicitly manipulated by writers of tests.
 100
 101     Each instance holds the total number of tests run, and collections of
 102     failures and errors that occurred among those test runs. The collections
 103     contain tuples of (testcase, exceptioninfo), where exceptioninfo is the
 104     formatted traceback of the error that occurred.
 105     """
 106     def __init__(self):
 107         self.failures = []
 108         self.errors = []
 109         self.testsRun = 0
 110         self.shouldStop = False
 111
 112     def startTest(self, test):
 113         "Called when the given test is about to be run"
 114         self.testsRun = self.testsRun + 1
 115
 116     def stopTest(self, test):
 117         "Called when the given test has been run"
 118         pass
 119
 120     def addError(self, test, err):
 121         """Called when an error has occurred. 'err' is a tuple of values as
 122         returned by sys.exc_info().
 123         """
 124         self.errors.append((test, self._exc_info_to_string(err, test)))
 125
 126     def addFailure(self, test, err):
 127         """Called when an error has occurred. 'err' is a tuple of values as
 128         returned by sys.exc_info()."""
 129         self.failures.append((test, self._exc_info_to_string(err, test)))
 130
 131     def addSuccess(self, test):
 132         "Called when a test has completed successfully"
 133         pass
 134
 135     def wasSuccessful(self):
 136         "Tells whether or not this result was a success"
 137         return len(self.failures) == len(self.errors) == 0
 138
 139     def stop(self):
 140         "Indicates that the tests should be aborted"
 141         self.shouldStop = True
 142
 143     def _exc_info_to_string(self, err, test):
 144         """Converts a sys.exc_info()-style tuple of values into a string."""
 145         exctype, value, tb = err
 146         # Skip test runner traceback levels
 147         while tb and self._is_relevant_tb_level(tb):
 148             tb = tb.tb_next
 149         if exctype is test.failureException:
 150             # Skip assert*() traceback levels
 151             length = self._count_relevant_tb_levels(tb)
 152             return ''.join(traceback.format_exception(exctype, value, tb, length))
 153         return ''.join(traceback.format_exception(exctype, value, tb))
 154
 155     def _is_relevant_tb_level(self, tb):
 156         return tb.tb_frame.f_globals.has_key('__unittest')
 157
 158     def _count_relevant_tb_levels(self, tb):
 159         length = 0
 160         while tb and not self._is_relevant_tb_level(tb):
 161             length += 1
 162             tb = tb.tb_next
 163         return length
 164
 165     def __repr__(self):
 166         return "<%s run=%i errors=%i failures=%i>" % \
 167                (_strclass(self.__class__), self.testsRun, len(self.errors),
 168                 len(self.failures))
 169
 170 class TestCase:
 171     """A class whose instances are single test cases.
 172
 173     By default, the test code itself should be placed in a method named
 174     'runTest'.
 175
 176     If the fixture may be used for many test cases, create as
 177     many test methods as are needed. When instantiating such a TestCase
 178     subclass, specify in the constructor arguments the name of the test method
 179     that the instance is to execute.
 180
 181     Test authors should subclass TestCase for their own tests. Construction
 182     and deconstruction of the test's environment ('fixture') can be
 183     implemented by overriding the 'setUp' and 'tearDown' methods respectively.
 184
 185     If it is necessary to override the __init__ method, the base class
 186     __init__ method must always be called. It is important that subclasses
 187     should not change the signature of their __init__ method, since instances
 188     of the classes are instantiated automatically by parts of the framework
 189     in order to be run.
 190     """
 191
 192     # This attribute determines which exception will be raised when
 193     # the instance's assertion methods fail; test methods raising this
 194     # exception will be deemed to have 'failed' rather than 'errored'
 195
 196     failureException = AssertionError
 197
 198     def __init__(self, methodName='runTest'):
 199         """Create an instance of the class that will use the named test
 200            method when executed. Raises a ValueError if the instance does
 201            not have a method with the specified name.
 202         """
 203         try:
 204             self._testMethodName = methodName
 205             testMethod = getattr(self, methodName)
 206             self._testMethodDoc = testMethod.__doc__
 207         except AttributeError:
 208             raise ValueError, "no such test method in %s: %s" % \
 209                   (self.__class__, methodName)
 210
 211     def setUp(self):
 212         "Hook method for setting up the test fixture before exercising it."
 213         pass
 214
 215     def tearDown(self):
 216         "Hook method for deconstructing the test fixture after testing it."
 217         pass
 218
 219     def countTestCases(self):
 220         return 1
 221
 222     def defaultTestResult(self):
 223         return TestResult()
 224
 225     def shortDescription(self):
 226         """Returns a one-line description of the test, or None if no
 227         description has been provided.
 228
 229         The default implementation of this method returns the first line of
 230         the specified test method's docstring.
 231         """
 232         doc = self._testMethodDoc
 233         return doc and doc.split("\n")[0].strip() or None
 234
 235     def id(self):
 236         return "%s.%s" % (_strclass(self.__class__), self._testMethodName)
 237
 238     def __eq__(self, other):
 239         if type(self) is not type(other):
 240             return False
 241
 242         return self._testMethodName == other._testMethodName
 243
 244     def __ne__(self, other):
 245         return not self == other
 246
 247     def __hash__(self):
 248         return hash((type(self), self._testMethodName))
 249
 250     def __str__(self):
 251         return "%s (%s)" % (self._testMethodName, _strclass(self.__class__))
 252
 253     def __repr__(self):
 254         return "<%s testMethod=%s>" % \
 255                (_strclass(self.__class__), self._testMethodName)
 256
 257     def run(self, result=None):
 258         if result is None: result = self.defaultTestResult()
 259         result.startTest(self)
 260         testMethod = getattr(self, self._testMethodName)
 261         try:
 262             try:
 263                 self.setUp()
 264             except KeyboardInterrupt:
 265                 raise
 266             except:
 267                 result.addError(self, self._exc_info())
 268                 return
 269
 270             ok = False
 271             try:
 272                 testMethod()
 273                 ok = True
 274             except self.failureException:
 275                 result.addFailure(self, self._exc_info())
 276             except KeyboardInterrupt:
 277                 raise
 278             except:
 279                 result.addError(self, self._exc_info())
 280
 281             try:
 282                 self.tearDown()
 283             except KeyboardInterrupt:
 284                 raise
 285             except:
 286                 result.addError(self, self._exc_info())
 287                 ok = False
 288             if ok: result.addSuccess(self)
 289         finally:
 290             result.stopTest(self)
 291
 292     def __call__(self, *args, **kwds):
 293         return self.run(*args, **kwds)
 294
 295     def debug(self):
 296         """Run the test without collecting errors in a TestResult"""
 297         self.setUp()
 298         getattr(self, self._testMethodName)()
 299         self.tearDown()
 300
 301     def _exc_info(self):
 302         """Return a version of sys.exc_info() with the traceback frame
 303            minimised; usually the top level of the traceback frame is not
 304            needed.
 305         """
 306         return sys.exc_info()
 307
 308     def fail(self, msg=None):
 309         """Fail immediately, with the given message."""
 310         raise self.failureException, msg
 311
 312     def failIf(self, expr, msg=None):
 313         "Fail the test if the expression is true."
 314         if expr: raise self.failureException, msg
 315
 316     def failUnless(self, expr, msg=None):
 317         """Fail the test unless the expression is true."""
 318         if not expr: raise self.failureException, msg
 319
 320     def failUnlessRaises(self, excClass, callableObj, *args, **kwargs):
 321         """Fail unless an exception of class excClass is thrown
 322            by callableObj when invoked with arguments args and keyword
 323            arguments kwargs. If a different type of exception is
 324            thrown, it will not be caught, and the test case will be
 325            deemed to have suffered an error, exactly as for an
 326            unexpected exception.
 327         """
 328         try:
 329             callableObj(*args, **kwargs)
 330         except excClass:
 331             return
 332         else:
 333             if hasattr(excClass,'__name__'): excName = excClass.__name__
 334             else: excName = str(excClass)
 335             raise self.failureException, "%s not raised" % excName
 336
 337     def failUnlessEqual(self, first, second, msg=None):
 338         """Fail if the two objects are unequal as determined by the '=='
 339            operator.
 340         """
 341         if not first == second:
 342             raise self.failureException, \
 343                   (msg or '%r != %r' % (first, second))
 344
 345     def failIfEqual(self, first, second, msg=None):
 346         """Fail if the two objects are equal as determined by the '=='
 347            operator.
 348         """
 349         if first == second:
 350             raise self.failureException, \
 351                   (msg or '%r == %r' % (first, second))
 352
 353     def failUnlessAlmostEqual(self, first, second, places=7, msg=None):
 354         """Fail if the two objects are unequal as determined by their
 355            difference rounded to the given number of decimal places
 356            (default 7) and comparing to zero.
 357
 358            Note that decimal places (from zero) are usually not the same
 359            as significant digits (measured from the most signficant digit).
 360         """
 361         if round(abs(second-first), places) != 0:
 362             raise self.failureException, \
 363                   (msg or '%r != %r within %r places' % (first, second, places))
 364
 365     def failIfAlmostEqual(self, first, second, places=7, msg=None):
 366         """Fail if the two objects are equal as determined by their
 367            difference rounded to the given number of decimal places
 368            (default 7) and comparing to zero.
 369
 370            Note that decimal places (from zero) are usually not the same
 371            as significant digits (measured from the most signficant digit).
 372         """
 373         if round(abs(second-first), places) == 0:
 374             raise self.failureException, \
 375                   (msg or '%r == %r within %r places' % (first, second, places))
 376
 377     # Synonyms for assertion methods
 378
 379     assertEqual = assertEquals = failUnlessEqual
 380
 381     assertNotEqual = assertNotEquals = failIfEqual
 382
 383     assertAlmostEqual = assertAlmostEquals = failUnlessAlmostEqual
 384
 385     assertNotAlmostEqual = assertNotAlmostEquals = failIfAlmostEqual
 386
 387     assertRaises = failUnlessRaises
 388
 389     assert_ = assertTrue = failUnless
 390
 391     assertFalse = failIf
 392
 393
 394
 395 class TestSuite:
 396     """A test suite is a composite test consisting of a number of TestCases.
 397
 398     For use, create an instance of TestSuite, then add test case instances.
 399     When all tests have been added, the suite can be passed to a test
 400     runner, such as TextTestRunner. It will run the individual test cases
 401     in the order in which they were added, aggregating the results. When
 402     subclassing, do not forget to call the base class constructor.
 403     """
 404     def __init__(self, tests=()):
 405         self._tests = []
 406         self.addTests(tests)
 407
 408     def __repr__(self):
 409         return "<%s tests=%s>" % (_strclass(self.__class__), self._tests)
 410
 411     __str__ = __repr__
 412
 413     def __eq__(self, other):
 414         if type(self) is not type(other):
 415             return False
 416         return self._tests == other._tests
 417
 418     def __ne__(self, other):
 419         return not self == other
 420
 421     def __iter__(self):
 422         return iter(self._tests)
 423
 424     def countTestCases(self):
 425         cases = 0
 426         for test in self._tests:
 427             cases += test.countTestCases()
 428         return cases
 429
 430     def addTest(self, test):
 431         # sanity checks
 432         if not callable(test):
 433             raise TypeError("the test to add must be callable")
 434         if (isinstance(test, (type, types.ClassType)) and
 435             issubclass(test, (TestCase, TestSuite))):
 436             raise TypeError("TestCases and TestSuites must be instantiated "
 437                             "before passing them to addTest()")
 438         self._tests.append(test)
 439
 440     def addTests(self, tests):
 441         if isinstance(tests, basestring):
 442             raise TypeError("tests must be an iterable of tests, not a string")
 443         for test in tests:
 444             self.addTest(test)
 445
 446     def run(self, result):
 447         for test in self._tests:
 448             if result.shouldStop:
 449                 break
 450             test(result)
 451         return result
 452
 453     def __call__(self, *args, **kwds):
 454         return self.run(*args, **kwds)
 455
 456     def debug(self):
 457         """Run the tests without collecting errors in a TestResult"""
 458         for test in self._tests: test.debug()
 459
 460
 461 class FunctionTestCase(TestCase):
 462     """A test case that wraps a test function.
 463
 464     This is useful for slipping pre-existing test functions into the
 465     unittest framework. Optionally, set-up and tidy-up functions can be
 466     supplied. As with TestCase, the tidy-up ('tearDown') function will
 467     always be called if the set-up ('setUp') function ran successfully.
 468     """
 469
 470     def __init__(self, testFunc, setUp=None, tearDown=None,
 471                  description=None):
 472         TestCase.__init__(self)
 473         self.__setUpFunc = setUp
 474         self.__tearDownFunc = tearDown
 475         self.__testFunc = testFunc
 476         self.__description = description
 477
 478     def setUp(self):
 479         if self.__setUpFunc is not None:
 480             self.__setUpFunc()
 481
 482     def tearDown(self):
 483         if self.__tearDownFunc is not None:
 484             self.__tearDownFunc()
 485
 486     def runTest(self):
 487         self.__testFunc()
 488
 489     def id(self):
 490         return self.__testFunc.__name__
 491
 492     def __eq__(self, other):
 493         if type(self) is not type(other):
 494             return False
 495
 496         return self.__setUpFunc == other.__setUpFunc and \
 497                self.__tearDownFunc == other.__tearDownFunc and \
 498                self.__testFunc == other.__testFunc and \
 499                self.__description == other.__description
 500
 501     def __ne__(self, other):
 502         return not self == other
 503
 504     def __hash__(self):
 505         return hash((type(self), self.__setUpFunc, self.__tearDownFunc,
 506                                            self.__testFunc, self.__description))
 507
 508     def __str__(self):
 509         return "%s (%s)" % (_strclass(self.__class__), self.__testFunc.__name__)
 510
 511     def __repr__(self):
 512         return "<%s testFunc=%s>" % (_strclass(self.__class__), self.__testFunc)
 513
 514     def shortDescription(self):
 515         if self.__description is not None: return self.__description
 516         doc = self.__testFunc.__doc__
 517         return doc and doc.split("\n")[0].strip() or None
 518
 519
 520
 521 ##############################################################################
 522 # Locating and loading tests
 523 ##############################################################################
 524
 525 class TestLoader:
 526     """This class is responsible for loading tests according to various
 527     criteria and returning them wrapped in a TestSuite
 528     """
 529     testMethodPrefix = 'test'
 530     sortTestMethodsUsing = cmp
 531     suiteClass = TestSuite
 532
 533     def loadTestsFromTestCase(self, testCaseClass):
 534         """Return a suite of all tests cases contained in testCaseClass"""
 535         if issubclass(testCaseClass, TestSuite):
 536             raise TypeError("Test cases should not be derived from TestSuite. Maybe you meant to derive from TestCase?")
 537         testCaseNames = self.getTestCaseNames(testCaseClass)
 538         if not testCaseNames and hasattr(testCaseClass, 'runTest'):
 539             testCaseNames = ['runTest']
 540         return self.suiteClass(map(testCaseClass, testCaseNames))
 541
 542     def loadTestsFromModule(self, module):
 543         """Return a suite of all tests cases contained in the given module"""
 544         tests = []
 545         for name in dir(module):
 546             obj = getattr(module, name)
 547             if (isinstance(obj, (type, types.ClassType)) and
 548                 issubclass(obj, TestCase)):
 549                 tests.append(self.loadTestsFromTestCase(obj))
 550         return self.suiteClass(tests)
 551
 552     def loadTestsFromName(self, name, module=None):
 553         """Return a suite of all tests cases given a string specifier.
 554
 555         The name may resolve either to a module, a test case class, a
 556         test method within a test case class, or a callable object which
 557         returns a TestCase or TestSuite instance.
 558
 559         The method optionally resolves the names relative to a given module.
 560         """
 561         parts = name.split('.')
 562         if module is None:
 563             parts_copy = parts[:]
 564             while parts_copy:
 565                 try:
 566                     module = __import__('.'.join(parts_copy))
 567                     break
 568                 except ImportError:
 569                     del parts_copy[-1]
 570                     if not parts_copy: raise
 571             parts = parts[1:]
 572         obj = module
 573         for part in parts:
 574             parent, obj = obj, getattr(obj, part)
 575
 576         if type(obj) == types.ModuleType:
 577             return self.loadTestsFromModule(obj)
 578         elif (isinstance(obj, (type, types.ClassType)) and
 579               issubclass(obj, TestCase)):
 580             return self.loadTestsFromTestCase(obj)
 581         elif (type(obj) == types.UnboundMethodType and
 582               isinstance(parent, (type, types.ClassType)) and
 583               issubclass(parent, TestCase)):
 584             return TestSuite([parent(obj.__name__)])
 585         elif isinstance(obj, TestSuite):
 586             return obj
 587         elif callable(obj):
 588             test = obj()
 589             if isinstance(test, TestSuite):
 590                 return test
 591             elif isinstance(test, TestCase):
 592                 return TestSuite([test])
 593             else:
 594                 raise TypeError("calling %s returned %s, not a test" %
 595                                 (obj, test))
 596         else:
 597             raise TypeError("don't know how to make test from: %s" % obj)
 598
 599     def loadTestsFromNames(self, names, module=None):
 600         """Return a suite of all tests cases found using the given sequence
 601         of string specifiers. See 'loadTestsFromName()'.
 602         """
 603         suites = [self.loadTestsFromName(name, module) for name in names]
 604         return self.suiteClass(suites)
 605
 606     def getTestCaseNames(self, testCaseClass):
 607         """Return a sorted sequence of method names found within testCaseClass
 608         """
 609         def isTestMethod(attrname, testCaseClass=testCaseClass, prefix=self.testMethodPrefix):
 610             return attrname.startswith(prefix) and callable(getattr(testCaseClass, attrname))
 611         testFnNames = filter(isTestMethod, dir(testCaseClass))
 612         if self.sortTestMethodsUsing:
 613             testFnNames.sort(self.sortTestMethodsUsing)
 614         return testFnNames
 615
 616
 617
 618 defaultTestLoader = TestLoader()
 619
 620
 621 ##############################################################################
 622 # Patches for old functions: these functions should be considered obsolete
 623 ##############################################################################
 624
 625 def _makeLoader(prefix, sortUsing, suiteClass=None):
 626     loader = TestLoader()
 627     loader.sortTestMethodsUsing = sortUsing
 628     loader.testMethodPrefix = prefix
 629     if suiteClass: loader.suiteClass = suiteClass
 630     return loader
 631
 632 def getTestCaseNames(testCaseClass, prefix, sortUsing=cmp):
 633     return _makeLoader(prefix, sortUsing).getTestCaseNames(testCaseClass)
 634
 635 def makeSuite(testCaseClass, prefix='test', sortUsing=cmp, suiteClass=TestSuite):
 636     return _makeLoader(prefix, sortUsing, suiteClass).loadTestsFromTestCase(testCaseClass)
 637
 638 def findTestCases(module, prefix='test', sortUsing=cmp, suiteClass=TestSuite):
 639     return _makeLoader(prefix, sortUsing, suiteClass).loadTestsFromModule(module)
 640
 641
 642 ##############################################################################
 643 # Text UI
 644 ##############################################################################
 645
 646 class _WritelnDecorator:
 647     """Used to decorate file-like objects with a handy 'writeln' method"""
 648     def __init__(self,stream):
 649         self.stream = stream
 650
 651     def __getattr__(self, attr):
 652         return getattr(self.stream,attr)
 653
 654     def writeln(self, arg=None):
 655         if arg: self.write(arg)
 656         self.write('\n') # text-mode streams translate to \r\n if needed
 657
 658
 659 class _TextTestResult(TestResult):
 660     """A test result class that can print formatted text results to a stream.
 661
 662     Used by TextTestRunner.
 663     """
 664     separator1 = '=' * 70
 665     separator2 = '-' * 70
 666
 667     def __init__(self, stream, descriptions, verbosity):
 668         TestResult.__init__(self)
 669         self.stream = stream
 670         self.showAll = verbosity > 1
 671         self.dots = verbosity == 1
 672         self.descriptions = descriptions
 673
 674     def getDescription(self, test):
 675         if self.descriptions:
 676             return test.shortDescription() or str(test)
 677         else:
 678             return str(test)
 679
 680     def startTest(self, test):
 681         TestResult.startTest(self, test)
 682         if self.showAll:
 683             self.stream.write(self.getDescription(test))
 684             self.stream.write(" ... ")
 685
 686     def addSuccess(self, test):
 687         TestResult.addSuccess(self, test)
 688         if self.showAll:
 689             self.stream.writeln("ok")
 690         elif self.dots:
 691             self.stream.write('.')
 692
 693     def addError(self, test, err):
 694         TestResult.addError(self, test, err)
 695         if self.showAll:
 696             self.stream.writeln("ERROR")
 697         elif self.dots:
 698             self.stream.write('E')
 699
 700     def addFailure(self, test, err):
 701         TestResult.addFailure(self, test, err)
 702         if self.showAll:
 703             self.stream.writeln("FAIL")
 704         elif self.dots:
 705             self.stream.write('F')
 706
 707     def printErrors(self):
 708         if self.dots or self.showAll:
 709             self.stream.writeln()
 710         self.printErrorList('ERROR', self.errors)
 711         self.printErrorList('FAIL', self.failures)
 712
 713     def printErrorList(self, flavour, errors):
 714         for test, err in errors:
 715             self.stream.writeln(self.separator1)
 716             self.stream.writeln("%s: %s" % (flavour,self.getDescription(test)))
 717             self.stream.writeln(self.separator2)
 718             self.stream.writeln("%s" % err)
 719
 720
 721 class TextTestRunner:
 722     """A test runner class that displays results in textual form.
 723
 724     It prints out the names of tests as they are run, errors as they
 725     occur, and a summary of the results at the end of the test run.
 726     """
 727     def __init__(self, stream=sys.stderr, descriptions=1, verbosity=1):
 728         self.stream = _WritelnDecorator(stream)
 729         self.descriptions = descriptions
 730         self.verbosity = verbosity
 731
 732     def _makeResult(self):
 733         return _TextTestResult(self.stream, self.descriptions, self.verbosity)
 734
 735     def run(self, test):
 736         "Run the given test case or test suite."
 737         result = self._makeResult()
 738         startTime = time.time()
 739         test(result)
 740         stopTime = time.time()
 741         timeTaken = stopTime - startTime
 742         result.printErrors()
 743         self.stream.writeln(result.separator2)
 744         run = result.testsRun
 745         self.stream.writeln("Ran %d test%s in %.3fs" %
 746                             (run, run != 1 and "s" or "", timeTaken))
 747         self.stream.writeln()
 748         if not result.wasSuccessful():
 749             self.stream.write("FAILED (")
 750             failed, errored = map(len, (result.failures, result.errors))
 751             if failed:
 752                 self.stream.write("failures=%d" % failed)
 753             if errored:
 754                 if failed: self.stream.write(", ")
 755                 self.stream.write("errors=%d" % errored)
 756             self.stream.writeln(")")
 757         else:
 758             self.stream.writeln("OK")
 759         return result
 760
 761
 762
 763 ##############################################################################
 764 # Facilities for running tests from the command line
 765 ##############################################################################
 766
 767 class TestProgram:
 768     """A command-line program that runs a set of tests; this is primarily
 769        for making test modules conveniently executable.
 770     """
 771     USAGE = """\
 772 Usage: %(progName)s [options] [test] [...]
 773
 774 Options:
 775   -h, --help       Show this message
 776   -v, --verbose    Verbose output
 777   -q, --quiet      Minimal output
 778
 779 Examples:
 780   %(progName)s                               - run default set of tests
 781   %(progName)s MyTestSuite                   - run suite 'MyTestSuite'
 782   %(progName)s MyTestCase.testSomething      - run MyTestCase.testSomething
 783   %(progName)s MyTestCase                    - run all 'test*' test methods
 784                                                in MyTestCase
 785 """
 786     def __init__(self, module='__main__', defaultTest=None,
 787                  argv=None, testRunner=TextTestRunner,
 788                  testLoader=defaultTestLoader):
 789         if type(module) == type(''):
 790             self.module = __import__(module)
 791             for part in module.split('.')[1:]:
 792                 self.module = getattr(self.module, part)
 793         else:
 794             self.module = module
 795         if argv is None:
 796             argv = sys.argv
 797         self.verbosity = 1
 798         self.defaultTest = defaultTest
 799         self.testRunner = testRunner
 800         self.testLoader = testLoader
 801         self.progName = os.path.basename(argv[0])
 802         self.parseArgs(argv)
 803         self.runTests()
 804
 805     def usageExit(self, msg=None):
 806         if msg: print msg
 807         print self.USAGE % self.__dict__
 808         sys.exit(2)
 809
 810     def parseArgs(self, argv):
 811         import getopt
 812         try:
 813             options, args = getopt.getopt(argv[1:], 'hHvq',
 814                                           ['help','verbose','quiet'])
 815             for opt, value in options:
 816                 if opt in ('-h','-H','--help'):
 817                     self.usageExit()
 818                 if opt in ('-q','--quiet'):
 819                     self.verbosity = 0
 820                 if opt in ('-v','--verbose'):
 821                     self.verbosity = 2
 822             if len(args) == 0 and self.defaultTest is None:
 823                 self.test = self.testLoader.loadTestsFromModule(self.module)
 824                 return
 825             if len(args) > 0:
 826                 self.testNames = args
 827             else:
 828                 self.testNames = (self.defaultTest,)
 829             self.createTests()
 830         except getopt.error, msg:
 831             self.usageExit(msg)
 832
 833     def createTests(self):
 834         self.test = self.testLoader.loadTestsFromNames(self.testNames,
 835                                                        self.module)
 836
 837     def runTests(self):
 838         if isinstance(self.testRunner, (type, types.ClassType)):
 839             try:
 840                 testRunner = self.testRunner(verbosity=self.verbosity)
 841             except TypeError:
 842                 # didn't accept the verbosity argument
 843                 testRunner = self.testRunner()
 844         else:
 845             # it is assumed to be a TestRunner instance
 846             testRunner = self.testRunner
 847         result = testRunner.run(self.test)
 848         sys.exit(not result.wasSuccessful())
 849
 850 main = TestProgram
 851
 852
 853 ##############################################################################
 854 # Executing this module from the command line
 855 ##############################################################################
 856
 857 if __name__ == "__main__":
 858     main(module=None)