1NOSETESTS(1)                         nose                         NOSETESTS(1)
2
3
4

NAME

6       nosetests - Nicer testing for Python
7

NICER TESTING FOR PYTHON

9   SYNOPSIS
10          nosetests [options] [names]
11
12   DESCRIPTION
13       nose collects tests automatically from python source files, directories
14       and packages found in its working directory (which defaults to the cur‐
15       rent  working  directory). Any python source file, directory or package
16       that  matches   the   testMatch   regular   expression   (by   default:
17       (?:^|[b_.-])[Tt]est) will be collected as a test (or source for collec‐
18       tion of tests). In addition, all other packages found  in  the  working
19       directory  will be examined for python source files or directories that
20       match testMatch. Package discovery descends all the way down the  tree,
21       so  package.tests and package.sub.tests and package.sub.sub2.tests will
22       all be collected.
23
24       Within a test directory or package, any  python  source  file  matching
25       testMatch  will be examined for test cases. Within a test module, func‐
26       tions and classes whose names match testMatch and  TestCase  subclasses
27       with  any  name will be loaded and executed as tests. Tests may use the
28       assert keyword or raise AssertionErrors to indicate test failure. Test‐
29       Case  subclasses  may  do  the same or use the various TestCase methods
30       available.
31
32       It is important to note that the default behavior of  nose  is  to  not
33       include  tests  from files which are executable.  To include tests from
34       such files, remove their executable bit or  use  the  --exe  flag  (see
35       'Options' section below).
36
37   Selecting Tests
38       To specify which tests to run, pass test names on the command line:
39
40          nosetests only_test_this.py
41
42       Test  names  specified  may be file or module names, and may optionally
43       indicate the test case to run by separating the  module  or  file  name
44       from  the  test  case  name  with a colon. Filenames may be relative or
45       absolute. Examples:
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
52       You may also change the working directory where nose looks for tests by
53       using the -w switch:
54
55          nosetests -w /path/to/tests
56
57       Note, however, that support for multiple -w arguments is now deprecated
58       and will be removed in a future release. As of nose 0.10, you  can  get
59       the  same  behavior by specifying the target directories without the -w
60       switch:
61
62          nosetests /path/to/tests /another/path/to/tests
63
64       Further customization of test selection and loading is possible through
65       the use of plugins.
66
67       Test  result  output  is  identical to that of unittest, except for the
68       additional features (error classes, and plugin-supplied  features  such
69       as  output  capture  and  assert introspection) detailed in the options
70       below.
71
72   Configuration
73       In addition to passing command-line options, you may also put  configu‐
74       ration  options  in  your  project's  setup.cfg  file,  or a .noserc or
75       nose.cfg file  in  your  home  directory.  In  any  of  these  standard
76       ini-style  config  files,  you  put  your  nosetests configuration in a
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          [nosetests]
82          verbosity=3
83          with-doctest=1
84
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   Using Plugins
90       There are numerous nose plugins available via  easy_install  and  else‐
91       where.  To  use  a plugin, just install it. The plugin will add command
92       line options to nosetests. To verify that the plugin is installed, run:
93
94          nosetests --plugins
95
96       You can add -v or -vv to that command to show  more  information  about
97       each plugin.
98
99       If  you  are  running  nose.main() or nose.run() from a script, you can
100       specify a list of plugins to use by passing a list of plugins with  the
101       plugins keyword argument.
102
103   0.9 plugins
104       nose  1.0  can  use  SOME  plugins  that were written for nose 0.9. The
105       default plugin manager inserts a compatibility wrapper around 0.9 plug‐
106       ins  that  adapts  the  changed plugin api calls. However, plugins that
107       access nose internals are likely to fail, especially if they attempt to
108       access  test  case or test suite classes. For example, plugins that try
109       to determine if a test passed to startTest is an individual test  or  a
110       suite  will  fail,  partly  because  suites  are  no  longer  passed to
111       startTest and partly because it's likely that the plugin is  trying  to
112       find out if the test is an instance of a class that no longer exists.
113
114   0.10 and 0.11 plugins
115       All plugins written for nose 0.10 and 0.11 should work with nose 1.0.
116
117   Options
118       -V, --version
119              Output nose version and exit
120
121       -p, --plugins
122              Output  list  of available plugins and exit. Combine with higher
123              verbosity for greater detail
124
125       -v=DEFAULT, --verbose=DEFAULT
126              Be more verbose. [NOSE_VERBOSE]
127
128       --verbosity=VERBOSITY
129              Set verbosity; --verbosity=2 is the same as -v
130
131       -q=DEFAULT, --quiet=DEFAULT
132              Be less verbose
133
134       -c=FILES, --config=FILES
135              Load configuration from config file(s). May be specified  multi‐
136              ple  times;  in  that  case, all config files will be loaded and
137              combined
138
139       -w=WHERE, --where=WHERE
140              Look for tests in this  directory.  May  be  specified  multiple
141              times.  The  first  directory passed will be used as the working
142              directory, in place of the current working directory,  which  is
143              the  default.  Others will be added to the list of tests to exe‐
144              cute. [NOSE_WHERE]
145
146       --py3where=PY3WHERE
147              Look for tests in this directory under Python 3.x. Functions the
148              same as 'where', but only applies if running under Python 3.x or
149              above.  Note that, if present under 3.x, this option  completely
150              replaces  any directories specified with 'where', so the 'where'
151              option becomes ineffective. [NOSE_PY3WHERE]
152
153       -m=REGEX, --match=REGEX, --testmatch=REGEX
154              Files, directories, function names, and class names  that  match
155              this   regular   expression   are  considered  tests.   Default:
156              (?:^|[b_./-])[Tt]est [NOSE_TESTMATCH]
157
158       --tests=NAMES
159              Run these tests (comma-separated list). This argument is  useful
160              mainly  from configuration files; on the command line, just pass
161              the tests to run as additional arguments with no switch.
162
163       -l=DEFAULT, --debug=DEFAULT
164              Activate debug logging for one or more systems. Available  debug
165              loggers:   nose,  nose.importer,  nose.inspector,  nose.plugins,
166              nose.result and nose.selector. Separate multiple  names  with  a
167              comma.
168
169       --debug-log=FILE
170              Log debug messages to this file (default: sys.stderr)
171
172       --logging-config=FILE, --log-config=FILE
173              Load logging config from this file -- bypasses all other logging
174              config settings.
175
176       -I=REGEX, --ignore-files=REGEX
177              Completely ignore any file that matches this regular expression.
178              Takes  precedence over any other settings or plugins. Specifying
179              this option will  replace  the  default  setting.  Specify  this
180              option   multiple   times   to   add  more  regular  expressions
181              [NOSE_IGNORE_FILES]
182
183       -e=REGEX, --exclude=REGEX
184              Don't run tests that match regular expression [NOSE_EXCLUDE]
185
186       -i=REGEX, --include=REGEX
187              This regular expression will be applied to  files,  directories,
188              function  names,  and  class names for a chance to include addi‐
189              tional tests that do not match TESTMATCH.  Specify  this  option
190              multiple times to add more regular expressions [NOSE_INCLUDE]
191
192       -x, --stop
193              Stop running tests after the first error or failure
194
195       -P, --no-path-adjustment
196              Don't   make   any   changes  to  sys.path  when  loading  tests
197              [NOSE_NOPATH]
198
199       --exe  Look for tests in python modules  that  are  executable.  Normal
200              behavior is to exclude executable modules, since they may not be
201              import-safe [NOSE_INCLUDE_EXE]
202
203       --noexe
204              DO NOT look for tests in python  modules  that  are  executable.
205              (The default on the windows platform is to do so.)
206
207       --traverse-namespace
208              Traverse through all path entries of a namespace package
209
210       --first-package-wins, --first-pkg-wins, --1st-pkg-wins
211              nose's  importer  will normally evict a package from sys.modules
212              if it sees a package with the same name in a different location.
213              Set this option to disable that behavior.
214
215       --no-byte-compile
216              Prevent  nose  from  byte-compiling  the  source into .pyc files
217              while nose is scanning for and running tests.
218
219       -a=ATTR, --attr=ATTR
220              Run  only  tests  that  have  attributes   specified   by   ATTR
221              [NOSE_ATTR]
222
223       -A=EXPR, --eval-attr=EXPR
224              Run  only  tests for whose attributes the Python expression EXPR
225              evaluates to True [NOSE_EVAL_ATTR]
226
227       -s, --nocapture
228              Don't capture stdout (any stdout output will be printed  immedi‐
229              ately) [NOSE_NOCAPTURE]
230
231       --nologcapture
232              Disable  logging  capture  plugin. Logging configuration will be
233              left intact. [NOSE_NOLOGCAPTURE]
234
235       --logging-format=FORMAT
236              Specify custom format to print statements. Uses the same  format
237              as used by standard logging handlers. [NOSE_LOGFORMAT]
238
239       --logging-datefmt=FORMAT
240              Specify  custom  date/time  format to print statements. Uses the
241              same format as used by  standard  logging  handlers.  [NOSE_LOG‐
242              DATEFMT]
243
244       --logging-filter=FILTER
245              Specify  which  statements  to filter in/out. By default, every‐
246              thing is captured. If the output is too verbose, use this option
247              to filter out needless output.  Example: filter=foo will capture
248              statements issued ONLY to
249               foo or foo.what.ever.sub but not foobar or other logger.  Spec‐
250              ify  multiple  loggers  with  comma: filter=foo,bar,baz.  If any
251              logger name is prefixed with a minus, eg filter=-foo, it will be
252              excluded rather than included. Default: exclude logging messages
253              from nose itself (-nose). [NOSE_LOGFILTER]
254
255       --logging-clear-handlers
256              Clear all other logging handlers
257
258       --logging-level=DEFAULT
259              Set the log level to capture
260
261       --with-coverage
262              Enable plugin Coverage: Activate a  coverage  report  using  Ned
263              Batchelder's coverage module.
264               [NOSE_WITH_COVERAGE]
265
266       --cover-package=PACKAGE
267              Restrict  coverage output to selected packages [NOSE_COVER_PACK‐
268              AGE]
269
270       --cover-erase
271              Erase previously collected coverage statistics before run
272
273       --cover-tests
274              Include test modules in coverage report [NOSE_COVER_TESTS]
275
276       --cover-min-percentage=DEFAULT
277              Minimum   percentage   of   coverage   for   tests    to    pass
278              [NOSE_COVER_MIN_PERCENTAGE]
279
280       --cover-inclusive
281              Include  all  python  files  under working directory in coverage
282              report.  Useful for discovering holes in test  coverage  if  not
283              all files are imported by the test suite. [NOSE_COVER_INCLUSIVE]
284
285       --cover-html
286              Produce HTML coverage information
287
288       --cover-html-dir=DIR
289              Produce HTML coverage information in dir
290
291       --cover-branches
292              Include branch coverage in coverage report [NOSE_COVER_BRANCHES]
293
294       --cover-xml
295              Produce XML coverage information
296
297       --cover-xml-file=FILE
298              Produce XML coverage information in file
299
300       --pdb  Drop into debugger on failures or errors
301
302       --pdb-failures
303              Drop into debugger on failures
304
305       --pdb-errors
306              Drop into debugger on errors
307
308       --no-deprecated
309              Disable special handling of DeprecatedTest exceptions.
310
311       --with-doctest
312              Enable  plugin  Doctest: Activate doctest plugin to find and run
313              doctests in non-test modules.
314               [NOSE_WITH_DOCTEST]
315
316       --doctest-tests
317              Also look for doctests in test modules. Note that classes, meth‐
318              ods  and  functions  should  have either doctests or non-doctest
319              tests, not both. [NOSE_DOCTEST_TESTS]
320
321       --doctest-extension=EXT
322              Also  look  for  doctests   in   files   with   this   extension
323              [NOSE_DOCTEST_EXTENSION]
324
325       --doctest-result-variable=VAR
326              Change  the  variable  name set to the result of the last inter‐
327              preter command from the default '_'. Can be used to  avoid  con‐
328              flicts   with  the  _()  function  used  for  text  translation.
329              [NOSE_DOCTEST_RESULT_VAR]
330
331       --doctest-fixtures=SUFFIX
332              Find fixtures for a  doctest  file  in  module  with  this  name
333              appended to the base name of the doctest file
334
335       --doctest-options=OPTIONS
336              Specify  options  to  pass  to  doctest. Eg. '+ELLIPSIS,+NORMAL‐
337              IZE_WHITESPACE'
338
339       --with-isolation
340              Enable plugin IsolationPlugin: Activate the isolation plugin  to
341              isolate  changes  to external modules to a single test module or
342              package. The isolation plugin resets the contents of sys.modules
343              after  each  test module or package runs to its state before the
344              test. PLEASE NOTE that this plugin should not be used  with  the
345              coverage plugin, or in any other case where module reloading may
346              produce undesirable side-effects.
347               [NOSE_WITH_ISOLATION]
348
349       -d, --detailed-errors, --failure-detail
350              Add detail to error output  by  attempting  to  evaluate  failed
351              asserts [NOSE_DETAILED_ERRORS]
352
353       --with-profile
354              Enable  plugin  Profile:  Use this plugin to run tests using the
355              hotshot profiler.
356               [NOSE_WITH_PROFILE]
357
358       --profile-sort=SORT
359              Set sort order for profiler output
360
361       --profile-stats-file=FILE
362              Profiler stats file; default is a new temp file on each run
363
364       --profile-restrict=RESTRICT
365              Restrict profiler output. See help for pstats.Stats for details
366
367       --no-skip
368              Disable special handling of SkipTest exceptions.
369
370       --with-id
371              Enable plugin TestId: Activate to add a test  id  (like  #1)  to
372              each  test  name output. Activate with --failed to rerun failing
373              tests only.
374               [NOSE_WITH_ID]
375
376       --id-file=FILE
377              Store test ids found in test runs in this file. Default  is  the
378              file .noseids in the working directory.
379
380       --failed
381              Run the tests that failed in the last test run.
382
383       --processes=NUM
384              Spread test run among this many processes. Set a number equal to
385              the number of processors or  cores  in  your  machine  for  best
386              results.  Pass a negative number to have the number of processes
387              automatically set to the number of cores.  Passing  0  means  to
388              disable  parallel testing. Default is 0 unless NOSE_PROCESSES is
389              set. [NOSE_PROCESSES]
390
391       --process-timeout=SECONDS
392              Set timeout for return of results from each test runner process.
393              Default is 10. [NOSE_PROCESS_TIMEOUT]
394
395       --process-restartworker
396              If  set,  will  restart each worker process once their tests are
397              done, this helps control memory leaks from killing  the  system.
398              [NOSE_PROCESS_RESTARTWORKER]
399
400       --with-xunit
401              Enable  plugin  Xunit:  This plugin provides test results in the
402              standard XUnit XML format. [NOSE_WITH_XUNIT]
403
404       --xunit-file=FILE
405              Path to xml file to  store  the  xunit  report  in.  Default  is
406              nosetests.xml in the working directory [NOSE_XUNIT_FILE]
407
408       --xunit-testsuite-name=PACKAGE
409              Name  of  the  testsuite  in the xunit xml, generated by plugin.
410              Default test suite name is nosetests.
411
412       --all-modules
413              Enable plugin AllModules: Collect tests from all python modules.
414               [NOSE_ALL_MODULES]
415
416       --collect-only
417              Enable collect-only: Collect and output test names  only,  don't
418              run any tests.
419               [COLLECT_ONLY]
420

AUTHOR

422       Nose developers
423
425       2009, Jason Pellerin
426
427
428
429
4301.3                             April 04, 2015                    NOSETESTS(1)
Impressum