Skip to content

Commit 73b9d17

Browse files
jpellerinjpellerin
committed
More plugin doc updates
1 parent 27108d9 commit 73b9d17

23 files changed

Lines changed: 511 additions & 72 deletions

‎doc/errorclassplugin.html‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
<html>
2+
<head>
3+
<title>nose: ErrorClass Plugins</title>
4+
<link rel="stylesheet" href="site.css" type="text/css"></link>
5+
</head>
6+
<body>
7+
8+
<div id="menu">
9+
<p>This document covers nose version <b>0.10.0a1</b></p>
10+
FIXME -- menu
11+
<p>Last update: <b>Thu Jun 21 13:14:42 2007</b></p>
12+
</div>
13+
14+
<div id="main">
15+
<h1>nose: ErrorClass Plugins</h1>
16+
17+
<p>ErrorClass plugins provide an easy way to add support for custom
18+
handling of particular classes of exceptions.</p>
19+
<p>An ErrorClass plugin defines one or more ErrorClasses and how each is
20+
handled and reported on. Each error class is stored in a different
21+
attribute on the result, and reported separately. Each error class must
22+
indicate the exceptions that fall under that class, the label to use
23+
for reporting, and whether exceptions of the class should be
24+
considered as failures for the whole test run.</p>
25+
<p>ErrorClasses use a declarative syntax. Assign an ErrorClass to the
26+
attribute you wish to add to the result object, defining the
27+
exceptions, label and isfailure attributes. For example, to declare an
28+
ErrorClassPlugin that defines TodoErrors (and subclasses of TodoError)
29+
as an error class with the label 'TODO' that is considered a failure,
30+
do this:</p>
31+
<blockquote>
32+
<pre class="doctest-block">
33+
&gt;&gt;&gt; class Todo(Exception):
34+
... pass
35+
&gt;&gt;&gt; class TodoError(ErrorClassPlugin):
36+
... todo = ErrorClass(Todo, label='TODO', isfailure=True)
37+
</pre>
38+
</blockquote>
39+
<p>The MetaErrorClass metaclass translates the ErrorClass declarations
40+
into the tuples used by the error handling and reporting functions in
41+
the result. This is an internal format and subject to change; you
42+
should always use the declarative syntax for attaching ErrorClasses to
43+
an ErrorClass plugin.</p>
44+
<blockquote>
45+
<pre class="doctest-block">
46+
&gt;&gt;&gt; TodoError.errorClasses # doctest: +ELLIPSIS
47+
((&lt;class ...Todo...&gt;, ('todo', 'TODO', True)),)
48+
</pre>
49+
</blockquote>
50+
<p>Let's see the plugin in action. First some boilerplate.</p>
51+
<blockquote>
52+
<pre class="doctest-block">
53+
&gt;&gt;&gt; import sys
54+
&gt;&gt;&gt; import unittest
55+
&gt;&gt;&gt; buf = unittest._WritelnDecorator(sys.stdout)
56+
</pre>
57+
</blockquote>
58+
<p>Now define a test case that raises a Todo.</p>
59+
<blockquote>
60+
<pre class="doctest-block">
61+
&gt;&gt;&gt; class TestTodo(unittest.TestCase):
62+
... def runTest(self):
63+
... raise Todo(&quot;I need to test something&quot;)
64+
&gt;&gt;&gt; case = TestTodo()
65+
</pre>
66+
</blockquote>
67+
<p>Prepare the result using our plugin. Normally this happens during the
68+
course of test execution within nose.</p>
69+
<blockquote>
70+
<pre class="doctest-block">
71+
&gt;&gt;&gt; plugin = TodoError()
72+
&gt;&gt;&gt; result = unittest._TextTestResult(stream=buf,
73+
... descriptions=0, verbosity=2)
74+
&gt;&gt;&gt; plugin.prepareTestResult(result)
75+
</pre>
76+
</blockquote>
77+
<p>Now run the test. TODO is printed.</p>
78+
<blockquote>
79+
<pre class="doctest-block">
80+
&gt;&gt;&gt; case(result) # doctest: +ELLIPSIS
81+
runTest (....TestTodo) ... TODO
82+
</pre>
83+
</blockquote>
84+
<p>Errors and failures are empty, but todo has our test:</p>
85+
<blockquote>
86+
<pre class="doctest-block">
87+
&gt;&gt;&gt; result.errors
88+
[]
89+
&gt;&gt;&gt; result.failures
90+
[]
91+
&gt;&gt;&gt; result.todo # doctest: +ELLIPSIS
92+
[(&lt;....TestTodo testMethod=runTest&gt;, '...Todo: I need to test something\n')]
93+
&gt;&gt;&gt; result.printErrors() # doctest: +ELLIPSIS
94+
&lt;BLANKLINE&gt;
95+
======================================================================
96+
TODO: runTest (....TestTodo)
97+
----------------------------------------------------------------------
98+
Traceback (most recent call last):
99+
...
100+
Todo: I need to test something
101+
&lt;BLANKLINE&gt;
102+
</pre>
103+
</blockquote>
104+
<p>Since we defined a Todo as a failure, the run was not successful.</p>
105+
<blockquote>
106+
<pre class="doctest-block">
107+
&gt;&gt;&gt; result.wasSuccessful()
108+
False
109+
</pre>
110+
</blockquote>
111+
112+
113+
</div>
114+
</body>
115+
</html>
116+

