README.txt 16 KB

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