27
36
will run nose.main()::
29
38
python /path/to/nose/core.py
31
40
Please see the usage message for the nosetests script for information
32
41
about how to control which tests nose runs, which plugins are loaded,
33
42
and the test output.
41
nose begins running tests as soon as the first test module is loaded, it
42
does not wait to collect all tests before running the first.
47
Unless called with the -s (--nocapture) switch, nose will capture stdout
48
during each test run, and print the captured output only for tests that
49
fail or have errors. The captured output is printed immediately
50
following the error or failure output for the test. (Note that output in
51
teardown methods is captured, but can't be output with failing tests,
52
because teardown has not yet run at the time of the failure.)
57
When run with the -d (--detailed-errors) switch, nose will try to output
58
additional information about the assert expression that failed with each
59
failing test. Currently, this means that names in the assert expression
60
will be expanded into any values found for them in the locals or globals
61
in the frame in which the expression executed.
63
In other words if you have a test like::
47
Writing tests is easier
48
=======================
50
nose collects tests from `unittest.TestCase` subclasses, of course. But you can
51
also write simple test functions, and test classes that are not subclasses of
52
`unittest.TestCase`. nose also supplies a number of helpful functions for
53
writing timed tests, testing for exceptions, and other common use cases. See
54
`Writing tests`_ and `Testing tools`_ for more.
56
Running tests is easier
57
=======================
59
nose collects tests automatically, as long as you follow some simple
60
guidelines for organizing your library and test code. There's no need
61
to manually collect test cases into test suites. Running tests is
62
responsive, since nose begins running tests as soon as the first test
63
module is loaded. See `Finding and running tests`_ for more.
65
Setting up your test environment is easier
66
==========================================
68
nose supports fixtures at the package, module, class, and test case
69
level, so expensive initialization can be done as infrequently as
70
possible. See Fixtures_ for more.
72
Doing what you want to do is easier
73
===================================
75
nose has plugin hooks for loading, running, watching and reporting on
76
tests and test runs. If you don't like the default collection scheme,
77
or it doesn't suit the layout of your project, or you need reports in
78
a format different from the unittest standard, or you need to collect
79
some additional information about tests (like code coverage or
80
profiling data), you can write a plugin to do so. See `Writing plugins`_
81
for more. nose comes with a number of builtin plugins, for
86
Unless called with the -s (--nocapture) switch, nose will capture stdout
87
during each test run, and print the captured output only for tests that
88
fail or have errors. The captured output is printed immediately
89
following the error or failure output for the test. (Note that output in
90
teardown methods is captured, but can't be output with failing tests,
91
because teardown has not yet run at the time of the failure.)
93
* Assert introspection
95
When run with the -d (--detailed-errors) switch, nose will try to output
96
additional information about the assert expression that failed with each
97
failing test. Currently, this means that names in the assert expression
98
will be expanded into any values found for them in the locals or globals
99
in the frame in which the expression executed.
67
assert a == 4, "assert 2 is 4"
69
You will get output like::
71
File "/path/to/file.py", line XX, in test_integers:
101
In other words if you have a test like::
72
105
assert a == 4, "assert 2 is 4"
73
AssertionError: assert 2 is 4
74
>> assert 2 == 4, "assert 2 is 4"
107
You will get output like::
109
File "/path/to/file.py", line XX, in test_integers:
110
assert a == 4, "assert 2 is 4"
111
AssertionError: assert 2 is 4
112
>> assert 2 == 4, "assert 2 is 4"
114
Please note that dotted names are not expanded, and callables are not called
76
117
Setuptools integration
77
118
======================
89
130
python setup.py test
91
132
When running under setuptools, you can configure nose settings via the
92
environment variables detailed in the nosetests script usage message.
133
environment variables detailed in the nosetests script usage message,
134
or the setup.cfg or ~/.noserc or ~/.nose.cfg config files.
94
136
Please note that when run under the setuptools test command, some plugins will
95
not be available, including the builtin coverage, profiler, and missed test
137
not be available, including the builtin coverage, and profiler plugins.
98
nose 1.0 will include a custom setuptools command that will enable all
139
nose also includes its own setuptools command, ``nosetests``, that
140
provides support for all plugins and command line options. See
141
nose.commands_ for more information about the ``nosetests`` command.
101
143
.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
144
.. _nose.commands: #commands
106
As with py.test and TestGears, nose tests need not be subclasses of
107
TestCase. Any function or class that matches the configured testMatch regular
108
expression ('(?:^|[\\b_\\.-])[Tt]est)'' by default) and lives in a module that
109
also matches that expression will be run as a test. For the sake of
110
compatibility with legacy unittest test cases, nose will also load tests from
111
unittest.TestCase subclasses just like unittest does. Like py.test and
112
TestGears, functional tests will be run in the order in which they appear in
113
the module file. TestCase derived tests and other test classes are run in
149
As with py.test_, nose tests need not be subclasses of
150
`unittest.TestCase`. Any function or class that matches the configured
151
testMatch regular expression (`(?:^|[\\b_\\.-])[Tt]est)` by default --
152
that is, has test or Test at a word boundary or following a - or _)
153
and lives in a module that also matches that expression will be run as
154
a test. For the sake of compatibility with legacy unittest test cases,
155
nose will also load tests from `unittest.TestCase` subclasses just
156
like unittest does. Like py.test, functional tests will be run in the
157
order in which they appear in the module file. TestCase derived tests
158
and other test classes are run in alphabetical order.
160
.. _py.test: http://codespeak.net/py/current/doc/test.html
119
165
nose supports fixtures (setup and teardown methods) at the package,
120
module, and test level. As with py.test or unittest fixtures, setup always
121
runs before any test (or collection of tests for test packages and modules);
122
teardown runs if setup has completed successfully, whether or not the test
123
or tests pass. For more detail on fixtures at each level, see below.
166
module, class, and test level. As with py.test or unittest fixtures,
167
setup always runs before any test (or collection of tests for test
168
packages and modules); teardown runs if setup has completed
169
successfully, whether or not the test or tests pass. For more detail
170
on fixtures at each level, see below.
132
179
create and tear it down once per test module or test case.
134
181
To create package-level setup and teardown methods, define setup and/or
135
teardown functions in the __init__.py of a test package. Setup methods may
136
be named 'setup', 'setup_package', 'setUp',or 'setUpPackage'; teardown may
137
be named 'teardown', 'teardown_package', 'tearDown' or 'tearDownPackage'.
182
teardown functions in the `__init__.py` of a test package. Setup methods may
183
be named `setup`, `setup_package`, `setUp`, or `setUpPackage`; teardown may
184
be named `teardown`, `teardown_package`, `tearDown` or `tearDownPackage`.
138
185
Execution of tests in a test package begins as soon as the first test
139
186
module is loaded from the test package.
144
191
A test module is a python module that matches the testMatch regular
145
192
expression. Test modules offer module-level setup and teardown; define the
146
method 'setup', 'setup_module', 'setUp' or 'setUpModule' for setup,
147
'teardown', 'teardown_module', or 'tearDownModule' for teardown. Execution
193
method `setup`, `setup_module`, `setUp` or `setUpModule` for setup,
194
`teardown`, `teardown_module`, or `tearDownModule` for teardown. Execution
148
195
of tests in a test module begins after all tests are collected.
153
A test class is a class defined in a test module that is either a subclass
154
of unittest.TestCase, or matches testMatch. Test classes that don't
155
descend from unittest.TestCase are run in the same way as those that do:
156
methods in the class that match testMatch are discovered, and a test case
157
constructed to run each with a fresh instance of the test class. Like
158
unittest.TestCase subclasses, other test classes may define setUp and
159
tearDown methods that will be run before and after each test method.
200
A test class is a class defined in a test module that is either a subclass of
201
`unittest.TestCase`, or matches testMatch. Test classes that don't descend
202
from `unittest.TestCase` are run in the same way as those that do: methods in
203
the class that match testMatch are discovered, and a test case constructed to
204
run each with a fresh instance of the test class. Like `unittest.TestCase`
205
subclasses, other test classes may define setUp and tearDown methods that will
206
be run before and after each test method. Test classes that do not descend
207
from `unittest.TestCase` may also include generator methods, and class-level
208
fixtures. Class level fixtures may be named `setup_class`, `setupClass`,
209
`setUpClass`, `setupAll` or `setUpAll` for set up and `teardown_class`,
210
`teardownClass`, `tearDownClass`, `teardownAll` or `tearDownAll` for teardown
211
and must be class methods.
164
216
Any function in a test module that matches testMatch will be wrapped in a
165
FunctionTestCase and run as a test. The simplest possible failing test is
217
`FunctionTestCase` and run as a test. The simplest possible failing test is
184
236
def teardown_func():
187
@with_setup(setup_func,teardown_func)
191
For python 2.3, add the attributes by calling the decorator function like
196
test = with_setup(setup_func,teardown_func)(test)
239
@with_setup(setup_func, teardown_func)
243
For python 2.3 or earlier, add the attributes by calling the decorator
248
test = with_setup(setup_func, teardown_func)(test)
198
250
or by direct assignment::
200
252
test.setup = setup_func
201
253
test.teardown = teardown_func
255
Please note that `with_setup` is useful *only* for test functions, not
256
for test methods in `unittest.TestCase` subclasses or other test
257
classes. For those cases, define `setUp` and `tearDown` methods in the
232
294
For generator methods, the setUp and tearDown methods of the class (if any)
233
295
will be run before and after each generated test case.
235
Please note that method generators `are not` supported in unittest.TestCase
297
Please note that method generators *are not* supported in `unittest.TestCase`
300
Finding and running tests
301
-------------------------
303
nose, by default, follows a few simple rules for test discovery.
305
* If it looks like a test, it's a test. Names of directories, modules,
306
classes and functions are compared against the testMatch regular
307
expression, and those that match are considered tests. Any class that is a
308
`unittest.TestCase` subclass is also collected, so long as it is inside of a
309
module that looks like a test.
311
* Directories that don't look like tests and aren't packages are not
314
* Packages are always inspected, but they are only collected if they look
315
like tests. This means that you can include your tests inside of your
316
packages (somepackage/tests) and nose will collect the tests without
317
running package code inappropriately.
319
* When a project appears to have library and test code organized into
320
separate directories, library directories are examined first.
322
* When nose imports a module, it adds that module's directory to sys.path;
323
when the module is inside of a package, like package.module, it will be
324
loaded as package.module and the directory of *package* will be added to
327
* If an object defines a __test__ attribute that does not evaluate to
328
True, that object will not be collected, nor will any objects it
331
Be aware that plugins and command line options can change any of those rules.
336
The nose.tools module provides a number of testing aids that you may
337
find useful, including decorators for restricting test execution time
338
and testing for exceptions, and all of the same assertX methods found
339
in `unittest.TestCase` (only spelled in pep08 fashion, so `assert_equal`
340
rather than `assertEqual`). See `nose.tools`_ for a complete list.
342
.. _nose.tools: http://code.google.com/p/python-nose/wiki/TestingTools
258
365
nose was inspired mainly by py.test_, which is a great test runner, but
259
366
formerly was not all that easy to install, and is not based on unittest.
261
TestGears_ is a similar test runner (now part of TurboGears) that was
262
released during development of nose. TestGears is a little farther towards
263
the 'no magic' side of the testing axis, and integrates with setuptools
264
with a custom action.
266
Test suites written for use with nose should work equally well with either
267
py.test or TestGears, and vice versa, except for the differences in output
268
capture and command line arguments for the respective tools.
368
Test suites written for use with nose should work equally well with py.test,
369
and vice versa, except for the differences in output capture and command line
370
arguments for the respective tools.
270
372
.. _py.test: http://codespeak.net/py/current/doc/test.html
271
.. _TestGears: http://www.turbogears.com/testgears/
273
374
License and copyright
274
375
---------------------
276
nose is copyright Jason Pellerin 2005-2006
377
nose is copyright Jason Pellerin 2005-2008
278
379
This program is free software; you can redistribute it and/or modify it
279
380
under the terms of the GNU Lesser General Public License as published by
290
391
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
293
from nose.core import TestCollector, collector, configure, main, run, run_exit
394
from nose.core import collector, main, run, run_exit, runmodule
395
# backwards compatibility
294
396
from nose.exc import SkipTest, DeprecatedTest
295
from nose.loader import TestLoader
296
from nose.suite import LazySuite
297
from nose.result import TextTestResult
298
from nose.tools import with_setup # backwards compatibility
299
from nose.util import file_like, split_test_name, test_address
397
from nose.tools import with_setup
301
399
__author__ = 'Jason Pellerin'
302
__version__ = '0.9.0'
303
__versioninfo__ = (0, 9, 0)
400
__versioninfo__ = (0, 10, 3)
401
__version__ = '.'.join(map(str, __versioninfo__))
306
'TextTestResult', 'LazySuite',
307
'SkipTest', 'DeprecatedTest',
308
'TestCollector', 'TestLoader',
309
'collector', 'configure', 'main', 'run', 'run_exit', 'with_setup',
310
'file_like', 'split_test_name', 'test_address'
404
'main', 'run', 'run_exit', 'runmodule', 'with_setup',
405
'SkipTest', 'DeprecatedTest', 'collector'
added
removed
nose/__init__.py
