functional_tests/doc_tests/test_doctest_fixtures/doctest_fixtures.rst

   1 Doctest Fixtures
   2 ----------------
   3
   4 Doctest files, like other tests, can be made more efficient or meaningful or
   5 at least easier to write by judicious use of fixtures. nose supports limited
   6 fixtures for use with doctest files.
   7
   8 Module-level fixtures
   9 =====================
  10
  11 Fixtures for a doctest file may define any or all of the following methods for
  12 module-level setup:
  13
  14 * setup
  15 * setup_module
  16 * setupModule
  17 * setUpModule
  18
  19 Each module-level setup function may optionally take a single argument, the
  20 fixtures module itself.
  21
  22 Example::
  23
  24   def setup_module(module):
  25       module.called[:] = []
  26
  27 Similarly, module-level teardown methods are available, which also optionally
  28 take the fixtures module as an argument:
  29
  30 * teardown
  31 * teardown_module
  32 * teardownModule
  33 * tearDownModule
  34
  35 Example::
  36
  37   def teardown_module(module):
  38       module.called[:] = []
  39       module.done = True
  40
  41 Module-level setup executes **before any tests are loaded** from the doctest
  42 file. This is the right place to raise :class:`nose.plugins.skip.SkipTest`,
  43 for example.
  44
  45 Test-level fixtures
  46 ===================
  47
  48 In addition to module-level fixtures, *test*-level fixtures are
  49 supported. Keep in mind that in the doctest lexicon, the *test* is the *entire
  50 doctest file* -- not each individual example within the file. So, like the
  51 module-level fixtures, test-level fixtures execute *once per file*. The
  52 differences are that:
  53
  54 - test-level fixtures execute **after** tests have been loaded, but **before**
  55   any tests have executed.
  56 - test-level fixtures receive the doctest :class:`doctest.DocFileCase` loaded
  57   from the file as their one *required* argument.
  58
  59 **setup_test(test)** is called before the test is run.
  60
  61 Example::
  62
  63   def setup_test(test):
  64       called.append(test)
  65       test.globs['count'] = len(called)
  66   setup_test.__test__ = False
  67
  68 **teardown_test(test)** is alled after the test, unless setup raised an
  69 uncaught exception. The argument is the :class:`doctest.DocFileCase` object,
  70 *not* a unittest.TestCase.
  71
  72 Example::
  73
  74   def teardown_test(test):
  75       pass
  76   teardown_test.__test__ = False
  77
  78 Bottom line: setup_test, teardown_test have access to the *doctest test*,
  79 while setup, setup_module, etc have access to the *fixture*
  80 module. setup_module runs before tests are loaded, setup_test after.
  81
  82 .. note ::
  83
  84    As in the examples, it's a good idea to tag your setup_test/teardown_test
  85    functions with ``__test__ = False`` to avoid them being collected as tests.
  86
  87 Lastly, the fixtures for a doctest file may supply a **globs(globs)**
  88 function. The dict returned by this function will be passed to the doctest
  89 runner as the globals available to the test. You can use this, for example, to
  90 easily inject a module's globals into a doctest that has been moved from the
  91 module to a separate file.
  92
  93 Example
  94 =======
  95
  96 This doctest has some simple fixtures:
  97
  98 .. include :: doctest_fixtures_fixtures.py
  99    :literal:
 100
 101 The ``globs`` defined in the fixtures make the variable ``something``
 102 available in all examples.
 103
 104     >>> something
 105     'Something?'
 106
 107 The ``count`` variable is injected by the test-level fixture.
 108
 109     >>> count
 110     1
 111
 112 .. warning ::
 113
 114   This whole file is one doctest test. setup_test doesn't do what you think!
 115   It exists to give you access to the test case and examples, but it runs
 116   *once*, before all of them, not before each.
 117
 118     >>> count
 119     1
 120
 121   Thus, ``count`` stays 1 throughout the test, no matter how many examples it
 122   includes.