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