1nosetests(1) User Commands nosetests(1)
2
6 nosetests - nicer testing for python
7
10 nosetests [options] [names]
11
15 nose collects tests automatically from python source files, directories
16 and packages found in its working directory (which defaults to the cur‐
17 rent working directory). Any python source file, directory or package
18 that matches the testMatch regular expression (by default:
19 (?:^|[b_.-])[Tt]est) will be collected as a test (or source for collec‐
20 tion of tests). In addition, all other packages found in the working
21 directory will be examined for python source files or directories that
22 match testMatch. Package discovery descends all the way down the tree,
23 so package.tests and package.sub.tests and package.sub.sub2.tests will
24 all be collected.
25 Within a test directory or package, any python source file matching
27 testMatch will be examined for test cases. Within a test module, func‐
28 tions and classes whose names match testMatch and TestCase subclasses
29 with any name will be loaded and executed as tests. Tests may use the
30 assert keyword or raise AssertionErrors to indicate test failure. Test‐
31 Case subclasses may do the same or use the various TestCase methods
32 available.
33 Selecting Tests
37 To specify which tests to run, pass test names on the command line:
38 nosetests only_test_this.py
41 Test names specified may be file or module names, and may optionally
42 indicate the test case to run by separating the module or file name
43 from the test case name with a colon. Filenames may be relative or
44 absolute. Examples:
45 nosetests test.module
48 nosetests another.test:TestCase.test_method
49 nosetests a.test:TestCase
50 nosetests /path/to/test/file.py:test_function
51 You may also change the working directory where nose looks for tests by
52 using the -w switch:
53 nosetests -w /path/to/tests
56 Note, however, that support for multiple -w arguments is now deprecated
57 and will be removed in a future release. As of nose 0.10, you can get
58 the same behavior by specifying the target directories without the -w
59 switch:
60 nosetests /path/to/tests /another/path/to/tests
63 Further customization of test selection and loading is possible through
64 the use of plugins.
65 Test result output is identical to that of unittest, except for the
67 additional features (error classes, and plugin-supplied features such
68 as output capture and assert introspection) detailed in the options
69 below.
70 Configuration
74 In addition to passing command-line options, you may also put configu‐
75 ration options in your project´s setup.cfg file, or a .noserc or
76 nose.cfg file in your home directory. In any of these standard
77 [nosetests] section. Options are the same as on the command line, with
78 the -- prefix removed. For options that are simple switches, you must
79 supply a value:
80 [nosetests]
83 verbosity=3
84 with-doctest=1
85 All configuration files that are found will be loaded and their options
86 combined. You can override the standard config file loading with the -c
87 option.
88 Using Plugins
92 There are numerous nose plugins available via easy_install and else‐
93 where. To use a plugin, just install it. The plugin will add command
94 line options to nosetests. To verify that the plugin is installed, run:
95 nosetests --plugins
98 You can add -v or -vv to that command to show more information about
99 each plugin.
100 If you are running nose.main() or nose.run() from a script, you can
102 specify a list of plugins to use by passing a list of plugins with the
103 plugins keyword argument.
104 0.9 plugins
108 nose 0.11 can use SOME plugins that were written for nose 0.9. The
109 default plugin manager inserts a compatibility wrapper around 0.9 plug‐
110 ins that adapts the changed plugin api calls. However, plugins that
111 access nose internals are likely to fail, especially if they attempt to
112 access test case or test suite classes. For example, plugins that try
113 to determine if a test passed to startTest is an individual test or a
114 suite will fail, partly because suites are no longer passed to
115 startTest and partly because it´s likely that the plugin is trying to
116 find out if the test is an instance of a class that no longer exists.
117 0.10 plugins
121 All plugins written for nose 0.10 should work with nose 0.11.
122 Options
126 -V, --version
127 Output nose version and exit
128 -p, --plugins
132 Output list of available plugins and exit. Combine with higher
133 verbosity for greater detail
134 -v=DEFAULT, --verbose=DEFAULT
138 Be more verbose. [NOSE_VERBOSE]
139 --verbosity=VERBOSITY
143 Set verbosity; --verbosity=2 is the same as -v
144 -q=DEFAULT, --quiet=DEFAULT
148 Be less verbose
149 -c=FILES, --config=FILES
153 Load configuration from config file(s). May be specified multi‐
154 ple times; in that case, all config files will be loaded and
155 combined
156 -w=WHERE, --where=WHERE
160 Look for tests in this directory. May be specified multiple
161 times. The first directory passed will be used as the working
162 directory, in place of the current working directory, which is
163 the default. Others will be added to the list of tests to exe‐
164 cute. [NOSE_WHERE]
165 -m=REGEX, --match=REGEX, --testmatch=REGEX
169 Files, directories, function names, and class names that match
170 this regular expression are considered tests. Default:
171 (?:^|[b_./-])[Tt]est [NOSE_TESTMATCH]
172 --tests=NAMES
176 Run these tests (comma-separated list). This argument is useful
177 mainly from configuration files; on the command line, just pass
178 the tests to run as additional arguments with no switch.
179 -l=DEFAULT, --debug=DEFAULT
183 Activate debug logging for one or more systems. Available debug
184 loggers: nose, nose.importer, nose.inspector, nose.plugins,
185 nose.result and nose.selector. Separate multiple names with a
186 comma.
187 --debug-log=FILE
191 Log debug messages to this file (default: sys.stderr)
192 --logging-config=FILE, --log-config=FILE
196 Load logging config from this file -- bypasses all other logging
197 config settings.
198 -e=REGEX, --exclude=REGEX
202 Don´t run tests that match regular expression [NOSE_EXCLUDE]
203 -i=REGEX, --include=REGEX
207 This regular expression will be applied to files, directories,
208 function names, and class names for a chance to include addi‐
209 tional tests that do not match TESTMATCH. Specify this option
210 multiple times to add more regular expressions [NOSE_INCLUDE]
211 -x, --stop
215 Stop running tests after the first error or failure
216 -P, --no-path-adjustment
220 Don´t make any changes to sys.path when loading tests
221 [NOSE_NOPATH]
222 --exe Look for tests in python modules that are executable. Normal
226 behavior is to exclude executable modules, since they may not be
227 import-safe [NOSE_INCLUDE_EXE]
228 --noexe
232 DO NOT look for tests in python modules that are executable.
233 (The default on the windows platform is to do so.)
234 --traverse-namespace
238 Traverse through all path entries of a namespace package
239 --first-package-wins=DEFAULT, --first-pkg-wins=DEFAULT,
243 --1st-pkg-wins=DEFAULT
244 nose´s importer will normally evict a package from sys.modules
245 if it sees a package with the same name in a different location.
246 Set this option to disable that behavior.
247 -a=ATTR, --attr=ATTR
251 Run only tests that have attributes specified by ATTR
252 [NOSE_ATTR]
253 -A=EXPR, --eval-attr=EXPR
257 Run only tests for whose attributes the Python expression EXPR
258 evaluates to True [NOSE_EVAL_ATTR]
259 -s, --nocapture
263 Don´t capture stdout (any stdout output will be printed immedi‐
264 ately) [NOSE_NOCAPTURE]
265 --nologcapture
269 Disable logging capture plugin. Logging configurtion will be
270 left intact. [NOSE_NOLOGCAPTURE]
271 --logging-format=FORMAT
275 Specify custom format to print statements. Uses the same format
276 as used by standard logging handlers. [NOSE_LOGFORMAT]
277 --logging-datefmt=FORMAT
281 Specify custom date/time format to print statements. Uses the
282 same format as used by standard logging handlers. [NOSE_LOG‐
283 DATEFMT]
284 --logging-filter=FILTER
288 Specify which statements to filter in/out. By default, every‐
289 thing is captured. If the output is too verbose, use this option
290 to filter out needless output. Example: filter=foo will capture
291 statements issued ONLY to
292 foo or foo.what.ever.sub but not foobar or other logger. Spec‐
293 ify multiple loggers with comma: filter=foo,bar,baz. If any
294 logger name is prefixed with a minus, eg filter=-foo, it will be
295 excluded rather than included. Default: exclude logging messages
296 from nose itself (-nose). [NOSE_LOGFILTER]
297 --logging-clear-handlers
301 Clear all other logging handlers
302 --with-coverage
306 Enable plugin Coverage: Activate a coverage report using Ned
307 Batchelder´s coverage module.
308 [NOSE_WITH_COVERAGE]
309 --cover-package=PACKAGE
313 Restrict coverage output to selected packages [NOSE_COVER_PACK‐
314 AGE]
315 --cover-erase
319 Erase previously collected coverage statistics before run
320 --cover-tests
324 Include test modules in coverage report [NOSE_COVER_TESTS]
325 --cover-inclusive
329 Include all python files under working directory in coverage
330 report. Useful for discovering holes in test coverage if not
331 all files are imported by the test suite. [NOSE_COVER_INCLUSIVE]
332 --cover-html
336 Produce HTML coverage information
337 --cover-html-dir=DIR
341 Produce HTML coverage information in dir
342 --pdb Drop into debugger on errors
346 --pdb-failures
350 Drop into debugger on failures
351 --no-deprecated
355 Disable special handling of DeprecatedTest exceptions.
356 --with-doctest
360 Enable plugin Doctest: Activate doctest plugin to find and run
361 doctests in non-test modules.
362 [NOSE_WITH_DOCTEST]
363 --doctest-tests
367 Also look for doctests in test modules. Note that classes, meth‐
368 ods and functions should have either doctests or non-doctest
369 tests, not both. [NOSE_DOCTEST_TESTS]
370 --doctest-extension=EXT
374 Also look for doctests in files with this extension
375 [NOSE_DOCTEST_EXTENSION]
376 --doctest-result-variable=VAR
380 Change the variable name set to the result of the last inter‐
381 preter command from the default ´_´. Can be used to avoid con‐
382 flicts with the _() function used for text translation.
383 [NOSE_DOCTEST_RESULT_VAR]
384 --doctest-fixtures=SUFFIX
388 Find fixtures for a doctest file in module with this name
389 appended to the base name of the doctest file
390 --with-isolation
394 Enable plugin IsolationPlugin: Activate the isolation plugin to
395 isolate changes to external modules to a single test module or
396 package. The isolation plugin resets the contents of sys.modules
397 after each test module or package runs to its state before the
398 test. PLEASE NOTE that this plugin should not be used with the
399 coverage plugin, or in any other case where module reloading may
400 produce undesirable side-effects.
401 [NOSE_WITH_ISOLATION]
402 -d, --detailed-errors, --failure-detail
406 Add detail to error output by attempting to evaluate failed
407 asserts [NOSE_DETAILED_ERRORS]
408 --with-profile
412 Enable plugin Profile: Use this plugin to run tests using the
413 hotshot profiler.
414 [NOSE_WITH_PROFILE]
415 --profile-sort=SORT
419 Set sort order for profiler output
420 --profile-stats-file=FILE
424 Profiler stats file; default is a new temp file on each run
425 --profile-restrict=RESTRICT
429 Restrict profiler output. See help for pstats.Stats for details
430 --no-skip
434 Disable special handling of SkipTest exceptions.
435 --with-id
439 Enable plugin TestId: Activate to add a test id (like #1) to
440 each test name output. Activate with --failed to rerun failing
441 tests only.
442 [NOSE_WITH_ID]
443 --id-file=FILE
447 Store test ids found in test runs in this file. Default is the
448 file .noseids in the working directory.
449 --failed
453 Run the tests that failed in the last test run.
454 --processes=NUM
458 Spread test run among this many processes. Set a number equal to
459 the number of processors or cores in your machine for best
460 results. [NOSE_PROCESSES]
461 --process-timeout=SECONDS
465 Set timeout for return of results from each test runner process.
466 [NOSE_PROCESS_TIMEOUT]
467 --with-xunit
471 Enable plugin Xunit: This plugin provides test results in the
472 standard XUnit XML format. [NOSE_WITH_XUNIT]
473 --xunit-file=FILE
477 Path to xml file to store the xunit report in. Default is
478 nosetests.xml in the working directory [NOSE_XUNIT_FILE]
479 --all-modules
483 Enable plugin AllModules: Collect tests from all python modules.
484 [NOSE_ALL_MODULES]
485 --collect-only
489 Enable collect-only: Collect and output test names only, don´t
490 run any tests.
491 [COLLECT_ONLY]
492
496 jpellerin+nose@gmail.com
497
500 LGPL
5010.11 2009-04-23 nosetests(1)