nose/plugins/__init__.py

   1 """
   2 Writing Plugins
   3 ---------------
   4
   5 nose supports plugins for test collection, selection, observation and
   6 reporting. There are two basic rules for plugins:
   7
   8 * Plugin classes should subclass :class:`nose.plugins.Plugin`.
   9
  10 * Plugins may implement any of the methods described in the class
  11   :doc:`IPluginInterface <interface>` in nose.plugins.base. Please note that
  12   this class is for documentary purposes only; plugins may not subclass
  13   IPluginInterface.
  14
  15 Hello World
  16 ===========
  17
  18 Here's a basic plugin.  It doesn't do much so read on for more ideas or dive
  19 into the :doc:`IPluginInterface <interface>` to see all available hooks.
  20
  21 .. code-block:: python
  22
  23     import logging
  24     import os
  25
  26     from nose.plugins import Plugin
  27
  28     log = logging.getLogger('nose.plugins.helloworld')
  29
  30     class HelloWorld(Plugin):
  31         name = 'helloworld'
  32
  33         def options(self, parser, env=os.environ):
  34             super(HelloWorld, self).options(parser, env=env)
  35
  36         def configure(self, options, conf):
  37             super(HelloWorld, self).configure(options, conf)
  38             if not self.enabled:
  39                 return
  40
  41         def finalize(self, result):
  42             log.info('Hello pluginized world!')
  43
  44 Registering
  45 ===========
  46
  47 .. Note::
  48   Important note: the following applies only to the default
  49   plugin manager. Other plugin managers may use different means to
  50   locate and load plugins.
  51
  52 For nose to find a plugin, it must be part of a package that uses
  53 setuptools_, and the plugin must be included in the entry points defined
  54 in the setup.py for the package:
  55
  56 .. code-block:: python
  57
  58     setup(name='Some plugin',
  59         # ...
  60         entry_points = {
  61             'nose.plugins.0.10': [
  62                 'someplugin = someplugin:SomePlugin'
  63                 ]
  64             },
  65         # ...
  66         )
  67
  68 Once the package is installed with install or develop, nose will be able
  69 to load the plugin.
  70
  71 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
  72
  73 Registering a plugin without setuptools
  74 =======================================
  75
  76 It is currently possible to register a plugin programmatically by
  77 creating a custom nose runner like this :
  78
  79 .. code-block:: python
  80
  81     import nose
  82     from yourplugin import YourPlugin
  83
  84     if __name__ == '__main__':
  85         nose.main(addplugins=[YourPlugin()])
  86
  87 Defining options
  88 ================
  89
  90 All plugins must implement the methods ``options(self, parser, env)``
  91 and ``configure(self, options, conf)``. Subclasses of nose.plugins.Plugin
  92 that want the standard options should call the superclass methods.
  93
  94 nose uses optparse.OptionParser from the standard library to parse
  95 arguments. A plugin's ``options()`` method receives a parser
  96 instance. It's good form for a plugin to use that instance only to add
  97 additional arguments that take only long arguments (--like-this). Most
  98 of nose's built-in arguments get their default value from an environment
  99 variable.
 100
 101 A plugin's ``configure()`` method receives the parsed ``OptionParser`` options
 102 object, as well as the current config object. Plugins should configure their
 103 behavior based on the user-selected settings, and may raise exceptions
 104 if the configured behavior is nonsensical.
 105
 106 Logging
 107 =======
 108
 109 nose uses the logging classes from the standard library. To enable users
 110 to view debug messages easily, plugins should use ``logging.getLogger()`` to
 111 acquire a logger in the ``nose.plugins`` namespace.
 112
 113 Recipes
 114 =======
 115
 116 * Writing a plugin that monitors or controls test result output
 117
 118   Implement any or all of ``addError``, ``addFailure``, etc., to monitor test
 119   results. If you also want to monitor output, implement
 120   ``setOutputStream`` and keep a reference to the output stream. If you
 121   want to prevent the builtin ``TextTestResult`` output, implement
 122   ``setOutputSteam`` and *return a dummy stream*. The default output will go
 123   to the dummy stream, while you send your desired output to the real stream.
 124
 125   Example: `examples/html_plugin/htmlplug.py`_
 126
 127 * Writing a plugin that handles exceptions
 128
 129   Subclass :doc:`ErrorClassPlugin <errorclasses>`.
 130
 131   Examples: :doc:`nose.plugins.deprecated <deprecated>`,
 132   :doc:`nose.plugins.skip <skip>`
 133
 134 * Writing a plugin that adds detail to error reports
 135
 136   Implement ``formatError`` and/or ``formatFailure``. The error tuple
 137   you return (error class, error message, traceback) will replace the
 138   original error tuple.
 139
 140   Examples: :doc:`nose.plugins.capture <capture>`,
 141   :doc:`nose.plugins.failuredetail <failuredetail>`
 142
 143 * Writing a plugin that loads tests from files other than python modules
 144
 145   Implement ``wantFile`` and ``loadTestsFromFile``. In ``wantFile``,
 146   return True for files that you want to examine for tests. In
 147   ``loadTestsFromFile``, for those files, return an iterable
 148   containing TestCases (or yield them as you find them;
 149   ``loadTestsFromFile`` may also be a generator).
 150
 151   Example: :doc:`nose.plugins.doctests <doctests>`
 152
 153 * Writing a plugin that prints a report
 154
 155   Implement ``begin`` if you need to perform setup before testing
 156   begins. Implement ``report`` and output your report to the provided stream.
 157
 158   Examples: :doc:`nose.plugins.cover <cover>`, :doc:`nose.plugins.prof <prof>`
 159
 160 * Writing a plugin that selects or rejects tests
 161
 162   Implement any or all ``want*``  methods. Return False to reject the test
 163   candidate, True to accept it -- which  means that the test candidate
 164   will pass through the rest of the system, so you must be prepared to
 165   load tests from it if tests can't be loaded by the core loader or
 166   another plugin -- and None if you don't care.
 167
 168   Examples: :doc:`nose.plugins.attrib <attrib>`,
 169   :doc:`nose.plugins.doctests <doctests>`, :doc:`nose.plugins.testid <testid>`
 170
 171
 172 More Examples
 173 =============
 174
 175 See any builtin plugin or example plugin in the examples_ directory in
 176 the nose source distribution. There is a list of third-party plugins
 177 `on jottit`_.
 178
 179 .. _examples/html_plugin/htmlplug.py: http://python-nose.googlecode.com/svn/trunk/examples/html_plugin/htmlplug.py
 180 .. _examples: http://python-nose.googlecode.com/svn/trunk/examples
 181 .. _on jottit: http://nose-plugins.jottit.com/
 182
 183 """
 184 from nose.plugins.base import Plugin
 185 from nose.plugins.manager import *
 186 from nose.plugins.plugintest import PluginTester
 187
 188 if __name__ == '__main__':
 189     import doctest
 190     doctest.testmod()