lib/testtools/MANUAL

   1 ======
   2 Manual
   3 ======
   4
   5 Introduction
   6 ------------
   7
   8 This document provides overview of the features provided by testtools.  Refer
   9 to the API docs (i.e. docstrings) for full details on a particular feature.
  10
  11 Extensions to TestCase
  12 ----------------------
  13
  14 Controlling test execution
  15 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  16
  17 Testtools supports two ways to control how tests are executed. The simplest
  18 is to add a new exception to self.exception_handlers::
  19
  20     >>> self.exception_handlers.insert(-1, (ExceptionClass, handler)).
  21
  22 Having done this, if any of setUp, tearDown, or the test method raise
  23 ExceptionClass, handler will be called with the test case, test result and the
  24 raised exception.
  25
  26 Secondly, by overriding __init__ to pass in runTest=RunTestFactory the whole
  27 execution of the test can be altered. The default is testtools.runtest.RunTest
  28 and calls  case._run_setup, case._run_test_method and finally
  29 case._run_teardown. Other methods to control what RunTest is used may be
  30 added in future.
  31
  32
  33 TestCase.addCleanup
  34 ~~~~~~~~~~~~~~~~~~~
  35
  36 addCleanup is a robust way to arrange for a cleanup function to be called
  37 before tearDown.  This is a powerful and simple alternative to putting cleanup
  38 logic in a try/finally block or tearDown method.  e.g.::
  39
  40     def test_foo(self):
  41         foo.lock()
  42         self.addCleanup(foo.unlock)
  43         ...
  44
  45
  46 TestCase.addOnException
  47 ~~~~~~~~~~~~~~~~~~~~~~~
  48
  49 addOnException adds an exception handler that will be called from the test
  50 framework when it detects an exception from your test code. The handler is
  51 given the exc_info for the exception, and can use this opportunity to attach
  52 more data (via the addDetails API) and potentially other uses.
  53
  54
  55 TestCase.skip
  56 ~~~~~~~~~~~~~
  57
  58 ``skip`` is a simple way to have a test stop running and be reported as a
  59 skipped test, rather than a success/error/failure. This is an alternative to
  60 convoluted logic during test loading, permitting later and more localized
  61 decisions about the appropriateness of running a test. Many reasons exist to
  62 skip a test - for instance when a dependency is missing, or if the test is
  63 expensive and should not be run while on laptop battery power, or if the test
  64 is testing an incomplete feature (this is sometimes called a TODO). Using this
  65 feature when running your test suite with a TestResult object that is missing
  66 the ``addSkip`` method will result in the ``addError`` method being invoked
  67 instead.
  68
  69
  70 New assertion methods
  71 ~~~~~~~~~~~~~~~~~~~~~
  72
  73 testtools adds several assertion methods:
  74
  75  * assertIn
  76  * assertNotIn
  77  * assertIs
  78  * assertIsNot
  79  * assertIsInstance
  80  * assertThat
  81
  82
  83 Improved assertRaises
  84 ~~~~~~~~~~~~~~~~~~~~~
  85
  86 TestCase.assertRaises returns the caught exception.  This is useful for
  87 asserting more things about the exception than just the type::
  88
  89         error = self.assertRaises(UnauthorisedError, thing.frobnicate)
  90         self.assertEqual('bob', error.username)
  91         self.assertEqual('User bob cannot frobnicate', str(error))
  92
  93
  94 TestCase.assertThat
  95 ~~~~~~~~~~~~~~~~~~~
  96
  97 assertThat is a clean way to write complex assertions without tying them to
  98 the TestCase inheritance hierarchy (and thus making them easier to reuse).
  99
 100 assertThat takes an object to be matched, and a matcher, and fails if the
 101 matcher does not match the matchee.
 102
 103 See pydoc testtools.Matcher for the protocol that matchers need to implement.
 104
 105 testtools includes some matchers in testtools.matchers.
 106 python -c 'import testtools.matchers; print testtools.matchers.__all__' will
 107 list those matchers.
 108
 109 An example using the DocTestMatches matcher which uses doctests example
 110 matching logic::
 111
 112     def test_foo(self):
 113         self.assertThat([1,2,3,4], DocTestMatches('[1, 2, 3, 4]'))
 114
 115
 116 Creation methods
 117 ~~~~~~~~~~~~~~~~
 118
 119 testtools.TestCase implements creation methods called ``getUniqueString`` and
 120 ``getUniqueInteger``.  See pages 419-423 of *xUnit Test Patterns* by Meszaros
 121 for a detailed discussion of creation methods.
 122
 123
 124 Test renaming
 125 ~~~~~~~~~~~~~
 126
 127 ``testtools.clone_test_with_new_id`` is a function to copy a test case
 128 instance to one with a new name.  This is helpful for implementing test
 129 parameterization.
 130
 131
 132 Extensions to TestResult
 133 ------------------------
 134
 135 TestResult.addSkip
 136 ~~~~~~~~~~~~~~~~~~
 137
 138 This method is called on result objects when a test skips. The
 139 ``testtools.TestResult`` class records skips in its ``skip_reasons`` instance
 140 dict. The can be reported on in much the same way as succesful tests.
 141
 142
 143 TestResult.time
 144 ~~~~~~~~~~~~~~~
 145
 146 This method controls the time used by a TestResult, permitting accurate
 147 timing of test results gathered on different machines or in different threads.
 148 See pydoc testtools.TestResult.time for more details.
 149
 150
 151 ThreadsafeForwardingResult
 152 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 153
 154 A TestResult which forwards activity to another test result, but synchronises
 155 on a semaphore to ensure that all the activity for a single test arrives in a
 156 batch. This allows simple TestResults which do not expect concurrent test
 157 reporting to be fed the activity from multiple test threads, or processes.
 158
 159 Note that when you provide multiple errors for a single test, the target sees
 160 each error as a distinct complete test.
 161
 162
 163 TextTestResult
 164 ~~~~~~~~~~~~~~
 165
 166 A TestResult that provides a text UI very similar to the Python standard
 167 library UI. Key differences are that its supports the extended outcomes and
 168 details API, and is completely encapsulated into the result object, permitting
 169 it to be used without a 'TestRunner' object. Not all the Python 2.7 outcomes
 170 are displayed (yet). It is also a 'quiet' result with no dots or verbose mode.
 171 These limitations will be corrected soon.
 172
 173
 174 Test Doubles
 175 ~~~~~~~~~~~~
 176
 177 In testtools.testresult.doubles there are three test doubles that testtools
 178 uses for its own testing: Python26TestResult, Python27TestResult,
 179 ExtendedTestResult. These TestResult objects implement a single variation of
 180 the TestResult API each, and log activity to a list self._events. These are
 181 made available for the convenience of people writing their own extensions.
 182
 183
 184 startTestRun and stopTestRun
 185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 186
 187 Python 2.7 added hooks 'startTestRun' and 'stopTestRun' which are called
 188 before and after the entire test run. 'stopTestRun' is particularly useful for
 189 test results that wish to produce summary output.
 190
 191 testtools.TestResult provides empty startTestRun and stopTestRun methods, and
 192 the default testtools runner will call these methods appropriately.
 193
 194
 195 Extensions to TestSuite
 196 -----------------------
 197
 198 ConcurrentTestSuite
 199 ~~~~~~~~~~~~~~~~~~~
 200
 201 A TestSuite for parallel testing. This is used in conjuction with a helper that
 202 runs a single suite in some parallel fashion (for instance, forking, handing
 203 off to a subprocess, to a compute cloud, or simple threads).
 204 ConcurrentTestSuite uses the helper to get a number of separate runnable
 205 objects with a run(result), runs them all in threads using the
 206 ThreadsafeForwardingResult to coalesce their activity.
 207
 208
 209 Running tests
 210 -------------
 211
 212 Testtools provides a convenient way to run a test suite using the testtools
 213 result object: python -m testtools.run testspec [testspec...].