doc/plugins.rst

   1 Extending and customizing nose with plugins
   2 ===========================================
   3
   4 nose has plugin hooks for loading, running, watching and reporting on tests and
   5 test runs. If you don't like the default collection scheme, or it doesn't suit
   6 the layout of your project, or you need reports in a format different from the
   7 unittest standard, or you need to collect some additional information about
   8 tests (like code coverage or profiling data), you can write a plugin to do so.
   9 See the section on `writing plugins`_ for more.
  10
  11 nose also comes with a number of built-in plugins, such as:
  12
  13 * Output capture
  14
  15   Unless called with the ``-s`` (``--nocapture``) switch, nose will capture
  16   stdout during each test run, and print the captured output only for tests
  17   that fail or have errors. The captured output is printed immediately
  18   following the error or failure output for the test. (Note that output in
  19   teardown methods is captured, but can't be output with failing tests, because
  20   teardown has not yet run at the time of the failure.)
  21
  22 * Assert introspection
  23
  24   When run with the ``-d`` (``--detailed-errors``) switch, nose will try to
  25   output additional information about the assert expression that failed with
  26   each failing test. Currently, this means that names in the assert expression
  27   will be expanded into any values found for them in the locals or globals in
  28   the frame in which the expression executed.
  29
  30   In other words, if you have a test like::
  31
  32     def test_integers():
  33         a = 2
  34         assert a == 4, "assert 2 is 4"
  35
  36   You will get output like::
  37
  38       File "/path/to/file.py", line XX, in test_integers:
  39            assert a == 4, "assert 2 is 4"
  40       AssertionError: assert 2 is 4
  41         >>  assert 2 == 4, "assert 2 is 4"
  42
  43   Please note that dotted names are not expanded, and callables are not called
  44   in the expansion.
  45
  46 See below for the rest of the built-in plugins.
  47
  48 Using Builtin plugins
  49 ---------------------
  50
  51 See :doc:`plugins/builtin`
  52
  53 Writing plugins
  54 ---------------
  55
  56 .. toctree ::
  57    :maxdepth: 2
  58
  59    plugins/writing
  60    plugins/interface
  61    plugins/errorclasses
  62    plugins/documenting
  63
  64 Testing plugins
  65 ---------------
  66
  67 .. toctree ::
  68    :maxdepth: 2
  69
  70    plugins/testing