blob: ec113288eeb81dd7b59c1bb27dac76b82697554b [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*'
17 self.assertEquals((1 + 2), 3)
18 self.assertEquals(0 + 1, 1)
Steve Purcell7b065702001-09-06 08:24:40 +000019 def testMultiply(self):
Steve Purcell5ddd1a82001-03-22 08:45:36 +000020 self.assertEquals((0 * 10), 0)
21 self.assertEquals((5 * 8), 40)
22
23 if __name__ == '__main__':
24 unittest.main()
25
26Further information is available in the bundled documentation, and from
27
Guido van Rossumd8faa362007-04-27 19:54:29 +000028 http://docs.python.org/lib/module-unittest.html
Steve Purcell5ddd1a82001-03-22 08:45:36 +000029
Steve Purcell7e743842003-09-22 11:08:12 +000030Copyright (c) 1999-2003 Steve Purcell
Fred Drake02538202001-03-21 18:09:46 +000031This module is free software, and you may redistribute it and/or modify
32it under the same terms as Python itself, so long as this copyright message
33and disclaimer are retained in their original form.
34
35IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
36SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF
37THIS CODE, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
38DAMAGE.
39
40THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT
41LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
42PARTICULAR PURPOSE. THE CODE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS,
43AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
44SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
Steve Purcell5ddd1a82001-03-22 08:45:36 +000045'''
Fred Drake02538202001-03-21 18:09:46 +000046
Steve Purcell5ddd1a82001-03-22 08:45:36 +000047__author__ = "Steve Purcell"
48__email__ = "stephen_purcell at yahoo dot com"
Steve Purcellb8d5f242003-12-06 13:03:13 +000049__version__ = "#Revision: 1.63 $"[11:-2]
Fred Drake02538202001-03-21 18:09:46 +000050
51import time
52import sys
53import traceback
Fred Drake02538202001-03-21 18:09:46 +000054import os
Steve Purcell5ddd1a82001-03-22 08:45:36 +000055import types
Benjamin Peterson5254c042009-03-23 22:25:03 +000056import functools
Fred Drake02538202001-03-21 18:09:46 +000057
58##############################################################################
Steve Purcelld75e7e42003-09-15 11:01:21 +000059# Exported classes and functions
60##############################################################################
61__all__ = ['TestResult', 'TestCase', 'TestSuite', 'TextTestRunner',
62 'TestLoader', 'FunctionTestCase', 'main', 'defaultTestLoader']
63
Steve Purcell7e743842003-09-22 11:08:12 +000064# Expose obsolete functions for backwards compatibility
Steve Purcelld75e7e42003-09-15 11:01:21 +000065__all__.extend(['getTestCaseNames', 'makeSuite', 'findTestCases'])
66
67
68##############################################################################
Fred Drake02538202001-03-21 18:09:46 +000069# Test framework core
70##############################################################################
71
Steve Purcelldc391a62002-08-09 09:46:23 +000072def _strclass(cls):
73 return "%s.%s" % (cls.__module__, cls.__name__)
74
Benjamin Peterson5254c042009-03-23 22:25:03 +000075
76class SkipTest(Exception):
77 """
78 Raise this exception in a test to skip it.
79
80 Usually you can use TestResult.skip() or one of the skipping decorators
81 instead of raising this directly.
82 """
83 pass
84
85class _ExpectedFailure(Exception):
86 """
87 Raise this when a test is expected to fail.
88
89 This is an implementation detail.
90 """
91
92 def __init__(self, exc_info):
93 super(_ExpectedFailure, self).__init__()
94 self.exc_info = exc_info
95
96class _UnexpectedSuccess(Exception):
97 """
98 The test was supposed to fail, but it didn't!
99 """
100 pass
101
102def _id(obj):
103 return obj
104
105def skip(reason):
106 """
107 Unconditionally skip a test.
108 """
109 def decorator(test_item):
110 if isinstance(test_item, type) and issubclass(test_item, TestCase):
111 test_item.__unittest_skip__ = True
112 test_item.__unittest_skip_why__ = reason
113 return test_item
114 @functools.wraps(test_item)
115 def skip_wrapper(*args, **kwargs):
116 raise SkipTest(reason)
117 return skip_wrapper
118 return decorator
119
120def skipIf(condition, reason):
121 """
122 Skip a test if the condition is true.
123 """
124 if condition:
125 return skip(reason)
126 return _id
127
128def skipUnless(condition, reason):
129 """
130 Skip a test unless the condition is true.
131 """
132 if not condition:
133 return skip(reason)
134 return _id
135
136
137def expectedFailure(func):
138 @functools.wraps(func)
139 def wrapper(*args, **kwargs):
140 try:
141 func(*args, **kwargs)
142 except Exception:
143 raise _ExpectedFailure(sys.exc_info())
144 raise _UnexpectedSuccess
145 return wrapper
146
147
Steve Purcellb8d5f242003-12-06 13:03:13 +0000148__unittest = 1
149
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000150class TestResult(object):
Fred Drake02538202001-03-21 18:09:46 +0000151 """Holder for test result information.
152
153 Test results are automatically managed by the TestCase and TestSuite
154 classes, and do not need to be explicitly manipulated by writers of tests.
155
156 Each instance holds the total number of tests run, and collections of
157 failures and errors that occurred among those test runs. The collections
Steve Purcell7b065702001-09-06 08:24:40 +0000158 contain tuples of (testcase, exceptioninfo), where exceptioninfo is the
Fred Drake656f9ec2001-09-06 19:13:14 +0000159 formatted traceback of the error that occurred.
Fred Drake02538202001-03-21 18:09:46 +0000160 """
161 def __init__(self):
162 self.failures = []
163 self.errors = []
164 self.testsRun = 0
Benjamin Peterson5254c042009-03-23 22:25:03 +0000165 self.skipped = []
166 self.expected_failures = []
167 self.unexpected_successes = []
Guido van Rossumd8faa362007-04-27 19:54:29 +0000168 self.shouldStop = False
Fred Drake02538202001-03-21 18:09:46 +0000169
170 def startTest(self, test):
171 "Called when the given test is about to be run"
172 self.testsRun = self.testsRun + 1
173
174 def stopTest(self, test):
175 "Called when the given test has been run"
176 pass
177
178 def addError(self, test, err):
Steve Purcell7b065702001-09-06 08:24:40 +0000179 """Called when an error has occurred. 'err' is a tuple of values as
180 returned by sys.exc_info().
181 """
Steve Purcellb8d5f242003-12-06 13:03:13 +0000182 self.errors.append((test, self._exc_info_to_string(err, test)))
Fred Drake02538202001-03-21 18:09:46 +0000183
184 def addFailure(self, test, err):
Steve Purcell7b065702001-09-06 08:24:40 +0000185 """Called when an error has occurred. 'err' is a tuple of values as
186 returned by sys.exc_info()."""
Steve Purcellb8d5f242003-12-06 13:03:13 +0000187 self.failures.append((test, self._exc_info_to_string(err, test)))
Fred Drake02538202001-03-21 18:09:46 +0000188
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000189 def addSuccess(self, test):
190 "Called when a test has completed successfully"
191 pass
192
Benjamin Peterson5254c042009-03-23 22:25:03 +0000193 def addSkip(self, test, reason):
194 """Called when a test is skipped."""
195 self.skipped.append((test, reason))
196
197 def addExpectedFailure(self, test, err):
198 """Called when an expected failure/error occured."""
199 self.expected_failures.append(
200 (test, self._exc_info_to_string(err, test)))
201
202 def addUnexpectedSuccess(self, test):
203 """Called when a test was expected to fail, but succeed."""
204 self.unexpected_successes.append(test)
205
Fred Drake02538202001-03-21 18:09:46 +0000206 def wasSuccessful(self):
207 "Tells whether or not this result was a success"
208 return len(self.failures) == len(self.errors) == 0
209
210 def stop(self):
211 "Indicates that the tests should be aborted"
Steve Purcell7e743842003-09-22 11:08:12 +0000212 self.shouldStop = True
Tim Petersa19a1682001-03-29 04:36:09 +0000213
Steve Purcellb8d5f242003-12-06 13:03:13 +0000214 def _exc_info_to_string(self, err, test):
Steve Purcell7b065702001-09-06 08:24:40 +0000215 """Converts a sys.exc_info()-style tuple of values into a string."""
Steve Purcellb8d5f242003-12-06 13:03:13 +0000216 exctype, value, tb = err
217 # Skip test runner traceback levels
218 while tb and self._is_relevant_tb_level(tb):
219 tb = tb.tb_next
220 if exctype is test.failureException:
221 # Skip assert*() traceback levels
222 length = self._count_relevant_tb_levels(tb)
Collin Winterce36ad82007-08-30 01:19:48 +0000223 return ''.join(traceback.format_exception(exctype, value,
224 tb, length))
Steve Purcellb8d5f242003-12-06 13:03:13 +0000225 return ''.join(traceback.format_exception(exctype, value, tb))
226
227 def _is_relevant_tb_level(self, tb):
Guido van Rossume2b70bc2006-08-18 22:13:04 +0000228 return '__unittest' in tb.tb_frame.f_globals
Steve Purcellb8d5f242003-12-06 13:03:13 +0000229
230 def _count_relevant_tb_levels(self, tb):
231 length = 0
232 while tb and not self._is_relevant_tb_level(tb):
233 length += 1
234 tb = tb.tb_next
235 return length
Steve Purcell7b065702001-09-06 08:24:40 +0000236
Fred Drake02538202001-03-21 18:09:46 +0000237 def __repr__(self):
238 return "<%s run=%i errors=%i failures=%i>" % \
Steve Purcelldc391a62002-08-09 09:46:23 +0000239 (_strclass(self.__class__), self.testsRun, len(self.errors),
Fred Drake02538202001-03-21 18:09:46 +0000240 len(self.failures))
241
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000242class AssertRaisesContext(object):
Antoine Pitrou5acd41e2008-12-28 14:29:00 +0000243 def __init__(self, expected, test_case, callable_obj=None):
244 self.expected = expected
245 self.failureException = test_case.failureException
246 if callable_obj is not None:
247 try:
248 self.obj_name = callable_obj.__name__
249 except AttributeError:
250 self.obj_name = str(callable_obj)
251 else:
252 self.obj_name = None
253 def __enter__(self):
254 pass
255 def __exit__(self, exc_type, exc_value, traceback):
256 if exc_type is None:
257 try:
258 exc_name = self.expected.__name__
259 except AttributeError:
260 exc_name = str(self.expected)
261 if self.obj_name:
262 raise self.failureException("{0} not raised by {1}"
263 .format(exc_name, self.obj_name))
264 else:
265 raise self.failureException("{0} not raised"
266 .format(exc_name))
267 if issubclass(exc_type, self.expected):
268 return True
269 # Let unexpected exceptions skip through
270 return False
271
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000272class TestCase(object):
Fred Drake02538202001-03-21 18:09:46 +0000273 """A class whose instances are single test cases.
274
Fred Drake02538202001-03-21 18:09:46 +0000275 By default, the test code itself should be placed in a method named
276 'runTest'.
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000277
Tim Petersa19a1682001-03-29 04:36:09 +0000278 If the fixture may be used for many test cases, create as
Fred Drake02538202001-03-21 18:09:46 +0000279 many test methods as are needed. When instantiating such a TestCase
280 subclass, specify in the constructor arguments the name of the test method
281 that the instance is to execute.
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000282
Tim Petersa19a1682001-03-29 04:36:09 +0000283 Test authors should subclass TestCase for their own tests. Construction
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000284 and deconstruction of the test's environment ('fixture') can be
285 implemented by overriding the 'setUp' and 'tearDown' methods respectively.
286
287 If it is necessary to override the __init__ method, the base class
288 __init__ method must always be called. It is important that subclasses
289 should not change the signature of their __init__ method, since instances
290 of the classes are instantiated automatically by parts of the framework
291 in order to be run.
Fred Drake02538202001-03-21 18:09:46 +0000292 """
Steve Purcell15d89272001-04-12 09:05:01 +0000293
294 # This attribute determines which exception will be raised when
295 # the instance's assertion methods fail; test methods raising this
296 # exception will be deemed to have 'failed' rather than 'errored'
297
298 failureException = AssertionError
299
Fred Drake02538202001-03-21 18:09:46 +0000300 def __init__(self, methodName='runTest'):
301 """Create an instance of the class that will use the named test
302 method when executed. Raises a ValueError if the instance does
303 not have a method with the specified name.
304 """
305 try:
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000306 self._testMethodName = methodName
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000307 testMethod = getattr(self, methodName)
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000308 self._testMethodDoc = testMethod.__doc__
Fred Drake02538202001-03-21 18:09:46 +0000309 except AttributeError:
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000310 raise ValueError("no such test method in %s: %s" % \
311 (self.__class__, methodName))
Fred Drake02538202001-03-21 18:09:46 +0000312
313 def setUp(self):
314 "Hook method for setting up the test fixture before exercising it."
315 pass
316
317 def tearDown(self):
318 "Hook method for deconstructing the test fixture after testing it."
319 pass
320
321 def countTestCases(self):
322 return 1
323
324 def defaultTestResult(self):
325 return TestResult()
326
327 def shortDescription(self):
328 """Returns a one-line description of the test, or None if no
329 description has been provided.
330
331 The default implementation of this method returns the first line of
332 the specified test method's docstring.
333 """
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000334 doc = self._testMethodDoc
Steve Purcell7e743842003-09-22 11:08:12 +0000335 return doc and doc.split("\n")[0].strip() or None
Fred Drake02538202001-03-21 18:09:46 +0000336
337 def id(self):
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000338 return "%s.%s" % (_strclass(self.__class__), self._testMethodName)
Fred Drake02538202001-03-21 18:09:46 +0000339
Guido van Rossumd8faa362007-04-27 19:54:29 +0000340 def __eq__(self, other):
341 if type(self) is not type(other):
342 return False
343
344 return self._testMethodName == other._testMethodName
345
346 def __ne__(self, other):
347 return not self == other
348
349 def __hash__(self):
350 return hash((type(self), self._testMethodName))
351
Fred Drake02538202001-03-21 18:09:46 +0000352 def __str__(self):
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000353 return "%s (%s)" % (self._testMethodName, _strclass(self.__class__))
Fred Drake02538202001-03-21 18:09:46 +0000354
355 def __repr__(self):
356 return "<%s testMethod=%s>" % \
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000357 (_strclass(self.__class__), self._testMethodName)
Fred Drake02538202001-03-21 18:09:46 +0000358
359 def run(self, result=None):
Fred Drake02538202001-03-21 18:09:46 +0000360 if result is None: result = self.defaultTestResult()
361 result.startTest(self)
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000362 testMethod = getattr(self, self._testMethodName)
Fred Drake02538202001-03-21 18:09:46 +0000363 try:
364 try:
365 self.setUp()
Benjamin Peterson5254c042009-03-23 22:25:03 +0000366 except SkipTest as e:
367 result.addSkip(self, str(e))
368 return
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000369 except Exception:
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000370 result.addError(self, self._exc_info())
Fred Drake02538202001-03-21 18:09:46 +0000371 return
372
Benjamin Peterson5254c042009-03-23 22:25:03 +0000373 success = False
Fred Drake02538202001-03-21 18:09:46 +0000374 try:
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000375 testMethod()
Skip Montanaroae5c37b2003-07-13 15:18:12 +0000376 except self.failureException:
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000377 result.addFailure(self, self._exc_info())
Benjamin Peterson5254c042009-03-23 22:25:03 +0000378 except _ExpectedFailure as e:
379 result.addExpectedFailure(self, e.exc_info)
380 except _UnexpectedSuccess:
381 result.addUnexpectedSuccess(self)
382 except SkipTest as e:
383 result.addSkip(self, str(e))
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000384 except Exception:
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000385 result.addError(self, self._exc_info())
Benjamin Peterson5254c042009-03-23 22:25:03 +0000386 else:
387 success = True
Fred Drake02538202001-03-21 18:09:46 +0000388
389 try:
390 self.tearDown()
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000391 except Exception:
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000392 result.addError(self, self._exc_info())
Benjamin Peterson5254c042009-03-23 22:25:03 +0000393 success = False
394 if success:
395 result.addSuccess(self)
Fred Drake02538202001-03-21 18:09:46 +0000396 finally:
397 result.stopTest(self)
398
Raymond Hettinger664347b2004-12-04 21:21:53 +0000399 def __call__(self, *args, **kwds):
400 return self.run(*args, **kwds)
Steve Purcell7e743842003-09-22 11:08:12 +0000401
Fred Drake02538202001-03-21 18:09:46 +0000402 def debug(self):
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000403 """Run the test without collecting errors in a TestResult"""
Fred Drake02538202001-03-21 18:09:46 +0000404 self.setUp()
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000405 getattr(self, self._testMethodName)()
Fred Drake02538202001-03-21 18:09:46 +0000406 self.tearDown()
407
Georg Brandl81cdb4e2006-01-20 17:55:00 +0000408 def _exc_info(self):
Steve Purcell15d89272001-04-12 09:05:01 +0000409 """Return a version of sys.exc_info() with the traceback frame
410 minimised; usually the top level of the traceback frame is not
411 needed.
Fred Drake02538202001-03-21 18:09:46 +0000412 """
Guido van Rossumd8faa362007-04-27 19:54:29 +0000413 return sys.exc_info()
Fred Drake02538202001-03-21 18:09:46 +0000414
Benjamin Peterson5254c042009-03-23 22:25:03 +0000415 def skip(self, reason):
416 """Skip this test."""
417 raise SkipTest(reason)
418
Steve Purcell15d89272001-04-12 09:05:01 +0000419 def fail(self, msg=None):
420 """Fail immediately, with the given message."""
Collin Winterce36ad82007-08-30 01:19:48 +0000421 raise self.failureException(msg)
Fred Drake02538202001-03-21 18:09:46 +0000422
423 def failIf(self, expr, msg=None):
424 "Fail the test if the expression is true."
Collin Winterce36ad82007-08-30 01:19:48 +0000425 if expr: raise self.failureException(msg)
Fred Drake02538202001-03-21 18:09:46 +0000426
Steve Purcell15d89272001-04-12 09:05:01 +0000427 def failUnless(self, expr, msg=None):
428 """Fail the test unless the expression is true."""
Collin Winterce36ad82007-08-30 01:19:48 +0000429 if not expr: raise self.failureException(msg)
Steve Purcell15d89272001-04-12 09:05:01 +0000430
Antoine Pitrou5acd41e2008-12-28 14:29:00 +0000431 def failUnlessRaises(self, excClass, callableObj=None, *args, **kwargs):
Steve Purcell15d89272001-04-12 09:05:01 +0000432 """Fail unless an exception of class excClass is thrown
Fred Drake02538202001-03-21 18:09:46 +0000433 by callableObj when invoked with arguments args and keyword
434 arguments kwargs. If a different type of exception is
435 thrown, it will not be caught, and the test case will be
436 deemed to have suffered an error, exactly as for an
437 unexpected exception.
Antoine Pitrou5acd41e2008-12-28 14:29:00 +0000438
439 If called with callableObj omitted or None, will return a
440 context object used like this::
441
442 with self.failUnlessRaises(some_error_class):
443 do_something()
Fred Drake02538202001-03-21 18:09:46 +0000444 """
Antoine Pitrou5acd41e2008-12-28 14:29:00 +0000445 context = AssertRaisesContext(excClass, self, callableObj)
446 if callableObj is None:
447 return context
448 with context:
Guido van Rossum68468eb2003-02-27 20:14:51 +0000449 callableObj(*args, **kwargs)
Fred Drake02538202001-03-21 18:09:46 +0000450
Steve Purcell15d89272001-04-12 09:05:01 +0000451 def failUnlessEqual(self, first, second, msg=None):
Raymond Hettingerc377cbf2003-04-04 22:56:42 +0000452 """Fail if the two objects are unequal as determined by the '=='
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000453 operator.
454 """
Raymond Hettingerc377cbf2003-04-04 22:56:42 +0000455 if not first == second:
Collin Winterce36ad82007-08-30 01:19:48 +0000456 raise self.failureException(msg or '%r != %r' % (first, second))
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000457
Steve Purcell15d89272001-04-12 09:05:01 +0000458 def failIfEqual(self, first, second, msg=None):
459 """Fail if the two objects are equal as determined by the '=='
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000460 operator.
461 """
Steve Purcell15d89272001-04-12 09:05:01 +0000462 if first == second:
Collin Winterce36ad82007-08-30 01:19:48 +0000463 raise self.failureException(msg or '%r == %r' % (first, second))
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000464
Jeffrey Yasskinaaaef112007-09-07 15:00:39 +0000465 def failUnlessAlmostEqual(self, first, second, *, places=7, msg=None):
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000466 """Fail if the two objects are unequal as determined by their
467 difference rounded to the given number of decimal places
468 (default 7) and comparing to zero.
469
Steve Purcell397b45d2003-10-26 10:41:03 +0000470 Note that decimal places (from zero) are usually not the same
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000471 as significant digits (measured from the most signficant digit).
472 """
Jeffrey Yasskin1cc55442007-09-06 18:55:17 +0000473 if round(abs(second-first), places) != 0:
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000474 raise self.failureException(
475 msg or '%r != %r within %r places' % (first, second, places))
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000476
Jeffrey Yasskinaaaef112007-09-07 15:00:39 +0000477 def failIfAlmostEqual(self, first, second, *, places=7, msg=None):
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000478 """Fail if the two objects are equal as determined by their
479 difference rounded to the given number of decimal places
480 (default 7) and comparing to zero.
481
Steve Purcellcca34912003-10-26 16:38:16 +0000482 Note that decimal places (from zero) are usually not the same
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000483 as significant digits (measured from the most signficant digit).
484 """
Jeffrey Yasskin1cc55442007-09-06 18:55:17 +0000485 if round(abs(second-first), places) == 0:
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000486 raise self.failureException(
487 msg or '%r == %r within %r places' % (first, second, places))
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000488
Steve Purcell7e743842003-09-22 11:08:12 +0000489 # Synonyms for assertion methods
490
Steve Purcell15d89272001-04-12 09:05:01 +0000491 assertEqual = assertEquals = failUnlessEqual
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000492
Steve Purcell15d89272001-04-12 09:05:01 +0000493 assertNotEqual = assertNotEquals = failIfEqual
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000494
Raymond Hettingerc7b07692002-12-29 17:59:24 +0000495 assertAlmostEqual = assertAlmostEquals = failUnlessAlmostEqual
496
497 assertNotAlmostEqual = assertNotAlmostEquals = failIfAlmostEqual
498
Steve Purcell15d89272001-04-12 09:05:01 +0000499 assertRaises = failUnlessRaises
500
Steve Purcell7e743842003-09-22 11:08:12 +0000501 assert_ = assertTrue = failUnless
502
503 assertFalse = failIf
Steve Purcell15d89272001-04-12 09:05:01 +0000504
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000505
Fred Drake02538202001-03-21 18:09:46 +0000506
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000507class TestSuite(object):
Fred Drake02538202001-03-21 18:09:46 +0000508 """A test suite is a composite test consisting of a number of TestCases.
509
510 For use, create an instance of TestSuite, then add test case instances.
511 When all tests have been added, the suite can be passed to a test
512 runner, such as TextTestRunner. It will run the individual test cases
513 in the order in which they were added, aggregating the results. When
514 subclassing, do not forget to call the base class constructor.
515 """
516 def __init__(self, tests=()):
517 self._tests = []
518 self.addTests(tests)
519
520 def __repr__(self):
Steve Purcelldc391a62002-08-09 09:46:23 +0000521 return "<%s tests=%s>" % (_strclass(self.__class__), self._tests)
Fred Drake02538202001-03-21 18:09:46 +0000522
523 __str__ = __repr__
524
Guido van Rossumd8faa362007-04-27 19:54:29 +0000525 def __eq__(self, other):
Benjamin Peterson5254c042009-03-23 22:25:03 +0000526 if not isinstance(other, self.__class__):
527 return NotImplemented
Guido van Rossumd8faa362007-04-27 19:54:29 +0000528 return self._tests == other._tests
529
530 def __ne__(self, other):
531 return not self == other
532
Jim Fultonfafd8742004-08-28 15:22:12 +0000533 def __iter__(self):
534 return iter(self._tests)
535
Fred Drake02538202001-03-21 18:09:46 +0000536 def countTestCases(self):
537 cases = 0
538 for test in self._tests:
Steve Purcell7e743842003-09-22 11:08:12 +0000539 cases += test.countTestCases()
Fred Drake02538202001-03-21 18:09:46 +0000540 return cases
541
542 def addTest(self, test):
Guido van Rossumd8faa362007-04-27 19:54:29 +0000543 # sanity checks
Guido van Rossumd59da4b2007-05-22 18:11:13 +0000544 if not hasattr(test, '__call__'):
Guido van Rossumd8faa362007-04-27 19:54:29 +0000545 raise TypeError("the test to add must be callable")
Guido van Rossum13257902007-06-07 23:15:56 +0000546 if isinstance(test, type) and issubclass(test, (TestCase, TestSuite)):
Guido van Rossumd8faa362007-04-27 19:54:29 +0000547 raise TypeError("TestCases and TestSuites must be instantiated "
548 "before passing them to addTest()")
Fred Drake02538202001-03-21 18:09:46 +0000549 self._tests.append(test)
550
551 def addTests(self, tests):
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000552 if isinstance(tests, str):
Guido van Rossumd8faa362007-04-27 19:54:29 +0000553 raise TypeError("tests must be an iterable of tests, not a string")
Fred Drake02538202001-03-21 18:09:46 +0000554 for test in tests:
555 self.addTest(test)
556
557 def run(self, result):
Fred Drake02538202001-03-21 18:09:46 +0000558 for test in self._tests:
559 if result.shouldStop:
560 break
561 test(result)
562 return result
563
Raymond Hettinger664347b2004-12-04 21:21:53 +0000564 def __call__(self, *args, **kwds):
565 return self.run(*args, **kwds)
566
Fred Drake02538202001-03-21 18:09:46 +0000567 def debug(self):
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000568 """Run the tests without collecting errors in a TestResult"""
Fred Drake02538202001-03-21 18:09:46 +0000569 for test in self._tests: test.debug()
Fred Drake02538202001-03-21 18:09:46 +0000570
571
Benjamin Peterson5254c042009-03-23 22:25:03 +0000572class ClassTestSuite(TestSuite):
573 """
574 Suite of tests derived from a single TestCase class.
575 """
576
577 def __init__(self, tests, class_collected_from):
578 super(ClassTestSuite, self).__init__(tests)
579 self.collected_from = class_collected_from
580
581 def id(self):
582 module = getattr(self.collected_from, "__module__", None)
583 if module is not None:
584 return "{0}.{1}".format(module, self.collected_from.__name__)
585 return self.collected_from.__name__
586
587 def run(self, result):
588 if getattr(self.collected_from, "__unittest_skip__", False):
589 # ClassTestSuite result pretends to be a TestCase enough to be
590 # reported.
591 result.startTest(self)
592 try:
593 result.addSkip(self, self.collected_from.__unittest_skip_why__)
594 finally:
595 result.stopTest(self)
596 else:
597 result = super(ClassTestSuite, self).run(result)
598 return result
599
600 shortDescription = id
601
602
Fred Drake02538202001-03-21 18:09:46 +0000603class FunctionTestCase(TestCase):
604 """A test case that wraps a test function.
605
606 This is useful for slipping pre-existing test functions into the
Guido van Rossumd8faa362007-04-27 19:54:29 +0000607 unittest framework. Optionally, set-up and tidy-up functions can be
Fred Drake02538202001-03-21 18:09:46 +0000608 supplied. As with TestCase, the tidy-up ('tearDown') function will
609 always be called if the set-up ('setUp') function ran successfully.
610 """
611
612 def __init__(self, testFunc, setUp=None, tearDown=None,
613 description=None):
614 TestCase.__init__(self)
615 self.__setUpFunc = setUp
616 self.__tearDownFunc = tearDown
617 self.__testFunc = testFunc
618 self.__description = description
619
620 def setUp(self):
621 if self.__setUpFunc is not None:
622 self.__setUpFunc()
623
624 def tearDown(self):
625 if self.__tearDownFunc is not None:
626 self.__tearDownFunc()
627
628 def runTest(self):
629 self.__testFunc()
630
631 def id(self):
632 return self.__testFunc.__name__
633
Guido van Rossumd8faa362007-04-27 19:54:29 +0000634 def __eq__(self, other):
635 if type(self) is not type(other):
636 return False
637
638 return self.__setUpFunc == other.__setUpFunc and \
639 self.__tearDownFunc == other.__tearDownFunc and \
640 self.__testFunc == other.__testFunc and \
641 self.__description == other.__description
642
643 def __ne__(self, other):
644 return not self == other
645
646 def __hash__(self):
647 return hash((type(self), self.__setUpFunc, self.__tearDownFunc,
Collin Winterce36ad82007-08-30 01:19:48 +0000648 self.__testFunc, self.__description))
Guido van Rossumd8faa362007-04-27 19:54:29 +0000649
Fred Drake02538202001-03-21 18:09:46 +0000650 def __str__(self):
Collin Winterce36ad82007-08-30 01:19:48 +0000651 return "%s (%s)" % (_strclass(self.__class__),
652 self.__testFunc.__name__)
Fred Drake02538202001-03-21 18:09:46 +0000653
654 def __repr__(self):
Collin Winterce36ad82007-08-30 01:19:48 +0000655 return "<%s testFunc=%s>" % (_strclass(self.__class__),
656 self.__testFunc)
Fred Drake02538202001-03-21 18:09:46 +0000657
658 def shortDescription(self):
659 if self.__description is not None: return self.__description
660 doc = self.__testFunc.__doc__
Steve Purcell7e743842003-09-22 11:08:12 +0000661 return doc and doc.split("\n")[0].strip() or None
Fred Drake02538202001-03-21 18:09:46 +0000662
663
664
665##############################################################################
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000666# Locating and loading tests
Fred Drake02538202001-03-21 18:09:46 +0000667##############################################################################
668
Raymond Hettingerd4cb56d2008-01-30 02:55:10 +0000669def CmpToKey(mycmp):
670 'Convert a cmp= function into a key= function'
671 class K(object):
672 def __init__(self, obj, *args):
673 self.obj = obj
674 def __lt__(self, other):
675 return mycmp(self.obj, other.obj) == -1
676 return K
677
Mark Dickinsona56c4672009-01-27 18:17:45 +0000678def three_way_cmp(x, y):
679 """Return -1 if x < y, 0 if x == y and 1 if x > y"""
680 return (x > y) - (x < y)
681
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000682class TestLoader(object):
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000683 """This class is responsible for loading tests according to various
Guido van Rossumd8faa362007-04-27 19:54:29 +0000684 criteria and returning them wrapped in a TestSuite
Fred Drake02538202001-03-21 18:09:46 +0000685 """
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000686 testMethodPrefix = 'test'
Mark Dickinsona56c4672009-01-27 18:17:45 +0000687 sortTestMethodsUsing = staticmethod(three_way_cmp)
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000688 suiteClass = TestSuite
Benjamin Peterson5254c042009-03-23 22:25:03 +0000689 classSuiteClass = ClassTestSuite
Fred Drake02538202001-03-21 18:09:46 +0000690
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000691 def loadTestsFromTestCase(self, testCaseClass):
Steve Purcell15d89272001-04-12 09:05:01 +0000692 """Return a suite of all tests cases contained in testCaseClass"""
Johannes Gijsbersd7b6ad42004-11-07 15:46:25 +0000693 if issubclass(testCaseClass, TestSuite):
Collin Winterce36ad82007-08-30 01:19:48 +0000694 raise TypeError("Test cases should not be derived from TestSuite."
695 "Maybe you meant to derive from TestCase?")
Steve Purcell7e743842003-09-22 11:08:12 +0000696 testCaseNames = self.getTestCaseNames(testCaseClass)
697 if not testCaseNames and hasattr(testCaseClass, 'runTest'):
698 testCaseNames = ['runTest']
Benjamin Peterson5254c042009-03-23 22:25:03 +0000699 suite = self.classSuiteClass(map(testCaseClass, testCaseNames),
700 testCaseClass)
701 return suite
Fred Drake02538202001-03-21 18:09:46 +0000702
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000703 def loadTestsFromModule(self, module):
Steve Purcell15d89272001-04-12 09:05:01 +0000704 """Return a suite of all tests cases contained in the given module"""
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000705 tests = []
706 for name in dir(module):
707 obj = getattr(module, name)
Guido van Rossum13257902007-06-07 23:15:56 +0000708 if isinstance(obj, type) and issubclass(obj, TestCase):
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000709 tests.append(self.loadTestsFromTestCase(obj))
710 return self.suiteClass(tests)
Fred Drake02538202001-03-21 18:09:46 +0000711
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000712 def loadTestsFromName(self, name, module=None):
Steve Purcell15d89272001-04-12 09:05:01 +0000713 """Return a suite of all tests cases given a string specifier.
714
715 The name may resolve either to a module, a test case class, a
716 test method within a test case class, or a callable object which
717 returns a TestCase or TestSuite instance.
Tim Peters613b2222001-04-13 05:37:27 +0000718
Steve Purcell15d89272001-04-12 09:05:01 +0000719 The method optionally resolves the names relative to a given module.
720 """
Steve Purcell7e743842003-09-22 11:08:12 +0000721 parts = name.split('.')
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000722 if module is None:
Steve Purcell7e743842003-09-22 11:08:12 +0000723 parts_copy = parts[:]
724 while parts_copy:
725 try:
726 module = __import__('.'.join(parts_copy))
727 break
728 except ImportError:
729 del parts_copy[-1]
730 if not parts_copy: raise
Armin Rigo1b3c04b2003-10-24 17:15:29 +0000731 parts = parts[1:]
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000732 obj = module
733 for part in parts:
Steve Purcell7e743842003-09-22 11:08:12 +0000734 parent, obj = obj, getattr(obj, part)
Fred Drake02538202001-03-21 18:09:46 +0000735
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000736 if isinstance(obj, types.ModuleType):
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000737 return self.loadTestsFromModule(obj)
Guido van Rossum13257902007-06-07 23:15:56 +0000738 elif isinstance(obj, type) and issubclass(obj, TestCase):
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000739 return self.loadTestsFromTestCase(obj)
Christian Heimes4a22b5d2007-11-25 09:39:14 +0000740 elif (isinstance(obj, types.FunctionType) and
Guido van Rossum13257902007-06-07 23:15:56 +0000741 isinstance(parent, type) and
Guido van Rossumd8faa362007-04-27 19:54:29 +0000742 issubclass(parent, TestCase)):
Christian Heimes4a22b5d2007-11-25 09:39:14 +0000743 name = obj.__name__
744 inst = parent(name)
745 # static methods follow a different path
Christian Heimes4975a1f2007-11-26 10:14:51 +0000746 if not isinstance(getattr(inst, name), types.FunctionType):
Christian Heimes4a22b5d2007-11-25 09:39:14 +0000747 return TestSuite([inst])
Steve Purcell397b45d2003-10-26 10:41:03 +0000748 elif isinstance(obj, TestSuite):
Steve Purcell7e743842003-09-22 11:08:12 +0000749 return obj
Christian Heimes4a22b5d2007-11-25 09:39:14 +0000750
751 if hasattr(obj, '__call__'):
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000752 test = obj()
Guido van Rossumd8faa362007-04-27 19:54:29 +0000753 if isinstance(test, TestSuite):
754 return test
755 elif isinstance(test, TestCase):
756 return TestSuite([test])
757 else:
758 raise TypeError("calling %s returned %s, not a test" %
759 (obj, test))
Fred Drake02538202001-03-21 18:09:46 +0000760 else:
Guido van Rossumd8faa362007-04-27 19:54:29 +0000761 raise TypeError("don't know how to make test from: %s" % obj)
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000762
763 def loadTestsFromNames(self, names, module=None):
Steve Purcell15d89272001-04-12 09:05:01 +0000764 """Return a suite of all tests cases found using the given sequence
765 of string specifiers. See 'loadTestsFromName()'.
766 """
Steve Purcell7e743842003-09-22 11:08:12 +0000767 suites = [self.loadTestsFromName(name, module) for name in names]
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000768 return self.suiteClass(suites)
769
770 def getTestCaseNames(self, testCaseClass):
Steve Purcell15d89272001-04-12 09:05:01 +0000771 """Return a sorted sequence of method names found within testCaseClass
772 """
Collin Winterce36ad82007-08-30 01:19:48 +0000773 def isTestMethod(attrname, testCaseClass=testCaseClass,
774 prefix=self.testMethodPrefix):
775 return attrname.startswith(prefix) \
776 and hasattr(getattr(testCaseClass, attrname), '__call__')
Guido van Rossumc1f779c2007-07-03 08:25:58 +0000777 testFnNames = list(filter(isTestMethod, dir(testCaseClass)))
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000778 if self.sortTestMethodsUsing:
Raymond Hettingerd4cb56d2008-01-30 02:55:10 +0000779 testFnNames.sort(key=CmpToKey(self.sortTestMethodsUsing))
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000780 return testFnNames
781
782
783
784defaultTestLoader = TestLoader()
785
786
787##############################################################################
788# Patches for old functions: these functions should be considered obsolete
789##############################################################################
790
791def _makeLoader(prefix, sortUsing, suiteClass=None):
792 loader = TestLoader()
793 loader.sortTestMethodsUsing = sortUsing
794 loader.testMethodPrefix = prefix
795 if suiteClass: loader.suiteClass = suiteClass
796 return loader
797
Mark Dickinsonc429a832009-01-27 20:27:05 +0000798def getTestCaseNames(testCaseClass, prefix, sortUsing=three_way_cmp):
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000799 return _makeLoader(prefix, sortUsing).getTestCaseNames(testCaseClass)
800
Mark Dickinsonc429a832009-01-27 20:27:05 +0000801def makeSuite(testCaseClass, prefix='test', sortUsing=three_way_cmp,
802 suiteClass=TestSuite):
803 return _makeLoader(prefix, sortUsing, suiteClass).loadTestsFromTestCase(
804 testCaseClass)
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000805
Mark Dickinsonc429a832009-01-27 20:27:05 +0000806def findTestCases(module, prefix='test', sortUsing=three_way_cmp,
807 suiteClass=TestSuite):
808 return _makeLoader(prefix, sortUsing, suiteClass).loadTestsFromModule(
809 module)
Fred Drake02538202001-03-21 18:09:46 +0000810
811
812##############################################################################
813# Text UI
814##############################################################################
815
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000816class _WritelnDecorator(object):
Fred Drake02538202001-03-21 18:09:46 +0000817 """Used to decorate file-like objects with a handy 'writeln' method"""
818 def __init__(self,stream):
819 self.stream = stream
Fred Drake02538202001-03-21 18:09:46 +0000820
821 def __getattr__(self, attr):
822 return getattr(self.stream,attr)
823
Raymond Hettinger91dd19d2003-09-13 02:58:00 +0000824 def writeln(self, arg=None):
825 if arg: self.write(arg)
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000826 self.write('\n') # text-mode streams translate to \r\n if needed
Tim Petersa19a1682001-03-29 04:36:09 +0000827
Fred Drake02538202001-03-21 18:09:46 +0000828
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000829class _TextTestResult(TestResult):
Fred Drake02538202001-03-21 18:09:46 +0000830 """A test result class that can print formatted text results to a stream.
831
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000832 Used by TextTestRunner.
Fred Drake02538202001-03-21 18:09:46 +0000833 """
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000834 separator1 = '=' * 70
835 separator2 = '-' * 70
Fred Drake02538202001-03-21 18:09:46 +0000836
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000837 def __init__(self, stream, descriptions, verbosity):
Fred Drake02538202001-03-21 18:09:46 +0000838 TestResult.__init__(self)
839 self.stream = stream
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000840 self.showAll = verbosity > 1
841 self.dots = verbosity == 1
Fred Drake02538202001-03-21 18:09:46 +0000842 self.descriptions = descriptions
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000843
844 def getDescription(self, test):
845 if self.descriptions:
846 return test.shortDescription() or str(test)
847 else:
848 return str(test)
849
Fred Drake02538202001-03-21 18:09:46 +0000850 def startTest(self, test):
851 TestResult.startTest(self, test)
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000852 if self.showAll:
853 self.stream.write(self.getDescription(test))
854 self.stream.write(" ... ")
Alexandre Vassalotti8ae3e052008-05-16 00:41:41 +0000855 self.stream.flush()
Fred Drake02538202001-03-21 18:09:46 +0000856
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000857 def addSuccess(self, test):
858 TestResult.addSuccess(self, test)
859 if self.showAll:
Fred Drake02538202001-03-21 18:09:46 +0000860 self.stream.writeln("ok")
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000861 elif self.dots:
862 self.stream.write('.')
Alexandre Vassalotti8ae3e052008-05-16 00:41:41 +0000863 self.stream.flush()
Fred Drake02538202001-03-21 18:09:46 +0000864
865 def addError(self, test, err):
866 TestResult.addError(self, test, err)
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000867 if self.showAll:
868 self.stream.writeln("ERROR")
869 elif self.dots:
870 self.stream.write('E')
Alexandre Vassalotti8ae3e052008-05-16 00:41:41 +0000871 self.stream.flush()
Fred Drake02538202001-03-21 18:09:46 +0000872
873 def addFailure(self, test, err):
874 TestResult.addFailure(self, test, err)
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000875 if self.showAll:
876 self.stream.writeln("FAIL")
877 elif self.dots:
878 self.stream.write('F')
Alexandre Vassalotti8ae3e052008-05-16 00:41:41 +0000879 self.stream.flush()
Fred Drake02538202001-03-21 18:09:46 +0000880
Benjamin Peterson5254c042009-03-23 22:25:03 +0000881 def addSkip(self, test, reason):
882 TestResult.addSkip(self, test, reason)
883 if self.showAll:
884 self.stream.writeln("skipped {0!r}".format(reason))
885 elif self.dots:
886 self.stream.write("s")
887 self.stream.flush()
888
889 def addExpectedFailure(self, test, err):
890 TestResult.addExpectedFailure(self, test, err)
891 if self.showAll:
892 self.stream.writeln("expected failure")
893 elif self.dots:
894 self.stream.write(".")
895 self.stream.flush()
896
897 def addUnexpectedSuccess(self, test):
898 TestResult.addUnexpectedSuccess(self, test)
899 if self.showAll:
900 self.stream.writeln("unexpected success")
901 elif self.dots:
902 self.stream.write(".")
903 self.stream.flush()
904
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000905 def printErrors(self):
906 if self.dots or self.showAll:
Fred Drake02538202001-03-21 18:09:46 +0000907 self.stream.writeln()
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000908 self.printErrorList('ERROR', self.errors)
909 self.printErrorList('FAIL', self.failures)
910
911 def printErrorList(self, flavour, errors):
912 for test, err in errors:
913 self.stream.writeln(self.separator1)
914 self.stream.writeln("%s: %s" % (flavour,self.getDescription(test)))
915 self.stream.writeln(self.separator2)
Steve Purcell7b065702001-09-06 08:24:40 +0000916 self.stream.writeln("%s" % err)
Fred Drake02538202001-03-21 18:09:46 +0000917
918
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000919class TextTestRunner(object):
Fred Drake02538202001-03-21 18:09:46 +0000920 """A test runner class that displays results in textual form.
Tim Petersa19a1682001-03-29 04:36:09 +0000921
Fred Drake02538202001-03-21 18:09:46 +0000922 It prints out the names of tests as they are run, errors as they
923 occur, and a summary of the results at the end of the test run.
924 """
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000925 def __init__(self, stream=sys.stderr, descriptions=1, verbosity=1):
Fred Drake02538202001-03-21 18:09:46 +0000926 self.stream = _WritelnDecorator(stream)
927 self.descriptions = descriptions
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000928 self.verbosity = verbosity
929
930 def _makeResult(self):
931 return _TextTestResult(self.stream, self.descriptions, self.verbosity)
Fred Drake02538202001-03-21 18:09:46 +0000932
933 def run(self, test):
934 "Run the given test case or test suite."
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000935 result = self._makeResult()
Fred Drake02538202001-03-21 18:09:46 +0000936 startTime = time.time()
937 test(result)
938 stopTime = time.time()
Steve Purcell397b45d2003-10-26 10:41:03 +0000939 timeTaken = stopTime - startTime
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000940 result.printErrors()
941 self.stream.writeln(result.separator2)
Fred Drake02538202001-03-21 18:09:46 +0000942 run = result.testsRun
943 self.stream.writeln("Ran %d test%s in %.3fs" %
Neal Norwitz76165042002-05-31 14:15:11 +0000944 (run, run != 1 and "s" or "", timeTaken))
Fred Drake02538202001-03-21 18:09:46 +0000945 self.stream.writeln()
Benjamin Peterson5254c042009-03-23 22:25:03 +0000946 results = map(len, (result.expected_failures,
947 result.unexpected_successes,
948 result.skipped))
949 expected_fails, unexpected_successes, skipped = results
950 infos = []
Fred Drake02538202001-03-21 18:09:46 +0000951 if not result.wasSuccessful():
Benjamin Peterson5254c042009-03-23 22:25:03 +0000952 self.stream.write("FAILED")
Guido van Rossumc1f779c2007-07-03 08:25:58 +0000953 failed, errored = len(result.failures), len(result.errors)
Fred Drake02538202001-03-21 18:09:46 +0000954 if failed:
Benjamin Peterson5254c042009-03-23 22:25:03 +0000955 infos.append("failures=%d" % failed)
Fred Drake02538202001-03-21 18:09:46 +0000956 if errored:
Benjamin Peterson5254c042009-03-23 22:25:03 +0000957 infos.append("errors=%d" % errored)
Fred Drake02538202001-03-21 18:09:46 +0000958 else:
Benjamin Peterson5254c042009-03-23 22:25:03 +0000959 self.stream.write("OK")
960 if skipped:
961 infos.append("skipped=%d" % skipped)
962 if expected_fails:
963 infos.append("expected failures=%d" % expected_fails)
964 if unexpected_successes:
965 infos.append("unexpected successes=%d" % unexpected_successes)
966 if infos:
967 self.stream.writeln(" (%s)" % (", ".join(infos),))
Fred Drake02538202001-03-21 18:09:46 +0000968 return result
Tim Petersa19a1682001-03-29 04:36:09 +0000969
Fred Drake02538202001-03-21 18:09:46 +0000970
Fred Drake02538202001-03-21 18:09:46 +0000971
972##############################################################################
973# Facilities for running tests from the command line
974##############################################################################
975
Benjamin Peterson1467ac82009-01-09 03:42:38 +0000976class TestProgram(object):
Fred Drake02538202001-03-21 18:09:46 +0000977 """A command-line program that runs a set of tests; this is primarily
978 for making test modules conveniently executable.
979 """
980 USAGE = """\
Steve Purcell17a781b2001-04-09 15:37:31 +0000981Usage: %(progName)s [options] [test] [...]
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000982
983Options:
984 -h, --help Show this message
985 -v, --verbose Verbose output
986 -q, --quiet Minimal output
Fred Drake02538202001-03-21 18:09:46 +0000987
988Examples:
989 %(progName)s - run default set of tests
990 %(progName)s MyTestSuite - run suite 'MyTestSuite'
Steve Purcell5ddd1a82001-03-22 08:45:36 +0000991 %(progName)s MyTestCase.testSomething - run MyTestCase.testSomething
992 %(progName)s MyTestCase - run all 'test*' test methods
Fred Drake02538202001-03-21 18:09:46 +0000993 in MyTestCase
994"""
995 def __init__(self, module='__main__', defaultTest=None,
Guido van Rossumd8faa362007-04-27 19:54:29 +0000996 argv=None, testRunner=TextTestRunner,
997 testLoader=defaultTestLoader):
Antoine Pitroue7bd8682009-01-09 19:29:16 +0000998 if isinstance(module, str):
Fred Drake02538202001-03-21 18:09:46 +0000999 self.module = __import__(module)
Steve Purcell7e743842003-09-22 11:08:12 +00001000 for part in module.split('.')[1:]:
Fred Drake02538202001-03-21 18:09:46 +00001001 self.module = getattr(self.module, part)
1002 else:
1003 self.module = module
1004 if argv is None:
1005 argv = sys.argv
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001006 self.verbosity = 1
Fred Drake02538202001-03-21 18:09:46 +00001007 self.defaultTest = defaultTest
1008 self.testRunner = testRunner
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001009 self.testLoader = testLoader
Fred Drake02538202001-03-21 18:09:46 +00001010 self.progName = os.path.basename(argv[0])
1011 self.parseArgs(argv)
Fred Drake02538202001-03-21 18:09:46 +00001012 self.runTests()
1013
1014 def usageExit(self, msg=None):
Guido van Rossumbe19ed72007-02-09 05:37:30 +00001015 if msg: print(msg)
1016 print(self.USAGE % self.__dict__)
Fred Drake02538202001-03-21 18:09:46 +00001017 sys.exit(2)
1018
1019 def parseArgs(self, argv):
1020 import getopt
Benjamin Peterson5254c042009-03-23 22:25:03 +00001021 long_opts = ['help','verbose','quiet']
Fred Drake02538202001-03-21 18:09:46 +00001022 try:
Benjamin Peterson5254c042009-03-23 22:25:03 +00001023 options, args = getopt.getopt(argv[1:], 'hHvq', long_opts)
Fred Drake02538202001-03-21 18:09:46 +00001024 for opt, value in options:
1025 if opt in ('-h','-H','--help'):
1026 self.usageExit()
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001027 if opt in ('-q','--quiet'):
1028 self.verbosity = 0
1029 if opt in ('-v','--verbose'):
1030 self.verbosity = 2
Fred Drake02538202001-03-21 18:09:46 +00001031 if len(args) == 0 and self.defaultTest is None:
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001032 self.test = self.testLoader.loadTestsFromModule(self.module)
1033 return
Fred Drake02538202001-03-21 18:09:46 +00001034 if len(args) > 0:
1035 self.testNames = args
1036 else:
1037 self.testNames = (self.defaultTest,)
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001038 self.createTests()
Guido van Rossumb940e112007-01-10 16:19:56 +00001039 except getopt.error as msg:
Fred Drake02538202001-03-21 18:09:46 +00001040 self.usageExit(msg)
1041
1042 def createTests(self):
Steve Purcell5ddd1a82001-03-22 08:45:36 +00001043 self.test = self.testLoader.loadTestsFromNames(self.testNames,
1044 self.module)
Fred Drake02538202001-03-21 18:09:46 +00001045
1046 def runTests(self):
Guido van Rossum13257902007-06-07 23:15:56 +00001047 if isinstance(self.testRunner, type):
Guido van Rossumd8faa362007-04-27 19:54:29 +00001048 try:
1049 testRunner = self.testRunner(verbosity=self.verbosity)
1050 except TypeError:
1051 # didn't accept the verbosity argument
1052 testRunner = self.testRunner()
1053 else:
1054 # it is assumed to be a TestRunner instance
1055 testRunner = self.testRunner
1056 result = testRunner.run(self.test)
Tim Petersa19a1682001-03-29 04:36:09 +00001057 sys.exit(not result.wasSuccessful())
Fred Drake02538202001-03-21 18:09:46 +00001058
1059main = TestProgram
1060
1061
1062##############################################################################
1063# Executing this module from the command line
1064##############################################################################
1065
1066if __name__ == "__main__":
1067 main(module=None)