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