man pages section 1: User Commands

Exit Print View

Updated: July 2014

nosetests (1)


nosetests - nicer testing for python


nosetests [options] [names]


User Commands                                        nosetests(1)

     nosetests - nicer testing for python

     nosetests [options] [names]

     nose  collects tests automatically from python source files,
     directories and packages  found  in  its  working  directory
     (which  defaults  to  the  current  working  directory). Any
     python source file, directory or package  that  matches  the
     testMatch      regular      expression      (by     default:
     (?:^|[b_.-])[Tt]est) will be collected as a test (or  source
     for  collection  of  tests). In addition, all other packages
     found in the working directory will be examined  for  python
     source  files  or  directories that match testMatch. Package
     discovery descends all the  way  down  the  tree,  so  pack-
     age.tests  and  package.sub.tests and package.sub.sub2.tests
     will all be collected.

     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  test-
     Match  and  TestCase subclasses with any name will be 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 meth-
     ods available.

  Selecting Tests
     To  specify  which tests to run, pass test names on the com-
     mand line:

     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:

     nosetests test.module
     nosetests another.test:TestCase.test_method
     nosetests a.test:TestCase
     nosetests /path/to/test/
     You  may  also change the working directory where nose looks
     for tests by using the -w switch:

0.11                 Last change: 2009-04-23                    1

User Commands                                        nosetests(1)

     nosetests -w /path/to/tests
     Note, however, that 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 pos-
     sible through the use of plugins.

     Test result output is identical to that of unittest,  except
     for  the additional features (error classes, and plugin-sup-
     plied features such as output capture and assert  introspec-
     tion) detailed in the options below.

     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
     [nosetests] section. Options are the same as on the  command
     line,  with the -- prefix removed. For options that are sim-
     ple switches, you must supply a value:

     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.

  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 informa-
     tion about each plugin.

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

0.11                 Last change: 2009-04-23                    2

User Commands                                        nosetests(1)

  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, 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.

     -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]

          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  speci-
          fied  multiple  times;  in  that case, all config files
          will be loaded and combined

0.11                 Last change: 2009-04-23                    3

User Commands                                        nosetests(1)

     -w=WHERE, --where=WHERE
          Look for tests in this directory. May be specified mul-
          tiple 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]

          Look for tests in  this  directory  under  Python  3.x.
          Functions the same as 'where', but only applies if run-
          ning under Python 3.x or above.  Note that, if  present
          under 3.x, this option completely replaces any directo-
          ries 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]

          Run  these  tests (comma-separated list). This argument
          is useful mainly from configuration files; on the  com-
          mand  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.  Avail-
          able  debug  loggers: nose, nose.importer, nose.inspec-
          tor, nose.plugins, nose.result and nose.selector. Sepa-
          rate multiple names with a comma.

          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.

0.11                 Last change: 2009-04-23                    4

User Commands                                        nosetests(1)

     -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

     -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

          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]

          DO NOT look for tests in python modules that  are  exe-
          cutable.  (The default on the windows platform is to do

          Traverse through all path entries of a namespace  pack-

0.11                 Last change: 2009-04-23                    5

User Commands                                        nosetests(1)

     --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

     -a=ATTR, --attr=ATTR
          Run only tests that have attributes specified  by  ATTR

     -A=EXPR, --eval-attr=EXPR
          Run  only tests for whose attributes the Python expres-
          sion EXPR evaluates to True [NOSE_EVAL_ATTR]

     -s, --nocapture
          Don't capture stdout (any stdout output will be printed
          immediately) [NOSE_NOCAPTURE]

          Disable  logging  capture  plugin. Logging configurtion
          will be left intact. [NOSE_NOLOGCAPTURE]

          Specify custom format to  print  statements.  Uses  the
          same  format  as  used  by  standard  logging handlers.

          Specify custom date/time format  to  print  statements.
          Uses  the  same format as used by standard logging han-
          dlers. [NOSE_LOGDATEFMT]

          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.   Exam-
          ple: filter=foo will capture statements issued ONLY to
           foo  or  foo.what.ever.sub  but  not  foobar  or other

