lib/testtools/testtools/runtest.py

   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
  10 import sys
  11
  12 from testtools.testresult import ExtendedToOriginalDecorator
  13
  14
  15 class 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
  22 class 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
 202
 203 # Signal that this is part of the testing framework, and that code from this
 204 # should not normally appear in tracebacks.
 205 __unittest = True