1Using nose2
2===========
3
4Naming Tests
5------------
6
7nose2 will look in each directory under the starting directory, unless
8the configuration modifies the included paths. Within directories and
9within any Python packages found in the starting directory and any
10source directories in the starting directory, nose2 will discover
11test modules and load tests from them. "Test modules" means any
12modules whose names start with "test". See the Configuration section
13for ways to modify searching for tests.
14
15Directories nose2 will look in:
16
17* Directory that contains an ``__init__.py`` file (a Python package)
18* Directory name that contains "test" after being lowercased.
19* Directory name that is either ``lib`` or ``src``
20
21Each of the following test files will be run::
22
23  test.py
24  test_views.py
25  test_models.py
26  testThingy.py
27
28These files will not be run::
29
30  not_a_test.py
31  myapp_test.py
32  some_test_file.py
33
34
35Within test modules, nose2 will load tests from
36:class:`unittest.TestCase` subclasses, and from test functions
37(functions whose names begin with "test").
38
39
40Running Tests
41-------------
42
43In the simplest case, go to the directory that includes your project
44source and run ``nose2`` there::
45
46  nose2
47
48This will discover tests in packages and test directories under that
49directory, load them, and run them, then output something like::
50
51  .............................................................................
52  ----------------------------------------------------------------------
53  Ran 77 tests in 1.897s
54
55  OK
56
57.. todo ::
58
59   ... and test classes (classes whose names begin with "Test")
60
61To change the place discovery starts, or to change the top-level
62importable directory of the project, use the :option:`-s` and
63:option:`-t` options.
64
65.. cmdoption :: -s START_DIR, --start-dir START_DIR
66
67   Directory to start discovery. Defaults to the current working
68   directory. This directory is where nose2 will start looking for
69   tests.
70
71.. cmdoption :: -t TOP_LEVEL_DIRECTORY, --top-level-directory TOP_LEVEL_DIRECTORY, --project-directory TOP_LEVEL_DIRECTORY
72
73   Top-level directory of the project. Defaults to the starting
74   directory. This is the directory containing importable modules and
75   packages, and is always prepended to ``sys.path`` before test discovery
76   begins.
77
78Specifying Tests to Run
79~~~~~~~~~~~~~~~~~~~~~~~
80
81Pass *test names* to nose2 on the command line to run individual test
82modules, classes, or tests.
83
84A test name consists of a *python object part* and, for generator or
85parameterized tests, an *argument part*. The *python object part* is a
86dotted name, such as
87``pkg1.tests.test_things.SomeTests.test_ok``. The argument
88part is separated from the python object part by a colon (":") and
89specifies the *index* of the generated test to select, *starting from
901*. For example, ``pkg1.test.test_things.test_params_func:1`` would
91select the *first* test generated from the parameterized test
92``test_params_func``.
93
94Plugins may provide other means of test selection.
95
96Running Tests with ``python setup.py test``
97~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98
99nose2 supports distribute/setuptools' ``python setup.py test``
100standard for running tests. To use nose2 to run your package's tests,
101add the following to your setup.py::
102
103  setup(...
104        test_suite='nose2.collector.collector',
105        ...
106        )
107
108(Not literally. Don't put the '...' parts in.)
109
110Two warnings about running tests this way.
111
112One: because the setuptools test command is limited, nose2 returns a "test
113suite" that actually takes over the test running process completely,
114bypassing the test result and test runner that call it. This may be
115incompatible with some packages.
116
117Two: because the command line arguments to the test command may not
118match up properly with nose2's arguments, the nose2 instance started
119by the collector *does not accept any command line arguments*. This
120means that it always runs all tests, and that you cannot configure
121plugins on the command line when running tests this way. As a
122workaround, when running under the test command, nose2 will read
123configuration from ``setup.cfg`` if it is present, in addition to
124``unittest.cfg`` and ``nose2.cfg``. This enables you to put
125configuration specific to the setuptools test command in ``setup.cfg``
126-- for instance to activate plugins that you would otherwise activate
127via the command line.
128
129
130Getting Help
131------------
132
133Run::
134
135  nose2 -h
136
137to get help for nose2 itself and all loaded plugins.
138
139::
140
141  usage: nose2 [-s START_DIR] [-t TOP_LEVEL_DIRECTORY] [--config [CONFIG]]
142               [--no-user-config] [--no-plugins] [--verbose] [--quiet] [-B] [-D]
143               [--collect-only] [--log-capture] [-P] [-h]
144               [testNames [testNames ...]]
145
146  positional arguments:
147    testNames
148
149  optional arguments:
150    -s START_DIR, --start-dir START_DIR
151                          Directory to start discovery ('.' default)
152    -t TOP_LEVEL_DIRECTORY, --top-level-directory TOP_LEVEL_DIRECTORY, --project-directory TOP_LEVEL_DIRECTORY
153                          Top level directory of project (defaults to start dir)
154    --config [CONFIG], -c [CONFIG]
155                          Config files to load, if they exist. ('unittest.cfg'
156                          and 'nose2.cfg' in start directory default)
157    --no-user-config      Do not load user config files
158    --no-plugins          Do not load any plugins. Warning: nose2 does not do
159                          anything if no plugins are loaded
160    --verbose, -v
161    --quiet
162    -h, --help            Show this help message and exit
163
164  plugin arguments:
165    Command-line arguments added by plugins:
166
167    -B, --output-buffer   Enable output buffer
168    -D, --debugger        Enter pdb on test fail or error
169    --collect-only        Collect and output test names, do not run any tests
170    --log-capture         Enable log capture
171    -P, --print-hooks     Print names of hooks in order of execution
172