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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
Using nose2
===========
Naming Tests
------------
nose2 will look in each directory under the starting directory, unless
the configuration modifies the included paths. Within directories and
within any Python packages found in the starting directory and any
source directories in the starting directory, nose2 will discover
test modules and load tests from them. "Test modules" means any
modules whose names start with "test". See the Configuration section
for ways to modify searching for tests.
Directories nose2 will look in:
* Directory that contains an __init__.py file (a Python package)
* Directory name that contains "test" after being lowercased.
* Directory name that is either "lib" or "src"
Each of the following test files will be run::
test.py
test_views.py
test_models.py
testThingy.py
These files will not be run::
not_a_test.py
myapp_test.py
some_test_file.py
Within test modules, nose2 will load tests from
:class:`unittest.TestCase` subclasses, and from test functions
(functions whose names begin with "test").
Running Tests
-------------
In the simplest case, go to the directory that includes your project
source and run ``nose2`` there::
nose2
This will discover tests in packages and test directories under that
directory, load them, and run them, then output something like::
.............................................................................
----------------------------------------------------------------------
Ran 77 tests in 1.897s
OK
.. todo ::
... and test classes (classes whose names begin with "Test")
To change the place discovery starts, or to change the top-level
importable directory of the project, use the :option:`-s` and
:option:`-t` options.
.. cmdoption :: -s START_DIR, --start-dir START_DIR
Directory to start discovery. Defaults to the current working
directory. This directory is where nose2 will start looking for
tests.
.. cmdoption :: -t TOP_LEVEL_DIRECTORY, --top-level-directory TOP_LEVEL_DIRECTORY, --project-directory TOP_LEVEL_DIRECTORY
Top-level directory of the project. Defaults to the starting
directory. This is the directory containing importable modules and
packages, and is always prepended to sys.path before test discovery
begins.
Specifying Tests to Run
~~~~~~~~~~~~~~~~~~~~~~~
Pass *test names* to nose2 on the command line to run individual test
modules, classes, or tests.
A test name consists of a *python object part* and, for generator or
parameterized tests, an *argument part*. The *python object part* is a
dotted name, such as
``pkg1.tests.test_things.SomeTests.test_ok``. The argument
part is separated from the python object part by a colon (":") and
specifies the *index* of the generated test to select, *starting from
1*. For example, ``pkg1.test.test_things.test_params_func:1`` would
select the *first* test generated from the parameterized test
``test_params_func``.
Plugins may provide other means of test selection.
Running Tests with ``python setup.py test``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
nose2 supports distribute/setuptools' ``python setup.py test``
standard for running tests. To use nose2 to run your package's tests,
add the following to your setup.py::
setup(...
test_suite='nose2.collector.collector',
...
)
(Not literally. Don't put the '...' parts in.)
Two warnings about running tests this way.
One: because the setuptools test command is limited, nose2 returns a "test
suite" that actually takes over the test running process completely,
bypassing the test result and test runner that call it. This may be
incompatible with some packages.
Two: because the command line arguments to the test command may not
match up properly with nose2's arguments, the nose2 instance started
by the collector *does not accept any command line arguments*. This
means that it always runs all tests, and that you cannot configure
plugins on the command line when running tests this way. As a
workaround, when running under the test command, nose2 will read
configuration from ``setup.cfg`` if it is present, in addition to
``unittest.cfg`` and ``nose2.cfg``. This enables you to put
configuration specific to the setuptools test command in ``setup.cfg``
-- for instance to activate plugins that you would otherwise activate
via the command line.
Getting Help
------------
Run::
nose2 -h
to get help for nose2 itself and all loaded plugins.
::
usage: nose2 [-s START_DIR] [-t TOP_LEVEL_DIRECTORY] [--config [CONFIG]]
[--no-user-config] [--no-plugins] [--verbose] [--quiet] [-B] [-D]
[--collect-only] [--log-capture] [-P] [-h]
[testNames [testNames ...]]
positional arguments:
testNames
optional arguments:
-s START_DIR, --start-dir START_DIR
Directory to start discovery ('.' default)
-t TOP_LEVEL_DIRECTORY, --top-level-directory TOP_LEVEL_DIRECTORY, --project-directory TOP_LEVEL_DIRECTORY
Top level directory of project (defaults to start dir)
--config [CONFIG], -c [CONFIG]
Config files to load, if they exist. ('unittest.cfg'
and 'nose2.cfg' in start directory default)
--no-user-config Do not load user config files
--no-plugins Do not load any plugins. Warning: nose2 does not do
anything if no plugins are loaded
--verbose, -v
--quiet
-h, --help Show this help message and exit
plugin arguments:
Command-line arguments added by plugins:
-B, --output-buffer Enable output buffer
-D, --debugger Enter pdb on test fail or error
--collect-only Collect and output test names, do not run any tests
--log-capture Enable log capture
-P, --print-hooks Print names of hooks in order of execution
|
