/doc/plugins.rst

 1Extending and customizing nose with plugins
 2===========================================
 3
 4nose has plugin hooks for loading, running, watching and reporting on tests and
 5test runs. If you don't like the default collection scheme, or it doesn't suit
 6the layout of your project, or you need reports in a format different from the
 7unittest standard, or you need to collect some additional information about
 8tests (like code coverage or profiling data), you can write a plugin to do so.
 9See the section on `writing plugins`_ for more. 
10
11nose also comes with a number of built-in plugins, such as:
12
13* Output capture
14  
15  Unless called with the ``-s`` (``--nocapture``) switch, nose will capture
16  stdout during each test run, and print the captured output only for tests
17  that fail or have errors. The captured output is printed immediately
18  following the error or failure output for the test. (Note that output in
19  teardown methods is captured, but can't be output with failing tests, because
20  teardown has not yet run at the time of the failure.)
21
22* Assert introspection
23
24  When run with the ``-d`` (``--detailed-errors``) switch, nose will try to
25  output additional information about the assert expression that failed with
26  each failing test. Currently, this means that names in the assert expression
27  will be expanded into any values found for them in the locals or globals in
28  the frame in which the expression executed.
29  
30  In other words, if you have a test like::
31  
32    def test_integers():
33        a = 2
34        assert a == 4, "assert 2 is 4"
35    
36  You will get output like::
37    
38      File "/path/to/file.py", line XX, in test_integers:
39           assert a == 4, "assert 2 is 4"
40      AssertionError: assert 2 is 4
41        >>  assert 2 == 4, "assert 2 is 4"
42    
43  Please note that dotted names are not expanded, and callables are not called
44  in the expansion.
45
46See below for the rest of the built-in plugins.
47
48Using Builtin plugins
49---------------------
50
51See :doc:`plugins/builtin`
52
53Writing plugins
54---------------
55
56.. toctree ::
57   :maxdepth: 2
58   
59   plugins/writing
60   plugins/interface
61   plugins/errorclasses
62   plugins/documenting
63   
64Testing plugins
65---------------
66
67.. toctree ::
68   :maxdepth: 2
69   
70   plugins/testing