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://pyunit.sourceforge.net/
  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 = 0
 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 __str__(self):
 239         return "%s (%s)" % (self._testMethodName, _strclass(self.__class__))
 240
 241     def __repr__(self):
 242         return "<%s testMethod=%s>" % \
 243                (_strclass(self.__class__), self._testMethodName)
 244
 245     def run(self, result=None):
 246         if result is None: result = self.defaultTestResult()
 247         result.startTest(self)
 248         testMethod = getattr(self, self._testMethodName)
 249         try:
 250             try:
 251                 self.setUp()
 252             except KeyboardInterrupt:
 253                 raise
 254             except:
 255                 result.addError(self, self._exc_info())
 256                 return
 257
 258             ok = False
 259             try:
 260                 testMethod()
 261                 ok = True
 262             except self.failureException:
 263                 result.addFailure(self, self._exc_info())
 264             except KeyboardInterrupt:
 265                 raise
 266             except:
 267                 result.addError(self, self._exc_info())
 268
 269             try:
 270                 self.tearDown()
 271             except KeyboardInterrupt:
 272                 raise
 273             except:
 274                 result.addError(self, self._exc_info())
 275                 ok = False
 276             if ok: result.addSuccess(self)
 277         finally:
 278             result.stopTest(self)
 279
 280     def __call__(self, *args, **kwds):
 281         return self.run(*args, **kwds)
 282
 283     def debug(self):
 284         """Run the test without collecting errors in a TestResult"""
 285         self.setUp()
 286         getattr(self, self._testMethodName)()
 287         self.tearDown()
 288
 289     def _exc_info(self):
 290         """Return a version of sys.exc_info() with the traceback frame
 291            minimised; usually the top level of the traceback frame is not
 292            needed.
 293         """
 294         exctype, excvalue, tb = sys.exc_info()
 295         if sys.platform[:4] == 'java': ## tracebacks look different in Jython
 296             return (exctype, excvalue, tb)
 297         return (exctype, excvalue, tb)
 298
 299     def fail(self, msg=None):
 300         """Fail immediately, with the given message."""
 301         raise self.failureException, msg
 302
 303     def failIf(self, expr, msg=None):
 304         "Fail the test if the expression is true."
 305         if expr: raise self.failureException, msg
 306
 307     def failUnless(self, expr, msg=None):
 308         """Fail the test unless the expression is true."""
 309         if not expr: raise self.failureException, msg
 310
 311     def failUnlessRaises(self, excClass, callableObj, *args, **kwargs):
 312         """Fail unless an exception of class excClass is thrown
 313            by callableObj when invoked with arguments args and keyword
 314            arguments kwargs. If a different type of exception is
 315            thrown, it will not be caught, and the test case will be
 316            deemed to have suffered an error, exactly as for an
 317            unexpected exception.
 318         """
 319         try:
 320             callableObj(*args, **kwargs)
 321         except excClass:
 322             return
 323         else:
 324             if hasattr(excClass,'__name__'): excName = excClass.__name__
 325             else: excName = str(excClass)
 326             raise self.failureException, "%s not raised" % excName
 327
 328     def failUnlessEqual(self, first, second, msg=None):
 329         """Fail if the two objects are unequal as determined by the '=='
 330            operator.
 331         """
 332         if not first == second:
 333             raise self.failureException, \
 334                   (msg or '%r != %r' % (first, second))
 335
 336     def failIfEqual(self, first, second, msg=None):
 337         """Fail if the two objects are equal as determined by the '=='
 338            operator.
 339         """
 340         if first == second:
 341             raise self.failureException, \
 342                   (msg or '%r == %r' % (first, second))
 343
 344     def failUnlessAlmostEqual(self, first, second, places=7, msg=None):
 345         """Fail if the two objects are unequal as determined by their
 346            difference rounded to the given number of decimal places
 347            (default 7) and comparing to zero.
 348
 349            Note that decimal places (from zero) are usually not the same
 350            as significant digits (measured from the most signficant digit).
 351         """
 352         if round(second-first, places) != 0:
 353             raise self.failureException, \
 354                   (msg or '%r != %r within %r places' % (first, second, places))
 355
 356     def failIfAlmostEqual(self, first, second, places=7, msg=None):
 357         """Fail if the two objects are equal as determined by their
 358            difference rounded to the given number of decimal places
 359            (default 7) and comparing to zero.
 360
 361            Note that decimal places (from zero) are usually not the same
 362            as significant digits (measured from the most signficant digit).
 363         """
 364         if round(second-first, places) == 0:
 365             raise self.failureException, \
 366                   (msg or '%r == %r within %r places' % (first, second, places))
 367
 368     # Synonyms for assertion methods
 369
 370     assertEqual = assertEquals = failUnlessEqual
 371
 372     assertNotEqual = assertNotEquals = failIfEqual
 373
 374     assertAlmostEqual = assertAlmostEquals = failUnlessAlmostEqual
 375
 376     assertNotAlmostEqual = assertNotAlmostEquals = failIfAlmostEqual
 377
 378     assertRaises = failUnlessRaises
 379
 380     assert_ = assertTrue = failUnless
 381
 382     assertFalse = failIf
 383
 384
 385
 386 class TestSuite:
 387     """A test suite is a composite test consisting of a number of TestCases.
 388
 389     For use, create an instance of TestSuite, then add test case instances.
 390     When all tests have been added, the suite can be passed to a test
 391     runner, such as TextTestRunner. It will run the individual test cases
 392     in the order in which they were added, aggregating the results. When
 393     subclassing, do not forget to call the base class constructor.
 394     """
 395     def __init__(self, tests=()):
 396         self._tests = []
 397         self.addTests(tests)
 398
 399     def __repr__(self):
 400         return "<%s tests=%s>" % (_strclass(self.__class__), self._tests)
 401
 402     __str__ = __repr__
 403
 404     def __iter__(self):
 405         return iter(self._tests)
 406
 407     def countTestCases(self):
 408         cases = 0
 409         for test in self._tests:
 410             cases += test.countTestCases()
 411         return cases
 412
 413     def addTest(self, test):
 414         self._tests.append(test)
 415
 416     def addTests(self, tests):
 417         for test in tests:
 418             self.addTest(test)
 419
 420     def run(self, result):
 421         for test in self._tests:
 422             if result.shouldStop:
 423                 break
 424             test(result)
 425         return result
 426
 427     def __call__(self, *args, **kwds):
 428         return self.run(*args, **kwds)
 429
 430     def debug(self):
 431         """Run the tests without collecting errors in a TestResult"""
 432         for test in self._tests: test.debug()
 433
 434
 435 class FunctionTestCase(TestCase):
 436     """A test case that wraps a test function.
 437
 438     This is useful for slipping pre-existing test functions into the
 439     PyUnit framework. Optionally, set-up and tidy-up functions can be
 440     supplied. As with TestCase, the tidy-up ('tearDown') function will
 441     always be called if the set-up ('setUp') function ran successfully.
 442     """
 443
 444     def __init__(self, testFunc, setUp=None, tearDown=None,
 445                  description=None):
 446         TestCase.__init__(self)
 447         self.__setUpFunc = setUp
 448         self.__tearDownFunc = tearDown
 449         self.__testFunc = testFunc
 450         self.__description = description
 451
 452     def setUp(self):
 453         if self.__setUpFunc is not None:
 454             self.__setUpFunc()
 455
 456     def tearDown(self):
 457         if self.__tearDownFunc is not None:
 458             self.__tearDownFunc()
 459
 460     def runTest(self):
 461         self.__testFunc()
 462
 463     def id(self):
 464         return self.__testFunc.__name__
 465
 466     def __str__(self):
 467         return "%s (%s)" % (_strclass(self.__class__), self.__testFunc.__name__)
 468
 469     def __repr__(self):
 470         return "<%s testFunc=%s>" % (_strclass(self.__class__), self.__testFunc)
 471
 472     def shortDescription(self):
 473         if self.__description is not None: return self.__description
 474         doc = self.__testFunc.__doc__
 475         return doc and doc.split("\n")[0].strip() or None
 476
 477
 478
 479 ##############################################################################
 480 # Locating and loading tests
 481 ##############################################################################
 482
 483 class TestLoader:
 484     """This class is responsible for loading tests according to various
 485     criteria and returning them wrapped in a Test
 486     """
 487     testMethodPrefix = 'test'
 488     sortTestMethodsUsing = cmp
 489     suiteClass = TestSuite
 490
 491     def loadTestsFromTestCase(self, testCaseClass):
 492         """Return a suite of all tests cases contained in testCaseClass"""
 493         if issubclass(testCaseClass, TestSuite):
 494             raise TypeError("Test cases should not be derived from TestSuite. Maybe you meant to derive from TestCase?")
 495         testCaseNames = self.getTestCaseNames(testCaseClass)
 496         if not testCaseNames and hasattr(testCaseClass, 'runTest'):
 497             testCaseNames = ['runTest']
 498         return self.suiteClass(map(testCaseClass, testCaseNames))
 499
 500     def loadTestsFromModule(self, module):
 501         """Return a suite of all tests cases contained in the given module"""
 502         tests = []
 503         for name in dir(module):
 504             obj = getattr(module, name)
 505             if (isinstance(obj, (type, types.ClassType)) and
 506                 issubclass(obj, TestCase)):
 507                 tests.append(self.loadTestsFromTestCase(obj))
 508         return self.suiteClass(tests)
 509
 510     def loadTestsFromName(self, name, module=None):
 511         """Return a suite of all tests cases given a string specifier.
 512
 513         The name may resolve either to a module, a test case class, a
 514         test method within a test case class, or a callable object which
 515         returns a TestCase or TestSuite instance.
 516
 517         The method optionally resolves the names relative to a given module.
 518         """
 519         parts = name.split('.')
 520         if module is None:
 521             parts_copy = parts[:]
 522             while parts_copy:
 523                 try:
 524                     module = __import__('.'.join(parts_copy))
 525                     break
 526                 except ImportError:
 527                     del parts_copy[-1]
 528                     if not parts_copy: raise
 529             parts = parts[1:]
 530         obj = module
 531         for part in parts:
 532             parent, obj = obj, getattr(obj, part)
 533
 534         if type(obj) == types.ModuleType:
 535             return self.loadTestsFromModule(obj)
 536         elif (isinstance(obj, (type, types.ClassType)) and
 537               issubclass(obj, TestCase)):
 538             return self.loadTestsFromTestCase(obj)
 539         elif type(obj) == types.UnboundMethodType:
 540             return parent(obj.__name__)
 541         elif isinstance(obj, TestSuite):
 542             return obj
 543         elif callable(obj):
 544             test = obj()
 545             if not isinstance(test, (TestCase, TestSuite)):
 546                 raise ValueError, \
 547                       "calling %s returned %s, not a test" % (obj,test)
 548             return test
 549         else:
 550             raise ValueError, "don't know how to make test from: %s" % obj
 551
 552     def loadTestsFromNames(self, names, module=None):
 553         """Return a suite of all tests cases found using the given sequence
 554         of string specifiers. See 'loadTestsFromName()'.
 555         """
 556         suites = [self.loadTestsFromName(name, module) for name in names]
 557         return self.suiteClass(suites)
 558
 559     def getTestCaseNames(self, testCaseClass):
 560         """Return a sorted sequence of method names found within testCaseClass
 561         """
 562         def isTestMethod(attrname, testCaseClass=testCaseClass, prefix=self.testMethodPrefix):
 563             return attrname.startswith(prefix) and callable(getattr(testCaseClass, attrname))
 564         testFnNames = filter(isTestMethod, dir(testCaseClass))
 565         for baseclass in testCaseClass.__bases__:
 566             for testFnName in self.getTestCaseNames(baseclass):
 567                 if testFnName not in testFnNames:  # handle overridden methods
 568                     testFnNames.append(testFnName)
 569         if self.sortTestMethodsUsing:
 570             testFnNames.sort(self.sortTestMethodsUsing)
 571         return testFnNames
 572
 573
 574
 575 defaultTestLoader = TestLoader()
 576
 577
 578 ##############################################################################
 579 # Patches for old functions: these functions should be considered obsolete
 580 ##############################################################################
 581
 582 def _makeLoader(prefix, sortUsing, suiteClass=None):
 583     loader = TestLoader()
 584     loader.sortTestMethodsUsing = sortUsing
 585     loader.testMethodPrefix = prefix
 586     if suiteClass: loader.suiteClass = suiteClass
 587     return loader
 588
 589 def getTestCaseNames(testCaseClass, prefix, sortUsing=cmp):
 590     return _makeLoader(prefix, sortUsing).getTestCaseNames(testCaseClass)
 591
 592 def makeSuite(testCaseClass, prefix='test', sortUsing=cmp, suiteClass=TestSuite):
 593     return _makeLoader(prefix, sortUsing, suiteClass).loadTestsFromTestCase(testCaseClass)
 594
 595 def findTestCases(module, prefix='test', sortUsing=cmp, suiteClass=TestSuite):
 596     return _makeLoader(prefix, sortUsing, suiteClass).loadTestsFromModule(module)
 597
 598
 599 ##############################################################################
 600 # Text UI
 601 ##############################################################################
 602
 603 class _WritelnDecorator:
 604     """Used to decorate file-like objects with a handy 'writeln' method"""
 605     def __init__(self,stream):
 606         self.stream = stream
 607
 608     def __getattr__(self, attr):
 609         return getattr(self.stream,attr)
 610
 611     def writeln(self, arg=None):
 612         if arg: self.write(arg)
 613         self.write('\n') # text-mode streams translate to \r\n if needed
 614
 615
 616 class _TextTestResult(TestResult):
 617     """A test result class that can print formatted text results to a stream.
 618
 619     Used by TextTestRunner.
 620     """
 621     separator1 = '=' * 70
 622     separator2 = '-' * 70
 623
 624     def __init__(self, stream, descriptions, verbosity):
 625         TestResult.__init__(self)
 626         self.stream = stream
 627         self.showAll = verbosity > 1
 628         self.dots = verbosity == 1
 629         self.descriptions = descriptions
 630
 631     def getDescription(self, test):
 632         if self.descriptions:
 633             return test.shortDescription() or str(test)
 634         else:
 635             return str(test)
 636
 637     def startTest(self, test):
 638         TestResult.startTest(self, test)
 639         if self.showAll:
 640             self.stream.write(self.getDescription(test))
 641             self.stream.write(" ... ")
 642
 643     def addSuccess(self, test):
 644         TestResult.addSuccess(self, test)
 645         if self.showAll:
 646             self.stream.writeln("ok")
 647         elif self.dots:
 648             self.stream.write('.')
 649
 650     def addError(self, test, err):
 651         TestResult.addError(self, test, err)
 652         if self.showAll:
 653             self.stream.writeln("ERROR")
 654         elif self.dots:
 655             self.stream.write('E')
 656
 657     def addFailure(self, test, err):
 658         TestResult.addFailure(self, test, err)
 659         if self.showAll:
 660             self.stream.writeln("FAIL")
 661         elif self.dots:
 662             self.stream.write('F')
 663
 664     def printErrors(self):
 665         if self.dots or self.showAll:
 666             self.stream.writeln()
 667         self.printErrorList('ERROR', self.errors)
 668         self.printErrorList('FAIL', self.failures)
 669
 670     def printErrorList(self, flavour, errors):
 671         for test, err in errors:
 672             self.stream.writeln(self.separator1)
 673             self.stream.writeln("%s: %s" % (flavour,self.getDescription(test)))
 674             self.stream.writeln(self.separator2)
 675             self.stream.writeln("%s" % err)
 676
 677
 678 class TextTestRunner:
 679     """A test runner class that displays results in textual form.
 680
 681     It prints out the names of tests as they are run, errors as they
 682     occur, and a summary of the results at the end of the test run.
 683     """
 684     def __init__(self, stream=sys.stderr, descriptions=1, verbosity=1):
 685         self.stream = _WritelnDecorator(stream)
 686         self.descriptions = descriptions
 687         self.verbosity = verbosity
 688
 689     def _makeResult(self):
 690         return _TextTestResult(self.stream, self.descriptions, self.verbosity)
 691
 692     def run(self, test):
 693         "Run the given test case or test suite."
 694         result = self._makeResult()
 695         startTime = time.time()
 696         test(result)
 697         stopTime = time.time()
 698         timeTaken = stopTime - startTime
 699         result.printErrors()
 700         self.stream.writeln(result.separator2)
 701         run = result.testsRun
 702         self.stream.writeln("Ran %d test%s in %.3fs" %
 703                             (run, run != 1 and "s" or "", timeTaken))
 704         self.stream.writeln()
 705         if not result.wasSuccessful():
 706             self.stream.write("FAILED (")
 707             failed, errored = map(len, (result.failures, result.errors))
 708             if failed:
 709                 self.stream.write("failures=%d" % failed)
 710             if errored:
 711                 if failed: self.stream.write(", ")
 712                 self.stream.write("errors=%d" % errored)
 713             self.stream.writeln(")")
 714         else:
 715             self.stream.writeln("OK")
 716         return result
 717
 718
 719
 720 ##############################################################################
 721 # Facilities for running tests from the command line
 722 ##############################################################################
 723
 724 class TestProgram:
 725     """A command-line program that runs a set of tests; this is primarily
 726        for making test modules conveniently executable.
 727     """
 728     USAGE = """\
 729 Usage: %(progName)s [options] [test] [...]
 730
 731 Options:
 732   -h, --help       Show this message
 733   -v, --verbose    Verbose output
 734   -q, --quiet      Minimal output
 735
 736 Examples:
 737   %(progName)s                               - run default set of tests
 738   %(progName)s MyTestSuite                   - run suite 'MyTestSuite'
 739   %(progName)s MyTestCase.testSomething      - run MyTestCase.testSomething
 740   %(progName)s MyTestCase                    - run all 'test*' test methods
 741                                                in MyTestCase
 742 """
 743     def __init__(self, module='__main__', defaultTest=None,
 744                  argv=None, testRunner=None, testLoader=defaultTestLoader):
 745         if type(module) == type(''):
 746             self.module = __import__(module)
 747             for part in module.split('.')[1:]:
 748                 self.module = getattr(self.module, part)
 749         else:
 750             self.module = module
 751         if argv is None:
 752             argv = sys.argv
 753         self.verbosity = 1
 754         self.defaultTest = defaultTest
 755         self.testRunner = testRunner
 756         self.testLoader = testLoader
 757         self.progName = os.path.basename(argv[0])
 758         self.parseArgs(argv)
 759         self.runTests()
 760
 761     def usageExit(self, msg=None):
 762         if msg: print msg
 763         print self.USAGE % self.__dict__
 764         sys.exit(2)
 765
 766     def parseArgs(self, argv):
 767         import getopt
 768         try:
 769             options, args = getopt.getopt(argv[1:], 'hHvq',
 770                                           ['help','verbose','quiet'])
 771             for opt, value in options:
 772                 if opt in ('-h','-H','--help'):
 773                     self.usageExit()
 774                 if opt in ('-q','--quiet'):
 775                     self.verbosity = 0
 776                 if opt in ('-v','--verbose'):
 777                     self.verbosity = 2
 778             if len(args) == 0 and self.defaultTest is None:
 779                 self.test = self.testLoader.loadTestsFromModule(self.module)
 780                 return
 781             if len(args) > 0:
 782                 self.testNames = args
 783             else:
 784                 self.testNames = (self.defaultTest,)
 785             self.createTests()
 786         except getopt.error, msg:
 787             self.usageExit(msg)
 788
 789     def createTests(self):
 790         self.test = self.testLoader.loadTestsFromNames(self.testNames,
 791                                                        self.module)
 792
 793     def runTests(self):
 794         if self.testRunner is None:
 795             self.testRunner = TextTestRunner(verbosity=self.verbosity)
 796         result = self.testRunner.run(self.test)
 797         sys.exit(not result.wasSuccessful())
 798
 799 main = TestProgram
 800
 801
 802 ##############################################################################
 803 # Executing this module from the command line
 804 ##############################################################################
 805
 806 if __name__ == "__main__":
 807     main(module=None)