‎doc/plugin_attrib.html‎

Lines changed: 39 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -8,57 +8,59 @@
88
<div id="menu">
99
<p>This document covers nose version <b>0.10.0a1</b></p>
1010
FIXME -- menu
11-
<p>Last update: <b>Thu Jun 21 11:46:57 2007</b></p>
11+
<p>Last update: <b>Thu Jun 21 13:14:42 2007</b></p>
1212
</div>
1313

1414
<div id="main">
1515
<h1>nose: builtin plugin: attrib</h1>
1616

1717
<p>Attribute selector plugin.</p>
18-
<dl class="docutils">
19-
<dt>Simple syntax (-a, --attr) examples:</dt>
20-
<dd><ul class="first last">
21-
<li><p class="first">nosetests -a status=stable
22-
=&gt; only test cases with attribute &quot;status&quot; having value &quot;stable&quot;</p>
18+
<p>Simple syntax (-a, --attr) examples:</p>
19+
<ul>
20+
<li><dl class="first docutils">
21+
<dt><cite>nosetests -a status=stable</cite>:</dt>
22+
<dd><p class="first last">Only test cases with attribute &quot;status&quot; having value &quot;stable&quot;</p>
23+
</dd>
24+
</dl>
2325
</li>
24-
<li><p class="first">nosetests -a priority=2,status=stable
25-
=&gt; both attributes must match</p>
26+
<li><dl class="first docutils">
27+
<dt><cite>nosetests -a priority=2,status=stable</cite>:</dt>
28+
<dd><p class="first last">Both attributes must match</p>
29+
</dd>
30+
</dl>
2631
</li>
27-
<li><p class="first">nosetests -a priority=2 -a slow
28-
=&gt; either attribute must match</p>
32+
<li><dl class="first docutils">
33+
<dt><cite>nosetests -a priority=2 -a slow</cite>:</dt>
34+
<dd><p class="first last">Either attribute must match</p>
35+
</dd>
36+
</dl>
2937
</li>
30-
<li><p class="first">nosetests -a tags=http
31-
=&gt; attribute list &quot;tags&quot; must contain value &quot;http&quot; (see test_foobar()</p>
32-
<div class="system-message">
33-
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">&lt;string&gt;</tt>, line 15)</p>
34-
<p>Unexpected indentation.</p>
35-
</div>
36-
<blockquote>
37-
<p>below for definition)</p>
38-
</blockquote>
38+
<li><dl class="first docutils">
39+
<dt><cite>nosetests -a tags=http</cite>:</dt>
40+
<dd><p class="first last">Attribute list &quot;tags&quot; must contain value &quot;http&quot; (see test_foobar()
41+
below for definition)</p>
42+
</dd>
43+
</dl>
3944
</li>
40-
<li><p class="first">nosetests -a slow
41-
=&gt; attribute &quot;slow&quot; must be defined and its value cannot equal to False</p>
42-
<div class="system-message">
43-
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">&lt;string&gt;</tt>, line 19)</p>
44-
<p>Unexpected indentation.</p>
45-
</div>
46-
<blockquote>
47-
<p>(False, [], &quot;&quot;, etc...)</p>
48-
</blockquote>
45+
<li><dl class="first docutils">
46+
<dt><cite>nosetests -a slow</cite>:</dt>
47+
<dd><p class="first last">Attribute &quot;slow&quot; must be defined and its value cannot equal to False
48+
(False, [], &quot;&quot;, etc...)</p>
49+
</dd>
50+
</dl>
4951
</li>
50-
<li><p class="first">nosetests -a !slow
51-
=&gt; attribute &quot;slow&quot; must NOT be defined or its value must be equal to False</p>
52+
<li><dl class="first docutils">
53+
<dt><cite>nosetests -a !slow</cite>:</dt>
54+
<dd><p class="first last">Attribute &quot;slow&quot; must NOT be defined or its value must be equal to False</p>
55+
</dd>
56+
</dl>
5257
</li>
5358
</ul>
54-
</dd>
55-
<dt>Eval expression syntax (-A, --eval-attr) examples:</dt>
56-
<dd><ul class="first last simple">
57-
<li>nosetests -A &quot;not slow&quot;</li>
58-
<li>nosetests -A &quot;(priority &gt; 5) and not slow&quot;</li>
59+
<p>Eval expression syntax (-A, --eval-attr) examples:</p>
60+
<ul class="simple">
61+
<li><cite>nosetests -A &quot;not slow&quot;</cite></li>
62+
<li><cite>nosetests -A &quot;(priority &gt; 5) and not slow&quot;</cite></li>
5963
</ul>
60-
</dd>
61-
</dl>
6264

