NOSETESTS(1)

📦 version 1.3.7, in debian bookworm, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ NOSETESTS(1) ✨

the <code>nose</code> manual page 🫶 aka the nicer-testing-for-Python girlies' bible

💖 NAME 💖

nosetests — Nicer testing for Python 🎀

🌸 NICER TESTING FOR PYTHON 🌸

✨ SYNOPSIS ✨

nosetests [options] [names]

🦋 DESCRIPTION 🦋

okay so bestie, here's the tea 🍓 — nose collects tests automatically from python source files, directories and packages it finds in its working directory (and yeah, that defaults to the current working directory, no cap). Any python source file, directory or package that matches the testMatch regular expression gets collected as a test (or as a source for collecting tests). The default testMatch is:

(?:^|[b_.-])[Tt]est

and also? Every other package chillin' in the working directory gets examined for python source files or directories that match testMatch too. Package discovery descends all the way down the tree — like, package.tests and package.sub.tests and package.sub.sub2.tests will all be collected. it's giving thorough 💅

Within a test directory or package, any python source file matching testMatch will be examined for test cases. Within a test module, functions and classes whose names match testMatch, plus TestCase subclasses with any name, get loaded and executed as tests. Tests may use the assert keyword or raise AssertionErrors to indicate test failure. TestCase subclasses may do the same, or use the various TestCase methods available. iconic behavior honestly 👑

⚠️ IMPORTANT SIS: the default behavior of nose is to not include tests from files which are executable. To include tests from such files, remove their executable bit or use the --exe flag (see the Options section below). don't say I didn't warn you 😭

🎀 Selecting Tests 🎀

To specify which tests to run, pass test names on the command line:

nosetests only_test_this.py

Test names specified may be file or module names, and may optionally indicate the test case to run by separating the module or file name from the test case name with a colon. Filenames may be relative or absolute. Examples, periodt:

nosetests test.module
nosetests another.test:TestCase.test_method
nosetests a.test:TestCase
nosetests /path/to/test/file.py:test_function

You may also change the working directory where nose looks for tests by using the -w switch:

nosetests -w /path/to/tests
🚨 but heads up: support for multiple -w arguments is now deprecated and will be removed in a future release. As of nose 0.10, you can get the same behavior by specifying the target directories without the -w switch:
nosetests /path/to/tests /another/path/to/tests

Further customization of test selection and loading is possible through the use of plugins 🧚

Test result output is identical to that of unittest, except for the additional features (error classes, and plugin-supplied features such as output capture and assert introspection) detailed in the options below. same energy, extra sparkle ✨

💜 Configuration 💜

In addition to passing command-line options, you may also put configuration options in your project's setup.cfg file, or a .noserc or nose.cfg file in your home directory 🏠 In any of these standard ini-style config files, you put your nosetests configuration in a [nosetests] section. Options are the same as on the command line, with the -- prefix removed. For options that are simple switches, you must supply a value:

[nosetests]
verbosity=3
with-doctest=1

All configuration files that are found will be loaded and their options combined. You can override the standard config file loading with the -c option. so much power 💅

🌈 Using Plugins 🌈

There are numerous nose plugins available via easy_install and elsewhere. To use a plugin, just install it. The plugin will add command line options to nosetests. To verify that the plugin is installed, run:

nosetests --plugins

You can add -v or -vv to that command to show more information about each plugin. slay 🫶

If you are running nose.main() or nose.run() from a script, you can specify a list of plugins to use by passing a list of plugins with the plugins keyword argument.

🧚 0.9 plugins

nose 1.0 can use SOME plugins that were written for nose 0.9. The default plugin manager inserts a compatibility wrapper around 0.9 plugins that adapts the changed plugin api calls. However — and this is the part where it gets a little rough 😭 — plugins that access nose internals are likely to fail, especially if they attempt to access test case or test suite classes. For example, plugins that try to determine if a test passed to startTest is an individual test or a suite will fail, partly because suites are no longer passed to startTest and partly because it's likely that the plugin is trying to find out if the test is an instance of a class that no longer exists. 💀

🌟 0.10 and 0.11 plugins

All plugins written for nose 0.10 and 0.11 should work with nose 1.0. no cap, they're fine 💖

