1# Copyright (c) 2009-2010 testtools developers. See LICENSE for details.
2
3"""Individual test case execution."""
4
5__all__ = [
6    'MultipleExceptions',
7    'RunTest',
8    ]
9
10import sys
11
12from testtools.testresult import ExtendedToOriginalDecorator
13
14
15class MultipleExceptions(Exception):
16    """Represents many exceptions raised from some operation.
17
18    :ivar args: The sys.exc_info() tuples for each exception.
19    """
20
21
22class RunTest(object):
23    """An object to run a test.
24
25    RunTest objects are used to implement the internal logic involved in
26    running a test. TestCase.__init__ stores _RunTest as the class of RunTest
27    to execute.  Passing the runTest= parameter to TestCase.__init__ allows a
28    different RunTest class to be used to execute the test.
29
30    Subclassing or replacing RunTest can be useful to add functionality to the
31    way that tests are run in a given project.
32
33    :ivar case: The test case that is to be run.
34    :ivar result: The result object a case is reporting to.
35    :ivar handlers: A list of (ExceptionClass, handler_function) for
36        exceptions that should be caught if raised from the user
37        code. Exceptions that are caught are checked against this list in
38        first to last order.  There is a catch-all of 'Exception' at the end
39        of the list, so to add a new exception to the list, insert it at the
40        front (which ensures that it will be checked before any existing base
41        classes in the list. If you add multiple exceptions some of which are
42        subclasses of each other, add the most specific exceptions last (so
43        they come before their parent classes in the list).
44    :ivar exception_caught: An object returned when _run_user catches an
45        exception.
46    :ivar _exceptions: A list of caught exceptions, used to do the single
47        reporting of error/failure/skip etc.
48    """
49
50    def __init__(self, case, handlers=None):
51        """Create a RunTest to run a case.
52
53        :param case: A testtools.TestCase test case object.
54        :param handlers: Exception handlers for this RunTest. These are stored
55            in self.handlers and can be modified later if needed.
56        """
57        self.case = case
58        self.handlers = handlers or []
59        self.exception_caught = object()
60        self._exceptions = []
61
62    def run(self, result=None):
63        """Run self.case reporting activity to result.
64
65        :param result: Optional testtools.TestResult to report activity to.
66        :return: The result object the test was run against.
67        """
68        if result is None:
69            actual_result = self.case.defaultTestResult()
70            actual_result.startTestRun()
71        else:
72            actual_result = result
73        try:
74            return self._run_one(actual_result)
75        finally:
76            if result is None:
77                actual_result.stopTestRun()
78
79    def _run_one(self, result):
80        """Run one test reporting to result.
81
82        :param result: A testtools.TestResult to report activity to.
83            This result object is decorated with an ExtendedToOriginalDecorator
84            to ensure that the latest TestResult API can be used with
85            confidence by client code.
86        :return: The result object the test was run against.
87        """
88        return self._run_prepared_result(ExtendedToOriginalDecorator(result))
89
90    def _run_prepared_result(self, result):
91        """Run one test reporting to result.
92
93        :param result: A testtools.TestResult to report activity to.
94        :return: The result object the test was run against.
95        """
96        result.startTest(self.case)
97        self.result = result
98        try:
99            self._exceptions = []
100            self._run_core()
101            if self._exceptions:
102                # One or more caught exceptions, now trigger the test's
103                # reporting method for just one.
104                e = self._exceptions.pop()
105                for exc_class, handler in self.handlers:
106                    if isinstance(e, exc_class):
107                        handler(self.case, self.result, e)
108                        break
109        finally:
110            result.stopTest(self.case)
111        return result
112
113    def _run_core(self):
114        """Run the user supplied test code."""
115        if self.exception_caught == self._run_user(self.case._run_setup,
116            self.result):
117            # Don't run the test method if we failed getting here.
118            self._run_cleanups(self.result)
119            return
120        # Run everything from here on in. If any of the methods raise an
121        # exception we'll have failed.
122        failed = False
123        try:
124            if self.exception_caught == self._run_user(
125                self.case._run_test_method, self.result):
126                failed = True
127        finally:
128            try:
129                if self.exception_caught == self._run_user(
130                    self.case._run_teardown, self.result):
131                    failed = True
132            finally:
133                try:
134                    if self.exception_caught == self._run_user(
135                        self._run_cleanups, self.result):
136                        failed = True
137                finally:
138                    if not failed:
139                        self.result.addSuccess(self.case,
140                            details=self.case.getDetails())
141
142    def _run_cleanups(self, result):
143        """Run the cleanups that have been added with addCleanup.
144
145        See the docstring for addCleanup for more information.
146
147        :return: None if all cleanups ran without error,
148            ``exception_caught`` if there was an error.
149        """
150        failing = False
151        while self.case._cleanups:
152            function, arguments, keywordArguments = self.case._cleanups.pop()
153            got_exception = self._run_user(
154                function, *arguments, **keywordArguments)
155            if got_exception == self.exception_caught:
156                failing = True
157        if failing:
158            return self.exception_caught
159
160    def _run_user(self, fn, *args, **kwargs):
161        """Run a user supplied function.
162
163        Exceptions are processed by `_got_user_exception`.
164
165        :return: Either whatever 'fn' returns or ``exception_caught`` if
166            'fn' raised an exception.
167        """
168        try:
169            return fn(*args, **kwargs)
170        except KeyboardInterrupt:
171            raise
172        except:
173            return self._got_user_exception(sys.exc_info())
174
175    def _got_user_exception(self, exc_info, tb_label='traceback'):
176        """Called when user code raises an exception.
177
178        If 'exc_info' is a `MultipleExceptions`, then we recurse into it
179        unpacking the errors that it's made up from.
180
181        :param exc_info: A sys.exc_info() tuple for the user error.
182        :param tb_label: An optional string label for the error.  If
183            not specified, will default to 'traceback'.
184        :return: 'exception_caught' if we catch one of the exceptions that
185            have handlers in 'handlers', otherwise raise the error.
186        """
187        if exc_info[0] is MultipleExceptions:
188            for sub_exc_info in exc_info[1].args:
189                self._got_user_exception(sub_exc_info, tb_label)
190            return self.exception_caught
191        try:
192            e = exc_info[1]
193            self.case.onException(exc_info, tb_label=tb_label)
194        finally:
195            del exc_info
196        for exc_class, handler in self.handlers:
197            if isinstance(e, exc_class):
198                self._exceptions.append(e)
199                return self.exception_caught
200        raise e
201