s4-python: Install external included packages only if they're not present on the...
[nivanova/samba-autobuild/.git] / lib / testtools / testcase.py
1 # Copyright (c) 2008, 2009 Jonathan M. Lange. See LICENSE for details.
2
3 """Test case related stuff."""
4
5 __metaclass__ = type
6 __all__ = [
7     'clone_test_with_new_id',
8     'TestCase',
9     'skip',
10     'skipIf',
11     'skipUnless',
12     ]
13
14 import copy
15 try:
16     from functools import wraps
17 except ImportError:
18     wraps = None
19 import itertools
20 import sys
21 import types
22 import unittest
23
24 from testtools import content
25 from testtools.runtest import RunTest
26 from testtools.testresult import TestResult
27 from testtools.utils import advance_iterator
28
29
30 try:
31     # Try to use the python2.7 SkipTest exception for signalling skips.
32     from unittest.case import SkipTest as TestSkipped
33 except ImportError:
34     class TestSkipped(Exception):
35         """Raised within TestCase.run() when a test is skipped."""
36
37
38 try:
39     # Try to use the same exceptions python 2.7 does.
40     from unittest.case import _ExpectedFailure, _UnexpectedSuccess
41 except ImportError:
42     # Oops, not available, make our own.
43     class _UnexpectedSuccess(Exception):
44         """An unexpected success was raised.
45
46         Note that this exception is private plumbing in testtools' testcase
47         module.
48         """
49
50     class _ExpectedFailure(Exception):
51         """An expected failure occured.
52
53         Note that this exception is private plumbing in testtools' testcase
54         module.
55         """
56
57
58 class TestCase(unittest.TestCase):
59     """Extensions to the basic TestCase.
60
61     :ivar exception_handlers: Exceptions to catch from setUp, runTest and
62         tearDown. This list is able to be modified at any time and consists of
63         (exception_class, handler(case, result, exception_value)) pairs.
64     """
65
66     skipException = TestSkipped
67
68     def __init__(self, *args, **kwargs):
69         """Construct a TestCase.
70
71         :param testMethod: The name of the method to run.
72         :param runTest: Optional class to use to execute the test. If not
73             supplied testtools.runtest.RunTest is used. The instance to be
74             used is created when run() is invoked, so will be fresh each time.
75         """
76         unittest.TestCase.__init__(self, *args, **kwargs)
77         self._cleanups = []
78         self._unique_id_gen = itertools.count(1)
79         self.__setup_called = False
80         self.__teardown_called = False
81         self.__details = {}
82         self.__RunTest = kwargs.get('runTest', RunTest)
83         self.__exception_handlers = []
84         self.exception_handlers = [
85             (self.skipException, self._report_skip),
86             (self.failureException, self._report_failure),
87             (_ExpectedFailure, self._report_expected_failure),
88             (_UnexpectedSuccess, self._report_unexpected_success),
89             (Exception, self._report_error),
90             ]
91
92     def __eq__(self, other):
93         eq = getattr(unittest.TestCase, '__eq__', None)
94         if eq is not None and not unittest.TestCase.__eq__(self, other):
95             return False
96         return self.__dict__ == other.__dict__
97
98     def __repr__(self):
99         # We add id to the repr because it makes testing testtools easier.
100         return "<%s id=0x%0x>" % (self.id(), id(self))
101
102     def addDetail(self, name, content_object):
103         """Add a detail to be reported with this test's outcome.
104
105         For more details see pydoc testtools.TestResult.
106
107         :param name: The name to give this detail.
108         :param content_object: The content object for this detail. See
109             testtools.content for more detail.
110         """
111         self.__details[name] = content_object
112
113     def getDetails(self):
114         """Get the details dict that will be reported with this test's outcome.
115
116         For more details see pydoc testtools.TestResult.
117         """
118         return self.__details
119
120     def shortDescription(self):
121         return self.id()
122
123     def skip(self, reason):
124         """Cause this test to be skipped.
125
126         This raises self.skipException(reason). skipException is raised
127         to permit a skip to be triggered at any point (during setUp or the
128         testMethod itself). The run() method catches skipException and
129         translates that into a call to the result objects addSkip method.
130
131         :param reason: The reason why the test is being skipped. This must
132             support being cast into a unicode string for reporting.
133         """
134         raise self.skipException(reason)
135
136     def _formatTypes(self, classOrIterable):
137         """Format a class or a bunch of classes for display in an error."""
138         className = getattr(classOrIterable, '__name__', None)
139         if className is None:
140             className = ', '.join(klass.__name__ for klass in classOrIterable)
141         return className
142
143     def _runCleanups(self, result):
144         """Run the cleanups that have been added with addCleanup.
145
146         See the docstring for addCleanup for more information.
147
148         Returns True if all cleanups ran without error, False otherwise.
149         """
150         ok = True
151         while self._cleanups:
152             function, arguments, keywordArguments = self._cleanups.pop()
153             try:
154                 function(*arguments, **keywordArguments)
155             except KeyboardInterrupt:
156                 raise
157             except:
158                 self._report_error(self, result, None)
159                 ok = False
160         return ok
161
162     def addCleanup(self, function, *arguments, **keywordArguments):
163         """Add a cleanup function to be called after tearDown.
164
165         Functions added with addCleanup will be called in reverse order of
166         adding after the test method and before tearDown.
167
168         If a function added with addCleanup raises an exception, the error
169         will be recorded as a test error, and the next cleanup will then be
170         run.
171
172         Cleanup functions are always called before a test finishes running,
173         even if setUp is aborted by an exception.
174         """
175         self._cleanups.append((function, arguments, keywordArguments))
176
177     def addOnException(self, handler):
178         """Add a handler to be called when an exception occurs in test code.
179
180         This handler cannot affect what result methods are called, and is
181         called before any outcome is called on the result object. An example
182         use for it is to add some diagnostic state to the test details dict
183         which is expensive to calculate and not interesting for reporting in
184         the success case.
185
186         Handlers are called before the outcome (such as addFailure) that
187         the exception has caused.
188
189         Handlers are called in first-added, first-called order, and if they
190         raise an exception, that will propogate out of the test running
191         machinery, halting test processing. As a result, do not call code that
192         may unreasonably fail.
193         """
194         self.__exception_handlers.append(handler)
195
196     def _add_reason(self, reason):
197         self.addDetail('reason', content.Content(
198             content.ContentType('text', 'plain'),
199             lambda: [reason.encode('utf8')]))
200
201     def assertIn(self, needle, haystack):
202         """Assert that needle is in haystack."""
203         self.assertTrue(
204             needle in haystack, '%r not in %r' % (needle, haystack))
205
206     def assertIs(self, expected, observed, message=''):
207         """Assert that 'expected' is 'observed'.
208
209         :param expected: The expected value.
210         :param observed: The observed value.
211         :param message: An optional message describing the error.
212         """
213         if message:
214             message = ': ' + message
215         self.assertTrue(
216             expected is observed,
217             '%r is not %r%s' % (expected, observed, message))
218
219     def assertIsNot(self, expected, observed, message=''):
220         """Assert that 'expected' is not 'observed'."""
221         if message:
222             message = ': ' + message
223         self.assertTrue(
224             expected is not observed,
225             '%r is %r%s' % (expected, observed, message))
226
227     def assertNotIn(self, needle, haystack):
228         """Assert that needle is not in haystack."""
229         self.assertTrue(
230             needle not in haystack, '%r in %r' % (needle, haystack))
231
232     def assertIsInstance(self, obj, klass):
233         self.assertTrue(
234             isinstance(obj, klass),
235             '%r is not an instance of %s' % (obj, self._formatTypes(klass)))
236
237     def assertRaises(self, excClass, callableObj, *args, **kwargs):
238         """Fail unless an exception of class excClass is thrown
239            by callableObj when invoked with arguments args and keyword
240            arguments kwargs. If a different type of exception is
241            thrown, it will not be caught, and the test case will be
242            deemed to have suffered an error, exactly as for an
243            unexpected exception.
244         """
245         try:
246             ret = callableObj(*args, **kwargs)
247         except excClass:
248             return sys.exc_info()[1]
249         else:
250             excName = self._formatTypes(excClass)
251             self.fail("%s not raised, %r returned instead." % (excName, ret))
252     failUnlessRaises = assertRaises
253
254     def assertThat(self, matchee, matcher):
255         """Assert that matchee is matched by matcher.
256
257         :param matchee: An object to match with matcher.
258         :param matcher: An object meeting the testtools.Matcher protocol.
259         :raises self.failureException: When matcher does not match thing.
260         """
261         mismatch = matcher.match(matchee)
262         if not mismatch:
263             return
264         self.fail('Match failed. Matchee: "%s"\nMatcher: %s\nDifference: %s\n'
265             % (matchee, matcher, mismatch.describe()))
266
267     def defaultTestResult(self):
268         return TestResult()
269
270     def expectFailure(self, reason, predicate, *args, **kwargs):
271         """Check that a test fails in a particular way.
272
273         If the test fails in the expected way, a KnownFailure is caused. If it
274         succeeds an UnexpectedSuccess is caused.
275
276         The expected use of expectFailure is as a barrier at the point in a
277         test where the test would fail. For example:
278         >>> def test_foo(self):
279         >>>    self.expectFailure("1 should be 0", self.assertNotEqual, 1, 0)
280         >>>    self.assertEqual(1, 0)
281
282         If in the future 1 were to equal 0, the expectFailure call can simply
283         be removed. This separation preserves the original intent of the test
284         while it is in the expectFailure mode.
285         """
286         self._add_reason(reason)
287         try:
288             predicate(*args, **kwargs)
289         except self.failureException:
290             exc_info = sys.exc_info()
291             self.addDetail('traceback',
292                 content.TracebackContent(exc_info, self))
293             raise _ExpectedFailure(exc_info)
294         else:
295             raise _UnexpectedSuccess(reason)
296
297     def getUniqueInteger(self):
298         """Get an integer unique to this test.
299
300         Returns an integer that is guaranteed to be unique to this instance.
301         Use this when you need an arbitrary integer in your test, or as a
302         helper for custom anonymous factory methods.
303         """
304         return advance_iterator(self._unique_id_gen)
305
306     def getUniqueString(self, prefix=None):
307         """Get a string unique to this test.
308
309         Returns a string that is guaranteed to be unique to this instance. Use
310         this when you need an arbitrary string in your test, or as a helper
311         for custom anonymous factory methods.
312
313         :param prefix: The prefix of the string. If not provided, defaults
314             to the id of the tests.
315         :return: A bytestring of '<prefix>-<unique_int>'.
316         """
317         if prefix is None:
318             prefix = self.id()
319         return '%s-%d' % (prefix, self.getUniqueInteger())
320
321     def onException(self, exc_info):
322         """Called when an exception propogates from test code.
323
324         :seealso addOnException:
325         """
326         for handler in self.__exception_handlers:
327             handler(exc_info)
328
329     @staticmethod
330     def _report_error(self, result, err):
331         self._report_traceback()
332         result.addError(self, details=self.getDetails())
333
334     @staticmethod
335     def _report_expected_failure(self, result, err):
336         result.addExpectedFailure(self, details=self.getDetails())
337
338     @staticmethod
339     def _report_failure(self, result, err):
340         self._report_traceback()
341         result.addFailure(self, details=self.getDetails())
342
343     @staticmethod
344     def _report_skip(self, result, err):
345         if err.args:
346             reason = err.args[0]
347         else:
348             reason = "no reason given."
349         self._add_reason(reason)
350         result.addSkip(self, details=self.getDetails())
351
352     def _report_traceback(self):
353         self.addDetail('traceback',
354             content.TracebackContent(sys.exc_info(), self))
355
356     @staticmethod
357     def _report_unexpected_success(self, result, err):
358         result.addUnexpectedSuccess(self, details=self.getDetails())
359
360     def run(self, result=None):
361         return self.__RunTest(self, self.exception_handlers).run(result)
362
363     def _run_setup(self, result):
364         """Run the setUp function for this test.
365
366         :param result: A testtools.TestResult to report activity to.
367         :raises ValueError: If the base class setUp is not called, a
368             ValueError is raised.
369         """
370         self.setUp()
371         if not self.__setup_called:
372             raise ValueError(
373                 "TestCase.setUp was not called. Have you upcalled all the "
374                 "way up the hierarchy from your setUp? e.g. Call "
375                 "super(%s, self).setUp() from your setUp()."
376                 % self.__class__.__name__)
377
378     def _run_teardown(self, result):
379         """Run the tearDown function for this test.
380
381         :param result: A testtools.TestResult to report activity to.
382         :raises ValueError: If the base class tearDown is not called, a
383             ValueError is raised.
384         """
385         self.tearDown()
386         if not self.__teardown_called:
387             raise ValueError(
388                 "TestCase.tearDown was not called. Have you upcalled all the "
389                 "way up the hierarchy from your tearDown? e.g. Call "
390                 "super(%s, self).tearDown() from your tearDown()."
391                 % self.__class__.__name__)
392
393     def _run_test_method(self, result):
394         """Run the test method for this test.
395
396         :param result: A testtools.TestResult to report activity to.
397         :return: None.
398         """
399         absent_attr = object()
400         # Python 2.5+
401         method_name = getattr(self, '_testMethodName', absent_attr)
402         if method_name is absent_attr:
403             # Python 2.4
404             method_name = getattr(self, '_TestCase__testMethodName')
405         testMethod = getattr(self, method_name)
406         testMethod()
407
408     def setUp(self):
409         unittest.TestCase.setUp(self)
410         self.__setup_called = True
411
412     def tearDown(self):
413         unittest.TestCase.tearDown(self)
414         self.__teardown_called = True
415
416
417 # Python 2.4 did not know how to copy functions.
418 if types.FunctionType not in copy._copy_dispatch:
419     copy._copy_dispatch[types.FunctionType] = copy._copy_immutable
420
421
422
423 def clone_test_with_new_id(test, new_id):
424     """Copy a TestCase, and give the copied test a new id.
425     
426     This is only expected to be used on tests that have been constructed but
427     not executed.
428     """
429     newTest = copy.copy(test)
430     newTest.id = lambda: new_id
431     return newTest
432
433
434 def skip(reason):
435     """A decorator to skip unit tests.
436
437     This is just syntactic sugar so users don't have to change any of their
438     unit tests in order to migrate to python 2.7, which provides the
439     @unittest.skip decorator.
440     """
441     def decorator(test_item):
442         if wraps is not None:
443             @wraps(test_item)
444             def skip_wrapper(*args, **kwargs):
445                 raise TestCase.skipException(reason)
446         else:
447             def skip_wrapper(test_item):
448                 test_item.skip(reason)
449         return skip_wrapper
450     return decorator
451
452
453 def skipIf(condition, reason):
454     """Skip a test if the condition is true."""
455     if condition:
456         return skip(reason)
457     def _id(obj):
458         return obj
459     return _id
460
461
462 def skipUnless(condition, reason):
463     """Skip a test unless the condition is true."""
464     if not condition:
465         return skip(reason)
466     def _id(obj):
467         return obj
468     return _id