6365

6466
<h2>Plugin Methods Implemented</h2>
@@ -73,7 +75,6 @@ <h2>Commandline Options</h2>
7375
<p>This plugin adds the following commandline options:</p>
7476

7577
<pre>options:
76-
-h, --help show this help message and exit
7778
-a ATTR, --attr=ATTR Run only tests that have attributes specified by ATTR
7879
[NOSE_ATTR]
7980
-A EXPR, --eval-attr=EXPR

‎doc/plugin_capture.html‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
<html>
2+
<head>
3+
<title>nose: builtin plugin: capture</title>
4+
<link rel="stylesheet" href="site.css" type="text/css"></link>
5+
</head>
6+
<body>
7+
8+
<div id="menu">
9+
<p>This document covers nose version <b>0.10.0a1</b></p>
10+
FIXME -- menu
11+
<p>Last update: <b>Thu Jun 21 13:14:42 2007</b></p>
12+
</div>
13+
14+
<div id="main">
15+
<h1>nose: builtin plugin: capture</h1>
16+
17+
<p>This plugin captures stdout during test execution, appending any
18+
output captured to the error or failure output, should the test fail
19+
or raise an error. It is enabled by default but may be disable with
20+
the options -s or --nocapture.</p>
21+
22+
23+
<h2>Plugin Methods Implemented</h2>
24+
25+
<p>This plugin implements the following plugin interface methods:</p>
26+
27+
<ul><li><a href="plugin_interface.html#afterTest">afterTest</a></li><li><a href="plugin_interface.html#beforeTest">beforeTest</a></li><li><a href="plugin_interface.html#begin">begin</a></li><li><a href="plugin_interface.html#configure">configure</a></li><li><a href="plugin_interface.html#formatError">formatError</a></li><li><a href="plugin_interface.html#formatFailure">formatFailure</a></li><li><a href="plugin_interface.html#options">options</a></li></ul>
28+
29+
30+
<h2>Commandline Options</h2>
31+
32+
<p>This plugin adds the following commandline options:</p>
33+
34+
<pre>options:
35+
-s, --nocapture Don't capture stdout (any stdout output will be printed
36+
immediately) [NOSE_NOCAPTURE]
37+
</pre>
38+
39+
</div>
40+
</body>
41+
</html>
42+

‎doc/plugin_cover.html‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<div id="menu">
99
<p>This document covers nose version <b>0.10.0a1</b></p>
1010
FIXME -- menu
11-
<p>Last update: <b>Thu Jun 21 11:46:57 2007</b></p>
11+
<p>Last update: <b>Thu Jun 21 13:14:42 2007</b></p>
1212
</div>
1313

1414
<div id="main">
@@ -37,7 +37,6 @@ <h2>Commandline Options</h2>
3737
<p>This plugin adds the following commandline options:</p>
3838

