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