PageRenderTime 38ms CodeModel.GetById 21ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 1ms

/README.txt

https://bitbucket.org/jpellerin/nose/
Plain Text | 494 lines | 317 code | 177 blank | 0 comment | 0 complexity | 9f912c59e35f99bc430010643d0d5c11 MD5 | raw file
  1
  2Basic usage
  3***********
  4
  5Use the nosetests script (after installation by setuptools):
  6
  7   nosetests [options] [(optional) test files or directories]
  8
  9In addition to passing command-line options, you may also put
 10configuration options in a .noserc or nose.cfg file in your home
 11directory. These are standard .ini-style config files. Put your
 12nosetests configuration in a [nosetests] section, with the -- prefix
 13removed:
 14
 15   [nosetests]
 16   verbosity=3
 17   with-doctest=1
 18
 19There are several other ways to use the nose test runner besides the
 20*nosetests* script. You may use nose in a test script:
 21
 22   import nose
 23   nose.main()
 24
 25If you don't want the test script to exit with 0 on success and 1 on
 26failure (like unittest.main), use nose.run() instead:
 27
 28   import nose
 29   result = nose.run()
 30
 31*result* will be true if the test run succeeded, or false if any test
 32failed or raised an uncaught exception. Lastly, you can run nose.core
 33directly, which will run nose.main():
 34
 35   python /path/to/nose/core.py
 36
 37Please see the usage message for the nosetests script for information
 38about how to control which tests nose runs, which plugins are loaded,
 39and the test output.
 40
 41
 42Extended usage
 43==============
 44
 45nose collects tests automatically from python source files,
 46directories and packages found in its working directory (which
 47defaults to the current working directory). Any python source file,
 48directory or package that matches the testMatch regular expression (by
 49default: *(?:^|[b_.-])[Tt]est)* will be collected as a test (or source
 50for collection of tests). In addition, all other packages found in the
 51working directory will be examined for python source files or
 52directories that match testMatch. Package discovery descends all the
 53way down the tree, so package.tests and package.sub.tests and
 54package.sub.sub2.tests will all be collected.
 55
 56Within a test directory or package, any python source file matching
 57testMatch will be examined for test cases. Within a test module,
 58functions and classes whose names match testMatch and TestCase
 59subclasses with any name will be loaded and executed as tests. Tests
 60may use the assert keyword or raise AssertionErrors to indicate test
 61failure. TestCase subclasses may do the same or use the various
 62TestCase methods available.
 63
 64
 65Selecting Tests
 66---------------
 67
 68To specify which tests to run, pass test names on the command line:
 69
 70   nosetests only_test_this.py
 71
 72Test names specified may be file or module names, and may optionally
 73indicate the test case to run by separating the module or file name
 74from the test case name with a colon. Filenames may be relative or
 75absolute. Examples:
 76
 77   nosetests test.module
 78   nosetests another.test:TestCase.test_method
 79   nosetests a.test:TestCase
 80   nosetests /path/to/test/file.py:test_function
 81
 82You may also change the working directory where nose looks for tests
 83by using the -w switch:
 84
 85   nosetests -w /path/to/tests
 86
 87Note, however, that support for multiple -w arguments is now
 88deprecated and will be removed in a future release. As of nose 0.10,
 89you can get the same behavior by specifying the target directories
 90*without* the -w switch:
 91
 92   nosetests /path/to/tests /another/path/to/tests
 93
 94Further customization of test selection and loading is possible
 95through the use of plugins.
 96
 97Test result output is identical to that of unittest, except for the
 98additional features (error classes, and plugin-supplied features such
 99as output capture and assert introspection) detailed in the options
