1nosetests(1)                     User Commands                    nosetests(1)
2
3
4

NAME

6       nosetests - nicer testing for python
7
8

SYNOPSIS

10       nosetests [options] [names]
11
12
13

DESCRIPTION

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

AUTHOR

496       jpellerin+nose@gmail.com
497
498
500       LGPL
501
502
503
504
5050.11                              2009-04-23                      nosetests(1)
Impressum