1
# Copyright (c) 2009 Jonathan M. Lange. See LICENSE for details.
3
"""Individual test case execution."""
12
from testtools.testresult import ExtendedToOriginalDecorator
15
"""An object to run a test.
17
RunTest objects are used to implement the internal logic involved in
18
running a test. TestCase.__init__ stores _RunTest as the class of RunTest
19
to execute. Passing the runTest= parameter to TestCase.__init__ allows a
20
different RunTest class to be used to execute the test.
22
Subclassing or replacing RunTest can be useful to add functionality to the
23
way that tests are run in a given project.
25
:ivar case: The test case that is to be run.
26
:ivar result: The result object a case is reporting to.
27
:ivar handlers: A list of (ExceptionClass->handler code) for exceptions
28
that should be caught if raised from the user code. Exceptions that
29
are caught are checked against this list in first to last order.
30
There is a catchall of Exception at the end of the list, so to add
31
a new exception to the list, insert it at the front (which ensures that
32
it will be checked before any existing base classes in the list. If you
33
add multiple exceptions some of which are subclasses of each other, add
34
the most specific exceptions last (so they come before their parent
36
:ivar exception_caught: An object returned when _run_user catches an
40
def __init__(self, case, handlers=None):
41
"""Create a RunTest to run a case.
43
:param case: A testtools.TestCase test case object.
44
:param handlers: Exception handlers for this RunTest. These are stored
45
in self.handlers and can be modified later if needed.
48
self.handlers = handlers or []
49
self.exception_caught = object()
51
def run(self, result=None):
52
"""Run self.case reporting activity to result.
54
:param result: Optional testtools.TestResult to report activity to.
55
:return: The result object the test was run against.
58
actual_result = self.case.defaultTestResult()
59
actual_result.startTestRun()
61
actual_result = result
63
return self._run_one(actual_result)
66
actual_result.stopTestRun()
68
def _run_one(self, result):
69
"""Run one test reporting to result.
71
:param result: A testtools.TestResult to report activity to.
72
This result object is decorated with an ExtendedToOriginalDecorator
73
to ensure that the latest TestResult API can be used with
74
confidence by client code.
75
:return: The result object the test was run against.
77
return self._run_prepared_result(ExtendedToOriginalDecorator(result))
79
def _run_prepared_result(self, result):
80
"""Run one test reporting to result.
82
:param result: A testtools.TestResult to report activity to.
83
:return: The result object the test was run against.
85
result.startTest(self.case)
90
result.stopTest(self.case)
94
"""Run the user supplied test code."""
95
if self.exception_caught == self._run_user(self.case._run_setup,
97
# Don't run the test method if we failed getting here.
98
self.case._runCleanups(self.result)
100
# Run everything from here on in. If any of the methods raise an
101
# exception we'll have failed.
104
if self.exception_caught == self._run_user(
105
self.case._run_test_method, self.result):
109
if self.exception_caught == self._run_user(
110
self.case._run_teardown, self.result):
114
if not self._run_user(
115
self.case._runCleanups, self.result):
119
self.result.addSuccess(self.case,
120
details=self.case.getDetails())
122
def _run_user(self, fn, *args):
123
"""Run a user supplied function.
125
Exceptions are processed by self.handlers.
129
except KeyboardInterrupt:
132
# Note that bare exceptions are not caught, so raised strings will
133
# escape: but they are deprecated anyway.
134
exc_info = sys.exc_info()
136
for exc_class, handler in self.handlers:
137
self.case.onException(exc_info)
138
if isinstance(e, exc_class):
139
handler(self.case, self.result, e)
140
return self.exception_caught