100below.
101
102
103Configuration
104-------------
105
106In addition to passing command-line options, you may also put
107configuration options in your project's *setup.cfg* file, or a .noserc
108or 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,
111with the -- prefix removed. For options that are simple switches, you
112must supply a value:
113
114   [nosetests]
115   verbosity=3
116   with-doctest=1
117
118All configuration files that are found will be loaded and their
119options combined. You can override the standard config file loading
120with the "-c" option.
121
122
123Using Plugins
124-------------
125
126There are numerous nose plugins available via easy_install and
127elsewhere. To use a plugin, just install it. The plugin will add
128command line options to nosetests. To verify that the plugin is
129installed, run:
130
131   nosetests --plugins
132
133You can add -v or -vv to that command to show more information about
134each plugin.
135
136If you are running nose.main() or nose.run() from a script, you can
137specify a list of plugins to use by passing a list of plugins with the
138plugins keyword argument.
139
140
1410.9 plugins
142-----------
143
144nose 1.0 can use SOME plugins that were written for nose 0.9. The
145default plugin manager inserts a compatibility wrapper around 0.9
146plugins that adapts the changed plugin api calls. However, plugins
147that access nose internals are likely to fail, especially if they
148attempt to access test case or test suite classes. For example,
149plugins that try to determine if a test passed to startTest is an
150individual test or a suite will fail, partly because suites are no
151longer passed to startTest and partly because it's likely that the
152plugin is trying to find out if the test is an instance of a class
153that no longer exists.
154
155
1560.10 and 0.11 plugins
157---------------------
158
159All plugins written for nose 0.10 and 0.11 should work with nose 1.0.
160
161
162Options
163-------
164
165-V, --version
166
167   Output nose version and exit
168
169-p, --plugins
170
171   Output list of available plugins and exit. Combine with higher
172   verbosity for greater detail
173
174-v=DEFAULT, --verbose=DEFAULT
175
176   Be more verbose. [NOSE_VERBOSE]
177
178--verbosity=VERBOSITY
179
180   Set verbosity; --verbosity=2 is the same as -v
181
182-q=DEFAULT, --quiet=DEFAULT
183
184   Be less verbose
185
186-c=FILES, --config=FILES
187
188   Load configuration from config file(s). May be specified multiple
189   times; in that case, all config files will be loaded and combined
190
191-w=WHERE, --where=WHERE
192
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]
197
198--py3where=PY3WHERE
199
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]
205
206-m=REGEX, --match=REGEX, --testmatch=REGEX
207
208   Files, directories, function names, and class names that match this
209   regular expression are considered tests.  Default:
210   (?:^|[b_./-])[Tt]est [NOSE_TESTMATCH]
211
212--tests=NAMES
213
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.
217
218-l=DEFAULT, --debug=DEFAULT
219
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
223   comma.
224
225--debug-log=FILE
226
227   Log debug messages to this file (default: sys.stderr)
228
229--logging-config=FILE, --log-config=FILE
230
231   Load logging config from this file -- bypasses all other logging
232   config settings.
233
234-I=REGEX, --ignore-files=REGEX
235
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]
240
241-e=REGEX, --exclude=REGEX
242
243   Don't run tests that match regular expression [NOSE_EXCLUDE]
244
245-i=REGEX, --include=REGEX
246
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]
251
252-x, --stop
253
254   Stop running tests after the first error or failure
255
256-P, --no-path-adjustment
257
258   Don't make any changes to sys.path when loading tests [NOSE_NOPATH]
259
260--exe
261
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]
265
266--noexe
267
268   DO NOT look for tests in python modules that are executable. (The
269   default on the windows platform is to do so.)
270
271--traverse-namespace
272
273   Traverse through all path entries of a namespace package
274
275--first-package-wins, --first-pkg-wins, --1st-pkg-wins
276
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.
280
281-a=ATTR, --attr=ATTR
282
283   Run only tests that have attributes specified by ATTR [NOSE_ATTR]
284
285-A=EXPR, --eval-attr=EXPR
286
287   Run only tests for whose attributes the Python expression EXPR
288   evaluates to True [NOSE_EVAL_ATTR]
289
290-s, --nocapture
291
292   Don't capture stdout (any stdout output will be printed
293   immediately) [NOSE_NOCAPTURE]
294
295--nologcapture
296
297   Disable logging capture plugin. Logging configurtion will be left
298   intact. [NOSE_NOLOGCAPTURE]
299
300--logging-format=FORMAT
301
302   Specify custom format to print statements. Uses the same format as
303   used by standard logging handlers. [NOSE_LOGFORMAT]
304
305--logging-datefmt=FORMAT
306
307   Specify custom date/time format to print statements. Uses the same
308   format as used by standard logging handlers. [NOSE_LOGDATEFMT]
309
310--logging-filter=FILTER
311
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]
320
321--logging-clear-handlers
322
323   Clear all other logging handlers
324
325--with-coverage
326
327   Enable plugin Coverage:  Activate a coverage report using Ned
328   Batchelder's coverage module.  [NOSE_WITH_COVERAGE]
329
330--cover-package=PACKAGE
331
332   Restrict coverage output to selected packages [NOSE_COVER_PACKAGE]
333
334--cover-erase
335
336   Erase previously collected coverage statistics before run
337
338--cover-tests
339
340   Include test modules in coverage report [NOSE_COVER_TESTS]
341
342--cover-inclusive
343
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]
347
348--cover-html
349
350   Produce HTML coverage information
351
352--cover-html-dir=DIR
353
354   Produce HTML coverage information in dir
355
356--cover-branches
357
358   Include branch coverage in coverage report [NOSE_COVER_BRANCHES]
359
360--cover-xml
361
362   Produce XML coverage information
363
364--cover-xml-file=FILE
365
366   Produce XML coverage information in file
367
368--pdb
369
370   Drop into debugger on errors
371
372--pdb-failures
373
374   Drop into debugger on failures
375
376--no-deprecated
377
378   Disable special handling of DeprecatedTest exceptions.
379
380--with-doctest
381
382   Enable plugin Doctest:  Activate doctest plugin to find and run
383   doctests in non-test modules.  [NOSE_WITH_DOCTEST]
384
385--doctest-tests
386
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]
390
391--doctest-extension=EXT
392
393   Also look for doctests in files with this extension
394   [NOSE_DOCTEST_EXTENSION]
395
396--doctest-result-variable=VAR
397
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]
402
403--doctest-fixtures=SUFFIX
404
405   Find fixtures for a doctest file in module with this name appended
406   to the base name of the doctest file
407
408--with-isolation
409
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]
417
418-d, --detailed-errors, --failure-detail
419
420   Add detail to error output by attempting to evaluate failed asserts
421   [NOSE_DETAILED_ERRORS]
422
423--with-profile
424
425   Enable plugin Profile:  Use this plugin to run tests using the
426   hotshot profiler.   [NOSE_WITH_PROFILE]
427
428--profile-sort=SORT
429
430   Set sort order for profiler output
431
432--profile-stats-file=FILE
433
434   Profiler stats file; default is a new temp file on each run
435
436--profile-restrict=RESTRICT
437
438   Restrict profiler output. See help for pstats.Stats for details
439
440--no-skip
441
442   Disable special handling of SkipTest exceptions.
443
444--with-id
445
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
448   only.  [NOSE_WITH_ID]
449
450--id-file=FILE
451
452   Store test ids found in test runs in this file. Default is the file
453   .noseids in the working directory.
454
455--failed
456
457   Run the tests that failed in the last test run.
458
459--processes=NUM
460
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.
463   [NOSE_PROCESSES]
464
465--process-timeout=SECONDS
466
467   Set timeout for return of results from each test runner process.
468   [NOSE_PROCESS_TIMEOUT]
469
470--process-restartworker
471
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]
475
476--with-xunit
477
478   Enable plugin Xunit: This plugin provides test results in the
479   standard XUnit XML format. [NOSE_WITH_XUNIT]
480
481--xunit-file=FILE
482
483   Path to xml file to store the xunit report in. Default is
484   nosetests.xml in the working directory [NOSE_XUNIT_FILE]
485
486--all-modules
487
488   Enable plugin AllModules: Collect tests from all python modules.
489   [NOSE_ALL_MODULES]
490
491--collect-only
492
493   Enable collect-only:  Collect and output test names only, don't run
494   any tests.  [COLLECT_ONLY]