PageRenderTime 11ms CodeModel.GetById 1ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

/doc/plugins/interface.rst

https://bitbucket.org/jpellerin/nose/
ReStructuredText | 122 lines | 91 code | 31 blank | 0 comment | 0 complexity | 5145c3b96d498404a14cdf73e6c55961 MD5 | raw file
  1
  2.. _plugin-interface:
  3
  4Plugin Interface
  5================
  6
  7Plugin base class
  8-----------------
  9
 10.. autoclass :: nose.plugins.base.Plugin
 11   :members:
 12
 13Nose plugin API
 14---------------
 15
 16Plugins may implement any or all of the methods documented below. Please note
 17that they *must not* subclass `IPluginInterface`; `IPluginInterface` is only a
 18description of the plugin API.
 19
 20When plugins are called, the first plugin that implements a method and returns
 21a non-None value wins, and plugin processing ends. The exceptions to this are
 22methods marked as `generative` or `chainable`.  `generative` methods combine
 23the output of all plugins that respond with an iterable into a single
 24flattened iterable response (a generator, really). `chainable` methods pass
 25the results of calling plugin A as the input to plugin B, where the positions
 26in the chain are determined by the plugin sort order, which is in order by
 27`score` descending.
 28
 29In general, plugin methods correspond directly to methods of
 30`nose.selector.Selector`, `nose.loader.TestLoader` and
 31`nose.result.TextTestResult` are called by those methods when they are
 32called. In some cases, the plugin hook doesn't neatly match the method in
 33which it is called; for those, the documentation for the hook will tell you
 34where in the test process it is called.
 35
 36Plugin hooks fall into four broad categories: selecting and loading tests,
 37handling errors raised by tests, preparing objects used in the testing
 38process, and watching and reporting on test results.
 39
 40Selecting and loading tests
 41^^^^^^^^^^^^^^^^^^^^^^^^^^^
 42
 43To alter test selection behavior, implement any necessary `want*` methods as
 44outlined below. Keep in mind, though, that when your plugin returns True from
 45a `want*` method, you will send the requested object through the normal test
 46collection process. If the object represents something from which normal tests
 47can't be collected, you must also implement a loader method to load the tests.
 48
 49Examples:
 50
 51* The builtin :doc:`doctests plugin <doctests>` implements `wantFile` to
 52  enable loading of doctests from files that are not python modules. It
 53  also implements `loadTestsFromModule` to load doctests from
 54  python modules, and `loadTestsFromFile` to load tests from the
 55  non-module files selected by `wantFile`.
 56   
 57* The builtin :doc:`attrib plugin <attrib>` implements `wantFunction` and
 58  `wantMethod` so that it can reject tests that don't match the
 59  specified attributes.
 60
 61Handling errors
 62^^^^^^^^^^^^^^^
 63
 64To alter error handling behavior -- for instance to catch a certain class of 
 65exception and handle it differently from the normal error or failure handling
 66-- you should subclass :class:`nose.plugins.errorclass.ErrorClassPlugin`. See
 67:doc:`the section on ErrorClass plugins <errorclasses>` for more details.
 68
 69Examples:
 70
 71* The builtin :doc:`skip <skip>` and :doc:`deprecated <deprecated>` plugins are
 72  ErrorClass plugins.
 73
 74
 75Preparing test objects
 76^^^^^^^^^^^^^^^^^^^^^^
 77
 78To alter, get a handle on, or replace test framework objects such as the
 79loader, result, runner, and test cases, use the appropriate prepare methods.
 80The simplest reason to use prepare is in the case that you need to use an
 81object yourself. For example, the isolate plugin implements `prepareTestLoader`
 82so that it can use the loader later on to load tests. If you return a value
 83from a prepare method, that value will be used in place of the loader, result,
 84runner or test case, depending on which prepare method you use. Be aware that
 85when replacing test cases, you are replacing the *entire* test case -- including
 86the whole `run(result)` method of the `unittest.TestCase` -- so if you want
 87normal unittest test result reporting, you must implement the same calls to
 88result as `unittest.TestCase.run`.
 89
 90Examples:
 91
 92* The builtin :doc:`isolate plugin <isolate>` implements `prepareTestLoader`
 93  but does not replace the test loader.
 94
 95* The builtin :doc:`profile plugin <prof>` implements `prepareTest` and does
 96  replace the top-level test case by returning the case wrapped in
 97  the profiler function.
 98
 99Watching or reporting on tests
100^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
101
102To record information about tests or other modules imported during
103the testing process, output additional reports, or entirely change
104test report output, implement any of the methods outlined below that
105correspond to TextTestResult methods.
106
107Examples:
108
109* The builtin :doc:`cover plugin <cover>` implements `begin` and `report` to
110  capture and report code coverage metrics for all or selected modules
111  loaded during testing.
112   
113* The builtin :doc:`profile plugin <prof>` implements `begin`, `prepareTest`
114  and `report` to record and output profiling information. In this
115  case, the plugin's `prepareTest` method constructs a function that
116  runs the test through the hotshot profiler's runcall() method.
117
118Plugin interface methods
119------------------------
120
121.. autoclass :: nose.plugins.base.IPluginInterface
122   :members: