1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
.. _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:
|
