5 Use the nosetests script (after installation by setuptools):
7 nosetests [options] [(optional) test files or directories]
9 In addition to passing command-line options, you may also put
10 configuration options in a .noserc or nose.cfg file in your home
11 directory. These are standard .ini-style config files. Put your
12 nosetests configuration in a [nosetests] section, with the -- prefix
19 There are several other ways to use the nose test runner besides the
20 *nosetests* script. You may use nose in a test script:
25 If you don't want the test script to exit with 0 on success and 1 on
26 failure (like unittest.main), use nose.run() instead:
31 *result* will be true if the test run succeeded, or false if any test
32 failed or raised an uncaught exception. Lastly, you can run nose.core
33 directly, which will run nose.main():
35 python /path/to/nose/core.py
37 Please see the usage message for the nosetests script for information
38 about how to control which tests nose runs, which plugins are loaded,
45 nose collects tests automatically from python source files,
46 directories and packages found in its working directory (which
47 defaults to the current working directory). Any python source file,
48 directory or package that matches the testMatch regular expression (by
49 default: *(?:^|[b_.-])[Tt]est)* will be collected as a test (or source
50 for collection of tests). In addition, all other packages found in the
51 working directory will be examined for python source files or
52 directories that match testMatch. Package discovery descends all the
53 way down the tree, so package.tests and package.sub.tests and
54 package.sub.sub2.tests will all be collected.
56 Within a test directory or package, any python source file matching
57 testMatch will be examined for test cases. Within a test module,
58 functions and classes whose names match testMatch and TestCase
59 subclasses with any name will be loaded and executed as tests. Tests
60 may use the assert keyword or raise AssertionErrors to indicate test
61 failure. TestCase subclasses may do the same or use the various
62 TestCase methods available.
68 To specify which tests to run, pass test names on the command line:
70 nosetests only_test_this.py
72 Test names specified may be file or module names, and may optionally
73 indicate the test case to run by separating the module or file name
74 from the test case name with a colon. Filenames may be relative or
78 nosetests another.test:TestCase.test_method
79 nosetests a.test:TestCase
80 nosetests /path/to/test/file.py:test_function
82 You may also change the working directory where nose looks for tests
83 by using the -w switch:
85 nosetests -w /path/to/tests
87 Note, however, that support for multiple -w arguments is now
88 deprecated and will be removed in a future release. As of nose 0.10,
89 you can get the same behavior by specifying the target directories
90 *without* the -w switch:
92 nosetests /path/to/tests /another/path/to/tests
94 Further customization of test selection and loading is possible
95 through the use of plugins.
97 Test result output is identical to that of unittest, except for the
98 additional features (error classes, and plugin-supplied features such
99 as output capture and assert introspection) detailed in the options
106 In addition to passing command-line options, you may also put
107 configuration options in your project's *setup.cfg* file, or a .noserc
108 or nose.cfg file in your home directory. In any of these standard
109 .ini-style config files, you put your nosetests configuration in a
110 "[nosetests]" section. Options are the same as on the command line,
111 with the -- prefix removed. For options that are simple switches, you
118 All configuration files that are found will be loaded and their
119 options combined. You can override the standard config file loading
120 with the "-c" option.
126 There are numerous nose plugins available via easy_install and
127 elsewhere. To use a plugin, just install it. The plugin will add
128 command line options to nosetests. To verify that the plugin is
133 You can add -v or -vv to that command to show more information about
136 If you are running nose.main() or nose.run() from a script, you can
137 specify a list of plugins to use by passing a list of plugins with the
138 plugins keyword argument.
144 nose 1.0 can use SOME plugins that were written for nose 0.9. The
145 default plugin manager inserts a compatibility wrapper around 0.9
146 plugins that adapts the changed plugin api calls. However, plugins
147 that access nose internals are likely to fail, especially if they
148 attempt to access test case or test suite classes. For example,
149 plugins that try to determine if a test passed to startTest is an
150 individual test or a suite will fail, partly because suites are no
151 longer passed to startTest and partly because it's likely that the
152 plugin is trying to find out if the test is an instance of a class
153 that no longer exists.
156 0.10 and 0.11 plugins
157 ---------------------
159 All plugins written for nose 0.10 and 0.11 should work with nose 1.0.
167 Output nose version and exit
171 Output list of available plugins and exit. Combine with higher
172 verbosity for greater detail
174 -v=DEFAULT, --verbose=DEFAULT
176 Be more verbose. [NOSE_VERBOSE]
178 --verbosity=VERBOSITY
180 Set verbosity; --verbosity=2 is the same as -v
182 -q=DEFAULT, --quiet=DEFAULT
186 -c=FILES, --config=FILES
188 Load configuration from config file(s). May be specified multiple
189 times; in that case, all config files will be loaded and combined
191 -w=WHERE, --where=WHERE
193 Look for tests in this directory. May be specified multiple times.
194 The first directory passed will be used as the working directory,
195 in place of the current working directory, which is the default.
196 Others will be added to the list of tests to execute. [NOSE_WHERE]
200 Look for tests in this directory under Python 3.x. Functions the
201 same as 'where', but only applies if running under Python 3.x or
202 above. Note that, if present under 3.x, this option completely
203 replaces any directories specified with 'where', so the 'where'
204 option becomes ineffective. [NOSE_PY3WHERE]
206 -m=REGEX, --match=REGEX, --testmatch=REGEX
208 Files, directories, function names, and class names that match this
209 regular expression are considered tests. Default:
210 (?:^|[b_./-])[Tt]est [NOSE_TESTMATCH]
214 Run these tests (comma-separated list). This argument is useful
215 mainly from configuration files; on the command line, just pass the
216 tests to run as additional arguments with no switch.
218 -l=DEFAULT, --debug=DEFAULT
220 Activate debug logging for one or more systems. Available debug
221 loggers: nose, nose.importer, nose.inspector, nose.plugins,
222 nose.result and nose.selector. Separate multiple names with a
227 Log debug messages to this file (default: sys.stderr)
229 --logging-config=FILE, --log-config=FILE
231 Load logging config from this file -- bypasses all other logging
234 -I=REGEX, --ignore-files=REGEX
236 Completely ignore any file that matches this regular expression.
237 Takes precedence over any other settings or plugins. Specifying
238 this option will replace the default setting. Specify this option
239 multiple times to add more regular expressions [NOSE_IGNORE_FILES]
241 -e=REGEX, --exclude=REGEX
243 Don't run tests that match regular expression [NOSE_EXCLUDE]
245 -i=REGEX, --include=REGEX
247 This regular expression will be applied to files, directories,
248 function names, and class names for a chance to include additional
249 tests that do not match TESTMATCH. Specify this option multiple
250 times to add more regular expressions [NOSE_INCLUDE]
254 Stop running tests after the first error or failure
256 -P, --no-path-adjustment
258 Don't make any changes to sys.path when loading tests [NOSE_NOPATH]
262 Look for tests in python modules that are executable. Normal
263 behavior is to exclude executable modules, since they may not be
264 import-safe [NOSE_INCLUDE_EXE]
268 DO NOT look for tests in python modules that are executable. (The
269 default on the windows platform is to do so.)
273 Traverse through all path entries of a namespace package
275 --first-package-wins, --first-pkg-wins, --1st-pkg-wins
277 nose's importer will normally evict a package from sys.modules if
278 it sees a package with the same name in a different location. Set
279 this option to disable that behavior.
283 Run only tests that have attributes specified by ATTR [NOSE_ATTR]
285 -A=EXPR, --eval-attr=EXPR
287 Run only tests for whose attributes the Python expression EXPR
288 evaluates to True [NOSE_EVAL_ATTR]
292 Don't capture stdout (any stdout output will be printed
293 immediately) [NOSE_NOCAPTURE]
297 Disable logging capture plugin. Logging configurtion will be left
298 intact. [NOSE_NOLOGCAPTURE]
300 --logging-format=FORMAT
302 Specify custom format to print statements. Uses the same format as
303 used by standard logging handlers. [NOSE_LOGFORMAT]
305 --logging-datefmt=FORMAT
307 Specify custom date/time format to print statements. Uses the same
308 format as used by standard logging handlers. [NOSE_LOGDATEFMT]
310 --logging-filter=FILTER
312 Specify which statements to filter in/out. By default, everything
313 is captured. If the output is too verbose, use this option to
314 filter out needless output. Example: filter=foo will capture
315 statements issued ONLY to foo or foo.what.ever.sub but not foobar
316 or other logger. Specify multiple loggers with comma:
317 filter=foo,bar,baz. If any logger name is prefixed with a minus, eg
318 filter=-foo, it will be excluded rather than included. Default:
319 exclude logging messages from nose itself (-nose). [NOSE_LOGFILTER]
321 --logging-clear-handlers
323 Clear all other logging handlers
327 Enable plugin Coverage: Activate a coverage report using Ned
328 Batchelder's coverage module. [NOSE_WITH_COVERAGE]
330 --cover-package=PACKAGE
332 Restrict coverage output to selected packages [NOSE_COVER_PACKAGE]
336 Erase previously collected coverage statistics before run
340 Include test modules in coverage report [NOSE_COVER_TESTS]
344 Include all python files under working directory in coverage
345 report. Useful for discovering holes in test coverage if not all
346 files are imported by the test suite. [NOSE_COVER_INCLUSIVE]
350 Produce HTML coverage information
354 Produce HTML coverage information in dir
358 Include branch coverage in coverage report [NOSE_COVER_BRANCHES]
362 Produce XML coverage information
364 --cover-xml-file=FILE
366 Produce XML coverage information in file
370 Drop into debugger on errors
374 Drop into debugger on failures
378 Disable special handling of DeprecatedTest exceptions.
382 Enable plugin Doctest: Activate doctest plugin to find and run
383 doctests in non-test modules. [NOSE_WITH_DOCTEST]
387 Also look for doctests in test modules. Note that classes, methods
388 and functions should have either doctests or non-doctest tests, not
389 both. [NOSE_DOCTEST_TESTS]
391 --doctest-extension=EXT
393 Also look for doctests in files with this extension
394 [NOSE_DOCTEST_EXTENSION]
396 --doctest-result-variable=VAR
398 Change the variable name set to the result of the last interpreter
399 command from the default '_'. Can be used to avoid conflicts with
400 the _() function used for text translation.
401 [NOSE_DOCTEST_RESULT_VAR]
403 --doctest-fixtures=SUFFIX
405 Find fixtures for a doctest file in module with this name appended
406 to the base name of the doctest file
410 Enable plugin IsolationPlugin: Activate the isolation plugin to
411 isolate changes to external modules to a single test module or
412 package. The isolation plugin resets the contents of sys.modules
413 after each test module or package runs to its state before the
414 test. PLEASE NOTE that this plugin should not be used with the
415 coverage plugin, or in any other case where module reloading may
416 produce undesirable side-effects. [NOSE_WITH_ISOLATION]
418 -d, --detailed-errors, --failure-detail
420 Add detail to error output by attempting to evaluate failed asserts
421 [NOSE_DETAILED_ERRORS]
425 Enable plugin Profile: Use this plugin to run tests using the
426 hotshot profiler. [NOSE_WITH_PROFILE]
430 Set sort order for profiler output
432 --profile-stats-file=FILE
434 Profiler stats file; default is a new temp file on each run
436 --profile-restrict=RESTRICT
438 Restrict profiler output. See help for pstats.Stats for details
442 Disable special handling of SkipTest exceptions.
446 Enable plugin TestId: Activate to add a test id (like #1) to each
447 test name output. Activate with --failed to rerun failing tests
452 Store test ids found in test runs in this file. Default is the file
453 .noseids in the working directory.
457 Run the tests that failed in the last test run.
461 Spread test run among this many processes. Set a number equal to
462 the number of processors or cores in your machine for best results.
465 --process-timeout=SECONDS
467 Set timeout for return of results from each test runner process.
468 [NOSE_PROCESS_TIMEOUT]
470 --process-restartworker
472 If set, will restart each worker process once their tests are done,
473 this helps control memory leaks from killing the system.
474 [NOSE_PROCESS_RESTARTWORKER]
478 Enable plugin Xunit: This plugin provides test results in the
479 standard XUnit XML format. [NOSE_WITH_XUNIT]
483 Path to xml file to store the xunit report in. Default is
484 nosetests.xml in the working directory [NOSE_XUNIT_FILE]
488 Enable plugin AllModules: Collect tests from all python modules.
493 Enable collect-only: Collect and output test names only, don't run
494 any tests. [COLLECT_ONLY]