blob: 16a866343f7e53e78360480db0f2f266fa5852f5 [file] [log] [blame]
Fred Drake02538202001-03-21 18:09:46 +00001#!/usr/bin/env python
Steve Purcell5ddd1a82001-03-22 08:45:36 +00002'''
Fred Drake02538202001-03-21 18:09:46 +00003Python unit testing framework, based on Erich Gamma's JUnit and Kent Beck's
4Smalltalk testing framework.
5
Fred Drake02538202001-03-21 18:09:46 +00006This module contains the core framework classes that form the basis of
7specific test cases and suites (TestCase, TestSuite etc.), and also a
8text-based utility class for running the tests and reporting the results
Jeremy Hyltonefef5da2001-10-22 18:14:15 +00009 (TextTestRunner).
Fred Drake02538202001-03-21 18:09:46 +000010
Steve Purcell5ddd1a82001-03-22 08:45:36 +000011Simple usage:
12
13 import unittest
14
15 class IntegerArithmenticTestCase(unittest.TestCase):
16 def testAdd(self): ## test method names begin 'test*'
Benjamin Peterson7fe73a12009-04-04 16:35:46 +000017 self.assertEqual((1 + 2), 3)
18 self.assertEqual(0 + 1, 1)
Steve Purcell7b065702001-09-06 08:24:40 +000019 def testMultiply(self):
Benjamin Peterson7fe73a12009-04-04 16:35:46 +000020 self.assertEqual((0 * 10), 0)
21 self.assertEqual((5 * 8), 40)
Steve Purcell5ddd1a82001-03-22 08:45:36 +000022
23 if __name__ == '__main__':
24 unittest.main()
25
26Further information is available in the bundled documentation, and from
27
Benjamin Peterson52baa292009-03-24 00:56:30 +000028 http://docs.python.org/library/unittest.html
Steve Purcell5ddd1a82001-03-22 08:45:36 +000029
Steve Purcell7e743842003-09-22 11:08:12 +000030Copyright (c) 1999-2003 Steve Purcell
Benjamin Peterson52baa292009-03-24 00:56:30 +000031Copyright (c) 2003-2009 Python Software Foundation
Fred Drake02538202001-03-21 18:09:46 +000032This module is free software, and you may redistribute it and/or modify
33it under the same terms as Python itself, so long as this copyright message
34and disclaimer are retained in their original form.
35
36IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
37SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF
38THIS CODE, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
39DAMAGE.
40
41THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT
42LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
43PARTICULAR PURPOSE. THE CODE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS,
44AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
45SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
Steve Purcell5ddd1a82001-03-22 08:45:36 +000046'''
Fred Drake02538202001-03-21 18:09:46 +000047
Benjamin Peterson7fe73a12009-04-04 16:35:46 +000048import difflib
Benjamin Peterson5254c042009-03-23 22:25:03 +000049import functools
Benjamin Peterson7fe73a12009-04-04 16:35:46 +000050import os
51import pprint
52import re
53import sys
54import time
55import traceback
56import types
57import warnings
Fred Drake02538202001-03-21 18:09:46 +000058
59##############################################################################
Steve Purcelld75e7e42003-09-15 11:01:21 +000060# Exported classes and functions
61##############################################################################
Benjamin Peterson52baa292009-03-24 00:56:30 +000062__all__ = ['TestResult', 'TestCase', 'TestSuite', 'ClassTestSuite',
63 'TextTestRunner', 'TestLoader', 'FunctionTestCase', 'main',
Benjamin Peterson4c93dcb2009-03-24 01:33:55 +000064 'defaultTestLoader', 'SkipTest', 'skip', 'skipIf', 'skipUnless',
Benjamin Peterson52baa292009-03-24 00:56:30 +000065 'expectedFailure']
Steve Purcelld75e7e42003-09-15 11:01:21 +000066
Steve Purcell7e743842003-09-22 11:08:12 +000067# Expose obsolete functions for backwards compatibility
Steve Purcelld75e7e42003-09-15 11:01:21 +000068__all__.extend(['getTestCaseNames', 'makeSuite', 'findTestCases'])
69
70
71##############################################################################
Fred Drake02538202001-03-21 18:09:46 +000072# Test framework core
73##############################################################################
74
Steve Purcelldc391a62002-08-09 09:46:23 +000075def _strclass(cls):
76 return "%s.%s" % (cls.__module__, cls.__name__)
77
Benjamin Peterson5254c042009-03-23 22:25:03 +000078
79class SkipTest(Exception):
80 """
81 Raise this exception in a test to skip it.
82
83 Usually you can use TestResult.skip() or one of the skipping decorators
84 instead of raising this directly.
85 """
86 pass
87
88class _ExpectedFailure(Exception):
89 """
90 Raise this when a test is expected to fail.
91
92 This is an implementation detail.
93 """
94
95 def __init__(self, exc_info):
96 super(_ExpectedFailure, self).__init__()
97 self.exc_info = exc_info
98
99class _UnexpectedSuccess(Exception):
100 """
101 The test was supposed to fail, but it didn't!
102 """
103 pass
104
105def _id(obj):
106 return obj
107
108def skip(reason):
109 """
110 Unconditionally skip a test.
111 """
112 def decorator(test_item):
113 if isinstance(test_item, type) and issubclass(test_item, TestCase):
114 test_item.__unittest_skip__ = True
115 test_item.__unittest_skip_why__ = reason
116 return test_item
117 @functools.wraps(test_item)
118 def skip_wrapper(*args, **kwargs):
119 raise SkipTest(reason)
120 return skip_wrapper
121 return decorator
122
123def skipIf(condition, reason):
124 """
125 Skip a test if the condition is true.
126 """
127 if condition:
128 return skip(reason)
129 return _id
130
131def skipUnless(condition, reason):
132 """
133 Skip a test unless the condition is true.
134 """
135 if not condition:
136 return skip(reason)
137 return _id
138
139
140def expectedFailure(func):
141 @functools.wraps(func)
142 def wrapper(*args, **kwargs):
143 try:
144 func(*args, **kwargs)
145 except Exception:
146 raise _ExpectedFailure(sys.exc_info())
147 raise _UnexpectedSuccess
148 return wrapper
149
Steve Purcellb8d5f242003-12-06 13:03:13 +0000150__unittest = 1
151
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000152class TestResult(object):
Fred Drake02538202001-03-21 18:09:46 +0000153 """Holder for test result information.
154
155 Test results are automatically managed by the TestCase and TestSuite
156 classes, and do not need to be explicitly manipulated by writers of tests.
157
158 Each instance holds the total number of tests run, and collections of
159 failures and errors that occurred among those test runs. The collections
Steve Purcell7b065702001-09-06 08:24:40 +0000160 contain tuples of (testcase, exceptioninfo), where exceptioninfo is the
Fred Drake656f9ec2001-09-06 19:13:14 +0000161 formatted traceback of the error that occurred.
Fred Drake02538202001-03-21 18:09:46 +0000162 """
163 def __init__(self):
164 self.failures = []
165 self.errors = []
166 self.testsRun = 0
Benjamin Peterson5254c042009-03-23 22:25:03 +0000167 self.skipped = []
Benjamin Peterson52baa292009-03-24 00:56:30 +0000168 self.expectedFailures = []
169 self.unexpectedSuccesses = []
Guido van Rossumd8faa362007-04-27 19:54:29 +0000170 self.shouldStop = False
Fred Drake02538202001-03-21 18:09:46 +0000171
172 def startTest(self, test):
173 "Called when the given test is about to be run"
174 self.testsRun = self.testsRun + 1
175
176 def stopTest(self, test):
177 "Called when the given test has been run"
178 pass
179
180 def addError(self, test, err):
Steve Purcell7b065702001-09-06 08:24:40 +0000181 """Called when an error has occurred. 'err' is a tuple of values as
182 returned by sys.exc_info().
183 """
Steve Purcellb8d5f242003-12-06 13:03:13 +0000184 self.errors.append((test, self._exc_info_to_string(err, test)))
Fred Drake02538202001-03-21 18:09:46 +0000185
186 def addFailure(self, test, err):
Steve Purcell7b065702001-09-06 08:24:40 +0000187 """Called when an error has occurred. 'err' is a tuple of values as
188 returned by sys.exc_info()."""
Steve Purcellb8d5f242003-12-06 13:03:13 +0000189 self.failures.append((test, self._exc_info_to_string(err, test)))
Fred Drake02538202001-03-21 18:09:46 +0000190
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000191 def addSuccess(self, test):
192 "Called when a test has completed successfully"
193 pass
194
Benjamin Peterson5254c042009-03-23 22:25:03 +0000195 def addSkip(self, test, reason):
196 """Called when a test is skipped."""
197 self.skipped.append((test, reason))
198
199 def addExpectedFailure(self, test, err):
200 """Called when an expected failure/error occured."""
Benjamin Peterson52baa292009-03-24 00:56:30 +0000201 self.expectedFailures.append(
Benjamin Peterson5254c042009-03-23 22:25:03 +0000202 (test, self._exc_info_to_string(err, test)))
203
204 def addUnexpectedSuccess(self, test):
205 """Called when a test was expected to fail, but succeed."""
Benjamin Peterson52baa292009-03-24 00:56:30 +0000206 self.unexpectedSuccesses.append(test)
Benjamin Peterson5254c042009-03-23 22:25:03 +0000207
Fred Drake02538202001-03-21 18:09:46 +0000208 def wasSuccessful(self):
209 "Tells whether or not this result was a success"
210 return len(self.failures) == len(self.errors) == 0
211
212 def stop(self):
213 "Indicates that the tests should be aborted"
Steve Purcell7e743842003-09-22 11:08:12 +0000214 self.shouldStop = True
Tim Petersa19a1682001-03-29 04:36:09 +0000215
Steve Purcellb8d5f242003-12-06 13:03:13 +0000216 def _exc_info_to_string(self, err, test):
Steve Purcell7b065702001-09-06 08:24:40 +0000217 """Converts a sys.exc_info()-style tuple of values into a string."""
Steve Purcellb8d5f242003-12-06 13:03:13 +0000218 exctype, value, tb = err
219 # Skip test runner traceback levels
220 while tb and self._is_relevant_tb_level(tb):
221 tb = tb.tb_next
222 if exctype is test.failureException:
223 # Skip assert*() traceback levels
224 length = self._count_relevant_tb_levels(tb)
Collin Winterce36ad82007-08-30 01:19:48 +0000225 return ''.join(traceback.format_exception(exctype, value,
226 tb, length))
Steve Purcellb8d5f242003-12-06 13:03:13 +0000227 return ''.join(traceback.format_exception(exctype, value, tb))
228
229 def _is_relevant_tb_level(self, tb):
Guido van Rossume2b70bc2006-08-18 22:13:04 +0000230 return '__unittest' in tb.tb_frame.f_globals
Steve Purcellb8d5f242003-12-06 13:03:13 +0000231
232 def _count_relevant_tb_levels(self, tb):
233 length = 0
234 while tb and not self._is_relevant_tb_level(tb):
235 length += 1
236 tb = tb.tb_next
237 return length
Steve Purcell7b065702001-09-06 08:24:40 +0000238
Fred Drake02538202001-03-21 18:09:46 +0000239 def __repr__(self):
240 return "<%s run=%i errors=%i failures=%i>" % \
Steve Purcelldc391a62002-08-09 09:46:23 +0000241 (_strclass(self.__class__), self.testsRun, len(self.errors),
Fred Drake02538202001-03-21 18:09:46 +0000242 len(self.failures))
243
Benjamin Peterson52baa292009-03-24 00:56:30 +0000244
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000245class _AssertRaisesContext(object):
246 """A context manager used to implement TestCase.assertRaises* methods."""
Benjamin Peterson52baa292009-03-24 00:56:30 +0000247
248
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000249 def __init__(self, expected, test_case, callable_obj=None,
250 expected_regexp=None):
Antoine Pitrou5acd41e2008-12-28 14:29:00 +0000251 self.expected = expected
252 self.failureException = test_case.failureException
253 if callable_obj is not None:
254 try:
255 self.obj_name = callable_obj.__name__
256 except AttributeError:
257 self.obj_name = str(callable_obj)
258 else:
259 self.obj_name = None
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000260 self.expected_regex = expected_regexp
Benjamin Peterson52baa292009-03-24 00:56:30 +0000261
Antoine Pitrou5acd41e2008-12-28 14:29:00 +0000262 def __enter__(self):
263 pass
Benjamin Peterson52baa292009-03-24 00:56:30 +0000264
Antoine Pitrou5acd41e2008-12-28 14:29:00 +0000265 def __exit__(self, exc_type, exc_value, traceback):
266 if exc_type is None:
267 try:
268 exc_name = self.expected.__name__
269 except AttributeError:
270 exc_name = str(self.expected)
271 if self.obj_name:
272 raise self.failureException("{0} not raised by {1}"
273 .format(exc_name, self.obj_name))
274 else:
275 raise self.failureException("{0} not raised"
276 .format(exc_name))
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000277 if not issubclass(exc_type, self.expected):
278 # let unexpected exceptions pass through
279 return False
280 if self.expected_regex is None:
Antoine Pitrou5acd41e2008-12-28 14:29:00 +0000281 return True
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000282
283 expected_regexp = self.expected_regex
284 if isinstance(expected_regexp, (bytes, str)):
285 expected_regexp = re.compile(expected_regexp)
286 if not expected_regexp.search(str(exc_value)):
287 raise self.failureException('"%s" does not match "%s"' %
288 (expected_regexp.pattern, str(exc_value)))
289 return True
290
291
292class _AssertWrapper(object):
293 """Wrap entries in the _type_equality_funcs registry to make them deep
294 copyable."""
295
296 def __init__(self, function):
297 self.function = function
298
299 def __deepcopy__(self, memo):
300 memo[id(self)] = self
Antoine Pitrou5acd41e2008-12-28 14:29:00 +0000301
Benjamin Peterson52baa292009-03-24 00:56:30 +0000302
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000303class TestCase(object):
Fred Drake02538202001-03-21 18:09:46 +0000304 """A class whose instances are single test cases.
305
Fred Drake02538202001-03-21 18:09:46 +0000306 By default, the test code itself should be placed in a method named
307 'runTest'.
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000308
Tim Petersa19a1682001-03-29 04:36:09 +0000309 If the fixture may be used for many test cases, create as
Fred Drake02538202001-03-21 18:09:46 +0000310 many test methods as are needed. When instantiating such a TestCase
311 subclass, specify in the constructor arguments the name of the test method
312 that the instance is to execute.
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000313
Tim Petersa19a1682001-03-29 04:36:09 +0000314 Test authors should subclass TestCase for their own tests. Construction
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000315 and deconstruction of the test's environment ('fixture') can be
316 implemented by overriding the 'setUp' and 'tearDown' methods respectively.
317
318 If it is necessary to override the __init__ method, the base class
319 __init__ method must always be called. It is important that subclasses
320 should not change the signature of their __init__ method, since instances
321 of the classes are instantiated automatically by parts of the framework
322 in order to be run.
Fred Drake02538202001-03-21 18:09:46 +0000323 """
Steve Purcell15d89272001-04-12 09:05:01 +0000324
325 # This attribute determines which exception will be raised when
326 # the instance's assertion methods fail; test methods raising this
327 # exception will be deemed to have 'failed' rather than 'errored'
328
329 failureException = AssertionError
330
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000331 # This attribute determines whether long messages (including repr of
332 # objects used in assert methods) will be printed on failure in *addition*
333 # to any explicit message passed.
334
335 longMessage = False
336
337
Fred Drake02538202001-03-21 18:09:46 +0000338 def __init__(self, methodName='runTest'):
339 """Create an instance of the class that will use the named test
340 method when executed. Raises a ValueError if the instance does
341 not have a method with the specified name.
342 """
Benjamin Peterson52baa292009-03-24 00:56:30 +0000343 self._testMethodName = methodName
Fred Drake02538202001-03-21 18:09:46 +0000344 try:
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000345 testMethod = getattr(self, methodName)
Fred Drake02538202001-03-21 18:09:46 +0000346 except AttributeError:
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000347 raise ValueError("no such test method in %s: %s" % \
348 (self.__class__, methodName))
Benjamin Peterson52baa292009-03-24 00:56:30 +0000349 self._testMethodDoc = testMethod.__doc__
Fred Drake02538202001-03-21 18:09:46 +0000350
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000351 # Map types to custom assertEqual functions that will compare
352 # instances of said type in more detail to generate a more useful
353 # error message.
354 self._type_equality_funcs = {}
355 self.addTypeEqualityFunc(dict, self.assertDictEqual)
356 self.addTypeEqualityFunc(list, self.assertListEqual)
357 self.addTypeEqualityFunc(tuple, self.assertTupleEqual)
358 self.addTypeEqualityFunc(set, self.assertSetEqual)
359 self.addTypeEqualityFunc(frozenset, self.assertSetEqual)
360
361 def addTypeEqualityFunc(self, typeobj, function):
362 """Add a type specific assertEqual style function to compare a type.
363
364 This method is for use by TestCase subclasses that need to register
365 their own type equality functions to provide nicer error messages.
366
367 Args:
368 typeobj: The data type to call this function on when both values
369 are of the same type in assertEqual().
370 function: The callable taking two arguments and an optional
371 msg= argument that raises self.failureException with a
372 useful error message when the two arguments are not equal.
373 """
374 self._type_equality_funcs[typeobj] = _AssertWrapper(function)
375
Fred Drake02538202001-03-21 18:09:46 +0000376 def setUp(self):
377 "Hook method for setting up the test fixture before exercising it."
378 pass
379
380 def tearDown(self):
381 "Hook method for deconstructing the test fixture after testing it."
382 pass
383
384 def countTestCases(self):
385 return 1
386
387 def defaultTestResult(self):
388 return TestResult()
389
390 def shortDescription(self):
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000391 """Returns both the test method name and first line of its docstring.
Fred Drake02538202001-03-21 18:09:46 +0000392
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000393 If no docstring is given, only returns the method name.
394
395 This method overrides unittest.TestCase.shortDescription(), which
396 only returns the first line of the docstring, obscuring the name
397 of the test upon failure.
Fred Drake02538202001-03-21 18:09:46 +0000398 """
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000399 desc = str(self)
400 doc_first_line = None
401
402 if self._testMethodDoc:
403 doc_first_line = self._testMethodDoc.split("\n")[0].strip()
404 if doc_first_line:
405 desc = '\n'.join((desc, doc_first_line))
406 return desc
Fred Drake02538202001-03-21 18:09:46 +0000407
408 def id(self):
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000409 return "%s.%s" % (_strclass(self.__class__), self._testMethodName)
Fred Drake02538202001-03-21 18:09:46 +0000410
Guido van Rossumd8faa362007-04-27 19:54:29 +0000411 def __eq__(self, other):
412 if type(self) is not type(other):
Benjamin Peterson52baa292009-03-24 00:56:30 +0000413 return NotImplemented
Guido van Rossumd8faa362007-04-27 19:54:29 +0000414
415 return self._testMethodName == other._testMethodName
416
417 def __ne__(self, other):
418 return not self == other
419
420 def __hash__(self):
421 return hash((type(self), self._testMethodName))
422
Fred Drake02538202001-03-21 18:09:46 +0000423 def __str__(self):
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000424 return "%s (%s)" % (self._testMethodName, _strclass(self.__class__))
Fred Drake02538202001-03-21 18:09:46 +0000425
426 def __repr__(self):
427 return "<%s testMethod=%s>" % \
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000428 (_strclass(self.__class__), self._testMethodName)
Fred Drake02538202001-03-21 18:09:46 +0000429
430 def run(self, result=None):
Benjamin Peterson52baa292009-03-24 00:56:30 +0000431 if result is None:
432 result = self.defaultTestResult()
Fred Drake02538202001-03-21 18:09:46 +0000433 result.startTest(self)
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000434 testMethod = getattr(self, self._testMethodName)
Fred Drake02538202001-03-21 18:09:46 +0000435 try:
436 try:
437 self.setUp()
Benjamin Peterson5254c042009-03-23 22:25:03 +0000438 except SkipTest as e:
439 result.addSkip(self, str(e))
440 return
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000441 except Exception:
Benjamin Petersone549ead2009-03-28 21:42:05 +0000442 result.addError(self, sys.exc_info())
Fred Drake02538202001-03-21 18:09:46 +0000443 return
444
Benjamin Peterson5254c042009-03-23 22:25:03 +0000445 success = False
Fred Drake02538202001-03-21 18:09:46 +0000446 try:
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000447 testMethod()
Skip Montanaroae5c37b2003-07-13 15:18:12 +0000448 except self.failureException:
Benjamin Petersone549ead2009-03-28 21:42:05 +0000449 result.addFailure(self, sys.exc_info())
Benjamin Peterson5254c042009-03-23 22:25:03 +0000450 except _ExpectedFailure as e:
451 result.addExpectedFailure(self, e.exc_info)
452 except _UnexpectedSuccess:
453 result.addUnexpectedSuccess(self)
454 except SkipTest as e:
455 result.addSkip(self, str(e))
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000456 except Exception:
Benjamin Petersone549ead2009-03-28 21:42:05 +0000457 result.addError(self, sys.exc_info())
Benjamin Peterson5254c042009-03-23 22:25:03 +0000458 else:
459 success = True
Fred Drake02538202001-03-21 18:09:46 +0000460
461 try:
462 self.tearDown()
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000463 except Exception:
Benjamin Petersone549ead2009-03-28 21:42:05 +0000464 result.addError(self, sys.exc_info())
Benjamin Peterson5254c042009-03-23 22:25:03 +0000465 success = False
466 if success:
467 result.addSuccess(self)
Fred Drake02538202001-03-21 18:09:46 +0000468 finally:
469 result.stopTest(self)
470
Raymond Hettinger664347b2004-12-04 21:21:53 +0000471 def __call__(self, *args, **kwds):
472 return self.run(*args, **kwds)
Steve Purcell7e743842003-09-22 11:08:12 +0000473
Fred Drake02538202001-03-21 18:09:46 +0000474 def debug(self):
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000475 """Run the test without collecting errors in a TestResult"""
Fred Drake02538202001-03-21 18:09:46 +0000476 self.setUp()
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000477 getattr(self, self._testMethodName)()
Fred Drake02538202001-03-21 18:09:46 +0000478 self.tearDown()
479
Benjamin Petersone549ead2009-03-28 21:42:05 +0000480 def skipTest(self, reason):
Benjamin Peterson5254c042009-03-23 22:25:03 +0000481 """Skip this test."""
482 raise SkipTest(reason)
483
Steve Purcell15d89272001-04-12 09:05:01 +0000484 def fail(self, msg=None):
485 """Fail immediately, with the given message."""
Collin Winterce36ad82007-08-30 01:19:48 +0000486 raise self.failureException(msg)
Fred Drake02538202001-03-21 18:09:46 +0000487
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000488 def assertFalse(self, expr, msg=None):
Fred Drake02538202001-03-21 18:09:46 +0000489 "Fail the test if the expression is true."
Benjamin Peterson52baa292009-03-24 00:56:30 +0000490 if expr:
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000491 msg = self._formatMessage(msg, "%r is not False" % expr)
Benjamin Peterson52baa292009-03-24 00:56:30 +0000492 raise self.failureException(msg)
Fred Drake02538202001-03-21 18:09:46 +0000493
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000494 def assertTrue(self, expr, msg=None):
Steve Purcell15d89272001-04-12 09:05:01 +0000495 """Fail the test unless the expression is true."""
Benjamin Peterson52baa292009-03-24 00:56:30 +0000496 if not expr:
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000497 msg = self._formatMessage(msg, "%r is not True" % expr)
Benjamin Peterson52baa292009-03-24 00:56:30 +0000498 raise self.failureException(msg)
Steve Purcell15d89272001-04-12 09:05:01 +0000499
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000500 def _formatMessage(self, msg, standardMsg):
501 """Honour the longMessage attribute when generating failure messages.
502 If longMessage is False this means:
503 * Use only an explicit message if it is provided
504 * Otherwise use the standard message for the assert
505
506 If longMessage is True:
507 * Use the standard message
508 * If an explicit message is provided, plus ' : ' and the explicit message
509 """
510 if not self.longMessage:
511 return msg or standardMsg
512 if msg is None:
513 return standardMsg
514 return standardMsg + ' : ' + msg
515
516
517 def assertRaises(self, excClass, callableObj=None, *args, **kwargs):
Steve Purcell15d89272001-04-12 09:05:01 +0000518 """Fail unless an exception of class excClass is thrown
Fred Drake02538202001-03-21 18:09:46 +0000519 by callableObj when invoked with arguments args and keyword
520 arguments kwargs. If a different type of exception is
521 thrown, it will not be caught, and the test case will be
522 deemed to have suffered an error, exactly as for an
523 unexpected exception.
Antoine Pitrou5acd41e2008-12-28 14:29:00 +0000524
525 If called with callableObj omitted or None, will return a
526 context object used like this::
527
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000528 with self.assertRaises(some_error_class):
Antoine Pitrou5acd41e2008-12-28 14:29:00 +0000529 do_something()
Fred Drake02538202001-03-21 18:09:46 +0000530 """
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000531 context = _AssertRaisesContext(excClass, self, callableObj)
Antoine Pitrou5acd41e2008-12-28 14:29:00 +0000532 if callableObj is None:
533 return context
534 with context:
Guido van Rossum68468eb2003-02-27 20:14:51 +0000535 callableObj(*args, **kwargs)
Fred Drake02538202001-03-21 18:09:46 +0000536
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000537 def _getAssertEqualityFunc(self, first, second):
538 """Get a detailed comparison function for the types of the two args.
539
540 Returns: A callable accepting (first, second, msg=None) that will
541 raise a failure exception if first != second with a useful human
542 readable error message for those types.
543 """
544 #
545 # NOTE(gregory.p.smith): I considered isinstance(first, type(second))
546 # and vice versa. I opted for the conservative approach in case
547 # subclasses are not intended to be compared in detail to their super
548 # class instances using a type equality func. This means testing
549 # subtypes won't automagically use the detailed comparison. Callers
550 # should use their type specific assertSpamEqual method to compare
551 # subclasses if the detailed comparison is desired and appropriate.
552 # See the discussion in http://bugs.python.org/issue2578.
553 #
554 if type(first) is type(second):
555 asserter = self._type_equality_funcs.get(type(first))
556 if asserter is not None:
557 return asserter.function
558
559 return self._baseAssertEqual
560
561 def _baseAssertEqual(self, first, second, msg=None):
562 """The default assertEqual implementation, not type specific."""
563 if not first == second:
564 standardMsg = '%r != %r' % (first, second)
565 msg = self._formatMessage(msg, standardMsg)
566 raise self.failureException(msg)
567
568 def assertEqual(self, first, second, msg=None):
Raymond Hettingerc377cbf2003-04-04 22:56:42 +0000569 """Fail if the two objects are unequal as determined by the '=='
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000570 operator.
571 """
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000572 assertion_func = self._getAssertEqualityFunc(first, second)
573 assertion_func(first, second, msg=msg)
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000574
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000575 def assertNotEqual(self, first, second, msg=None):
Steve Purcell15d89272001-04-12 09:05:01 +0000576 """Fail if the two objects are equal as determined by the '=='
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000577 operator.
578 """
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000579 if not first != second:
580 msg = self._formatMessage(msg, '%r == %r' % (first, second))
581 raise self.failureException(msg)
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000582
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000583 def assertAlmostEqual(self, first, second, *, places=7, msg=None):
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000584 """Fail if the two objects are unequal as determined by their
585 difference rounded to the given number of decimal places
586 (default 7) and comparing to zero.
587
Steve Purcell397b45d2003-10-26 10:41:03 +0000588 Note that decimal places (from zero) are usually not the same
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000589 as significant digits (measured from the most signficant digit).
590 """
Jeffrey Yasskin1cc55442007-09-06 18:55:17 +0000591 if round(abs(second-first), places) != 0:
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000592 standardMsg = '%r != %r within %r places' % (first, second, places)
593 msg = self._formatMessage(msg, standardMsg)
594 raise self.failureException(msg)
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000595
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000596 def assertNotAlmostEqual(self, first, second, *, places=7, msg=None):
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000597 """Fail if the two objects are equal as determined by their
598 difference rounded to the given number of decimal places
599 (default 7) and comparing to zero.
600
Steve Purcellcca34912003-10-26 16:38:16 +0000601 Note that decimal places (from zero) are usually not the same
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000602 as significant digits (measured from the most signficant digit).
603 """
Jeffrey Yasskin1cc55442007-09-06 18:55:17 +0000604 if round(abs(second-first), places) == 0:
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000605 standardMsg = '%r == %r within %r places' % (first, second, places)
606 msg = self._formatMessage(msg, standardMsg)
607 raise self.failureException(msg)
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000608
Steve Purcell7e743842003-09-22 11:08:12 +0000609 # Synonyms for assertion methods
610
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000611 # The plurals are undocumented. Keep them that way to discourage use.
612 # Do not add more. Do not remove.
613 # Going through a deprecation cycle on these would annoy many people.
614 assertEquals = assertEqual
615 assertNotEquals = assertNotEqual
616 assertAlmostEquals = assertAlmostEqual
617 assertNotAlmostEquals = assertNotAlmostEqual
618 assert_ = assertTrue
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000619
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000620 # These fail* assertion method names are pending deprecation and will
621 # be a DeprecationWarning in 3.2; http://bugs.python.org/issue2578
622 def _deprecate(original_func):
623 def deprecated_func(*args, **kwargs):
624 warnings.warn(
625 'Please use {0} instead.'.format(original_func.__name__),
626 PendingDeprecationWarning, 2)
627 return original_func(*args, **kwargs)
628 return deprecated_func
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000629
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000630 failUnlessEqual = _deprecate(assertEqual)
631 failIfEqual = _deprecate(assertNotEqual)
632 failUnlessAlmostEqual = _deprecate(assertAlmostEqual)
633 failIfAlmostEqual = _deprecate(assertNotAlmostEqual)
634 failUnless = _deprecate(assertTrue)
635 failUnlessRaises = _deprecate(assertRaises)
636 failIf = _deprecate(assertFalse)
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000637
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000638 def assertSequenceEqual(self, seq1, seq2, msg=None, seq_type=None):
639 """An equality assertion for ordered sequences (like lists and tuples).
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000640
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000641 For the purposes of this function, a valid orderd sequence type is one
642 which can be indexed, has a length, and has an equality operator.
Steve Purcell15d89272001-04-12 09:05:01 +0000643
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000644 Args:
645 seq1: The first sequence to compare.
646 seq2: The second sequence to compare.
647 seq_type: The expected datatype of the sequences, or None if no
648 datatype should be enforced.
649 msg: Optional message to use on failure instead of a list of
650 differences.
651 """
652 if seq_type != None:
653 seq_type_name = seq_type.__name__
654 if not isinstance(seq1, seq_type):
655 raise self.failureException('First sequence is not a %s: %r'
656 % (seq_type_name, seq1))
657 if not isinstance(seq2, seq_type):
658 raise self.failureException('Second sequence is not a %s: %r'
659 % (seq_type_name, seq2))
660 else:
661 seq_type_name = "sequence"
Steve Purcell7e743842003-09-22 11:08:12 +0000662
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000663 differing = None
664 try:
665 len1 = len(seq1)
666 except (TypeError, NotImplementedError):
667 differing = 'First %s has no length. Non-sequence?' % (
668 seq_type_name)
Steve Purcell15d89272001-04-12 09:05:01 +0000669
Benjamin Peterson7fe73a12009-04-04 16:35:46 +0000670 if differing is None:
671 try:
672 len2 = len(seq2)
673 except (TypeError, NotImplementedError):
674 differing = 'Second %s has no length. Non-sequence?' % (
675 seq_type_name)
676
677 if differing is None:
678 if seq1 == seq2:
679 return
680
681 for i in range(min(len1, len2)):
682 try:
683 item1 = seq1[i]
684 except (TypeError, IndexError, NotImplementedError):
685 differing = ('Unable to index element %d of first %s\n' %
686 (i, seq_type_name))
687 break
688
689 try:
690 item2 = seq2[i]
691 except (TypeError, IndexError, NotImplementedError):
692 differing = ('Unable to index element %d of second %s\n' %
693 (i, seq_type_name))
694 break
695
696 if item1 != item2:
697 differing = ('First differing element %d:\n%s\n%s\n' %
698 (i, item1, item2))
699 break
700 else:
701 if (len1 == len2 and seq_type is None and
702 type(seq1) != type(seq2)):
703 # The sequences are the same, but have differing types.
704 return
705 # A catch-all message for handling arbitrary user-defined
706 # sequences.
707 differing = '%ss differ:\n' % seq_type_name.capitalize()
708 if len1 > len2:
709 differing = ('First %s contains %d additional '
710 'elements.\n' % (seq_type_name, len1 - len2))
711 try:
712 differing += ('First extra element %d:\n%s\n' %
713 (len2, seq1[len2]))
714 except (TypeError, IndexError, NotImplementedError):
715 differing += ('Unable to index element %d '
716 'of first %s\n' % (len2, seq_type_name))
717 elif len1 < len2:
718 differing = ('Second %s contains %d additional '
719 'elements.\n' % (seq_type_name, len2 - len1))
720 try:
721 differing += ('First extra element %d:\n%s\n' %
722 (len1, seq2[len1]))
723 except (TypeError, IndexError, NotImplementedError):
724 differing += ('Unable to index element %d '
725 'of second %s\n' % (len1, seq_type_name))
726 standardMsg = differing + '\n'.join(difflib.ndiff(pprint.pformat(seq1).splitlines(),
727 pprint.pformat(seq2).splitlines()))
728 msg = self._formatMessage(msg, standardMsg)
729 self.fail(msg)
730
731 def assertListEqual(self, list1, list2, msg=None):
732 """A list-specific equality assertion.
733
734 Args:
735 list1: The first list to compare.
736 list2: The second list to compare.
737 msg: Optional message to use on failure instead of a list of
738 differences.
739
740 """
741 self.assertSequenceEqual(list1, list2, msg, seq_type=list)
742
743 def assertTupleEqual(self, tuple1, tuple2, msg=None):
744 """A tuple-specific equality assertion.
745
746 Args:
747 tuple1: The first tuple to compare.
748 tuple2: The second tuple to compare.
749 msg: Optional message to use on failure instead of a list of
750 differences.
751 """
752 self.assertSequenceEqual(tuple1, tuple2, msg, seq_type=tuple)
753
754 def assertSetEqual(self, set1, set2, msg=None):
755 """A set-specific equality assertion.
756
757 Args:
758 set1: The first set to compare.
759 set2: The second set to compare.
760 msg: Optional message to use on failure instead of a list of
761 differences.
762
763 For more general containership equality, assertSameElements will work
764 with things other than sets. This uses ducktyping to support
765 different types of sets, and is optimized for sets specifically
766 (parameters must support a difference method).
767 """
768 try:
769 difference1 = set1.difference(set2)
770 except TypeError as e:
771 self.fail('invalid type when attempting set difference: %s' % e)
772 except AttributeError as e:
773 self.fail('first argument does not support set difference: %s' % e)
774
775 try:
776 difference2 = set2.difference(set1)
777 except TypeError as e:
778 self.fail('invalid type when attempting set difference: %s' % e)
779 except AttributeError as e:
780 self.fail('second argument does not support set difference: %s' % e)
781
782 if not (difference1 or difference2):
783 return
784
785 lines = []
786 if difference1:
787 lines.append('Items in the first set but not the second:')
788 for item in difference1:
789 lines.append(repr(item))
790 if difference2:
791 lines.append('Items in the second set but not the first:')
792 for item in difference2:
793 lines.append(repr(item))
794
795 standardMsg = '\n'.join(lines)
796 self.fail(self._formatMessage(msg, standardMsg))
797
798 def assertIn(self, member, container, msg=None):
799 """Just like self.assertTrue(a in b), but with a nicer default message."""
800 if member not in container:
801 standardMsg = '%r not found in %r' % (member, container)
802 self.fail(self._formatMessage(msg, standardMsg))
803
804 def assertNotIn(self, member, container, msg=None):
805 """Just like self.assertTrue(a not in b), but with a nicer default message."""
806 if member in container:
807 standardMsg = '%r unexpectedly found in %r' % (member, container)
808 self.fail(self._formatMessage(msg, standardMsg))
809
810 def assertDictEqual(self, d1, d2, msg=None):
811 self.assert_(isinstance(d1, dict), 'First argument is not a dictionary')
812 self.assert_(isinstance(d2, dict), 'Second argument is not a dictionary')
813
814 if d1 != d2:
815 standardMsg = ('\n' + '\n'.join(difflib.ndiff(
816 pprint.pformat(d1).splitlines(),
817 pprint.pformat(d2).splitlines())))
818 self.fail(self._formatMessage(msg, standardMsg))
819
820 def assertDictContainsSubset(self, expected, actual, msg=None):
821 """Checks whether actual is a superset of expected."""
822 missing = []
823 mismatched = []
824 for key, value in expected.items():
825 if key not in actual:
826 missing.append(key)
827 elif value != actual[key]:
828 mismatched.append('%s, expected: %s, actual: %s' % (key, value, actual[key]))
829
830 if not (missing or mismatched):
831 return
832
833 standardMsg = ''
834 if missing:
835 standardMsg = 'Missing: %r' % ','.join(missing)
836 if mismatched:
837 if standardMsg:
838 standardMsg += '; '
839 standardMsg += 'Mismatched values: %s' % ','.join(mismatched)
840
841 self.fail(self._formatMessage(msg, standardMsg))
842
843 def assertSameElements(self, expected_seq, actual_seq, msg=None):
844 """An unordered sequence specific comparison.
845
846 Raises with an error message listing which elements of expected_seq
847 are missing from actual_seq and vice versa if any.
848 """
849 try:
850 expected = set(expected_seq)
851 actual = set(actual_seq)
852 missing = list(expected.difference(actual))
853 unexpected = list(actual.difference(expected))
854 missing.sort()
855 unexpected.sort()
856 except TypeError:
857 # Fall back to slower list-compare if any of the objects are
858 # not hashable.
859 expected = list(expected_seq)
860 actual = list(actual_seq)
861 expected.sort()
862 actual.sort()
863 missing, unexpected = _SortedListDifference(expected, actual)
864 errors = []
865 if missing:
866 errors.append('Expected, but missing:\n %r' % missing)
867 if unexpected:
868 errors.append('Unexpected, but present:\n %r' % unexpected)
869 if errors:
870 standardMsg = '\n'.join(errors)
871 self.fail(self._formatMessage(msg, standardMsg))
872
873 def assertMultiLineEqual(self, first, second, msg=None):
874 """Assert that two multi-line strings are equal."""
875 self.assert_(isinstance(first, str), (
876 'First argument is not a string'))
877 self.assert_(isinstance(second, str), (
878 'Second argument is not a string'))
879
880 if first != second:
881 standardMsg = '\n' + ''.join(difflib.ndiff(first.splitlines(True), second.splitlines(True)))
882 self.fail(self._formatMessage(msg, standardMsg))
883
884 def assertLess(self, a, b, msg=None):
885 """Just like self.assertTrue(a < b), but with a nicer default message."""
886 if not a < b:
887 standardMsg = '%r not less than %r' % (a, b)
888 self.fail(self._formatMessage(msg, standardMsg))
889
890 def assertLessEqual(self, a, b, msg=None):
891 """Just like self.assertTrue(a <= b), but with a nicer default message."""
892 if not a <= b:
893 standardMsg = '%r not less than or equal to %r' % (a, b)
894 self.fail(self._formatMessage(msg, standardMsg))
895
896 def assertGreater(self, a, b, msg=None):
897 """Just like self.assertTrue(a > b), but with a nicer default message."""
898 if not a > b:
899 standardMsg = '%r not greater than %r' % (a, b)
900 self.fail(self._formatMessage(msg, standardMsg))
901
902 def assertGreaterEqual(self, a, b, msg=None):
903 """Just like self.assertTrue(a >= b), but with a nicer default message."""
904 if not a >= b:
905 standardMsg = '%r not greater than or equal to %r' % (a, b)
906 self.fail(self._formatMessage(msg, standardMsg))
907
908 def assertIsNone(self, obj, msg=None):
909 """Same as self.assertTrue(obj is None), with a nicer default message."""
910 if obj is not None:
911 standardMsg = '%r is not None' % obj
912 self.fail(self._formatMessage(msg, standardMsg))
913
914 def assertIsNotNone(self, obj, msg=None):
915 """Included for symmetry with assertIsNone."""
916 if obj is None:
917 standardMsg = 'unexpectedly None'
918 self.fail(self._formatMessage(msg, standardMsg))
919
920 def assertRaisesRegexp(self, expected_exception, expected_regexp,
921 callable_obj=None, *args, **kwargs):
922 """Asserts that the message in a raised exception matches a regexp.
923
924 Args:
925 expected_exception: Exception class expected to be raised.
926 expected_regexp: Regexp (re pattern object or string) expected
927 to be found in error message.
928 callable_obj: Function to be called.
929 args: Extra args.
930 kwargs: Extra kwargs.
931 """
932 context = _AssertRaisesContext(expected_exception, self, callable_obj,
933 expected_regexp)
934 if callable_obj is None:
935 return context
936 with context:
937 callable_obj(*args, **kwargs)
938
939 def assertRegexpMatches(self, text, expected_regex, msg=None):
940 if isinstance(expected_regex, (str, bytes)):
941 expected_regex = re.compile(expected_regex)
942 if not expected_regex.search(text):
943 msg = msg or "Regexp didn't match"
944 msg = '%s: %r not found in %r' % (msg, expected_regex.pattern, text)
945 raise self.failureException(msg)
946
947
948def _SortedListDifference(expected, actual):
949 """Finds elements in only one or the other of two, sorted input lists.
950
951 Returns a two-element tuple of lists. The first list contains those
952 elements in the "expected" list but not in the "actual" list, and the
953 second contains those elements in the "actual" list but not in the
954 "expected" list. Duplicate elements in either input list are ignored.
955 """
956 i = j = 0
957 missing = []
958 unexpected = []
959 while True:
960 try:
961 e = expected[i]
962 a = actual[j]
963 if e < a:
964 missing.append(e)
965 i += 1
966 while expected[i] == e:
967 i += 1
968 elif e > a:
969 unexpected.append(a)
970 j += 1
971 while actual[j] == a:
972 j += 1
973 else:
974 i += 1
975 try:
976 while expected[i] == e:
977 i += 1
978 finally:
979 j += 1
980 while actual[j] == a:
981 j += 1
982 except IndexError:
983 missing.extend(expected[i:])
984 unexpected.extend(actual[j:])
985 break
986 return missing, unexpected
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000987
Fred Drake02538202001-03-21 18:09:46 +0000988
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000989class TestSuite(object):
Fred Drake02538202001-03-21 18:09:46 +0000990 """A test suite is a composite test consisting of a number of TestCases.
991
992 For use, create an instance of TestSuite, then add test case instances.
993 When all tests have been added, the suite can be passed to a test
994 runner, such as TextTestRunner. It will run the individual test cases
995 in the order in which they were added, aggregating the results. When
996 subclassing, do not forget to call the base class constructor.
997 """
998 def __init__(self, tests=()):
999 self._tests = []
1000 self.addTests(tests)
1001
1002 def __repr__(self):
Steve Purcelldc391a62002-08-09 09:46:23 +00001003 return "<%s tests=%s>" % (_strclass(self.__class__), self._tests)
Fred Drake02538202001-03-21 18:09:46 +00001004
Guido van Rossumd8faa362007-04-27 19:54:29 +00001005 def __eq__(self, other):
Benjamin Peterson5254c042009-03-23 22:25:03 +00001006 if not isinstance(other, self.__class__):
1007 return NotImplemented
Guido van Rossumd8faa362007-04-27 19:54:29 +00001008 return self._tests == other._tests
1009
1010 def __ne__(self, other):
1011 return not self == other
1012
Jim Fultonfafd8742004-08-28 15:22:12 +00001013 def __iter__(self):
1014 return iter(self._tests)
1015
Fred Drake02538202001-03-21 18:09:46 +00001016 def countTestCases(self):
1017 cases = 0
1018 for test in self._tests:
Steve Purcell7e743842003-09-22 11:08:12 +00001019 cases += test.countTestCases()
Fred Drake02538202001-03-21 18:09:46 +00001020 return cases
1021
1022 def addTest(self, test):
Guido van Rossumd8faa362007-04-27 19:54:29 +00001023 # sanity checks
Guido van Rossumd59da4b2007-05-22 18:11:13 +00001024 if not hasattr(test, '__call__'):
Guido van Rossumd8faa362007-04-27 19:54:29 +00001025 raise TypeError("the test to add must be callable")
Guido van Rossum13257902007-06-07 23:15:56 +00001026 if isinstance(test, type) and issubclass(test, (TestCase, TestSuite)):
Guido van Rossumd8faa362007-04-27 19:54:29 +00001027 raise TypeError("TestCases and TestSuites must be instantiated "
1028 "before passing them to addTest()")
Fred Drake02538202001-03-21 18:09:46 +00001029 self._tests.append(test)
1030
1031 def addTests(self, tests):
Guido van Rossum3172c5d2007-10-16 18:12:55 +00001032 if isinstance(tests, str):
Guido van Rossumd8faa362007-04-27 19:54:29 +00001033 raise TypeError("tests must be an iterable of tests, not a string")
Fred Drake02538202001-03-21 18:09:46 +00001034 for test in tests:
1035 self.addTest(test)
1036
1037 def run(self, result):
Fred Drake02538202001-03-21 18:09:46 +00001038 for test in self._tests:
1039 if result.shouldStop:
1040 break
1041 test(result)
1042 return result
1043
Raymond Hettinger664347b2004-12-04 21:21:53 +00001044 def __call__(self, *args, **kwds):
1045 return self.run(*args, **kwds)
1046
Fred Drake02538202001-03-21 18:09:46 +00001047 def debug(self):
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001048 """Run the tests without collecting errors in a TestResult"""
Benjamin Peterson52baa292009-03-24 00:56:30 +00001049 for test in self._tests:
1050 test.debug()
Fred Drake02538202001-03-21 18:09:46 +00001051
1052
Benjamin Peterson5254c042009-03-23 22:25:03 +00001053class ClassTestSuite(TestSuite):
1054 """
1055 Suite of tests derived from a single TestCase class.
1056 """
1057
1058 def __init__(self, tests, class_collected_from):
1059 super(ClassTestSuite, self).__init__(tests)
1060 self.collected_from = class_collected_from
1061
1062 def id(self):
1063 module = getattr(self.collected_from, "__module__", None)
1064 if module is not None:
1065 return "{0}.{1}".format(module, self.collected_from.__name__)
1066 return self.collected_from.__name__
1067
1068 def run(self, result):
1069 if getattr(self.collected_from, "__unittest_skip__", False):
1070 # ClassTestSuite result pretends to be a TestCase enough to be
1071 # reported.
1072 result.startTest(self)
1073 try:
1074 result.addSkip(self, self.collected_from.__unittest_skip_why__)
1075 finally:
1076 result.stopTest(self)
1077 else:
1078 result = super(ClassTestSuite, self).run(result)
1079 return result
1080
1081 shortDescription = id
1082
1083
Fred Drake02538202001-03-21 18:09:46 +00001084class FunctionTestCase(TestCase):
1085 """A test case that wraps a test function.
1086
1087 This is useful for slipping pre-existing test functions into the
Guido van Rossumd8faa362007-04-27 19:54:29 +00001088 unittest framework. Optionally, set-up and tidy-up functions can be
Fred Drake02538202001-03-21 18:09:46 +00001089 supplied. As with TestCase, the tidy-up ('tearDown') function will
1090 always be called if the set-up ('setUp') function ran successfully.
1091 """
1092
Benjamin Peterson52baa292009-03-24 00:56:30 +00001093 def __init__(self, testFunc, setUp=None, tearDown=None, description=None):
1094 super(FunctionTestCase, self).__init__()
Benjamin Peterson7fe73a12009-04-04 16:35:46 +00001095 self._setUpFunc = setUp
1096 self._tearDownFunc = tearDown
1097 self._testFunc = testFunc
1098 self._description = description
Fred Drake02538202001-03-21 18:09:46 +00001099
1100 def setUp(self):
Benjamin Peterson7fe73a12009-04-04 16:35:46 +00001101 if self._setUpFunc is not None:
1102 self._setUpFunc()
Fred Drake02538202001-03-21 18:09:46 +00001103
1104 def tearDown(self):
Benjamin Peterson7fe73a12009-04-04 16:35:46 +00001105 if self._tearDownFunc is not None:
1106 self._tearDownFunc()
Fred Drake02538202001-03-21 18:09:46 +00001107
1108 def runTest(self):
Benjamin Peterson7fe73a12009-04-04 16:35:46 +00001109 self._testFunc()
Fred Drake02538202001-03-21 18:09:46 +00001110
1111 def id(self):
Benjamin Peterson7fe73a12009-04-04 16:35:46 +00001112 return self._testFunc.__name__
Fred Drake02538202001-03-21 18:09:46 +00001113
Guido van Rossumd8faa362007-04-27 19:54:29 +00001114 def __eq__(self, other):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001115 if not isinstance(other, self.__class__):
1116 return NotImplemented
Guido van Rossumd8faa362007-04-27 19:54:29 +00001117
Benjamin Peterson7fe73a12009-04-04 16:35:46 +00001118 return self._setUpFunc == other._setUpFunc and \
1119 self._tearDownFunc == other._tearDownFunc and \
1120 self._testFunc == other._testFunc and \
1121 self._description == other._description
Guido van Rossumd8faa362007-04-27 19:54:29 +00001122
1123 def __ne__(self, other):
1124 return not self == other
1125
1126 def __hash__(self):
Benjamin Peterson7fe73a12009-04-04 16:35:46 +00001127 return hash((type(self), self._setUpFunc, self._tearDownFunc,
1128 self._testFunc, self._description))
Guido van Rossumd8faa362007-04-27 19:54:29 +00001129
Fred Drake02538202001-03-21 18:09:46 +00001130 def __str__(self):
Collin Winterce36ad82007-08-30 01:19:48 +00001131 return "%s (%s)" % (_strclass(self.__class__),
1132 self.__testFunc.__name__)
Fred Drake02538202001-03-21 18:09:46 +00001133
1134 def __repr__(self):
Benjamin Peterson7fe73a12009-04-04 16:35:46 +00001135 return "<%s testFunc=%s>" % (_strclass(self.__class__), self._testFunc)
Fred Drake02538202001-03-21 18:09:46 +00001136
1137 def shortDescription(self):
Benjamin Peterson7fe73a12009-04-04 16:35:46 +00001138 if self._description is not None:
1139 return self._description
1140 doc = self._testFunc.__doc__
Steve Purcell7e743842003-09-22 11:08:12 +00001141 return doc and doc.split("\n")[0].strip() or None
Fred Drake02538202001-03-21 18:09:46 +00001142
1143
1144
1145##############################################################################
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001146# Locating and loading tests
Fred Drake02538202001-03-21 18:09:46 +00001147##############################################################################
1148
Raymond Hettingerd4cb56d2008-01-30 02:55:10 +00001149def CmpToKey(mycmp):
1150 'Convert a cmp= function into a key= function'
1151 class K(object):
1152 def __init__(self, obj, *args):
1153 self.obj = obj
1154 def __lt__(self, other):
1155 return mycmp(self.obj, other.obj) == -1
1156 return K
1157
Mark Dickinsona56c4672009-01-27 18:17:45 +00001158def three_way_cmp(x, y):
1159 """Return -1 if x < y, 0 if x == y and 1 if x > y"""
1160 return (x > y) - (x < y)
1161
Benjamin Peterson1467ac82009-01-09 03:42:38 +00001162class TestLoader(object):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001163 """
1164 This class is responsible for loading tests according to various criteria
1165 and returning them wrapped in a TestSuite
Fred Drake02538202001-03-21 18:09:46 +00001166 """
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001167 testMethodPrefix = 'test'
Mark Dickinsona56c4672009-01-27 18:17:45 +00001168 sortTestMethodsUsing = staticmethod(three_way_cmp)
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001169 suiteClass = TestSuite
Benjamin Peterson5254c042009-03-23 22:25:03 +00001170 classSuiteClass = ClassTestSuite
Fred Drake02538202001-03-21 18:09:46 +00001171
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001172 def loadTestsFromTestCase(self, testCaseClass):
Steve Purcell15d89272001-04-12 09:05:01 +00001173 """Return a suite of all tests cases contained in testCaseClass"""
Johannes Gijsbersd7b6ad42004-11-07 15:46:25 +00001174 if issubclass(testCaseClass, TestSuite):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001175 raise TypeError("Test cases should not be derived from TestSuite." \
1176 " Maybe you meant to derive from TestCase?")
Steve Purcell7e743842003-09-22 11:08:12 +00001177 testCaseNames = self.getTestCaseNames(testCaseClass)
1178 if not testCaseNames and hasattr(testCaseClass, 'runTest'):
1179 testCaseNames = ['runTest']
Benjamin Peterson5254c042009-03-23 22:25:03 +00001180 suite = self.classSuiteClass(map(testCaseClass, testCaseNames),
1181 testCaseClass)
1182 return suite
Fred Drake02538202001-03-21 18:09:46 +00001183
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001184 def loadTestsFromModule(self, module):
Steve Purcell15d89272001-04-12 09:05:01 +00001185 """Return a suite of all tests cases contained in the given module"""
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001186 tests = []
1187 for name in dir(module):
1188 obj = getattr(module, name)
Guido van Rossum13257902007-06-07 23:15:56 +00001189 if isinstance(obj, type) and issubclass(obj, TestCase):
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001190 tests.append(self.loadTestsFromTestCase(obj))
1191 return self.suiteClass(tests)
Fred Drake02538202001-03-21 18:09:46 +00001192
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001193 def loadTestsFromName(self, name, module=None):
Steve Purcell15d89272001-04-12 09:05:01 +00001194 """Return a suite of all tests cases given a string specifier.
1195
1196 The name may resolve either to a module, a test case class, a
1197 test method within a test case class, or a callable object which
1198 returns a TestCase or TestSuite instance.
Tim Peters613b2222001-04-13 05:37:27 +00001199
Steve Purcell15d89272001-04-12 09:05:01 +00001200 The method optionally resolves the names relative to a given module.
1201 """
Steve Purcell7e743842003-09-22 11:08:12 +00001202 parts = name.split('.')
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001203 if module is None:
Steve Purcell7e743842003-09-22 11:08:12 +00001204 parts_copy = parts[:]
1205 while parts_copy:
1206 try:
1207 module = __import__('.'.join(parts_copy))
1208 break
1209 except ImportError:
1210 del parts_copy[-1]
Benjamin Peterson52baa292009-03-24 00:56:30 +00001211 if not parts_copy:
1212 raise
Armin Rigo1b3c04b2003-10-24 17:15:29 +00001213 parts = parts[1:]
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001214 obj = module
1215 for part in parts:
Steve Purcell7e743842003-09-22 11:08:12 +00001216 parent, obj = obj, getattr(obj, part)
Fred Drake02538202001-03-21 18:09:46 +00001217
Benjamin Peterson1467ac82009-01-09 03:42:38 +00001218 if isinstance(obj, types.ModuleType):
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001219 return self.loadTestsFromModule(obj)
Guido van Rossum13257902007-06-07 23:15:56 +00001220 elif isinstance(obj, type) and issubclass(obj, TestCase):
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001221 return self.loadTestsFromTestCase(obj)
Christian Heimes4a22b5d2007-11-25 09:39:14 +00001222 elif (isinstance(obj, types.FunctionType) and
Guido van Rossum13257902007-06-07 23:15:56 +00001223 isinstance(parent, type) and
Guido van Rossumd8faa362007-04-27 19:54:29 +00001224 issubclass(parent, TestCase)):
Christian Heimes4a22b5d2007-11-25 09:39:14 +00001225 name = obj.__name__
1226 inst = parent(name)
1227 # static methods follow a different path
Christian Heimes4975a1f2007-11-26 10:14:51 +00001228 if not isinstance(getattr(inst, name), types.FunctionType):
Christian Heimes4a22b5d2007-11-25 09:39:14 +00001229 return TestSuite([inst])
Steve Purcell397b45d2003-10-26 10:41:03 +00001230 elif isinstance(obj, TestSuite):
Steve Purcell7e743842003-09-22 11:08:12 +00001231 return obj
Christian Heimes4a22b5d2007-11-25 09:39:14 +00001232
1233 if hasattr(obj, '__call__'):
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001234 test = obj()
Guido van Rossumd8faa362007-04-27 19:54:29 +00001235 if isinstance(test, TestSuite):
1236 return test
1237 elif isinstance(test, TestCase):
1238 return TestSuite([test])
1239 else:
1240 raise TypeError("calling %s returned %s, not a test" %
1241 (obj, test))
Fred Drake02538202001-03-21 18:09:46 +00001242 else:
Guido van Rossumd8faa362007-04-27 19:54:29 +00001243 raise TypeError("don't know how to make test from: %s" % obj)
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001244
1245 def loadTestsFromNames(self, names, module=None):
Steve Purcell15d89272001-04-12 09:05:01 +00001246 """Return a suite of all tests cases found using the given sequence
1247 of string specifiers. See 'loadTestsFromName()'.
1248 """
Steve Purcell7e743842003-09-22 11:08:12 +00001249 suites = [self.loadTestsFromName(name, module) for name in names]
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001250 return self.suiteClass(suites)
1251
1252 def getTestCaseNames(self, testCaseClass):
Steve Purcell15d89272001-04-12 09:05:01 +00001253 """Return a sorted sequence of method names found within testCaseClass
1254 """
Collin Winterce36ad82007-08-30 01:19:48 +00001255 def isTestMethod(attrname, testCaseClass=testCaseClass,
1256 prefix=self.testMethodPrefix):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001257 return attrname.startswith(prefix) and \
1258 hasattr(getattr(testCaseClass, attrname), '__call__')
Guido van Rossumc1f779c2007-07-03 08:25:58 +00001259 testFnNames = list(filter(isTestMethod, dir(testCaseClass)))
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001260 if self.sortTestMethodsUsing:
Raymond Hettingerd4cb56d2008-01-30 02:55:10 +00001261 testFnNames.sort(key=CmpToKey(self.sortTestMethodsUsing))
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001262 return testFnNames
1263
1264
1265
1266defaultTestLoader = TestLoader()
1267
1268
1269##############################################################################
1270# Patches for old functions: these functions should be considered obsolete
1271##############################################################################
1272
1273def _makeLoader(prefix, sortUsing, suiteClass=None):
1274 loader = TestLoader()
1275 loader.sortTestMethodsUsing = sortUsing
1276 loader.testMethodPrefix = prefix
1277 if suiteClass: loader.suiteClass = suiteClass
1278 return loader
1279
Mark Dickinsonc429a832009-01-27 20:27:05 +00001280def getTestCaseNames(testCaseClass, prefix, sortUsing=three_way_cmp):
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001281 return _makeLoader(prefix, sortUsing).getTestCaseNames(testCaseClass)
1282
Mark Dickinsonc429a832009-01-27 20:27:05 +00001283def makeSuite(testCaseClass, prefix='test', sortUsing=three_way_cmp,
1284 suiteClass=TestSuite):
1285 return _makeLoader(prefix, sortUsing, suiteClass).loadTestsFromTestCase(
1286 testCaseClass)
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001287
Mark Dickinsonc429a832009-01-27 20:27:05 +00001288def findTestCases(module, prefix='test', sortUsing=three_way_cmp,
1289 suiteClass=TestSuite):
1290 return _makeLoader(prefix, sortUsing, suiteClass).loadTestsFromModule(
1291 module)
Fred Drake02538202001-03-21 18:09:46 +00001292
1293
1294##############################################################################
1295# Text UI
1296##############################################################################
1297
Benjamin Peterson1467ac82009-01-09 03:42:38 +00001298class _WritelnDecorator(object):
Fred Drake02538202001-03-21 18:09:46 +00001299 """Used to decorate file-like objects with a handy 'writeln' method"""
1300 def __init__(self,stream):
1301 self.stream = stream
Fred Drake02538202001-03-21 18:09:46 +00001302
1303 def __getattr__(self, attr):
1304 return getattr(self.stream,attr)
1305
Raymond Hettinger91dd19d2003-09-13 02:58:00 +00001306 def writeln(self, arg=None):
Benjamin Petersone549ead2009-03-28 21:42:05 +00001307 if arg:
1308 self.write(arg)
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001309 self.write('\n') # text-mode streams translate to \r\n if needed
Tim Petersa19a1682001-03-29 04:36:09 +00001310
Fred Drake02538202001-03-21 18:09:46 +00001311
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001312class _TextTestResult(TestResult):
Fred Drake02538202001-03-21 18:09:46 +00001313 """A test result class that can print formatted text results to a stream.
1314
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001315 Used by TextTestRunner.
Fred Drake02538202001-03-21 18:09:46 +00001316 """
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001317 separator1 = '=' * 70
1318 separator2 = '-' * 70
Fred Drake02538202001-03-21 18:09:46 +00001319
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001320 def __init__(self, stream, descriptions, verbosity):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001321 super(_TextTestResult, self).__init__()
Fred Drake02538202001-03-21 18:09:46 +00001322 self.stream = stream
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001323 self.showAll = verbosity > 1
1324 self.dots = verbosity == 1
Fred Drake02538202001-03-21 18:09:46 +00001325 self.descriptions = descriptions
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001326
1327 def getDescription(self, test):
1328 if self.descriptions:
1329 return test.shortDescription() or str(test)
1330 else:
1331 return str(test)
1332
Fred Drake02538202001-03-21 18:09:46 +00001333 def startTest(self, test):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001334 super(_TextTestResult, self).startTest(test)
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001335 if self.showAll:
1336 self.stream.write(self.getDescription(test))
1337 self.stream.write(" ... ")
Alexandre Vassalotti8ae3e052008-05-16 00:41:41 +00001338 self.stream.flush()
Fred Drake02538202001-03-21 18:09:46 +00001339
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001340 def addSuccess(self, test):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001341 super(_TextTestResult, self).addSuccess(test)
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001342 if self.showAll:
Fred Drake02538202001-03-21 18:09:46 +00001343 self.stream.writeln("ok")
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001344 elif self.dots:
1345 self.stream.write('.')
Alexandre Vassalotti8ae3e052008-05-16 00:41:41 +00001346 self.stream.flush()
Fred Drake02538202001-03-21 18:09:46 +00001347
1348 def addError(self, test, err):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001349 super(_TextTestResult, self).addError(test, err)
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001350 if self.showAll:
1351 self.stream.writeln("ERROR")
1352 elif self.dots:
1353 self.stream.write('E')
Alexandre Vassalotti8ae3e052008-05-16 00:41:41 +00001354 self.stream.flush()
Fred Drake02538202001-03-21 18:09:46 +00001355
1356 def addFailure(self, test, err):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001357 super(_TextTestResult, self).addFailure(test, err)
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001358 if self.showAll:
1359 self.stream.writeln("FAIL")
1360 elif self.dots:
1361 self.stream.write('F')
Alexandre Vassalotti8ae3e052008-05-16 00:41:41 +00001362 self.stream.flush()
Fred Drake02538202001-03-21 18:09:46 +00001363
Benjamin Peterson5254c042009-03-23 22:25:03 +00001364 def addSkip(self, test, reason):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001365 super(_TextTestResult, self).addSkip(test, reason)
Benjamin Peterson5254c042009-03-23 22:25:03 +00001366 if self.showAll:
1367 self.stream.writeln("skipped {0!r}".format(reason))
1368 elif self.dots:
1369 self.stream.write("s")
1370 self.stream.flush()
1371
1372 def addExpectedFailure(self, test, err):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001373 super(_TextTestResult, self).addExpectedFailure(test, err)
Benjamin Peterson5254c042009-03-23 22:25:03 +00001374 if self.showAll:
1375 self.stream.writeln("expected failure")
1376 elif self.dots:
Benjamin Petersone549ead2009-03-28 21:42:05 +00001377 self.stream.write("x")
Benjamin Peterson5254c042009-03-23 22:25:03 +00001378 self.stream.flush()
1379
1380 def addUnexpectedSuccess(self, test):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001381 super(_TextTestResult, self).addUnexpectedSuccess(test)
Benjamin Peterson5254c042009-03-23 22:25:03 +00001382 if self.showAll:
1383 self.stream.writeln("unexpected success")
1384 elif self.dots:
Benjamin Petersone549ead2009-03-28 21:42:05 +00001385 self.stream.write("u")
Benjamin Peterson5254c042009-03-23 22:25:03 +00001386 self.stream.flush()
1387
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001388 def printErrors(self):
1389 if self.dots or self.showAll:
Fred Drake02538202001-03-21 18:09:46 +00001390 self.stream.writeln()
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001391 self.printErrorList('ERROR', self.errors)
1392 self.printErrorList('FAIL', self.failures)
1393
1394 def printErrorList(self, flavour, errors):
1395 for test, err in errors:
1396 self.stream.writeln(self.separator1)
1397 self.stream.writeln("%s: %s" % (flavour,self.getDescription(test)))
1398 self.stream.writeln(self.separator2)
Steve Purcell7b065702001-09-06 08:24:40 +00001399 self.stream.writeln("%s" % err)
Fred Drake02538202001-03-21 18:09:46 +00001400
1401
Benjamin Peterson1467ac82009-01-09 03:42:38 +00001402class TextTestRunner(object):
Fred Drake02538202001-03-21 18:09:46 +00001403 """A test runner class that displays results in textual form.
Tim Petersa19a1682001-03-29 04:36:09 +00001404
Fred Drake02538202001-03-21 18:09:46 +00001405 It prints out the names of tests as they are run, errors as they
1406 occur, and a summary of the results at the end of the test run.
1407 """
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001408 def __init__(self, stream=sys.stderr, descriptions=1, verbosity=1):
Fred Drake02538202001-03-21 18:09:46 +00001409 self.stream = _WritelnDecorator(stream)
1410 self.descriptions = descriptions
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001411 self.verbosity = verbosity
1412
1413 def _makeResult(self):
1414 return _TextTestResult(self.stream, self.descriptions, self.verbosity)
Fred Drake02538202001-03-21 18:09:46 +00001415
1416 def run(self, test):
1417 "Run the given test case or test suite."
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001418 result = self._makeResult()
Fred Drake02538202001-03-21 18:09:46 +00001419 startTime = time.time()
1420 test(result)
1421 stopTime = time.time()
Steve Purcell397b45d2003-10-26 10:41:03 +00001422 timeTaken = stopTime - startTime
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001423 result.printErrors()
1424 self.stream.writeln(result.separator2)
Fred Drake02538202001-03-21 18:09:46 +00001425 run = result.testsRun
1426 self.stream.writeln("Ran %d test%s in %.3fs" %
Neal Norwitz76165042002-05-31 14:15:11 +00001427 (run, run != 1 and "s" or "", timeTaken))
Fred Drake02538202001-03-21 18:09:46 +00001428 self.stream.writeln()
Benjamin Peterson52baa292009-03-24 00:56:30 +00001429 results = map(len, (result.expectedFailures,
1430 result.unexpectedSuccesses,
Benjamin Peterson5254c042009-03-23 22:25:03 +00001431 result.skipped))
Benjamin Peterson52baa292009-03-24 00:56:30 +00001432 expectedFails, unexpectedSuccesses, skipped = results
Benjamin Peterson5254c042009-03-23 22:25:03 +00001433 infos = []
Fred Drake02538202001-03-21 18:09:46 +00001434 if not result.wasSuccessful():
Benjamin Peterson5254c042009-03-23 22:25:03 +00001435 self.stream.write("FAILED")
Guido van Rossumc1f779c2007-07-03 08:25:58 +00001436 failed, errored = len(result.failures), len(result.errors)
Fred Drake02538202001-03-21 18:09:46 +00001437 if failed:
Benjamin Peterson5254c042009-03-23 22:25:03 +00001438 infos.append("failures=%d" % failed)
Fred Drake02538202001-03-21 18:09:46 +00001439 if errored:
Benjamin Peterson5254c042009-03-23 22:25:03 +00001440 infos.append("errors=%d" % errored)
Fred Drake02538202001-03-21 18:09:46 +00001441 else:
Benjamin Petersone549ead2009-03-28 21:42:05 +00001442 self.stream.write("OK")
Benjamin Peterson5254c042009-03-23 22:25:03 +00001443 if skipped:
1444 infos.append("skipped=%d" % skipped)
Benjamin Peterson52baa292009-03-24 00:56:30 +00001445 if expectedFails:
1446 infos.append("expected failures=%d" % expectedFails)
1447 if unexpectedSuccesses:
1448 infos.append("unexpected successes=%d" % unexpectedSuccesses)
Benjamin Peterson5254c042009-03-23 22:25:03 +00001449 if infos:
1450 self.stream.writeln(" (%s)" % (", ".join(infos),))
Benjamin Petersone549ead2009-03-28 21:42:05 +00001451 else:
1452 self.stream.write("\n")
Fred Drake02538202001-03-21 18:09:46 +00001453 return result
Tim Petersa19a1682001-03-29 04:36:09 +00001454
Fred Drake02538202001-03-21 18:09:46 +00001455
Fred Drake02538202001-03-21 18:09:46 +00001456
1457##############################################################################
1458# Facilities for running tests from the command line
1459##############################################################################
1460
Benjamin Peterson1467ac82009-01-09 03:42:38 +00001461class TestProgram(object):
Fred Drake02538202001-03-21 18:09:46 +00001462 """A command-line program that runs a set of tests; this is primarily
1463 for making test modules conveniently executable.
1464 """
1465 USAGE = """\
Steve Purcell17a781b2001-04-09 15:37:31 +00001466Usage: %(progName)s [options] [test] [...]
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001467
1468Options:
1469 -h, --help Show this message
1470 -v, --verbose Verbose output
1471 -q, --quiet Minimal output
Fred Drake02538202001-03-21 18:09:46 +00001472
1473Examples:
1474 %(progName)s - run default set of tests
1475 %(progName)s MyTestSuite - run suite 'MyTestSuite'
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001476 %(progName)s MyTestCase.testSomething - run MyTestCase.testSomething
1477 %(progName)s MyTestCase - run all 'test*' test methods
Fred Drake02538202001-03-21 18:09:46 +00001478 in MyTestCase
1479"""
1480 def __init__(self, module='__main__', defaultTest=None,
Guido van Rossumd8faa362007-04-27 19:54:29 +00001481 argv=None, testRunner=TextTestRunner,
1482 testLoader=defaultTestLoader):
Antoine Pitroue7bd8682009-01-09 19:29:16 +00001483 if isinstance(module, str):
Fred Drake02538202001-03-21 18:09:46 +00001484 self.module = __import__(module)
Steve Purcell7e743842003-09-22 11:08:12 +00001485 for part in module.split('.')[1:]:
Fred Drake02538202001-03-21 18:09:46 +00001486 self.module = getattr(self.module, part)
1487 else:
1488 self.module = module
1489 if argv is None:
1490 argv = sys.argv
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001491 self.verbosity = 1
Fred Drake02538202001-03-21 18:09:46 +00001492 self.defaultTest = defaultTest
1493 self.testRunner = testRunner
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001494 self.testLoader = testLoader
Fred Drake02538202001-03-21 18:09:46 +00001495 self.progName = os.path.basename(argv[0])
1496 self.parseArgs(argv)
Fred Drake02538202001-03-21 18:09:46 +00001497 self.runTests()
1498
1499 def usageExit(self, msg=None):
Benjamin Peterson52baa292009-03-24 00:56:30 +00001500 if msg:
1501 print(msg)
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001502 print(self.USAGE % self.__dict__)
Fred Drake02538202001-03-21 18:09:46 +00001503 sys.exit(2)
1504
1505 def parseArgs(self, argv):
1506 import getopt
Benjamin Peterson5254c042009-03-23 22:25:03 +00001507 long_opts = ['help','verbose','quiet']
Fred Drake02538202001-03-21 18:09:46 +00001508 try:
Benjamin Peterson5254c042009-03-23 22:25:03 +00001509 options, args = getopt.getopt(argv[1:], 'hHvq', long_opts)
Fred Drake02538202001-03-21 18:09:46 +00001510 for opt, value in options:
1511 if opt in ('-h','-H','--help'):
1512 self.usageExit()
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001513 if opt in ('-q','--quiet'):
1514 self.verbosity = 0
1515 if opt in ('-v','--verbose'):
1516 self.verbosity = 2
Fred Drake02538202001-03-21 18:09:46 +00001517 if len(args) == 0 and self.defaultTest is None:
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001518 self.test = self.testLoader.loadTestsFromModule(self.module)
1519 return
Fred Drake02538202001-03-21 18:09:46 +00001520 if len(args) > 0:
1521 self.testNames = args
1522 else:
1523 self.testNames = (self.defaultTest,)
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001524 self.createTests()
Guido van Rossumb940e112007-01-10 16:19:56 +00001525 except getopt.error as msg:
Fred Drake02538202001-03-21 18:09:46 +00001526 self.usageExit(msg)
1527
1528 def createTests(self):
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001529 self.test = self.testLoader.loadTestsFromNames(self.testNames,
1530 self.module)
Fred Drake02538202001-03-21 18:09:46 +00001531
1532 def runTests(self):
Guido van Rossum13257902007-06-07 23:15:56 +00001533 if isinstance(self.testRunner, type):
Guido van Rossumd8faa362007-04-27 19:54:29 +00001534 try:
1535 testRunner = self.testRunner(verbosity=self.verbosity)
1536 except TypeError:
1537 # didn't accept the verbosity argument
1538 testRunner = self.testRunner()
1539 else:
1540 # it is assumed to be a TestRunner instance
1541 testRunner = self.testRunner
1542 result = testRunner.run(self.test)
Tim Petersa19a1682001-03-29 04:36:09 +00001543 sys.exit(not result.wasSuccessful())
Fred Drake02538202001-03-21 18:09:46 +00001544
1545main = TestProgram
1546
1547
1548##############################################################################
1549# Executing this module from the command line
1550##############################################################################
1551
1552if __name__ == "__main__":
1553 main(module=None)