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     # Can't guarantee hash invariant, so flag as unhashable
 429     __hash__ = None
 430
 431     def __iter__(self):
 432         return iter(self._tests)
 433
 434     def countTestCases(self):
 435         cases = 0
 436         for test in self._tests:
 437             cases += test.countTestCases()
 438         return cases
 439
 440     def addTest(self, test):
 441         # sanity checks
 442         if not hasattr(test, '__call__'):
 443             raise TypeError("the test to add must be callable")
 444         if (isinstance(test, (type, types.ClassType)) and
 445             issubclass(test, (TestCase, TestSuite))):
 446             raise TypeError("TestCases and TestSuites must be instantiated "
 447                             "before passing them to addTest()")
 448         self._tests.append(test)
 449
 450     def addTests(self, tests):
 451         if isinstance(tests, basestring):
 452             raise TypeError("tests must be an iterable of tests, not a string")
 453         for test in tests:
 454             self.addTest(test)
 455
 456     def run(self, result):
 457         for test in self._tests:
 458             if result.shouldStop:
 459                 break
 460             test(result)
 461         return result
 462
 463     def __call__(self, *args, **kwds):
 464         return self.run(*args, **kwds)
 465
 466     def debug(self):
 467         """Run the tests without collecting errors in a TestResult"""
 468         for test in self._tests: test.debug()
 469
 470
 471 class FunctionTestCase(TestCase):
 472     """A test case that wraps a test function.
 473
 474     This is useful for slipping pre-existing test functions into the
 475     unittest framework. Optionally, set-up and tidy-up functions can be
 476     supplied. As with TestCase, the tidy-up ('tearDown') function will
 477     always be called if the set-up ('setUp') function ran successfully.
 478     """
 479
 480     def __init__(self, testFunc, setUp=None, tearDown=None,
 481                  description=None):
 482         TestCase.__init__(self)
 483         self.__setUpFunc = setUp
 484         self.__tearDownFunc = tearDown
 485         self.__testFunc = testFunc
 486         self.__description = description
 487
 488     def setUp(self):
 489         if self.__setUpFunc is not None:
 490             self.__setUpFunc()
 491
 492     def tearDown(self):
 493         if self.__tearDownFunc is not None:
 494             self.__tearDownFunc()
 495
 496     def runTest(self):
 497         self.__testFunc()
 498
 499     def id(self):
 500         return self.__testFunc.__name__
 501
 502     def __eq__(self, other):
 503         if type(self) is not type(other):
 504             return False
 505
 506         return self.__setUpFunc == other.__setUpFunc and \
 507                self.__tearDownFunc == other.__tearDownFunc and \
 508                self.__testFunc == other.__testFunc and \
 509                self.__description == other.__description
 510
 511     def __ne__(self, other):
 512         return not self == other
 513
 514     def __hash__(self):
 515         return hash((type(self), self.__setUpFunc, self.__tearDownFunc,
 516                                            self.__testFunc, self.__description))
 517
 518     def __str__(self):
 519         return "%s (%s)" % (_strclass(self.__class__), self.__testFunc.__name__)
 520
 521     def __repr__(self):
 522         return "<%s testFunc=%s>" % (_strclass(self.__class__), self.__testFunc)
 523
 524     def shortDescription(self):
 525         if self.__description is not None: return self.__description
 526         doc = self.__testFunc.__doc__
 527         return doc and doc.split("\n")[0].strip() or None
 528
 529
 530
 531 ##############################################################################
 532 # Locating and loading tests
 533 ##############################################################################
 534
 535 class TestLoader:
 536     """This class is responsible for loading tests according to various
 537     criteria and returning them wrapped in a TestSuite
 538     """
 539     testMethodPrefix = 'test'
 540     sortTestMethodsUsing = cmp
 541     suiteClass = TestSuite
 542
 543     def loadTestsFromTestCase(self, testCaseClass):
 544         """Return a suite of all tests cases contained in testCaseClass"""
 545         if issubclass(testCaseClass, TestSuite):
 546             raise TypeError("Test cases should not be derived from TestSuite. Maybe you meant to derive from TestCase?")
 547         testCaseNames = self.getTestCaseNames(testCaseClass)
 548         if not testCaseNames and hasattr(testCaseClass, 'runTest'):
 549             testCaseNames = ['runTest']
 550         return self.suiteClass(map(testCaseClass, testCaseNames))
 551
 552     def loadTestsFromModule(self, module):
 553         """Return a suite of all tests cases contained in the given module"""
 554         tests = []
 555         for name in dir(module):
 556             obj = getattr(module, name)
 557             if (isinstance(obj, (type, types.ClassType)) and
 558                 issubclass(obj, TestCase)):
 559                 tests.append(self.loadTestsFromTestCase(obj))
 560         return self.suiteClass(tests)
 561
 562     def loadTestsFromName(self, name, module=None):
 563         """Return a suite of all tests cases given a string specifier.
 564
 565         The name may resolve either to a module, a test case class, a
 566         test method within a test case class, or a callable object which
 567         returns a TestCase or TestSuite instance.
 568
 569         The method optionally resolves the names relative to a given module.
 570         """
 571         parts = name.split('.')
 572         if module is None:
 573             parts_copy = parts[:]
 574             while parts_copy:
 575                 try:
 576                     module = __import__('.'.join(parts_copy))
 577                     break
 578                 except ImportError:
 579                     del parts_copy[-1]
 580                     if not parts_copy: raise
 581             parts = parts[1:]
 582         obj = module
 583         for part in parts:
 584             parent, obj = obj, getattr(obj, part)
 585
 586         if type(obj) == types.ModuleType:
 587             return self.loadTestsFromModule(obj)
 588         elif (isinstance(obj, (type, types.ClassType)) and
 589               issubclass(obj, TestCase)):
 590             return self.loadTestsFromTestCase(obj)
 591         elif (type(obj) == types.UnboundMethodType and
 592               isinstance(parent, (type, types.ClassType)) and
 593               issubclass(parent, TestCase)):
 594             return TestSuite([parent(obj.__name__)])
 595         elif isinstance(obj, TestSuite):
 596             return obj
 597         elif hasattr(obj, '__call__'):
 598             test = obj()
 599             if isinstance(test, TestSuite):
 600                 return test
 601             elif isinstance(test, TestCase):
 602                 return TestSuite([test])
 603             else:
 604                 raise TypeError("calling %s returned %s, not a test" %
 605                                 (obj, test))
 606         else:
 607             raise TypeError("don't know how to make test from: %s" % obj)
 608
 609     def loadTestsFromNames(self, names, module=None):
 610         """Return a suite of all tests cases found using the given sequence
 611         of string specifiers. See 'loadTestsFromName()'.
 612         """
 613         suites = [self.loadTestsFromName(name, module) for name in names]
 614         return self.suiteClass(suites)
 615
 616     def getTestCaseNames(self, testCaseClass):
 617         """Return a sorted sequence of method names found within testCaseClass
 618         """
 619         def isTestMethod(attrname, testCaseClass=testCaseClass, prefix=self.testMethodPrefix):
 620             return attrname.startswith(prefix) and hasattr(getattr(testCaseClass, attrname), '__call__')
 621         testFnNames = filter(isTestMethod, dir(testCaseClass))
 622         if self.sortTestMethodsUsing:
 623             testFnNames.sort(key=_CmpToKey(self.sortTestMethodsUsing))
 624         return testFnNames
 625
 626
 627
 628 defaultTestLoader = TestLoader()
 629
 630
 631 ##############################################################################
 632 # Patches for old functions: these functions should be considered obsolete
 633 ##############################################################################
 634
 635 def _makeLoader(prefix, sortUsing, suiteClass=None):
 636     loader = TestLoader()
 637     loader.sortTestMethodsUsing = sortUsing
 638     loader.testMethodPrefix = prefix
 639     if suiteClass: loader.suiteClass = suiteClass
 640     return loader
 641
 642 def getTestCaseNames(testCaseClass, prefix, sortUsing=cmp):
 643     return _makeLoader(prefix, sortUsing).getTestCaseNames(testCaseClass)
 644
 645 def makeSuite(testCaseClass, prefix='test', sortUsing=cmp, suiteClass=TestSuite):
 646     return _makeLoader(prefix, sortUsing, suiteClass).loadTestsFromTestCase(testCaseClass)
 647
 648 def findTestCases(module, prefix='test', sortUsing=cmp, suiteClass=TestSuite):
 649     return _makeLoader(prefix, sortUsing, suiteClass).loadTestsFromModule(module)
 650
 651
 652 ##############################################################################
 653 # Text UI
 654 ##############################################################################
 655
 656 class _WritelnDecorator:
 657     """Used to decorate file-like objects with a handy 'writeln' method"""
 658     def __init__(self,stream):
 659         self.stream = stream
 660
 661     def __getattr__(self, attr):
 662         return getattr(self.stream,attr)
 663
 664     def writeln(self, arg=None):
 665         if arg: self.write(arg)
 666         self.write('\n') # text-mode streams translate to \r\n if needed
 667
 668
 669 class _TextTestResult(TestResult):
 670     """A test result class that can print formatted text results to a stream.
 671
 672     Used by TextTestRunner.
 673     """
 674     separator1 = '=' * 70
 675     separator2 = '-' * 70
 676
 677     def __init__(self, stream, descriptions, verbosity):
 678         TestResult.__init__(self)
 679         self.stream = stream
 680         self.showAll = verbosity > 1
 681         self.dots = verbosity == 1
 682         self.descriptions = descriptions
 683
 684     def getDescription(self, test):
 685         if self.descriptions:
 686             return test.shortDescription() or str(test)
 687         else:
 688             return str(test)
 689
 690     def startTest(self, test):
 691         TestResult.startTest(self, test)
 692         if self.showAll:
 693             self.stream.write(self.getDescription(test))
 694             self.stream.write(" ... ")
 695             self.stream.flush()
 696
 697     def addSuccess(self, test):
 698         TestResult.addSuccess(self, test)
 699         if self.showAll:
 700             self.stream.writeln("ok")
 701         elif self.dots:
 702             self.stream.write('.')
 703             self.stream.flush()
 704
 705     def addError(self, test, err):
 706         TestResult.addError(self, test, err)
 707         if self.showAll:
 708             self.stream.writeln("ERROR")
 709         elif self.dots:
 710             self.stream.write('E')
 711             self.stream.flush()
 712
 713     def addFailure(self, test, err):
 714         TestResult.addFailure(self, test, err)
 715         if self.showAll:
 716             self.stream.writeln("FAIL")
 717         elif self.dots:
 718             self.stream.write('F')
 719             self.stream.flush()
 720
 721     def printErrors(self):
 722         if self.dots or self.showAll:
 723             self.stream.writeln()
 724         self.printErrorList('ERROR', self.errors)
 725         self.printErrorList('FAIL', self.failures)
 726
 727     def printErrorList(self, flavour, errors):
 728         for test, err in errors:
 729             self.stream.writeln(self.separator1)
 730             self.stream.writeln("%s: %s" % (flavour,self.getDescription(test)))
 731             self.stream.writeln(self.separator2)
 732             self.stream.writeln("%s" % err)
 733
 734
 735 class TextTestRunner:
 736     """A test runner class that displays results in textual form.
 737
 738     It prints out the names of tests as they are run, errors as they
 739     occur, and a summary of the results at the end of the test run.
 740     """
 741     def __init__(self, stream=sys.stderr, descriptions=1, verbosity=1):
 742         self.stream = _WritelnDecorator(stream)
 743         self.descriptions = descriptions
 744         self.verbosity = verbosity
 745
 746     def _makeResult(self):
 747         return _TextTestResult(self.stream, self.descriptions, self.verbosity)
 748
 749     def run(self, test):
 750         "Run the given test case or test suite."
 751         result = self._makeResult()
 752         startTime = time.time()
 753         test(result)
 754         stopTime = time.time()
 755         timeTaken = stopTime - startTime
 756         result.printErrors()
 757         self.stream.writeln(result.separator2)
 758         run = result.testsRun
 759         self.stream.writeln("Ran %d test%s in %.3fs" %
 760                             (run, run != 1 and "s" or "", timeTaken))
 761         self.stream.writeln()
 762         if not result.wasSuccessful():
 763             self.stream.write("FAILED (")
 764             failed, errored = map(len, (result.failures, result.errors))
 765             if failed:
 766                 self.stream.write("failures=%d" % failed)
 767             if errored:
 768                 if failed: self.stream.write(", ")
 769                 self.stream.write("errors=%d" % errored)
 770             self.stream.writeln(")")
 771         else:
 772             self.stream.writeln("OK")
 773         return result
 774
 775
 776
 777 ##############################################################################
 778 # Facilities for running tests from the command line
 779 ##############################################################################
 780
 781 class TestProgram:
 782     """A command-line program that runs a set of tests; this is primarily
 783        for making test modules conveniently executable.
 784     """
 785     USAGE = """\
 786 Usage: %(progName)s [options] [test] [...]
 787
 788 Options:
 789   -h, --help       Show this message
 790   -v, --verbose    Verbose output
 791   -q, --quiet      Minimal output
 792
 793 Examples:
 794   %(progName)s                               - run default set of tests
 795   %(progName)s MyTestSuite                   - run suite 'MyTestSuite'
 796   %(progName)s MyTestCase.testSomething      - run MyTestCase.testSomething
 797   %(progName)s MyTestCase                    - run all 'test*' test methods
 798                                                in MyTestCase
 799 """
 800     def __init__(self, module='__main__', defaultTest=None,
 801                  argv=None, testRunner=TextTestRunner,
 802                  testLoader=defaultTestLoader):
 803         if type(module) == type(''):
 804             self.module = __import__(module)
 805             for part in module.split('.')[1:]:
 806                 self.module = getattr(self.module, part)
 807         else:
 808             self.module = module
 809         if argv is None:
 810             argv = sys.argv
 811         self.verbosity = 1
 812         self.defaultTest = defaultTest
 813         self.testRunner = testRunner
 814         self.testLoader = testLoader
 815         self.progName = os.path.basename(argv[0])
 816         self.parseArgs(argv)
 817         self.runTests()
 818
 819     def usageExit(self, msg=None):
 820         if msg: print msg
 821         print self.USAGE % self.__dict__
 822         sys.exit(2)
 823
 824     def parseArgs(self, argv):
 825         import getopt
 826         try:
 827             options, args = getopt.getopt(argv[1:], 'hHvq',
 828                                           ['help','verbose','quiet'])
 829             for opt, value in options:
 830                 if opt in ('-h','-H','--help'):
 831                     self.usageExit()
 832                 if opt in ('-q','--quiet'):
 833                     self.verbosity = 0
 834                 if opt in ('-v','--verbose'):
 835                     self.verbosity = 2
 836             if len(args) == 0 and self.defaultTest is None:
 837                 self.test = self.testLoader.loadTestsFromModule(self.module)
 838                 return
 839             if len(args) > 0:
 840                 self.testNames = args
 841             else:
 842                 self.testNames = (self.defaultTest,)
 843             self.createTests()
 844         except getopt.error, msg:
 845             self.usageExit(msg)
 846
 847     def createTests(self):
 848         self.test = self.testLoader.loadTestsFromNames(self.testNames,
 849                                                        self.module)
 850
 851     def runTests(self):
 852         if isinstance(self.testRunner, (type, types.ClassType)):
 853             try:
 854                 testRunner = self.testRunner(verbosity=self.verbosity)
 855             except TypeError:
 856                 # didn't accept the verbosity argument
 857                 testRunner = self.testRunner()
 858         else:
 859             # it is assumed to be a TestRunner instance
 860             testRunner = self.testRunner
 861         result = testRunner.run(self.test)
 862         sys.exit(not result.wasSuccessful())
 863
 864 main = TestProgram
 865
 866
 867 ##############################################################################
 868 # Executing this module from the command line
 869 ##############################################################################
 870
 871 if __name__ == "__main__":
 872     main(module=None)