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.assertEqual((1 + 2), 3)
  18             self.assertEqual(0 + 1, 1)
  19         def testMultiply(self):
  20             self.assertEqual((0 * 10), 0)
  21             self.assertEqual((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/library/unittest.html
  29
  30 Copyright (c) 1999-2003 Steve Purcell
  31 Copyright (c) 2003-2009 Python Software Foundation
  32 This module is free software, and you may redistribute it and/or modify
  33 it under the same terms as Python itself, so long as this copyright message
  34 and disclaimer are retained in their original form.
  35
  36 IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
  37 SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF
  38 THIS CODE, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  39 DAMAGE.
  40
  41 THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT
  42 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  43 PARTICULAR PURPOSE.  THE CODE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS,
  44 AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
  45 SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  46 '''
  47
  48 import difflib
  49 import functools
  50 import os
  51 import pprint
  52 import re
  53 import sys
  54 import time
  55 import traceback
  56 import types
  57 import warnings
  58
  59 ##############################################################################
  60 # Exported classes and functions
  61 ##############################################################################
  62 __all__ = ['TestResult', 'TestCase', 'TestSuite', 'ClassTestSuite',
  63            'TextTestRunner', 'TestLoader', 'FunctionTestCase', 'main',
  64            'defaultTestLoader', 'SkipTest', 'skip', 'skipIf', 'skipUnless',
  65            'expectedFailure']
  66
  67 # Expose obsolete functions for backwards compatibility
  68 __all__.extend(['getTestCaseNames', 'makeSuite', 'findTestCases'])
  69
  70
  71 ##############################################################################
  72 # Backward compatibility
  73 ##############################################################################
  74
  75 def _CmpToKey(mycmp):
  76     'Convert a cmp= function into a key= function'
  77     class K(object):
  78         def __init__(self, obj):
  79             self.obj = obj
  80         def __lt__(self, other):
  81             return mycmp(self.obj, other.obj) == -1
  82     return K
  83
  84 ##############################################################################
  85 # Test framework core
  86 ##############################################################################
  87
  88 def _strclass(cls):
  89     return "%s.%s" % (cls.__module__, cls.__name__)
  90
  91
  92 class SkipTest(Exception):
  93     """
  94     Raise this exception in a test to skip it.
  95
  96     Usually you can use TestResult.skip() or one of the skipping decorators
  97     instead of raising this directly.
  98     """
  99     pass
 100
 101 class _ExpectedFailure(Exception):
 102     """
 103     Raise this when a test is expected to fail.
 104
 105     This is an implementation detail.
 106     """
 107
 108     def __init__(self, exc_info):
 109         super(_ExpectedFailure, self).__init__()
 110         self.exc_info = exc_info
 111
 112 class _UnexpectedSuccess(Exception):
 113     """
 114     The test was supposed to fail, but it didn't!
 115     """
 116     pass
 117
 118 def _id(obj):
 119     return obj
 120
 121 def skip(reason):
 122     """
 123     Unconditionally skip a test.
 124     """
 125     def decorator(test_item):
 126         if isinstance(test_item, type) and issubclass(test_item, TestCase):
 127             test_item.__unittest_skip__ = True
 128             test_item.__unittest_skip_why__ = reason
 129             return test_item
 130         @functools.wraps(test_item)
 131         def skip_wrapper(*args, **kwargs):
 132             raise SkipTest(reason)
 133         return skip_wrapper
 134     return decorator
 135
 136 def skipIf(condition, reason):
 137     """
 138     Skip a test if the condition is true.
 139     """
 140     if condition:
 141         return skip(reason)
 142     return _id
 143
 144 def skipUnless(condition, reason):
 145     """
 146     Skip a test unless the condition is true.
 147     """
 148     if not condition:
 149         return skip(reason)
 150     return _id
 151
 152
 153 def expectedFailure(func):
 154     @functools.wraps(func)
 155     def wrapper(*args, **kwargs):
 156         try:
 157             func(*args, **kwargs)
 158         except Exception:
 159             raise _ExpectedFailure(sys.exc_info())
 160         raise _UnexpectedSuccess
 161     return wrapper
 162
 163 __unittest = 1
 164
 165 class TestResult(object):
 166     """Holder for test result information.
 167
 168     Test results are automatically managed by the TestCase and TestSuite
 169     classes, and do not need to be explicitly manipulated by writers of tests.
 170
 171     Each instance holds the total number of tests run, and collections of
 172     failures and errors that occurred among those test runs. The collections
 173     contain tuples of (testcase, exceptioninfo), where exceptioninfo is the
 174     formatted traceback of the error that occurred.
 175     """
 176     def __init__(self):
 177         self.failures = []
 178         self.errors = []
 179         self.testsRun = 0
 180         self.skipped = []
 181         self.expectedFailures = []
 182         self.unexpectedSuccesses = []
 183         self.shouldStop = False
 184
 185     def startTest(self, test):
 186         "Called when the given test is about to be run"
 187         self.testsRun = self.testsRun + 1
 188
 189     def stopTest(self, test):
 190         "Called when the given test has been run"
 191         pass
 192
 193     def addError(self, test, err):
 194         """Called when an error has occurred. 'err' is a tuple of values as
 195         returned by sys.exc_info().
 196         """
 197         self.errors.append((test, self._exc_info_to_string(err, test)))
 198
 199     def addFailure(self, test, err):
 200         """Called when an error has occurred. 'err' is a tuple of values as
 201         returned by sys.exc_info()."""
 202         self.failures.append((test, self._exc_info_to_string(err, test)))
 203
 204     def addSuccess(self, test):
 205         "Called when a test has completed successfully"
 206         pass
 207
 208     def addSkip(self, test, reason):
 209         """Called when a test is skipped."""
 210         self.skipped.append((test, reason))
 211
 212     def addExpectedFailure(self, test, err):
 213         """Called when an expected failure/error occured."""
 214         self.expectedFailures.append(
 215             (test, self._exc_info_to_string(err, test)))
 216
 217     def addUnexpectedSuccess(self, test):
 218         """Called when a test was expected to fail, but succeed."""
 219         self.unexpectedSuccesses.append(test)
 220
 221     def wasSuccessful(self):
 222         "Tells whether or not this result was a success"
 223         return len(self.failures) == len(self.errors) == 0
 224
 225     def stop(self):
 226         "Indicates that the tests should be aborted"
 227         self.shouldStop = True
 228
 229     def _exc_info_to_string(self, err, test):
 230         """Converts a sys.exc_info()-style tuple of values into a string."""
 231         exctype, value, tb = err
 232         # Skip test runner traceback levels
 233         while tb and self._is_relevant_tb_level(tb):
 234             tb = tb.tb_next
 235         if exctype is test.failureException:
 236             # Skip assert*() traceback levels
 237             length = self._count_relevant_tb_levels(tb)
 238             return ''.join(traceback.format_exception(exctype, value, tb, length))
 239         return ''.join(traceback.format_exception(exctype, value, tb))
 240
 241     def _is_relevant_tb_level(self, tb):
 242         return '__unittest' in tb.tb_frame.f_globals
 243
 244     def _count_relevant_tb_levels(self, tb):
 245         length = 0
 246         while tb and not self._is_relevant_tb_level(tb):
 247             length += 1
 248             tb = tb.tb_next
 249         return length
 250
 251     def __repr__(self):
 252         return "<%s run=%i errors=%i failures=%i>" % \
 253                (_strclass(self.__class__), self.testsRun, len(self.errors),
 254                 len(self.failures))
 255
 256
 257 class _AssertRaisesContext(object):
 258     """A context manager used to implement TestCase.assertRaises* methods."""
 259
 260     def __init__(self, expected, test_case, expected_regexp=None):
 261         self.expected = expected
 262         self.failureException = test_case.failureException
 263         self.expected_regex = expected_regexp
 264
 265     def __enter__(self):
 266         pass
 267
 268     def __exit__(self, exc_type, exc_value, traceback):
 269         if exc_type is None:
 270             try:
 271                 exc_name = self.expected.__name__
 272             except AttributeError:
 273                 exc_name = str(self.expected)
 274             raise self.failureException(
 275                 "{0} not raised".format(exc_name))
 276         if not issubclass(exc_type, self.expected):
 277             # let unexpected exceptions pass through
 278             return False
 279         if self.expected_regex is None:
 280             return True
 281
 282         expected_regexp = self.expected_regex
 283         if isinstance(expected_regexp, basestring):
 284             expected_regexp = re.compile(expected_regexp)
 285         if not expected_regexp.search(str(exc_value)):
 286             raise self.failureException('"%s" does not match "%s"' %
 287                      (expected_regexp.pattern, str(exc_value)))
 288         return True
 289
 290
 291 class _AssertWrapper(object):
 292     """Wrap entries in the _type_equality_funcs registry to make them deep
 293     copyable."""
 294
 295     def __init__(self, function):
 296         self.function = function
 297
 298     def __deepcopy__(self, memo):
 299         memo[id(self)] = self
 300
 301
 302 class TestCase(object):
 303     """A class whose instances are single test cases.
 304
 305     By default, the test code itself should be placed in a method named
 306     'runTest'.
 307
 308     If the fixture may be used for many test cases, create as
 309     many test methods as are needed. When instantiating such a TestCase
 310     subclass, specify in the constructor arguments the name of the test method
 311     that the instance is to execute.
 312
 313     Test authors should subclass TestCase for their own tests. Construction
 314     and deconstruction of the test's environment ('fixture') can be
 315     implemented by overriding the 'setUp' and 'tearDown' methods respectively.
 316
 317     If it is necessary to override the __init__ method, the base class
 318     __init__ method must always be called. It is important that subclasses
 319     should not change the signature of their __init__ method, since instances
 320     of the classes are instantiated automatically by parts of the framework
 321     in order to be run.
 322     """
 323
 324     # This attribute determines which exception will be raised when
 325     # the instance's assertion methods fail; test methods raising this
 326     # exception will be deemed to have 'failed' rather than 'errored'
 327
 328     failureException = AssertionError
 329
 330     # This attribute determines whether long messages (including repr of
 331     # objects used in assert methods) will be printed on failure in *addition*
 332     # to any explicit message passed.
 333
 334     longMessage = False
 335
 336
 337     def __init__(self, methodName='runTest'):
 338         """Create an instance of the class that will use the named test
 339            method when executed. Raises a ValueError if the instance does
 340            not have a method with the specified name.
 341         """
 342         self._testMethodName = methodName
 343         try:
 344             testMethod = getattr(self, methodName)
 345         except AttributeError:
 346             raise ValueError("no such test method in %s: %s" % \
 347                   (self.__class__, methodName))
 348         self._testMethodDoc = testMethod.__doc__
 349
 350         # Map types to custom assertEqual functions that will compare
 351         # instances of said type in more detail to generate a more useful
 352         # error message.
 353         self._type_equality_funcs = {}
 354         self.addTypeEqualityFunc(dict, self.assertDictEqual)
 355         self.addTypeEqualityFunc(list, self.assertListEqual)
 356         self.addTypeEqualityFunc(tuple, self.assertTupleEqual)
 357         self.addTypeEqualityFunc(set, self.assertSetEqual)
 358         self.addTypeEqualityFunc(frozenset, self.assertSetEqual)
 359
 360     def addTypeEqualityFunc(self, typeobj, function):
 361         """Add a type specific assertEqual style function to compare a type.
 362
 363         This method is for use by TestCase subclasses that need to register
 364         their own type equality functions to provide nicer error messages.
 365
 366         Args:
 367             typeobj: The data type to call this function on when both values
 368                     are of the same type in assertEqual().
 369             function: The callable taking two arguments and an optional
 370                     msg= argument that raises self.failureException with a
 371                     useful error message when the two arguments are not equal.
 372         """
 373         self._type_equality_funcs[typeobj] = _AssertWrapper(function)
 374
 375     def setUp(self):
 376         "Hook method for setting up the test fixture before exercising it."
 377         pass
 378
 379     def tearDown(self):
 380         "Hook method for deconstructing the test fixture after testing it."
 381         pass
 382
 383     def countTestCases(self):
 384         return 1
 385
 386     def defaultTestResult(self):
 387         return TestResult()
 388
 389     def shortDescription(self):
 390         """Returns both the test method name and first line of its docstring.
 391
 392         If no docstring is given, only returns the method name.
 393
 394         This method overrides unittest.TestCase.shortDescription(), which
 395         only returns the first line of the docstring, obscuring the name
 396         of the test upon failure.
 397         """
 398         desc = str(self)
 399         doc_first_line = None
 400
 401         if self._testMethodDoc:
 402             doc_first_line = self._testMethodDoc.split("\n")[0].strip()
 403         if doc_first_line:
 404             desc = '\n'.join((desc, doc_first_line))
 405         return desc
 406
 407     def id(self):
 408         return "%s.%s" % (_strclass(self.__class__), self._testMethodName)
 409
 410     def __eq__(self, other):
 411         if type(self) is not type(other):
 412             return NotImplemented
 413
 414         return self._testMethodName == other._testMethodName
 415
 416     def __ne__(self, other):
 417         return not self == other
 418
 419     def __hash__(self):
 420         return hash((type(self), self._testMethodName))
 421
 422     def __str__(self):
 423         return "%s (%s)" % (self._testMethodName, _strclass(self.__class__))
 424
 425     def __repr__(self):
 426         return "<%s testMethod=%s>" % \
 427                (_strclass(self.__class__), self._testMethodName)
 428
 429     def run(self, result=None):
 430         if result is None:
 431             result = self.defaultTestResult()
 432         result.startTest(self)
 433         testMethod = getattr(self, self._testMethodName)
 434         try:
 435             try:
 436                 self.setUp()
 437             except SkipTest as e:
 438                 result.addSkip(self, str(e))
 439                 return
 440             except Exception:
 441                 result.addError(self, sys.exc_info())
 442                 return
 443
 444             success = False
 445             try:
 446                 testMethod()
 447             except self.failureException:
 448                 result.addFailure(self, sys.exc_info())
 449             except _ExpectedFailure as e:
 450                 result.addExpectedFailure(self, e.exc_info)
 451             except _UnexpectedSuccess:
 452                 result.addUnexpectedSuccess(self)
 453             except SkipTest as e:
 454                 result.addSkip(self, str(e))
 455             except Exception:
 456                 result.addError(self, sys.exc_info())
 457             else:
 458                 success = True
 459
 460             try:
 461                 self.tearDown()
 462             except Exception:
 463                 result.addError(self, sys.exc_info())
 464                 success = False
 465             if success:
 466                 result.addSuccess(self)
 467         finally:
 468             result.stopTest(self)
 469
 470     def __call__(self, *args, **kwds):
 471         return self.run(*args, **kwds)
 472
 473     def debug(self):
 474         """Run the test without collecting errors in a TestResult"""
 475         self.setUp()
 476         getattr(self, self._testMethodName)()
 477         self.tearDown()
 478
 479     def skipTest(self, reason):
 480         """Skip this test."""
 481         raise SkipTest(reason)
 482
 483     def fail(self, msg=None):
 484         """Fail immediately, with the given message."""
 485         raise self.failureException(msg)
 486
 487     def assertFalse(self, expr, msg=None):
 488         "Fail the test if the expression is true."
 489         if expr:
 490             msg = self._formatMessage(msg, "%r is not False" % expr)
 491             raise self.failureException(msg)
 492
 493     def assertTrue(self, expr, msg=None):
 494         """Fail the test unless the expression is true."""
 495         if not expr:
 496             msg = self._formatMessage(msg, "%r is not True" % expr)
 497             raise self.failureException(msg)
 498
 499     def _formatMessage(self, msg, standardMsg):
 500         """Honour the longMessage attribute when generating failure messages.
 501         If longMessage is False this means:
 502         * Use only an explicit message if it is provided
 503         * Otherwise use the standard message for the assert
 504
 505         If longMessage is True:
 506         * Use the standard message
 507         * If an explicit message is provided, plus ' : ' and the explicit message
 508         """
 509         if not self.longMessage:
 510             return msg or standardMsg
 511         if msg is None:
 512             return standardMsg
 513         return standardMsg + ' : ' + msg
 514
 515
 516     def assertRaises(self, excClass, callableObj=None, *args, **kwargs):
 517         """Fail unless an exception of class excClass is thrown
 518            by callableObj when invoked with arguments args and keyword
 519            arguments kwargs. If a different type of exception is
 520            thrown, it will not be caught, and the test case will be
 521            deemed to have suffered an error, exactly as for an
 522            unexpected exception.
 523
 524            If called with callableObj omitted or None, will return a
 525            context object used like this::
 526
 527                 with self.assertRaises(some_error_class):
 528                     do_something()
 529         """
 530         context = _AssertRaisesContext(excClass, self)
 531         if callableObj is None:
 532             return context
 533         with context:
 534             callableObj(*args, **kwargs)
 535
 536     def _getAssertEqualityFunc(self, first, second):
 537         """Get a detailed comparison function for the types of the two args.
 538
 539         Returns: A callable accepting (first, second, msg=None) that will
 540         raise a failure exception if first != second with a useful human
 541         readable error message for those types.
 542         """
 543         #
 544         # NOTE(gregory.p.smith): I considered isinstance(first, type(second))
 545         # and vice versa.  I opted for the conservative approach in case
 546         # subclasses are not intended to be compared in detail to their super
 547         # class instances using a type equality func.  This means testing
 548         # subtypes won't automagically use the detailed comparison.  Callers
 549         # should use their type specific assertSpamEqual method to compare
 550         # subclasses if the detailed comparison is desired and appropriate.
 551         # See the discussion in http://bugs.python.org/issue2578.
 552         #
 553         if type(first) is type(second):
 554             asserter = self._type_equality_funcs.get(type(first))
 555             if asserter is not None:
 556                 return asserter.function
 557
 558         return self._baseAssertEqual
 559
 560     def _baseAssertEqual(self, first, second, msg=None):
 561         """The default assertEqual implementation, not type specific."""
 562         if not first == second:
 563             standardMsg = '%r != %r' % (first, second)
 564             msg = self._formatMessage(msg, standardMsg)
 565             raise self.failureException(msg)
 566
 567     def assertEqual(self, first, second, msg=None):
 568         """Fail if the two objects are unequal as determined by the '=='
 569            operator.
 570         """
 571         assertion_func = self._getAssertEqualityFunc(first, second)
 572         assertion_func(first, second, msg=msg)
 573
 574     def assertNotEqual(self, first, second, msg=None):
 575         """Fail if the two objects are equal as determined by the '=='
 576            operator.
 577         """
 578         if not first != second:
 579             msg = self._formatMessage(msg, '%r == %r' % (first, second))
 580             raise self.failureException(msg)
 581
 582     def assertAlmostEqual(self, first, second, places=7, msg=None):
 583         """Fail if the two objects are unequal as determined by their
 584            difference rounded to the given number of decimal places
 585            (default 7) and comparing to zero.
 586
 587            Note that decimal places (from zero) are usually not the same
 588            as significant digits (measured from the most signficant digit).
 589         """
 590         if round(abs(second-first), places) != 0:
 591             standardMsg = '%r != %r within %r places' % (first, second, places)
 592             msg = self._formatMessage(msg, standardMsg)
 593             raise self.failureException(msg)
 594
 595     def assertNotAlmostEqual(self, first, second, places=7, msg=None):
 596         """Fail if the two objects are equal as determined by their
 597            difference rounded to the given number of decimal places
 598            (default 7) and comparing to zero.
 599
 600            Note that decimal places (from zero) are usually not the same
 601            as significant digits (measured from the most signficant digit).
 602         """
 603         if round(abs(second-first), places) == 0:
 604             standardMsg = '%r == %r within %r places' % (first, second, places)
 605             msg = self._formatMessage(msg, standardMsg)
 606             raise self.failureException(msg)
 607
 608     # Synonyms for assertion methods
 609
 610     # The plurals are undocumented.  Keep them that way to discourage use.
 611     # Do not add more.  Do not remove.
 612     # Going through a deprecation cycle on these would annoy many people.
 613     assertEquals = assertEqual
 614     assertNotEquals = assertNotEqual
 615     assertAlmostEquals = assertAlmostEqual
 616     assertNotAlmostEquals = assertNotAlmostEqual
 617     assert_ = assertTrue
 618
 619     # These fail* assertion method names are pending deprecation and will
 620     # be a DeprecationWarning in 3.2; http://bugs.python.org/issue2578
 621     def _deprecate(original_func):
 622         def deprecated_func(*args, **kwargs):
 623             warnings.warn(
 624                 'Please use {0} instead.'.format(original_func.__name__),
 625                 PendingDeprecationWarning, 2)
 626             return original_func(*args, **kwargs)
 627         return deprecated_func
 628
 629     failUnlessEqual = _deprecate(assertEqual)
 630     failIfEqual = _deprecate(assertNotEqual)
 631     failUnlessAlmostEqual = _deprecate(assertAlmostEqual)
 632     failIfAlmostEqual = _deprecate(assertNotAlmostEqual)
 633     failUnless = _deprecate(assertTrue)
 634     failUnlessRaises = _deprecate(assertRaises)
 635     failIf = _deprecate(assertFalse)
 636
 637     def assertSequenceEqual(self, seq1, seq2, msg=None, seq_type=None):
 638         """An equality assertion for ordered sequences (like lists and tuples).
 639
 640         For the purposes of this function, a valid orderd sequence type is one
 641         which can be indexed, has a length, and has an equality operator.
 642
 643         Args:
 644             seq1: The first sequence to compare.
 645             seq2: The second sequence to compare.
 646             seq_type: The expected datatype of the sequences, or None if no
 647                     datatype should be enforced.
 648             msg: Optional message to use on failure instead of a list of
 649                     differences.
 650         """
 651         if seq_type != None:
 652             seq_type_name = seq_type.__name__
 653             if not isinstance(seq1, seq_type):
 654                 raise self.failureException('First sequence is not a %s: %r'
 655                                             % (seq_type_name, seq1))
 656             if not isinstance(seq2, seq_type):
 657                 raise self.failureException('Second sequence is not a %s: %r'
 658                                             % (seq_type_name, seq2))
 659         else:
 660             seq_type_name = "sequence"
 661
 662         differing = None
 663         try:
 664             len1 = len(seq1)
 665         except (TypeError, NotImplementedError):
 666             differing = 'First %s has no length.    Non-sequence?' % (
 667                     seq_type_name)
 668
 669         if differing is None:
 670             try:
 671                 len2 = len(seq2)
 672             except (TypeError, NotImplementedError):
 673                 differing = 'Second %s has no length.    Non-sequence?' % (
 674                         seq_type_name)
 675
 676         if differing is None:
 677             if seq1 == seq2:
 678                 return
 679
 680             for i in xrange(min(len1, len2)):
 681                 try:
 682                     item1 = seq1[i]
 683                 except (TypeError, IndexError, NotImplementedError):
 684                     differing = ('Unable to index element %d of first %s\n' %
 685                                  (i, seq_type_name))
 686                     break
 687
 688                 try:
 689                     item2 = seq2[i]
 690                 except (TypeError, IndexError, NotImplementedError):
 691                     differing = ('Unable to index element %d of second %s\n' %
 692                                  (i, seq_type_name))
 693                     break
 694
 695                 if item1 != item2:
 696                     differing = ('First differing element %d:\n%s\n%s\n' %
 697                                  (i, item1, item2))
 698                     break
 699             else:
 700                 if (len1 == len2 and seq_type is None and
 701                     type(seq1) != type(seq2)):
 702                     # The sequences are the same, but have differing types.
 703                     return
 704                 # A catch-all message for handling arbitrary user-defined
 705                 # sequences.
 706                 differing = '%ss differ:\n' % seq_type_name.capitalize()
 707                 if len1 > len2:
 708                     differing = ('First %s contains %d additional '
 709                                  'elements.\n' % (seq_type_name, len1 - len2))
 710                     try:
 711                         differing += ('First extra element %d:\n%s\n' %
 712                                       (len2, seq1[len2]))
 713                     except (TypeError, IndexError, NotImplementedError):
 714                         differing += ('Unable to index element %d '
 715                                       'of first %s\n' % (len2, seq_type_name))
 716                 elif len1 < len2:
 717                     differing = ('Second %s contains %d additional '
 718                                  'elements.\n' % (seq_type_name, len2 - len1))
 719                     try:
 720                         differing += ('First extra element %d:\n%s\n' %
 721                                       (len1, seq2[len1]))
 722                     except (TypeError, IndexError, NotImplementedError):
 723                         differing += ('Unable to index element %d '
 724                                       'of second %s\n' % (len1, seq_type_name))
 725         standardMsg = differing + '\n'.join(difflib.ndiff(pprint.pformat(seq1).splitlines(),
 726                                             pprint.pformat(seq2).splitlines()))
 727         msg = self._formatMessage(msg, standardMsg)
 728         self.fail(msg)
 729
 730     def assertListEqual(self, list1, list2, msg=None):
 731         """A list-specific equality assertion.
 732
 733         Args:
 734             list1: The first list to compare.
 735             list2: The second list to compare.
 736             msg: Optional message to use on failure instead of a list of
 737                     differences.
 738
 739         """
 740         self.assertSequenceEqual(list1, list2, msg, seq_type=list)
 741
 742     def assertTupleEqual(self, tuple1, tuple2, msg=None):
 743         """A tuple-specific equality assertion.
 744
 745         Args:
 746             tuple1: The first tuple to compare.
 747             tuple2: The second tuple to compare.
 748             msg: Optional message to use on failure instead of a list of
 749                     differences.
 750         """
 751         self.assertSequenceEqual(tuple1, tuple2, msg, seq_type=tuple)
 752
 753     def assertSetEqual(self, set1, set2, msg=None):
 754         """A set-specific equality assertion.
 755
 756         Args:
 757             set1: The first set to compare.
 758             set2: The second set to compare.
 759             msg: Optional message to use on failure instead of a list of
 760                     differences.
 761
 762         For more general containership equality, assertSameElements will work
 763         with things other than sets.    This uses ducktyping to support
 764         different types of sets, and is optimized for sets specifically
 765         (parameters must support a difference method).
 766         """
 767         try:
 768             difference1 = set1.difference(set2)
 769         except TypeError, e:
 770             self.fail('invalid type when attempting set difference: %s' % e)
 771         except AttributeError, e:
 772             self.fail('first argument does not support set difference: %s' % e)
 773
 774         try:
 775             difference2 = set2.difference(set1)
 776         except TypeError, e:
 777             self.fail('invalid type when attempting set difference: %s' % e)
 778         except AttributeError, e:
 779             self.fail('second argument does not support set difference: %s' % e)
 780
 781         if not (difference1 or difference2):
 782             return
 783
 784         lines = []
 785         if difference1:
 786             lines.append('Items in the first set but not the second:')
 787             for item in difference1:
 788                 lines.append(repr(item))
 789         if difference2:
 790             lines.append('Items in the second set but not the first:')
 791             for item in difference2:
 792                 lines.append(repr(item))
 793
 794         standardMsg = '\n'.join(lines)
 795         self.fail(self._formatMessage(msg, standardMsg))
 796
 797     def assertIn(self, member, container, msg=None):
 798         """Just like self.assertTrue(a in b), but with a nicer default message."""
 799         if member not in container:
 800             standardMsg = '%r not found in %r' % (member, container)
 801             self.fail(self._formatMessage(msg, standardMsg))
 802
 803     def assertNotIn(self, member, container, msg=None):
 804         """Just like self.assertTrue(a not in b), but with a nicer default message."""
 805         if member in container:
 806             standardMsg = '%r unexpectedly found in %r' % (member, container)
 807             self.fail(self._formatMessage(msg, standardMsg))
 808
 809     def assertIs(self, expr1, expr2, msg=None):
 810         """Just like self.assertTrue(a is b), but with a nicer default message."""
 811         if expr1 is not expr2:
 812             standardMsg = '%r is not %r' % (expr1, expr2)
 813             self.fail(self._formatMessage(msg, standardMsg))
 814
 815     def assertIsNot(self, expr1, expr2, msg=None):
 816         """Just like self.assertTrue(a is not b), but with a nicer default message."""
 817         if expr1 is expr2:
 818             standardMsg = 'unexpectedly identical: %r' % (expr1,)
 819             self.fail(self._formatMessage(msg, standardMsg))
 820
 821     def assertDictEqual(self, d1, d2, msg=None):
 822         self.assert_(isinstance(d1, dict), 'First argument is not a dictionary')
 823         self.assert_(isinstance(d2, dict), 'Second argument is not a dictionary')
 824
 825         if d1 != d2:
 826             standardMsg = ('\n' + '\n'.join(difflib.ndiff(
 827                            pprint.pformat(d1).splitlines(),
 828                            pprint.pformat(d2).splitlines())))
 829             self.fail(self._formatMessage(msg, standardMsg))
 830
 831     def assertDictContainsSubset(self, expected, actual, msg=None):
 832         """Checks whether actual is a superset of expected."""
 833         missing = []
 834         mismatched = []
 835         for key, value in expected.iteritems():
 836             if key not in actual:
 837                 missing.append(key)
 838             elif value != actual[key]:
 839                 mismatched.append('%s, expected: %s, actual: %s' % (key, value,                                                                                                       actual[key]))
 840
 841         if not (missing or mismatched):
 842             return
 843
 844         standardMsg = ''
 845         if missing:
 846             standardMsg = 'Missing: %r' % ','.join(missing)
 847         if mismatched:
 848             if standardMsg:
 849                 standardMsg += '; '
 850             standardMsg += 'Mismatched values: %s' % ','.join(mismatched)
 851
 852         self.fail(self._formatMessage(msg, standardMsg))
 853
 854     def assertSameElements(self, expected_seq, actual_seq, msg=None):
 855         """An unordered sequence specific comparison.
 856
 857         Raises with an error message listing which elements of expected_seq
 858         are missing from actual_seq and vice versa if any.
 859         """
 860         try:
 861             expected = set(expected_seq)
 862             actual = set(actual_seq)
 863             missing = list(expected.difference(actual))
 864             unexpected = list(actual.difference(expected))
 865             missing.sort()
 866             unexpected.sort()
 867         except TypeError:
 868             # Fall back to slower list-compare if any of the objects are
 869             # not hashable.
 870             expected = list(expected_seq)
 871             actual = list(actual_seq)
 872             expected.sort()
 873             actual.sort()
 874             missing, unexpected = _SortedListDifference(expected, actual)
 875         errors = []
 876         if missing:
 877             errors.append('Expected, but missing:\n    %r' % missing)
 878         if unexpected:
 879             errors.append('Unexpected, but present:\n    %r' % unexpected)
 880         if errors:
 881             standardMsg = '\n'.join(errors)
 882             self.fail(self._formatMessage(msg, standardMsg))
 883
 884     def assertMultiLineEqual(self, first, second, msg=None):
 885         """Assert that two multi-line strings are equal."""
 886         self.assert_(isinstance(first, basestring), (
 887                 'First argument is not a string'))
 888         self.assert_(isinstance(second, basestring), (
 889                 'Second argument is not a string'))
 890
 891         if first != second:
 892             standardMsg = '\n' + ''.join(difflib.ndiff(first.splitlines(True), second.splitlines(True)))
 893             self.fail(self._formatMessage(msg, standardMsg))
 894
 895     def assertLess(self, a, b, msg=None):
 896         """Just like self.assertTrue(a < b), but with a nicer default message."""
 897         if not a < b:
 898             standardMsg = '%r not less than %r' % (a, b)
 899             self.fail(self._formatMessage(msg, standardMsg))
 900
 901     def assertLessEqual(self, a, b, msg=None):
 902         """Just like self.assertTrue(a <= b), but with a nicer default message."""
 903         if not a <= b:
 904             standardMsg = '%r not less than or equal to %r' % (a, b)
 905             self.fail(self._formatMessage(msg, standardMsg))
 906
 907     def assertGreater(self, a, b, msg=None):
 908         """Just like self.assertTrue(a > b), but with a nicer default message."""
 909         if not a > b:
 910             standardMsg = '%r not greater than %r' % (a, b)
 911             self.fail(self._formatMessage(msg, standardMsg))
 912
 913     def assertGreaterEqual(self, a, b, msg=None):
 914         """Just like self.assertTrue(a >= b), but with a nicer default message."""
 915         if not a >= b:
 916             standardMsg = '%r not greater than or equal to %r' % (a, b)
 917             self.fail(self._formatMessage(msg, standardMsg))
 918
 919     def assertIsNone(self, obj, msg=None):
 920         """Same as self.assertTrue(obj is None), with a nicer default message."""
 921         if obj is not None:
 922             standardMsg = '%r is not None' % obj
 923             self.fail(self._formatMessage(msg, standardMsg))
 924
 925     def assertIsNotNone(self, obj, msg=None):
 926         """Included for symmetry with assertIsNone."""
 927         if obj is None:
 928             standardMsg = 'unexpectedly None'
 929             self.fail(self._formatMessage(msg, standardMsg))
 930
 931     def assertRaisesRegexp(self, expected_exception, expected_regexp,
 932                            callable_obj=None, *args, **kwargs):
 933         """Asserts that the message in a raised exception matches a regexp.
 934
 935         Args:
 936             expected_exception: Exception class expected to be raised.
 937             expected_regexp: Regexp (re pattern object or string) expected
 938                     to be found in error message.
 939             callable_obj: Function to be called.
 940             args: Extra args.
 941             kwargs: Extra kwargs.
 942         """
 943         context = _AssertRaisesContext(expected_exception, self, expected_regexp)
 944         if callable_obj is None:
 945             return context
 946         with context:
 947             callable_obj(*args, **kwargs)
 948
 949     def assertRegexpMatches(self, text, expected_regex, msg=None):
 950         if isinstance(expected_regex, basestring):
 951             expected_regex = re.compile(expected_regex)
 952         if not expected_regex.search(text):
 953             msg = msg or "Regexp didn't match"
 954             msg = '%s: %r not found in %r' % (msg, expected_regex.pattern, text)
 955             raise self.failureException(msg)
 956
 957
 958 def _SortedListDifference(expected, actual):
 959     """Finds elements in only one or the other of two, sorted input lists.
 960
 961     Returns a two-element tuple of lists.    The first list contains those
 962     elements in the "expected" list but not in the "actual" list, and the
 963     second contains those elements in the "actual" list but not in the
 964     "expected" list.    Duplicate elements in either input list are ignored.
 965     """
 966     i = j = 0
 967     missing = []
 968     unexpected = []
 969     while True:
 970         try:
 971             e = expected[i]
 972             a = actual[j]
 973             if e < a:
 974                 missing.append(e)
 975                 i += 1
 976                 while expected[i] == e:
 977                     i += 1
 978             elif e > a:
 979                 unexpected.append(a)
 980                 j += 1
 981                 while actual[j] == a:
 982                     j += 1
 983             else:
 984                 i += 1
 985                 try:
 986                     while expected[i] == e:
 987                         i += 1
 988                 finally:
 989                     j += 1
 990                     while actual[j] == a:
 991                         j += 1
 992         except IndexError:
 993             missing.extend(expected[i:])
 994             unexpected.extend(actual[j:])
 995             break
 996     return missing, unexpected
 997
 998
 999 class TestSuite(object):
1000     """A test suite is a composite test consisting of a number of TestCases.
1001
1002     For use, create an instance of TestSuite, then add test case instances.
1003     When all tests have been added, the suite can be passed to a test
1004     runner, such as TextTestRunner. It will run the individual test cases
1005     in the order in which they were added, aggregating the results. When
1006     subclassing, do not forget to call the base class constructor.
1007     """
1008     def __init__(self, tests=()):
1009         self._tests = []
1010         self.addTests(tests)
1011
1012     def __repr__(self):
1013         return "<%s tests=%s>" % (_strclass(self.__class__), list(self))
1014
1015     def __eq__(self, other):
1016         if not isinstance(other, self.__class__):
1017             return NotImplemented
1018         return self._tests == other._tests
1019
1020     def __ne__(self, other):
1021         return not self == other
1022
1023     # Can't guarantee hash invariant, so flag as unhashable
1024     __hash__ = None
1025
1026     def __iter__(self):
1027         return iter(self._tests)
1028
1029     def countTestCases(self):
1030         cases = 0
1031         for test in self:
1032             cases += test.countTestCases()
1033         return cases
1034
1035     def addTest(self, test):
1036         # sanity checks
1037         if not hasattr(test, '__call__'):
1038             raise TypeError("the test to add must be callable")
1039         if isinstance(test, type) and issubclass(test, (TestCase, TestSuite)):
1040             raise TypeError("TestCases and TestSuites must be instantiated "
1041                             "before passing them to addTest()")
1042         self._tests.append(test)
1043
1044     def addTests(self, tests):
1045         if isinstance(tests, basestring):
1046             raise TypeError("tests must be an iterable of tests, not a string")
1047         for test in tests:
1048             self.addTest(test)
1049
1050     def run(self, result):
1051         for test in self:
1052             if result.shouldStop:
1053                 break
1054             test(result)
1055         return result
1056
1057     def __call__(self, *args, **kwds):
1058         return self.run(*args, **kwds)
1059
1060     def debug(self):
1061         """Run the tests without collecting errors in a TestResult"""
1062         for test in self:
1063             test.debug()
1064
1065
1066 class ClassTestSuite(TestSuite):
1067     """
1068     Suite of tests derived from a single TestCase class.
1069     """
1070
1071     def __init__(self, tests, class_collected_from):
1072         super(ClassTestSuite, self).__init__(tests)
1073         self.collected_from = class_collected_from
1074
1075     def id(self):
1076         module = getattr(self.collected_from, "__module__", None)
1077         if module is not None:
1078             return "{0}.{1}".format(module, self.collected_from.__name__)
1079         return self.collected_from.__name__
1080
1081     def run(self, result):
1082         if getattr(self.collected_from, "__unittest_skip__", False):
1083             # ClassTestSuite result pretends to be a TestCase enough to be
1084             # reported.
1085             result.startTest(self)
1086             try:
1087                 result.addSkip(self, self.collected_from.__unittest_skip_why__)
1088             finally:
1089                 result.stopTest(self)
1090         else:
1091             result = super(ClassTestSuite, self).run(result)
1092         return result
1093
1094     shortDescription = id
1095
1096
1097 class FunctionTestCase(TestCase):
1098     """A test case that wraps a test function.
1099
1100     This is useful for slipping pre-existing test functions into the
1101     unittest framework. Optionally, set-up and tidy-up functions can be
1102     supplied. As with TestCase, the tidy-up ('tearDown') function will
1103     always be called if the set-up ('setUp') function ran successfully.
1104     """
1105
1106     def __init__(self, testFunc, setUp=None, tearDown=None, description=None):
1107         super(FunctionTestCase, self).__init__()
1108         self._setUpFunc = setUp
1109         self._tearDownFunc = tearDown
1110         self._testFunc = testFunc
1111         self._description = description
1112
1113     def setUp(self):
1114         if self._setUpFunc is not None:
1115             self._setUpFunc()
1116
1117     def tearDown(self):
1118         if self._tearDownFunc is not None:
1119             self._tearDownFunc()
1120
1121     def runTest(self):
1122         self._testFunc()
1123
1124     def id(self):
1125         return self._testFunc.__name__
1126
1127     def __eq__(self, other):
1128         if not isinstance(other, self.__class__):
1129             return NotImplemented
1130
1131         return self._setUpFunc == other._setUpFunc and \
1132                self._tearDownFunc == other._tearDownFunc and \
1133                self._testFunc == other._testFunc and \
1134                self._description == other._description
1135
1136     def __ne__(self, other):
1137         return not self == other
1138
1139     def __hash__(self):
1140         return hash((type(self), self._setUpFunc, self._tearDownFunc,
1141                      self._testFunc, self._description))
1142
1143     def __str__(self):
1144         return "%s (%s)" % (_strclass(self.__class__), self.__testFunc.__name__)
1145
1146     def __repr__(self):
1147         return "<%s testFunc=%s>" % (_strclass(self.__class__), self._testFunc)
1148
1149     def shortDescription(self):
1150         if self._description is not None:
1151             return self._description
1152         doc = self._testFunc.__doc__
1153         return doc and doc.split("\n")[0].strip() or None
1154
1155
1156
1157 ##############################################################################
1158 # Locating and loading tests
1159 ##############################################################################
1160
1161 class TestLoader(object):
1162     """
1163     This class is responsible for loading tests according to various criteria
1164     and returning them wrapped in a TestSuite
1165     """
1166     testMethodPrefix = 'test'
1167     sortTestMethodsUsing = cmp
1168     suiteClass = TestSuite
1169     classSuiteClass = ClassTestSuite
1170
1171     def loadTestsFromTestCase(self, testCaseClass):
1172         """Return a suite of all tests cases contained in testCaseClass"""
1173         if issubclass(testCaseClass, TestSuite):
1174             raise TypeError("Test cases should not be derived from TestSuite." \
1175                                 " Maybe you meant to derive from TestCase?")
1176         testCaseNames = self.getTestCaseNames(testCaseClass)
1177         if not testCaseNames and hasattr(testCaseClass, 'runTest'):
1178             testCaseNames = ['runTest']
1179         suite = self.classSuiteClass(map(testCaseClass, testCaseNames),
1180                                      testCaseClass)
1181         return suite
1182
1183     def loadTestsFromModule(self, module):
1184         """Return a suite of all tests cases contained in the given module"""
1185         tests = []
1186         for name in dir(module):
1187             obj = getattr(module, name)
1188             if isinstance(obj, type) and issubclass(obj, TestCase):
1189                 tests.append(self.loadTestsFromTestCase(obj))
1190         return self.suiteClass(tests)
1191
1192     def loadTestsFromName(self, name, module=None):
1193         """Return a suite of all tests cases given a string specifier.
1194
1195         The name may resolve either to a module, a test case class, a
1196         test method within a test case class, or a callable object which
1197         returns a TestCase or TestSuite instance.
1198
1199         The method optionally resolves the names relative to a given module.
1200         """
1201         parts = name.split('.')
1202         if module is None:
1203             parts_copy = parts[:]
1204             while parts_copy:
1205                 try:
1206                     module = __import__('.'.join(parts_copy))
1207                     break
1208                 except ImportError:
1209                     del parts_copy[-1]
1210                     if not parts_copy:
1211                         raise
1212             parts = parts[1:]
1213         obj = module
1214         for part in parts:
1215             parent, obj = obj, getattr(obj, part)
1216
1217         if isinstance(obj, types.ModuleType):
1218             return self.loadTestsFromModule(obj)
1219         elif isinstance(obj, type) and issubclass(obj, TestCase):
1220             return self.loadTestsFromTestCase(obj)
1221         elif (isinstance(obj, types.UnboundMethodType) and
1222               isinstance(parent, type) and
1223               issubclass(parent, TestCase)):
1224             return TestSuite([parent(obj.__name__)])
1225         elif isinstance(obj, TestSuite):
1226             return obj
1227         elif hasattr(obj, '__call__'):
1228             test = obj()
1229             if isinstance(test, TestSuite):
1230                 return test
1231             elif isinstance(test, TestCase):
1232                 return TestSuite([test])
1233             else:
1234                 raise TypeError("calling %s returned %s, not a test" %
1235                                 (obj, test))
1236         else:
1237             raise TypeError("don't know how to make test from: %s" % obj)
1238
1239     def loadTestsFromNames(self, names, module=None):
1240         """Return a suite of all tests cases found using the given sequence
1241         of string specifiers. See 'loadTestsFromName()'.
1242         """
1243         suites = [self.loadTestsFromName(name, module) for name in names]
1244         return self.suiteClass(suites)
1245
1246     def getTestCaseNames(self, testCaseClass):
1247         """Return a sorted sequence of method names found within testCaseClass
1248         """
1249         def isTestMethod(attrname, testCaseClass=testCaseClass,
1250                          prefix=self.testMethodPrefix):
1251             return attrname.startswith(prefix) and \
1252                 hasattr(getattr(testCaseClass, attrname), '__call__')
1253         testFnNames = filter(isTestMethod, dir(testCaseClass))
1254         if self.sortTestMethodsUsing:
1255             testFnNames.sort(key=_CmpToKey(self.sortTestMethodsUsing))
1256         return testFnNames
1257
1258
1259
1260 defaultTestLoader = TestLoader()
1261
1262
1263 ##############################################################################
1264 # Patches for old functions: these functions should be considered obsolete
1265 ##############################################################################
1266
1267 def _makeLoader(prefix, sortUsing, suiteClass=None):
1268     loader = TestLoader()
1269     loader.sortTestMethodsUsing = sortUsing
1270     loader.testMethodPrefix = prefix
1271     if suiteClass: loader.suiteClass = suiteClass
1272     return loader
1273
1274 def getTestCaseNames(testCaseClass, prefix, sortUsing=cmp):
1275     return _makeLoader(prefix, sortUsing).getTestCaseNames(testCaseClass)
1276
1277 def makeSuite(testCaseClass, prefix='test', sortUsing=cmp, suiteClass=TestSuite):
1278     return _makeLoader(prefix, sortUsing, suiteClass).loadTestsFromTestCase(testCaseClass)
1279
1280 def findTestCases(module, prefix='test', sortUsing=cmp, suiteClass=TestSuite):
1281     return _makeLoader(prefix, sortUsing, suiteClass).loadTestsFromModule(module)
1282
1283
1284 ##############################################################################
1285 # Text UI
1286 ##############################################################################
1287
1288 class _WritelnDecorator(object):
1289     """Used to decorate file-like objects with a handy 'writeln' method"""
1290     def __init__(self,stream):
1291         self.stream = stream
1292
1293     def __getattr__(self, attr):
1294         return getattr(self.stream,attr)
1295
1296     def writeln(self, arg=None):
1297         if arg:
1298             self.write(arg)
1299         self.write('\n') # text-mode streams translate to \r\n if needed
1300
1301
1302 class _TextTestResult(TestResult):
1303     """A test result class that can print formatted text results to a stream.
1304
1305     Used by TextTestRunner.
1306     """
1307     separator1 = '=' * 70
1308     separator2 = '-' * 70
1309
1310     def __init__(self, stream, descriptions, verbosity):
1311         super(_TextTestResult, self).__init__()
1312         self.stream = stream
1313         self.showAll = verbosity > 1
1314         self.dots = verbosity == 1
1315         self.descriptions = descriptions
1316
1317     def getDescription(self, test):
1318         if self.descriptions:
1319             return test.shortDescription() or str(test)
1320         else:
1321             return str(test)
1322
1323     def startTest(self, test):
1324         super(_TextTestResult, self).startTest(test)
1325         if self.showAll:
1326             self.stream.write(self.getDescription(test))
1327             self.stream.write(" ... ")
1328             self.stream.flush()
1329
1330     def addSuccess(self, test):
1331         super(_TextTestResult, self).addSuccess(test)
1332         if self.showAll:
1333             self.stream.writeln("ok")
1334         elif self.dots:
1335             self.stream.write('.')
1336             self.stream.flush()
1337
1338     def addError(self, test, err):
1339         super(_TextTestResult, self).addError(test, err)
1340         if self.showAll:
1341             self.stream.writeln("ERROR")
1342         elif self.dots:
1343             self.stream.write('E')
1344             self.stream.flush()
1345
1346     def addFailure(self, test, err):
1347         super(_TextTestResult, self).addFailure(test, err)
1348         if self.showAll:
1349             self.stream.writeln("FAIL")
1350         elif self.dots:
1351             self.stream.write('F')
1352             self.stream.flush()
1353
1354     def addSkip(self, test, reason):
1355         super(_TextTestResult, self).addSkip(test, reason)
1356         if self.showAll:
1357             self.stream.writeln("skipped {0!r}".format(reason))
1358         elif self.dots:
1359             self.stream.write("s")
1360             self.stream.flush()
1361
1362     def addExpectedFailure(self, test, err):
1363         super(_TextTestResult, self).addExpectedFailure(test, err)
1364         if self.showAll:
1365             self.stream.writeln("expected failure")
1366         elif self.dots:
1367             self.stream.write("x")
1368             self.stream.flush()
1369
1370     def addUnexpectedSuccess(self, test):
1371         super(_TextTestResult, self).addUnexpectedSuccess(test)
1372         if self.showAll:
1373             self.stream.writeln("unexpected success")
1374         elif self.dots:
1375             self.stream.write("u")
1376             self.stream.flush()
1377
1378     def printErrors(self):
1379         if self.dots or self.showAll:
1380             self.stream.writeln()
1381         self.printErrorList('ERROR', self.errors)
1382         self.printErrorList('FAIL', self.failures)
1383
1384     def printErrorList(self, flavour, errors):
1385         for test, err in errors:
1386             self.stream.writeln(self.separator1)
1387             self.stream.writeln("%s: %s" % (flavour,self.getDescription(test)))
1388             self.stream.writeln(self.separator2)
1389             self.stream.writeln("%s" % err)
1390
1391
1392 class TextTestRunner(object):
1393     """A test runner class that displays results in textual form.
1394
1395     It prints out the names of tests as they are run, errors as they
1396     occur, and a summary of the results at the end of the test run.
1397     """
1398     def __init__(self, stream=sys.stderr, descriptions=1, verbosity=1):
1399         self.stream = _WritelnDecorator(stream)
1400         self.descriptions = descriptions
1401         self.verbosity = verbosity
1402
1403     def _makeResult(self):
1404         return _TextTestResult(self.stream, self.descriptions, self.verbosity)
1405
1406     def run(self, test):
1407         "Run the given test case or test suite."
1408         result = self._makeResult()
1409         startTime = time.time()
1410         test(result)
1411         stopTime = time.time()
1412         timeTaken = stopTime - startTime
1413         result.printErrors()
1414         self.stream.writeln(result.separator2)
1415         run = result.testsRun
1416         self.stream.writeln("Ran %d test%s in %.3fs" %
1417                             (run, run != 1 and "s" or "", timeTaken))
1418         self.stream.writeln()
1419         results = map(len, (result.expectedFailures,
1420                             result.unexpectedSuccesses,
1421                             result.skipped))
1422         expectedFails, unexpectedSuccesses, skipped = results
1423         infos = []
1424         if not result.wasSuccessful():
1425             self.stream.write("FAILED")
1426             failed, errored = map(len, (result.failures, result.errors))
1427             if failed:
1428                 infos.append("failures=%d" % failed)
1429             if errored:
1430                 infos.append("errors=%d" % errored)
1431         else:
1432             self.stream.write("OK")
1433         if skipped:
1434             infos.append("skipped=%d" % skipped)
1435         if expectedFails:
1436             infos.append("expected failures=%d" % expectedFails)
1437         if unexpectedSuccesses:
1438             infos.append("unexpected successes=%d" % unexpectedSuccesses)
1439         if infos:
1440             self.stream.writeln(" (%s)" % (", ".join(infos),))
1441         else:
1442             self.stream.write("\n")
1443         return result
1444
1445
1446
1447 ##############################################################################
1448 # Facilities for running tests from the command line
1449 ##############################################################################
1450
1451 class TestProgram(object):
1452     """A command-line program that runs a set of tests; this is primarily
1453        for making test modules conveniently executable.
1454     """
1455     USAGE = """\
1456 Usage: %(progName)s [options] [test] [...]
1457
1458 Options:
1459   -h, --help       Show this message
1460   -v, --verbose    Verbose output
1461   -q, --quiet      Minimal output
1462
1463 Examples:
1464   %(progName)s                               - run default set of tests
1465   %(progName)s MyTestSuite                   - run suite 'MyTestSuite'
1466   %(progName)s MyTestCase.testSomething      - run MyTestCase.testSomething
1467   %(progName)s MyTestCase                    - run all 'test*' test methods
1468                                                in MyTestCase
1469 """
1470     def __init__(self, module='__main__', defaultTest=None,
1471                  argv=None, testRunner=TextTestRunner,
1472                  testLoader=defaultTestLoader):
1473         if isinstance(module, basestring):
1474             self.module = __import__(module)
1475             for part in module.split('.')[1:]:
1476                 self.module = getattr(self.module, part)
1477         else:
1478             self.module = module
1479         if argv is None:
1480             argv = sys.argv
1481         self.verbosity = 1
1482         self.defaultTest = defaultTest
1483         self.testRunner = testRunner
1484         self.testLoader = testLoader
1485         self.progName = os.path.basename(argv[0])
1486         self.parseArgs(argv)
1487         self.runTests()
1488
1489     def usageExit(self, msg=None):
1490         if msg:
1491             print msg
1492         print self.USAGE % self.__dict__
1493         sys.exit(2)
1494
1495     def parseArgs(self, argv):
1496         import getopt
1497         long_opts = ['help','verbose','quiet']
1498         try:
1499             options, args = getopt.getopt(argv[1:], 'hHvq', long_opts)
1500             for opt, value in options:
1501                 if opt in ('-h','-H','--help'):
1502                     self.usageExit()
1503                 if opt in ('-q','--quiet'):
1504                     self.verbosity = 0
1505                 if opt in ('-v','--verbose'):
1506                     self.verbosity = 2
1507             if len(args) == 0 and self.defaultTest is None:
1508                 self.test = self.testLoader.loadTestsFromModule(self.module)
1509                 return
1510             if len(args) > 0:
1511                 self.testNames = args
1512             else:
1513                 self.testNames = (self.defaultTest,)
1514             self.createTests()
1515         except getopt.error, msg:
1516             self.usageExit(msg)
1517
1518     def createTests(self):
1519         self.test = self.testLoader.loadTestsFromNames(self.testNames,
1520                                                        self.module)
1521
1522     def runTests(self):
1523         if isinstance(self.testRunner, (type, types.ClassType)):
1524             try:
1525                 testRunner = self.testRunner(verbosity=self.verbosity)
1526             except TypeError:
1527                 # didn't accept the verbosity argument
1528                 testRunner = self.testRunner()
1529         else:
1530             # it is assumed to be a TestRunner instance
1531             testRunner = self.testRunner
1532         result = testRunner.run(self.test)
1533         sys.exit(not result.wasSuccessful())
1534
1535 main = TestProgram
1536
1537
1538 ##############################################################################
1539 # Executing this module from the command line
1540 ##############################################################################
1541
1542 if __name__ == "__main__":
1543     main(module=None)