0.11                 Last change: 2009-04-23                    6

User Commands                                        nosetests(1)

          logger.  Specify  multiple  loggers  with  comma:  fil-
          ter=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]

          Clear all other logging handlers

          Enable plugin  Coverage:  Activate  a  coverage  report
          using Ned Batchelder's coverage module.

          Restrict   coverage   output   to   selected   packages

          Erase previously collected coverage  statistics  before

          Include     test    modules    in    coverage    report

          Include all python files  under  working  directory  in
          coverage  report.  Useful for discovering holes in test
          coverage if not all files  are  imported  by  the  test
          suite. [NOSE_COVER_INCLUSIVE]

          Produce HTML coverage information


0.11                 Last change: 2009-04-23                    7

User Commands                                        nosetests(1)

          Produce HTML coverage information in dir

          Include    branch    coverage    in   coverage   report

          Produce XML coverage information

          Produce XML coverage information in file

          Drop into debugger on errors

          Drop into debugger on failures

          Disable special handling of DeprecatedTest  exceptions.

          Enable  plugin Doctest: Activate doctest plugin to find
          and run doctests in non-test modules.

          Also look for  doctests  in  test  modules.  Note  that
          classes,  methods  and  functions  should  have  either
          doctests    or    non-doctest    tests,    not    both.

          Also  look  for  doctests  in files with this extension

0.11                 Last change: 2009-04-23                    8

User Commands                                        nosetests(1)


          Change the variable name set to the result of the  last
          interpreter  command  from the default '_'. Can be used
          to avoid conflicts with the _() function used for  text
          translation. [NOSE_DOCTEST_RESULT_VAR]

          Find  fixtures  for  a doctest file in module with this
          name appended to the base name of the doctest file

          Enable plugin IsolationPlugin: Activate  the  isolation
          plugin to isolate changes to external modules to a sin-
          gle test module or package. The isolation plugin resets
          the  contents  of sys.modules after each test module or
          package runs to its state before the 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.

     -d, --detailed-errors, --failure-detail
          Add  detail  to  error output by attempting to evaluate
          failed asserts [NOSE_DETAILED_ERRORS]

          Enable plugin Profile: Use this  plugin  to  run  tests
          using the hotshot profiler.

          Set sort order for profiler output

          Profiler stats file; default is a new temp file on each

0.11                 Last change: 2009-04-23                    9

User Commands                                        nosetests(1)

          Restrict profiler output. See help for pstats.Stats for

          Disable special handling of SkipTest exceptions.

          Enable  plugin  TestId: Activate to add a test id (like
          #1) to each test name output. Activate with --failed to
          rerun failing tests only.

          Store test ids found in test runs in this file. Default
          is the file .noseids in the working directory.

          Run the tests that failed in the last test run.

          Spread test run among this many processes. Set a number
          equal  to  the  number  of  processors or cores in your
          machine for best results. [NOSE_PROCESSES]

          Set timeout for return of results from each test runner
          process. [NOSE_PROCESS_TIMEOUT]

          If  set,  will  restart  each worker process once their
          tests are done, this helps control  memory  leaks  from
          killing the system. [NOSE_PROCESS_RESTARTWORKER]

          Enable  plugin Xunit: This plugin provides test results

0.11                 Last change: 2009-04-23                   10

User Commands                                        nosetests(1)

          in the standard XUnit XML format. [NOSE_WITH_XUNIT]

          Path to xml file to store the xunit report in.  Default
          is    nosetests.xml    in    the    working   directory

          Enable plugin AllModules: Collect tests from all python

          Enable  collect-only:  Collect  and  output  test names
          only, don't run any tests.



     See  attributes(5)  for  descriptions   of   the   following

     |Availability   | library/python-2/nose |
     |Stability      | Uncommitted           |
     This   software   was   built   from   source  available  at   The   original
     community       source       was       downloaded       from

0.11                 Last change: 2009-04-23                   11

User Commands                                        nosetests(1)

     Further  information about this software can be found on the
     open source community  website  at

0.11                 Last change: 2009-04-23                   12