👑 Options 👑

  • -V, --version — Output nose version and exit
  • -p, --plugins — Output list of available plugins and exit. Combine with higher verbosity for greater detail
  • -v=DEFAULT, --verbose=DEFAULT — Be more verbose. [NOSE_VERBOSE]
  • --verbosity=VERBOSITY — Set verbosity; --verbosity=2 is the same as -v
  • -q=DEFAULT, --quiet=DEFAULT — Be less verbose
  • -c=FILES, --config=FILES — Load configuration from config file(s). May be specified multiple times; in that case, all config files will be loaded and combined
  • -w=WHERE, --where=WHERE — Look for tests in this directory. May be specified multiple times. The first directory passed will be used as the working directory, in place of the current working directory, which is the default. Others will be added to the list of tests to execute. [NOSE_WHERE]
  • --py3where=PY3WHERE — Look for tests in this directory under Python 3.x. Functions the same as where, but only applies if running under Python 3.x or above. Note that, if present under 3.x, this option completely replaces any directories specified with where, so the where option becomes ineffective. [NOSE_PY3WHERE]
  • -m=REGEX, --match=REGEX, --testmatch=REGEX — Files, directories, function names, and class names that match this regular expression are considered tests. Default: (?:^|[b_./-])[Tt]est [NOSE_TESTMATCH]
  • --tests=NAMES — Run these tests (comma-separated list). This argument is useful mainly from configuration files; on the command line, just pass the tests to run as additional arguments with no switch.
  • -l=DEFAULT, --debug=DEFAULT — Activate debug logging for one or more systems. Available debug loggers: nose, nose.importer, nose.inspector, nose.plugins, nose.result and nose.selector. Separate multiple names with a comma.
  • --debug-log=FILE — Log debug messages to this file (default: sys.stderr)
  • --logging-config=FILE, --log-config=FILE — Load logging config from this file — bypasses all other logging config settings.
  • -I=REGEX, --ignore-files=REGEX — Completely ignore any file that matches this regular expression. Takes precedence over any other settings or plugins. Specifying this option will replace the default setting. Specify this option multiple times to add more regular expressions [NOSE_IGNORE_FILES]
  • -e=REGEX, --exclude=REGEX — Don't run tests that match regular expression [NOSE_EXCLUDE]
  • -i=REGEX, --include=REGEX — This regular expression will be applied to files, directories, function names, and class names for a chance to include additional tests that do not match TESTMATCH. Specify this option multiple times to add more regular expressions [NOSE_INCLUDE]
  • -x, --stop — Stop running tests after the first error or failure
  • -P, --no-path-adjustment — Don't make any changes to sys.path when loading tests [NOSE_NOPATH]
  • --exe — Look for tests in python modules that are executable. Normal behavior is to exclude executable modules, since they may not be import-safe [NOSE_INCLUDE_EXE]
  • --noexe — DO NOT look for tests in python modules that are executable. (The default on the windows platform is to do so.)
  • --traverse-namespace — Traverse through all path entries of a namespace package
  • --first-package-wins, --first-pkg-wins, --1st-pkg-wins — nose's importer will normally evict a package from sys.modules if it sees a package with the same name in a different location. Set this option to disable that behavior.
  • --no-byte-compile — Prevent nose from byte-compiling the source into .pyc files while nose is scanning for and running tests.
  • -a=ATTR, --attr=ATTR — Run only tests that have attributes specified by ATTR [NOSE_ATTR]
  • -A=EXPR, --eval-attr=EXPR — Run only tests for whose attributes the Python expression EXPR evaluates to True [NOSE_EVAL_ATTR]
  • -s, --nocapture — Don't capture stdout (any stdout output will be printed immediately) [NOSE_NOCAPTURE]
  • --nologcapture — Disable logging capture plugin. Logging configuration will be left intact. [NOSE_NOLOGCAPTURE]
  • --logging-format=FORMAT — Specify custom format to print statements. Uses the same format as used by standard logging handlers. [NOSE_LOGFORMAT]
  • --logging-datefmt=FORMAT — Specify custom date/time format to print statements. Uses the same format as used by standard logging handlers. [NOSE_LOGDATEFMT]
  • --logging-filter=FILTER — Specify which statements to filter in/out. By default, everything is captured. If the output is too verbose, use this option to filter out needless output. Example: filter=foo will capture statements issued ONLY to foo or foo.what.ever.sub but not foobar or other logger. Specify multiple loggers with comma: filter=foo,bar,baz. If any logger name is prefixed with a minus, eg filter=-foo, it will be excluded rather than included. Default: exclude logging messages from nose itself (-nose). [NOSE_LOGFILTER]
  • --logging-clear-handlers — Clear all other logging handlers
  • --logging-level=DEFAULT — Set the log level to capture
  • --with-coverage — Enable plugin Coverage: Activate a coverage report using Ned Batchelder's coverage module. [NOSE_WITH_COVERAGE]
  • --cover-package=PACKAGE — Restrict coverage output to selected packages [NOSE_COVER_PACKAGE]
  • --cover-erase — Erase previously collected coverage statistics before run
  • --cover-tests — Include test modules in coverage report [NOSE_COVER_TESTS]
  • --cover-min-percentage=DEFAULT — Minimum percentage of coverage for tests to pass [NOSE_COVER_MIN_PERCENTAGE]

