s4-python: Install external included packages only if they're not present on the...
[nivanova/samba-autobuild/.git] / lib / testtools / runtest.py
1 # Copyright (c) 2009 Jonathan M. Lange. See LICENSE for details.
2
3 """Individual test case execution."""
4
5 __metaclass__ = type
6 __all__ = [
7     'RunTest',
8     ]
9
10 import sys
11
12 from testtools.testresult import ExtendedToOriginalDecorator
13
14
15 class RunTest:
16     """An object to run a test.
17
18     RunTest objects are used to implement the internal logic involved in
19     running a test. TestCase.__init__ stores _RunTest as the class of RunTest
20     to execute.  Passing the runTest= parameter to TestCase.__init__ allows a
21     different RunTest class to be used to execute the test.
22
23     Subclassing or replacing RunTest can be useful to add functionality to the
24     way that tests are run in a given project.
25
26     :ivar case: The test case that is to be run.
27     :ivar result: The result object a case is reporting to.
28     :ivar handlers: A list of (ExceptionClass->handler code) for exceptions
29         that should be caught if raised from the user code. Exceptions that
30         are caught are checked against this list in first to last order.
31         There is a catchall of Exception at the end of the list, so to add
32         a new exception to the list, insert it at the front (which ensures that
33         it will be checked before any existing base classes in the list. If you
34         add multiple exceptions some of which are subclasses of each other, add
35         the most specific exceptions last (so they come before their parent
36         classes in the list).
37     :ivar exception_caught: An object returned when _run_user catches an
38         exception.
39     """
40
41     def __init__(self, case, handlers=None):
42         """Create a RunTest to run a case.
43
44         :param case: A testtools.TestCase test case object.
45         :param handlers: Exception handlers for this RunTest. These are stored
46             in self.handlers and can be modified later if needed.
47         """
48         self.case = case
49         self.handlers = handlers or []
50         self.exception_caught = object()
51
52     def run(self, result=None):
53         """Run self.case reporting activity to result.
54
55         :param result: Optional testtools.TestResult to report activity to.
56         :return: The result object the test was run against.
57         """
58         if result is None:
59             actual_result = self.case.defaultTestResult()
60             actual_result.startTestRun()
61         else:
62             actual_result = result
63         try:
64             return self._run_one(actual_result)
65         finally:
66             if result is None:
67                 actual_result.stopTestRun()
68
69     def _run_one(self, result):
70         """Run one test reporting to result.
71
72         :param result: A testtools.TestResult to report activity to.
73             This result object is decorated with an ExtendedToOriginalDecorator
74             to ensure that the latest TestResult API can be used with
75             confidence by client code.
76         :return: The result object the test was run against.
77         """
78         return self._run_prepared_result(ExtendedToOriginalDecorator(result))
79
80     def _run_prepared_result(self, result):
81         """Run one test reporting to result.
82
83         :param result: A testtools.TestResult to report activity to.
84         :return: The result object the test was run against.
85         """
86         result.startTest(self.case)
87         self.result = result
88         try:
89             self._run_core()
90         finally:
91             result.stopTest(self.case)
92         return result
93
94     def _run_core(self):
95         """Run the user supplied test code."""
96         if self.exception_caught == self._run_user(self.case._run_setup,
97             self.result):
98             # Don't run the test method if we failed getting here.
99             self.case._runCleanups(self.result)
100             return
101         # Run everything from here on in. If any of the methods raise an
102         # exception we'll have failed.
103         failed = False
104         try:
105             if self.exception_caught == self._run_user(
106                 self.case._run_test_method, self.result):
107                 failed = True
108         finally:
109             try:
110                 if self.exception_caught == self._run_user(
111                     self.case._run_teardown, self.result):
112                     failed = True
113             finally:
114                 try:
115                     if not self._run_user(
116                         self.case._runCleanups, self.result):
117                         failed = True
118                 finally:
119                     if not failed:
120                         self.result.addSuccess(self.case,
121                             details=self.case.getDetails())
122
123     def _run_user(self, fn, *args):
124         """Run a user supplied function.
125
126         Exceptions are processed by self.handlers.
127         """
128         try:
129             return fn(*args)
130         except KeyboardInterrupt:
131             raise
132         except Exception:
133             # Note that bare exceptions are not caught, so raised strings will
134             # escape: but they are deprecated anyway.
135             exc_info = sys.exc_info()
136             e = exc_info[1]
137             for exc_class, handler in self.handlers:
138                 self.case.onException(exc_info)
139                 if isinstance(e, exc_class):
140                     handler(self.case, self.result, e)
141                     return self.exception_caught
142             raise e