122 lines
No EOL
4.8 KiB
ReStructuredText
122 lines
No EOL
4.8 KiB
ReStructuredText
|
|
.. _plugin-interface:
|
|
|
|
Plugin Interface
|
|
================
|
|
|
|
Plugin base class
|
|
-----------------
|
|
|
|
.. autoclass :: nose.plugins.base.Plugin
|
|
:members:
|
|
|
|
Nose plugin API
|
|
---------------
|
|
|
|
Plugins may implement any or all of the methods documented below. Please note
|
|
that they *must not* subclass `IPluginInterface`; `IPluginInterface` is only a
|
|
description of the plugin API.
|
|
|
|
When plugins are called, the first plugin that implements a method and returns
|
|
a non-None value wins, and plugin processing ends. The exceptions to this are
|
|
methods marked as `generative` or `chainable`. `generative` methods combine
|
|
the output of all plugins that respond with an iterable into a single
|
|
flattened iterable response (a generator, really). `chainable` methods pass
|
|
the results of calling plugin A as the input to plugin B, where the positions
|
|
in the chain are determined by the plugin sort order, which is in order by
|
|
`score` descending.
|
|
|
|
In general, plugin methods correspond directly to methods of
|
|
`nose.selector.Selector`, `nose.loader.TestLoader` and
|
|
`nose.result.TextTestResult` are called by those methods when they are
|
|
called. In some cases, the plugin hook doesn't neatly match the method in
|
|
which it is called; for those, the documentation for the hook will tell you
|
|
where in the test process it is called.
|
|
|
|
Plugin hooks fall into four broad categories: selecting and loading tests,
|
|
handling errors raised by tests, preparing objects used in the testing
|
|
process, and watching and reporting on test results.
|
|
|
|
Selecting and loading tests
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
To alter test selection behavior, implement any necessary `want*` methods as
|
|
outlined below. Keep in mind, though, that when your plugin returns True from
|
|
a `want*` method, you will send the requested object through the normal test
|
|
collection process. If the object represents something from which normal tests
|
|
can't be collected, you must also implement a loader method to load the tests.
|
|
|
|
Examples:
|
|
|
|
* The builtin :doc:`doctests plugin <doctests>` implements `wantFile` to
|
|
enable loading of doctests from files that are not python modules. It
|
|
also implements `loadTestsFromModule` to load doctests from
|
|
python modules, and `loadTestsFromFile` to load tests from the
|
|
non-module files selected by `wantFile`.
|
|
|
|
* The builtin :doc:`attrib plugin <attrib>` implements `wantFunction` and
|
|
`wantMethod` so that it can reject tests that don't match the
|
|
specified attributes.
|
|
|
|
Handling errors
|
|
^^^^^^^^^^^^^^^
|
|
|
|
To alter error handling behavior -- for instance to catch a certain class of
|
|
exception and handle it differently from the normal error or failure handling
|
|
-- you should subclass :class:`nose.plugins.errorclass.ErrorClassPlugin`. See
|
|
:doc:`the section on ErrorClass plugins <errorclasses>` for more details.
|
|
|
|
Examples:
|
|
|
|
* The builtin :doc:`skip <skip>` and :doc:`deprecated <deprecated>` plugins are
|
|
ErrorClass plugins.
|
|
|
|
|
|
Preparing test objects
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
To alter, get a handle on, or replace test framework objects such as the
|
|
loader, result, runner, and test cases, use the appropriate prepare methods.
|
|
The simplest reason to use prepare is in the case that you need to use an
|
|
object yourself. For example, the isolate plugin implements `prepareTestLoader`
|
|
so that it can use the loader later on to load tests. If you return a value
|
|
from a prepare method, that value will be used in place of the loader, result,
|
|
runner or test case, depending on which prepare method you use. Be aware that
|
|
when replacing test cases, you are replacing the *entire* test case -- including
|
|
the whole `run(result)` method of the `unittest.TestCase` -- so if you want
|
|
normal unittest test result reporting, you must implement the same calls to
|
|
result as `unittest.TestCase.run`.
|
|
|
|
Examples:
|
|
|
|
* The builtin :doc:`isolate plugin <isolate>` implements `prepareTestLoader`
|
|
but does not replace the test loader.
|
|
|
|
* The builtin :doc:`profile plugin <prof>` implements `prepareTest` and does
|
|
replace the top-level test case by returning the case wrapped in
|
|
the profiler function.
|
|
|
|
Watching or reporting on tests
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
To record information about tests or other modules imported during
|
|
the testing process, output additional reports, or entirely change
|
|
test report output, implement any of the methods outlined below that
|
|
correspond to TextTestResult methods.
|
|
|
|
Examples:
|
|
|
|
* The builtin :doc:`cover plugin <cover>` implements `begin` and `report` to
|
|
capture and report code coverage metrics for all or selected modules
|
|
loaded during testing.
|
|
|
|
* The builtin :doc:`profile plugin <prof>` implements `begin`, `prepareTest`
|
|
and `report` to record and output profiling information. In this
|
|
case, the plugin's `prepareTest` method constructs a function that
|
|
runs the test through the hotshot profiler's runcall() method.
|
|
|
|
Plugin interface methods
|
|
------------------------
|
|
|
|
.. autoclass :: nose.plugins.base.IPluginInterface
|
|
:members: |