to be continued bestie… more of this page is coming 💖

  • --cover-inclusive — bestie this one scoops up every single python file chilling under your working directory and drags them into the coverage report. it's giving detective energy 🔍 — lowkey the best way to spot holes in your coverage when your test suite isn't even importing all your files. [NOSE_COVER_INCLUSIVE]
  • --cover-html — produce HTML coverage info ✨ cute little clickable report, we love to see it.
  • --cover-html-dir=DIR — same HTML coverage tea but drop it in DIR 💅
  • --cover-branches — now we're including branch coverage in the report, not just line coverage. main character coverage fr. [NOSE_COVER_BRANCHES]
  • --cover-xml — produce XML coverage info 🌈 for the machines, iykyk
  • --cover-xml-file=FILE — XML coverage info, but in FILE specifically 🎀
  • --pdb — failures or errors? we're dropping straight into the debugger 😭 no escape, no cap
  • --pdb-failures — only drop into the debugger on failures, not errors
  • --pdb-errors — only drop into the debugger on errors, not failures
  • --no-deprecated — turns OFF the special handling of DeprecatedTest exceptions. bye special treatment 💀
  • --with-doctest — enables the plugin Doctest: turns on the doctest plugin so it goes hunting for and runs doctests inside your non-test modules 🕵️♀️ [NOSE_WITH_DOCTEST]
  • --doctest-tests — also look for doctests inside test modules. ⚠️ but bestie, heads up: classes, methods and functions should have either doctests or non-doctest tests, not both. pick a lane 🫶 [NOSE_DOCTEST_TESTS]
  • --doctest-extension=EXT — also look for doctests in files with this extension, EXT 🌸 [NOSE_DOCTEST_EXTENSION]
  • --doctest-result-variable=VAR — changes the variable name that gets set to the result of the last interpreter command. default is '_'. use this when you need to dodge a conflict with the _() function used for text translation 🙈 [NOSE_DOCTEST_RESULT_VAR]
  • --doctest-fixtures=SUFFIX — find fixtures for a doctest file in the module whose name is the doctest file's base name with SUFFIX stuck on the end 💜
  • --doctest-options=OPTIONS — pass options straight through to doctest. eg. '+ELLIPSIS,+NORMALIZE_WHITESPACE' ✨
  • --with-isolation — enables the plugin IsolationPlugin: the isolation plugin isolates changes to external modules down to a single test module or package. it resets the contents of sys.modules after each test module or package runs, back to whatever state it was in before that test. 🧚
PLEASE NOTE that this plugin should not be used with the coverage plugin, or in any other case where module reloading may produce undesirable side-effects. fr fr do not do it 😭

[NOSE_WITH_ISOLATION]

  • -d, --detailed-errors, --failure-detail — adds detail to your error output by attempting to evaluate the asserts that failed 💅 [NOSE_DETAILED_ERRORS]
  • --with-profile — enables the plugin Profile: use this one to run your tests with the hotshot profiler 🔥 [NOSE_WITH_PROFILE]
  • --profile-sort=SORT — sets the sort order for the profiler output 👑
  • --profile-stats-file=FILE — the profiler stats file. default? a fresh new temp file on every single run, iconic behavior 🎀
  • --profile-restrict=RESTRICT — restricts the profiler output. see the help for pstats.Stats for the details 📖
  • --no-skip — disables the special handling of SkipTest exceptions. no more skipping, we stay ✋
  • --with-id — enables the plugin TestId: activate it and every test name in the output gets a test id like #1. pair it with --failed to rerun only the failing tests 🦋 [NOSE_WITH_ID]
  • --id-file=FILE — stores the test ids found during test runs in this file. default is the file .noseids in the working directory 🌸
  • --failed — runs the tests that failed in the last test run. round two, let's get it 🔥
  • --processes=NUM — spreads the test run across this many processes. set it equal to your machine's number of processors or cores for best results ✨. pass a negative number and the process count gets automatically set to the number of cores. passing 0 means parallel testing is disabled. default is 0 unless NOSE_PROCESSES is set. [NOSE_PROCESSES]
  • --process-timeout=SECONDS — sets the timeout for results coming back from each test runner process. default is 10. [NOSE_PROCESS_TIMEOUT]
  • --process-restartworker — if set, each worker process gets restarted once its tests are done. helps control memory leaks before they kill the whole system 💀 [NOSE_PROCESS_RESTARTWORKER]
  • --with-xunit — enables the plugin Xunit: delivers test results in the standard XUnit XML format 👑 [NOSE_WITH_XUNIT]
  • --xunit-file=FILE — path to the xml file where the xunit report goes. default is nosetests.xml in the working directory 🌈 [NOSE_XUNIT_FILE]
  • --xunit-testsuite-name=PACKAGE — the name of the testsuite in the xunit xml that the plugin generates. default testsuite name is nosetests. [NOSE_XUNIT_FILE]… ok ngl this one's just --xunit-testsuite-name=PACKAGE, no env var listed for it bestie 🙈
  • --all-modules — enables the plugin AllModules: collects tests from all python modules 🫶 [NOSE_ALL_MODULES]
  • --collect-only — enables collect-only: collects and outputs the test names only, doesn't run a single test. we're just looking respectfully 👀 [COLLECT_ONLY]

✨ AUTHOR ✨

Nose developers 💖

2009, Jason Pellerin

and that's a wrap bestie 🎀 this was nosetests version 1.3, dated April 04, 2015 — go forth and let your tests slay 💅✨

📦 where this page comes from