3 Python unit testing framework, based on Erich Gamma's JUnit and Kent Beck's
4 Smalltalk testing framework.
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
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)
23 if __name__ == '__main__':
26 Further information is available in the bundled documentation, and from
28 http://docs.python.org/library/unittest.html
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.
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
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.
59 ##############################################################################
60 # Exported classes and functions
61 ##############################################################################
62 __all__
= ['TestResult', 'TestCase', 'TestSuite', 'ClassTestSuite',
63 'TextTestRunner', 'TestLoader', 'FunctionTestCase', 'main',
64 'defaultTestLoader', 'SkipTest', 'skip', 'skipIf', 'skipUnless',
67 # Expose obsolete functions for backwards compatibility
68 __all__
.extend(['getTestCaseNames', 'makeSuite', 'findTestCases'])
71 ##############################################################################
72 # Backward compatibility
73 ##############################################################################
76 'Convert a cmp= function into a key= function'
78 def __init__(self
, obj
):
80 def __lt__(self
, other
):
81 return mycmp(self
.obj
, other
.obj
) == -1
84 ##############################################################################
86 ##############################################################################
89 return "%s.%s" % (cls
.__module
__, cls
.__name
__)
92 class SkipTest(Exception):
94 Raise this exception in a test to skip it.
96 Usually you can use TestResult.skip() or one of the skipping decorators
97 instead of raising this directly.
101 class _ExpectedFailure(Exception):
103 Raise this when a test is expected to fail.
105 This is an implementation detail.
108 def __init__(self
, exc_info
):
109 super(_ExpectedFailure
, self
).__init
__()
110 self
.exc_info
= exc_info
112 class _UnexpectedSuccess(Exception):
114 The test was supposed to fail, but it didn't!
123 Unconditionally skip a test.
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
130 @functools.wraps(test_item
)
131 def skip_wrapper(*args
, **kwargs
):
132 raise SkipTest(reason
)
136 def skipIf(condition
, reason
):
138 Skip a test if the condition is true.
144 def skipUnless(condition
, reason
):
146 Skip a test unless the condition is true.
153 def expectedFailure(func
):
154 @functools.wraps(func
)
155 def wrapper(*args
, **kwargs
):
157 func(*args
, **kwargs
)
159 raise _ExpectedFailure(sys
.exc_info())
160 raise _UnexpectedSuccess
165 class TestResult(object):
166 """Holder for test result information.
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.
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.
181 self
.expectedFailures
= []
182 self
.unexpectedSuccesses
= []
183 self
.shouldStop
= False
185 def startTest(self
, test
):
186 "Called when the given test is about to be run"
187 self
.testsRun
= self
.testsRun
+ 1
189 def stopTest(self
, test
):
190 "Called when the given test has been run"
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().
197 self
.errors
.append((test
, self
._exc
_info
_to
_string
(err
, test
)))
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
)))
204 def addSuccess(self
, test
):
205 "Called when a test has completed successfully"
208 def addSkip(self
, test
, reason
):
209 """Called when a test is skipped."""
210 self
.skipped
.append((test
, reason
))
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
)))
217 def addUnexpectedSuccess(self
, test
):
218 """Called when a test was expected to fail, but succeed."""
219 self
.unexpectedSuccesses
.append(test
)
221 def wasSuccessful(self
):
222 "Tells whether or not this result was a success"
223 return len(self
.failures
) == len(self
.errors
) == 0
226 "Indicates that the tests should be aborted"
227 self
.shouldStop
= True
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
):
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
))
241 def _is_relevant_tb_level(self
, tb
):
242 return '__unittest' in tb
.tb_frame
.f_globals
244 def _count_relevant_tb_levels(self
, tb
):
246 while tb
and not self
._is
_relevant
_tb
_level
(tb
):
252 return "<%s run=%i errors=%i failures=%i>" % \
253 (_strclass(self
.__class
__), self
.testsRun
, len(self
.errors
),
257 class _AssertRaisesContext(object):
258 """A context manager used to implement TestCase.assertRaises* methods."""
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
268 def __exit__(self
, exc_type
, exc_value
, traceback
):
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
279 if self
.expected_regex
is None:
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
)))
291 class _AssertWrapper(object):
292 """Wrap entries in the _type_equality_funcs registry to make them deep
295 def __init__(self
, function
):
296 self
.function
= function
298 def __deepcopy__(self
, memo
):
299 memo
[id(self
)] = self
302 class TestCase(object):
303 """A class whose instances are single test cases.
305 By default, the test code itself should be placed in a method named
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.
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.
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
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'
328 failureException
= AssertionError
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.
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.
342 self
._testMethodName
= methodName
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
__
350 # Map types to custom assertEqual functions that will compare
351 # instances of said type in more detail to generate a more useful
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
)
360 def addTypeEqualityFunc(self
, typeobj
, function
):
361 """Add a type specific assertEqual style function to compare a type.
363 This method is for use by TestCase subclasses that need to register
364 their own type equality functions to provide nicer error messages.
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.
373 self
._type
_equality
_funcs
[typeobj
] = _AssertWrapper(function
)
376 "Hook method for setting up the test fixture before exercising it."
380 "Hook method for deconstructing the test fixture after testing it."
383 def countTestCases(self
):
386 def defaultTestResult(self
):
389 def shortDescription(self
):
390 """Returns both the test method name and first line of its docstring.
392 If no docstring is given, only returns the method name.
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.
399 doc_first_line
= None
401 if self
._testMethodDoc
:
402 doc_first_line
= self
._testMethodDoc
.split("\n")[0].strip()
404 desc
= '\n'.join((desc
, doc_first_line
))
408 return "%s.%s" % (_strclass(self
.__class
__), self
._testMethodName
)
410 def __eq__(self
, other
):
411 if type(self
) is not type(other
):
412 return NotImplemented
414 return self
._testMethodName
== other
._testMethodName
416 def __ne__(self
, other
):
417 return not self
== other
420 return hash((type(self
), self
._testMethodName
))
423 return "%s (%s)" % (self
._testMethodName
, _strclass(self
.__class
__))
426 return "<%s testMethod=%s>" % \
427 (_strclass(self
.__class
__), self
._testMethodName
)
429 def run(self
, result
=None):
431 result
= self
.defaultTestResult()
432 result
.startTest(self
)
433 testMethod
= getattr(self
, self
._testMethodName
)
437 except SkipTest
as e
:
438 result
.addSkip(self
, str(e
))
441 result
.addError(self
, sys
.exc_info())
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
))
456 result
.addError(self
, sys
.exc_info())
463 result
.addError(self
, sys
.exc_info())
466 result
.addSuccess(self
)
468 result
.stopTest(self
)
470 def __call__(self
, *args
, **kwds
):
471 return self
.run(*args
, **kwds
)
474 """Run the test without collecting errors in a TestResult"""
476 getattr(self
, self
._testMethodName
)()
479 def skipTest(self
, reason
):
480 """Skip this test."""
481 raise SkipTest(reason
)
483 def fail(self
, msg
=None):
484 """Fail immediately, with the given message."""
485 raise self
.failureException(msg
)
487 def assertFalse(self
, expr
, msg
=None):
488 "Fail the test if the expression is true."
490 msg
= self
._formatMessage
(msg
, "%r is not False" % expr
)
491 raise self
.failureException(msg
)
493 def assertTrue(self
, expr
, msg
=None):
494 """Fail the test unless the expression is true."""
496 msg
= self
._formatMessage
(msg
, "%r is not True" % expr
)
497 raise self
.failureException(msg
)
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
505 If longMessage is True:
506 * Use the standard message
507 * If an explicit message is provided, plus ' : ' and the explicit message
509 if not self
.longMessage
:
510 return msg
or standardMsg
513 return standardMsg
+ ' : ' + msg
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.
524 If called with callableObj omitted or None, will return a
525 context object used like this::
527 with self.assertRaises(some_error_class):
530 context
= _AssertRaisesContext(excClass
, self
)
531 if callableObj
is None:
534 callableObj(*args
, **kwargs
)
536 def _getAssertEqualityFunc(self
, first
, second
):
537 """Get a detailed comparison function for the types of the two args.
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.
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.
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
558 return self
._baseAssertEqual
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
)
567 def assertEqual(self
, first
, second
, msg
=None):
568 """Fail if the two objects are unequal as determined by the '=='
571 assertion_func
= self
._getAssertEqualityFunc
(first
, second
)
572 assertion_func(first
, second
, msg
=msg
)
574 def assertNotEqual(self
, first
, second
, msg
=None):
575 """Fail if the two objects are equal as determined by the '=='
578 if not first
!= second
:
579 msg
= self
._formatMessage
(msg
, '%r == %r' % (first
, second
))
580 raise self
.failureException(msg
)
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.
587 Note that decimal places (from zero) are usually not the same
588 as significant digits (measured from the most signficant digit).
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
)
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.
600 Note that decimal places (from zero) are usually not the same
601 as significant digits (measured from the most signficant digit).
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
)
608 # Synonyms for assertion methods
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
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
):
624 'Please use {0} instead.'.format(original_func
.__name
__),
625 PendingDeprecationWarning
, 2)
626 return original_func(*args
, **kwargs
)
627 return deprecated_func
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
)
637 def assertSequenceEqual(self
, seq1
, seq2
, msg
=None, seq_type
=None):
638 """An equality assertion for ordered sequences (like lists and tuples).
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.
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
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
))
660 seq_type_name
= "sequence"
665 except (TypeError, NotImplementedError):
666 differing
= 'First %s has no length. Non-sequence?' % (
669 if differing
is None:
672 except (TypeError, NotImplementedError):
673 differing
= 'Second %s has no length. Non-sequence?' % (
676 if differing
is None:
680 for i
in xrange(min(len1
, len2
)):
683 except (TypeError, IndexError, NotImplementedError):
684 differing
= ('Unable to index element %d of first %s\n' %
690 except (TypeError, IndexError, NotImplementedError):
691 differing
= ('Unable to index element %d of second %s\n' %
696 differing
= ('First differing element %d:\n%s\n%s\n' %
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.
704 # A catch-all message for handling arbitrary user-defined
706 differing
= '%ss differ:\n' % seq_type_name
.capitalize()
708 differing
= ('First %s contains %d additional '
709 'elements.\n' % (seq_type_name
, len1
- len2
))
711 differing
+= ('First extra element %d:\n%s\n' %
713 except (TypeError, IndexError, NotImplementedError):
714 differing
+= ('Unable to index element %d '
715 'of first %s\n' % (len2
, seq_type_name
))
717 differing
= ('Second %s contains %d additional '
718 'elements.\n' % (seq_type_name
, len2
- len1
))
720 differing
+= ('First extra element %d:\n%s\n' %
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
)
730 def assertListEqual(self
, list1
, list2
, msg
=None):
731 """A list-specific equality assertion.
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
740 self
.assertSequenceEqual(list1
, list2
, msg
, seq_type
=list)
742 def assertTupleEqual(self
, tuple1
, tuple2
, msg
=None):
743 """A tuple-specific equality assertion.
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
751 self
.assertSequenceEqual(tuple1
, tuple2
, msg
, seq_type
=tuple)
753 def assertSetEqual(self
, set1
, set2
, msg
=None):
754 """A set-specific equality assertion.
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
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).
768 difference1
= set1
.difference(set2
)
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
)
775 difference2
= set2
.difference(set1
)
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
)
781 if not (difference1
or difference2
):
786 lines
.append('Items in the first set but not the second:')
787 for item
in difference1
:
788 lines
.append(repr(item
))
790 lines
.append('Items in the second set but not the first:')
791 for item
in difference2
:
792 lines
.append(repr(item
))
794 standardMsg
= '\n'.join(lines
)
795 self
.fail(self
._formatMessage
(msg
, standardMsg
))
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
))
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
))
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
))
815 def assertIsNot(self
, expr1
, expr2
, msg
=None):
816 """Just like self.assertTrue(a is not b), but with a nicer default message."""
818 standardMsg
= 'unexpectedly identical: %r' % (expr1
,)
819 self
.fail(self
._formatMessage
(msg
, standardMsg
))
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')
826 standardMsg
= ('\n' + '\n'.join(difflib
.ndiff(
827 pprint
.pformat(d1
).splitlines(),
828 pprint
.pformat(d2
).splitlines())))
829 self
.fail(self
._formatMessage
(msg
, standardMsg
))
831 def assertDictContainsSubset(self
, expected
, actual
, msg
=None):
832 """Checks whether actual is a superset of expected."""
835 for key
, value
in expected
.iteritems():
836 if key
not in actual
:
838 elif value
!= actual
[key
]:
839 mismatched
.append('%s, expected: %s, actual: %s' % (key
, value
, actual
[key
]))
841 if not (missing
or mismatched
):
846 standardMsg
= 'Missing: %r' % ','.join(missing
)
850 standardMsg
+= 'Mismatched values: %s' % ','.join(mismatched
)
852 self
.fail(self
._formatMessage
(msg
, standardMsg
))
854 def assertSameElements(self
, expected_seq
, actual_seq
, msg
=None):
855 """An unordered sequence specific comparison.
857 Raises with an error message listing which elements of expected_seq
858 are missing from actual_seq and vice versa if any.
861 expected
= set(expected_seq
)
862 actual
= set(actual_seq
)
863 missing
= list(expected
.difference(actual
))
864 unexpected
= list(actual
.difference(expected
))
868 # Fall back to slower list-compare if any of the objects are
870 expected
= list(expected_seq
)
871 actual
= list(actual_seq
)
874 missing
, unexpected
= _SortedListDifference(expected
, actual
)
877 errors
.append('Expected, but missing:\n %r' % missing
)
879 errors
.append('Unexpected, but present:\n %r' % unexpected
)
881 standardMsg
= '\n'.join(errors
)
882 self
.fail(self
._formatMessage
(msg
, standardMsg
))
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'))
892 standardMsg
= '\n' + ''.join(difflib
.ndiff(first
.splitlines(True), second
.splitlines(True)))
893 self
.fail(self
._formatMessage
(msg
, standardMsg
))
895 def assertLess(self
, a
, b
, msg
=None):
896 """Just like self.assertTrue(a < b), but with a nicer default message."""
898 standardMsg
= '%r not less than %r' % (a
, b
)
899 self
.fail(self
._formatMessage
(msg
, standardMsg
))
901 def assertLessEqual(self
, a
, b
, msg
=None):
902 """Just like self.assertTrue(a <= b), but with a nicer default message."""
904 standardMsg
= '%r not less than or equal to %r' % (a
, b
)
905 self
.fail(self
._formatMessage
(msg
, standardMsg
))
907 def assertGreater(self
, a
, b
, msg
=None):
908 """Just like self.assertTrue(a > b), but with a nicer default message."""
910 standardMsg
= '%r not greater than %r' % (a
, b
)
911 self
.fail(self
._formatMessage
(msg
, standardMsg
))
913 def assertGreaterEqual(self
, a
, b
, msg
=None):
914 """Just like self.assertTrue(a >= b), but with a nicer default message."""
916 standardMsg
= '%r not greater than or equal to %r' % (a
, b
)
917 self
.fail(self
._formatMessage
(msg
, standardMsg
))
919 def assertIsNone(self
, obj
, msg
=None):
920 """Same as self.assertTrue(obj is None), with a nicer default message."""
922 standardMsg
= '%r is not None' % obj
923 self
.fail(self
._formatMessage
(msg
, standardMsg
))
925 def assertIsNotNone(self
, obj
, msg
=None):
926 """Included for symmetry with assertIsNone."""
928 standardMsg
= 'unexpectedly None'
929 self
.fail(self
._formatMessage
(msg
, standardMsg
))
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.
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.
941 kwargs: Extra kwargs.
943 context
= _AssertRaisesContext(expected_exception
, self
, expected_regexp
)
944 if callable_obj
is None:
947 callable_obj(*args
, **kwargs
)
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
)
958 def _SortedListDifference(expected
, actual
):
959 """Finds elements in only one or the other of two, sorted input lists.
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.
976 while expected
[i
] == e
:
981 while actual
[j
] == a
:
986 while expected
[i
] == e
:
990 while actual
[j
] == a
:
993 missing
.extend(expected
[i
:])
994 unexpected
.extend(actual
[j
:])
996 return missing
, unexpected
999 class TestSuite(object):
1000 """A test suite is a composite test consisting of a number of TestCases.
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.
1008 def __init__(self
, tests
=()):
1010 self
.addTests(tests
)
1013 return "<%s tests=%s>" % (_strclass(self
.__class
__), list(self
))
1015 def __eq__(self
, other
):
1016 if not isinstance(other
, self
.__class
__):
1017 return NotImplemented
1018 return self
._tests
== other
._tests
1020 def __ne__(self
, other
):
1021 return not self
== other
1023 # Can't guarantee hash invariant, so flag as unhashable
1027 return iter(self
._tests
)
1029 def countTestCases(self
):
1032 cases
+= test
.countTestCases()
1035 def addTest(self
, test
):
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
)
1044 def addTests(self
, tests
):
1045 if isinstance(tests
, basestring
):
1046 raise TypeError("tests must be an iterable of tests, not a string")
1050 def run(self
, result
):
1052 if result
.shouldStop
:
1057 def __call__(self
, *args
, **kwds
):
1058 return self
.run(*args
, **kwds
)
1061 """Run the tests without collecting errors in a TestResult"""
1066 class ClassTestSuite(TestSuite
):
1068 Suite of tests derived from a single TestCase class.
1071 def __init__(self
, tests
, class_collected_from
):
1072 super(ClassTestSuite
, self
).__init
__(tests
)
1073 self
.collected_from
= class_collected_from
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
__
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
1085 result
.startTest(self
)
1087 result
.addSkip(self
, self
.collected_from
.__unittest
_skip
_why
__)
1089 result
.stopTest(self
)
1091 result
= super(ClassTestSuite
, self
).run(result
)
1094 shortDescription
= id
1097 class FunctionTestCase(TestCase
):
1098 """A test case that wraps a test function.
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.
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
1114 if self
._setUpFunc
is not None:
1118 if self
._tearDownFunc
is not None:
1119 self
._tearDownFunc
()
1125 return self
._testFunc
.__name
__
1127 def __eq__(self
, other
):
1128 if not isinstance(other
, self
.__class
__):
1129 return NotImplemented
1131 return self
._setUpFunc
== other
._setUpFunc
and \
1132 self
._tearDownFunc
== other
._tearDownFunc
and \
1133 self
._testFunc
== other
._testFunc
and \
1134 self
._description
== other
._description
1136 def __ne__(self
, other
):
1137 return not self
== other
1140 return hash((type(self
), self
._setUpFunc
, self
._tearDownFunc
,
1141 self
._testFunc
, self
._description
))
1144 return "%s (%s)" % (_strclass(self
.__class
__), self
.__testFunc
.__name
__)
1147 return "<%s testFunc=%s>" % (_strclass(self
.__class
__), self
._testFunc
)
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
1157 ##############################################################################
1158 # Locating and loading tests
1159 ##############################################################################
1161 class TestLoader(object):
1163 This class is responsible for loading tests according to various criteria
1164 and returning them wrapped in a TestSuite
1166 testMethodPrefix
= 'test'
1167 sortTestMethodsUsing
= cmp
1168 suiteClass
= TestSuite
1169 classSuiteClass
= ClassTestSuite
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
),
1183 def loadTestsFromModule(self
, module
):
1184 """Return a suite of all tests cases contained in the given module"""
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
)
1192 def loadTestsFromName(self
, name
, module
=None):
1193 """Return a suite of all tests cases given a string specifier.
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.
1199 The method optionally resolves the names relative to a given module.
1201 parts
= name
.split('.')
1203 parts_copy
= parts
[:]
1206 module
= __import__('.'.join(parts_copy
))
1215 parent
, obj
= obj
, getattr(obj
, part
)
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
):
1227 elif hasattr(obj
, '__call__'):
1229 if isinstance(test
, TestSuite
):
1231 elif isinstance(test
, TestCase
):
1232 return TestSuite([test
])
1234 raise TypeError("calling %s returned %s, not a test" %
1237 raise TypeError("don't know how to make test from: %s" % obj
)
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()'.
1243 suites
= [self
.loadTestsFromName(name
, module
) for name
in names
]
1244 return self
.suiteClass(suites
)
1246 def getTestCaseNames(self
, testCaseClass
):
1247 """Return a sorted sequence of method names found within testCaseClass
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
))
1260 defaultTestLoader
= TestLoader()
1263 ##############################################################################
1264 # Patches for old functions: these functions should be considered obsolete
1265 ##############################################################################
1267 def _makeLoader(prefix
, sortUsing
, suiteClass
=None):
1268 loader
= TestLoader()
1269 loader
.sortTestMethodsUsing
= sortUsing
1270 loader
.testMethodPrefix
= prefix
1271 if suiteClass
: loader
.suiteClass
= suiteClass
1274 def getTestCaseNames(testCaseClass
, prefix
, sortUsing
=cmp):
1275 return _makeLoader(prefix
, sortUsing
).getTestCaseNames(testCaseClass
)
1277 def makeSuite(testCaseClass
, prefix
='test', sortUsing
=cmp, suiteClass
=TestSuite
):
1278 return _makeLoader(prefix
, sortUsing
, suiteClass
).loadTestsFromTestCase(testCaseClass
)
1280 def findTestCases(module
, prefix
='test', sortUsing
=cmp, suiteClass
=TestSuite
):
1281 return _makeLoader(prefix
, sortUsing
, suiteClass
).loadTestsFromModule(module
)
1284 ##############################################################################
1286 ##############################################################################
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
1293 def __getattr__(self
, attr
):
1294 return getattr(self
.stream
,attr
)
1296 def writeln(self
, arg
=None):
1299 self
.write('\n') # text-mode streams translate to \r\n if needed
1302 class _TextTestResult(TestResult
):
1303 """A test result class that can print formatted text results to a stream.
1305 Used by TextTestRunner.
1307 separator1
= '=' * 70
1308 separator2
= '-' * 70
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
1317 def getDescription(self
, test
):
1318 if self
.descriptions
:
1319 return test
.shortDescription() or str(test
)
1323 def startTest(self
, test
):
1324 super(_TextTestResult
, self
).startTest(test
)
1326 self
.stream
.write(self
.getDescription(test
))
1327 self
.stream
.write(" ... ")
1330 def addSuccess(self
, test
):
1331 super(_TextTestResult
, self
).addSuccess(test
)
1333 self
.stream
.writeln("ok")
1335 self
.stream
.write('.')
1338 def addError(self
, test
, err
):
1339 super(_TextTestResult
, self
).addError(test
, err
)
1341 self
.stream
.writeln("ERROR")
1343 self
.stream
.write('E')
1346 def addFailure(self
, test
, err
):
1347 super(_TextTestResult
, self
).addFailure(test
, err
)
1349 self
.stream
.writeln("FAIL")
1351 self
.stream
.write('F')
1354 def addSkip(self
, test
, reason
):
1355 super(_TextTestResult
, self
).addSkip(test
, reason
)
1357 self
.stream
.writeln("skipped {0!r}".format(reason
))
1359 self
.stream
.write("s")
1362 def addExpectedFailure(self
, test
, err
):
1363 super(_TextTestResult
, self
).addExpectedFailure(test
, err
)
1365 self
.stream
.writeln("expected failure")
1367 self
.stream
.write("x")
1370 def addUnexpectedSuccess(self
, test
):
1371 super(_TextTestResult
, self
).addUnexpectedSuccess(test
)
1373 self
.stream
.writeln("unexpected success")
1375 self
.stream
.write("u")
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
)
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
)
1392 class TextTestRunner(object):
1393 """A test runner class that displays results in textual form.
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.
1398 def __init__(self
, stream
=sys
.stderr
, descriptions
=1, verbosity
=1):
1399 self
.stream
= _WritelnDecorator(stream
)
1400 self
.descriptions
= descriptions
1401 self
.verbosity
= verbosity
1403 def _makeResult(self
):
1404 return _TextTestResult(self
.stream
, self
.descriptions
, self
.verbosity
)
1406 def run(self
, test
):
1407 "Run the given test case or test suite."
1408 result
= self
._makeResult
()
1409 startTime
= time
.time()
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
,
1422 expectedFails
, unexpectedSuccesses
, skipped
= results
1424 if not result
.wasSuccessful():
1425 self
.stream
.write("FAILED")
1426 failed
, errored
= map(len, (result
.failures
, result
.errors
))
1428 infos
.append("failures=%d" % failed
)
1430 infos
.append("errors=%d" % errored
)
1432 self
.stream
.write("OK")
1434 infos
.append("skipped=%d" % skipped
)
1436 infos
.append("expected failures=%d" % expectedFails
)
1437 if unexpectedSuccesses
:
1438 infos
.append("unexpected successes=%d" % unexpectedSuccesses
)
1440 self
.stream
.writeln(" (%s)" % (", ".join(infos
),))
1442 self
.stream
.write("\n")
1447 ##############################################################################
1448 # Facilities for running tests from the command line
1449 ##############################################################################
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.
1456 Usage: %(progName)s [options] [test] [...]
1459 -h, --help Show this message
1460 -v, --verbose Verbose output
1461 -q, --quiet Minimal output
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
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
)
1478 self
.module
= module
1482 self
.defaultTest
= defaultTest
1483 self
.testRunner
= testRunner
1484 self
.testLoader
= testLoader
1485 self
.progName
= os
.path
.basename(argv
[0])
1486 self
.parseArgs(argv
)
1489 def usageExit(self
, msg
=None):
1492 print self
.USAGE
% self
.__dict
__
1495 def parseArgs(self
, argv
):
1497 long_opts
= ['help','verbose','quiet']
1499 options
, args
= getopt
.getopt(argv
[1:], 'hHvq', long_opts
)
1500 for opt
, value
in options
:
1501 if opt
in ('-h','-H','--help'):
1503 if opt
in ('-q','--quiet'):
1505 if opt
in ('-v','--verbose'):
1507 if len(args
) == 0 and self
.defaultTest
is None:
1508 self
.test
= self
.testLoader
.loadTestsFromModule(self
.module
)
1511 self
.testNames
= args
1513 self
.testNames
= (self
.defaultTest
,)
1515 except getopt
.error
, msg
:
1518 def createTests(self
):
1519 self
.test
= self
.testLoader
.loadTestsFromNames(self
.testNames
,
1523 if isinstance(self
.testRunner
, (type, types
.ClassType
)):
1525 testRunner
= self
.testRunner(verbosity
=self
.verbosity
)
1527 # didn't accept the verbosity argument
1528 testRunner
= self
.testRunner()
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())
1538 ##############################################################################
1539 # Executing this module from the command line
1540 ##############################################################################
1542 if __name__
== "__main__":