1 # Copyright (c) 2009-2010 Jonathan M. Lange. See LICENSE for details.
3 """Individual test case execution."""
12 from testtools.testresult import ExtendedToOriginalDecorator
15 class MultipleExceptions(Exception):
16 """Represents many exceptions raised from some operation.
18 :ivar args: The sys.exc_info() tuples for each exception.
22 class RunTest(object):
23 """An object to run a test.
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.
30 Subclassing or replacing RunTest can be useful to add functionality to the
31 way that tests are run in a given project.
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
46 :ivar _exceptions: A list of caught exceptions, used to do the single
47 reporting of error/failure/skip etc.
50 def __init__(self, case, handlers=None):
51 """Create a RunTest to run a case.
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.
58 self.handlers = handlers or []
59 self.exception_caught = object()
62 def run(self, result=None):
63 """Run self.case reporting activity to result.
65 :param result: Optional testtools.TestResult to report activity to.
66 :return: The result object the test was run against.
69 actual_result = self.case.defaultTestResult()
70 actual_result.startTestRun()
72 actual_result = result
74 return self._run_one(actual_result)
77 actual_result.stopTestRun()
79 def _run_one(self, result):
80 """Run one test reporting to result.
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.
88 return self._run_prepared_result(ExtendedToOriginalDecorator(result))
90 def _run_prepared_result(self, result):
91 """Run one test reporting to result.
93 :param result: A testtools.TestResult to report activity to.
94 :return: The result object the test was run against.
96 result.startTest(self.case)
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)
110 result.stopTest(self.case)
114 """Run the user supplied test code."""
115 if self.exception_caught == self._run_user(self.case._run_setup,
117 # Don't run the test method if we failed getting here.
118 self._run_cleanups(self.result)
120 # Run everything from here on in. If any of the methods raise an
121 # exception we'll have failed.
124 if self.exception_caught == self._run_user(
125 self.case._run_test_method, self.result):
129 if self.exception_caught == self._run_user(
130 self.case._run_teardown, self.result):
134 if self.exception_caught == self._run_user(
135 self._run_cleanups, self.result):
139 self.result.addSuccess(self.case,
140 details=self.case.getDetails())
142 def _run_cleanups(self, result):
143 """Run the cleanups that have been added with addCleanup.
145 See the docstring for addCleanup for more information.
147 :return: None if all cleanups ran without error,
148 `self.exception_caught` if there was an error.
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:
158 return self.exception_caught
160 def _run_user(self, fn, *args, **kwargs):
161 """Run a user supplied function.
163 Exceptions are processed by `_got_user_exception`.
165 :return: Either whatever 'fn' returns or `self.exception_caught` if
166 'fn' raised an exception.
169 return fn(*args, **kwargs)
170 except KeyboardInterrupt:
173 return self._got_user_exception(sys.exc_info())
175 def _got_user_exception(self, exc_info, tb_label='traceback'):
176 """Called when user code raises an exception.
178 If 'exc_info' is a `MultipleExceptions`, then we recurse into it
179 unpacking the errors that it's made up from.
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 `self.handlers`, otherwise raise the error.
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
193 self.case.onException(exc_info, tb_label=tb_label)
196 for exc_class, handler in self.handlers:
197 if isinstance(e, exc_class):
198 self._exceptions.append(e)
199 return self.exception_caught