1nosetests(1) User Commands nosetests(1)
2
3
4
6 nosetests - nicer testing for python
7
8
10 nosetests [options] [names]
11
12
13
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
26 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
34
35
36 Selecting Tests
37 To specify which tests to run, pass test names on the command line:
38
39
40 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
46
47 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
54
55 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
61
62 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
66 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
71
72
73 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
81
82 [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
89
90
91 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
96
97 nosetests --plugins
98 You can add -v or -vv to that command to show more information about
99 each plugin.
100
101 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
105
106
107 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
118
119
120 0.10 plugins
121 All plugins written for nose 0.10 should work with nose 0.11.
122
123
124
125 Options
126 -V, --version
127 Output nose version and exit
128
129
130
131 -p, --plugins
132 Output list of available plugins and exit. Combine with higher
133 verbosity for greater detail
134
135
136
137 -v=DEFAULT, --verbose=DEFAULT
138 Be more verbose. [NOSE_VERBOSE]
139
140
141
142 --verbosity=VERBOSITY
143 Set verbosity; --verbosity=2 is the same as -v
144
145
146
147 -q=DEFAULT, --quiet=DEFAULT
148 Be less verbose
149
150
151
152 -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
157
158
159 -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
166
167
168 -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
173
174
175 --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
180
181
182 -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
188
189
190 --debug-log=FILE
191 Log debug messages to this file (default: sys.stderr)
192
193
194
195 --logging-config=FILE, --log-config=FILE
196 Load logging config from this file -- bypasses all other logging
197 config settings.
198
199
200
201 -e=REGEX, --exclude=REGEX
202 Don´t run tests that match regular expression [NOSE_EXCLUDE]
203
204
205
206 -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
212
213
214 -x, --stop
215 Stop running tests after the first error or failure
216
217
218
219 -P, --no-path-adjustment
220 Don´t make any changes to sys.path when loading tests
221 [NOSE_NOPATH]
222
223
224
225 --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
229
230
231 --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
235
236
237 --traverse-namespace
238 Traverse through all path entries of a namespace package
239
240
241
242 --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
248
249
250 -a=ATTR, --attr=ATTR
251 Run only tests that have attributes specified by ATTR
252 [NOSE_ATTR]
253
254
255
256 -A=EXPR, --eval-attr=EXPR
257 Run only tests for whose attributes the Python expression EXPR
258 evaluates to True [NOSE_EVAL_ATTR]
259
260
261
262 -s, --nocapture
263 Don´t capture stdout (any stdout output will be printed immedi‐
264 ately) [NOSE_NOCAPTURE]
265
266
267
268 --nologcapture
269 Disable logging capture plugin. Logging configurtion will be
270 left intact. [NOSE_NOLOGCAPTURE]
271
272
273
274 --logging-format=FORMAT
275 Specify custom format to print statements. Uses the same format
276 as used by standard logging handlers. [NOSE_LOGFORMAT]
277
278
279
280 --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
285
286
287 --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
298
299
300 --logging-clear-handlers
301 Clear all other logging handlers
302
303
304
305 --with-coverage
306 Enable plugin Coverage: Activate a coverage report using Ned
307 Batchelder´s coverage module.
308 [NOSE_WITH_COVERAGE]
309
310
311
312 --cover-package=PACKAGE
313 Restrict coverage output to selected packages [NOSE_COVER_PACK‐
314 AGE]
315
316
317
318 --cover-erase
319 Erase previously collected coverage statistics before run
320
321
322
323 --cover-tests
324 Include test modules in coverage report [NOSE_COVER_TESTS]
325
326
327
328 --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
333
334
335 --cover-html
336 Produce HTML coverage information
337
338
339
340 --cover-html-dir=DIR
341 Produce HTML coverage information in dir
342
343
344
345 --pdb Drop into debugger on errors
346
347
348
349 --pdb-failures
350 Drop into debugger on failures
351
352
353
354 --no-deprecated
355 Disable special handling of DeprecatedTest exceptions.
356
357
358
359 --with-doctest
360 Enable plugin Doctest: Activate doctest plugin to find and run
361 doctests in non-test modules.
362 [NOSE_WITH_DOCTEST]
363
364
365
366 --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
371
372
373 --doctest-extension=EXT
374 Also look for doctests in files with this extension
375 [NOSE_DOCTEST_EXTENSION]
376
377
378
379 --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
385
386
387 --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
391
392
393 --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
403
404
405 -d, --detailed-errors, --failure-detail
406 Add detail to error output by attempting to evaluate failed
407 asserts [NOSE_DETAILED_ERRORS]
408
409
410
411 --with-profile
412 Enable plugin Profile: Use this plugin to run tests using the
413 hotshot profiler.
414 [NOSE_WITH_PROFILE]
415
416
417
418 --profile-sort=SORT
419 Set sort order for profiler output
420
421
422
423 --profile-stats-file=FILE
424 Profiler stats file; default is a new temp file on each run
425
426
427
428 --profile-restrict=RESTRICT
429 Restrict profiler output. See help for pstats.Stats for details
430
431
432
433 --no-skip
434 Disable special handling of SkipTest exceptions.
435
436
437
438 --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
444
445
446 --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
450
451
452 --failed
453 Run the tests that failed in the last test run.
454
455
456
457 --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
462
463
464 --process-timeout=SECONDS
465 Set timeout for return of results from each test runner process.
466 [NOSE_PROCESS_TIMEOUT]
467
468
469
470 --with-xunit
471 Enable plugin Xunit: This plugin provides test results in the
472 standard XUnit XML format. [NOSE_WITH_XUNIT]
473
474
475
476 --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
480
481
482 --all-modules
483 Enable plugin AllModules: Collect tests from all python modules.
484 [NOSE_ALL_MODULES]
485
486
487
488 --collect-only
489 Enable collect-only: Collect and output test names only, don´t
490 run any tests.
491 [COLLECT_ONLY]
492
493
494
496 jpellerin+nose@gmail.com
497
498
500 LGPL
501
502
503
504
5050.11 2009-04-23 nosetests(1)