3939
<pre>options:
40-
-h, --help show this help message and exit
4140
--with-coverage Enable plugin Coverage: If you have Ned Batchelder's
4241
coverage module installed, you may activate a coverage
4342
report. The coverage report will cover any python

‎doc/plugin_debug.html‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<html>
2+
<head>
3+
<title>nose: builtin plugin: debug</title>
4+
<link rel="stylesheet" href="site.css" type="text/css"></link>
5+
</head>
6+
<body>
7+
8+
<div id="menu">
9+
<p>This document covers nose version <b>0.10.0a1</b></p>
10+
FIXME -- menu
11+
<p>Last update: <b>Thu Jun 21 13:14:42 2007</b></p>
12+
</div>
13+
14+
<div id="main">
15+
<h1>nose: builtin plugin: debug</h1>
16+
17+
<p>This plugin provides --pdb and --pdb-failures options that cause the
18+
test runner to drop into pdb if it encounters an error or failure,
19+
respectively.</p>
20+
21+
22+
<h2>Plugin Methods Implemented</h2>
23+
24+
<p>This plugin implements the following plugin interface methods:</p>
25+
26+
<ul><li><a href="plugin_interface.html#addError">addError</a></li><li><a href="plugin_interface.html#addFailure">addFailure</a></li><li><a href="plugin_interface.html#configure">configure</a></li><li><a href="plugin_interface.html#options">options</a></li></ul>
27+
28+
29+
<h2>Commandline Options</h2>
30+
31+
<p>This plugin adds the following commandline options:</p>
32+
33+
<pre>options:
34+
--pdb Drop into debugger on errors
35+
--pdb-failures Drop into debugger on failures
36+
</pre>
37+
38+
</div>
39+
</body>
40+
</html>
41+

‎doc/plugin_deprecated.html‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
<html>
2+
<head>
3+
<title>nose: builtin plugin: deprecated</title>
4+
<link rel="stylesheet" href="site.css" type="text/css"></link>
5+
</head>
6+
<body>
7+
8+
<div id="menu">
9+
<p>This document covers nose version <b>0.10.0a1</b></p>
10+
FIXME -- menu
11+
<p>Last update: <b>Thu Jun 21 13:14:42 2007</b></p>
12+
</div>
13+
14+
<div id="main">
15+
<h1>nose: builtin plugin: deprecated</h1>
16+
17+
<p>This plugin installs a DEPRECATED error class for the DeprecatedTest
18+
exception. It is enabled by default. When DeprecatedTest is raised, the
19+
exception will be logged in the deprecated attribute of the result,
20+
'D' or 'DEPRECATED' (verbose) will be output, and the exception will
21+
not be counted as an error or failure.</p>
22+
23+
24+
<h2>Plugin Methods Implemented</h2>
25+
26+
<p>This plugin implements the following plugin interface methods:</p>
27+
28+
<ul><li><a href="plugin_interface.html#addError">addError</a></li><li><a href="plugin_interface.html#configure">configure</a></li><li><a href="plugin_interface.html#options">options</a></li><li><a href="plugin_interface.html#prepareTestResult">prepareTestResult</a></li></ul>
29+
30+
31+
<h2>Commandline Options</h2>
32+
33+
<p>This plugin adds the following commandline options:</p>
34+
35+
<pre>options:
36+
--no-deprecated Disable special handling of DeprecatedTest exceptions.
37+
</pre>
38+
39+
</div>
40+
</body>
41+
</html>
42+

‎doc/plugin_doctests.html‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<div id="menu">
99
<p>This document covers nose version <b>0.10.0a1</b></p>
1010
FIXME -- menu
11-
<p>Last update: <b>Thu Jun 21 11:46:57 2007</b></p>
11+
<p>Last update: <b>Thu Jun 21 13:14:42 2007</b></p>
1212
</div>
1313

1414
<div id="main">
@@ -40,7 +40,6 @@ <h2>Commandline Options</h2>
4040
<p>This plugin adds the following commandline options:</p>
4141

4242
<pre>options:
43-
-h, --help show this help message and exit
4443
--with-doctest Enable plugin Doctest: Activate doctest plugin to
4544
find and run doctests in non-test modules.
4645
[NOSE_WITH_DOCTEST]

0 commit comments

Comments
 (0)