nose: a discovery-based unittest extension.

nose provides an alternate test discovery and running process for unittest, one that is intended to mimic the behavior of py.test as much as is reasonably possible without resorting to too much magic.

News

nose 0.9.3 is mainly a bugfix release. The one new feature is support for user configuration files: now you can put your frequently used configuration options in .noserc or nose.cfg files, rather than typing them over and over and over again. Many thanks to Antoine Pitrou for that patch, and thanks to all of the other users who reported bugs and submitted patches and suggestions.

Barring catastrophic bugs, this will be the last release of nose in the 0.9 series. An alpha release of nose 0.10 should be forthcoming within a few weeks. Details about the new features and architecture changes in nose 0.10 may be found here.

Or check out a preview of the nose 0.10 documentation.

See the changelog for details.

Install

On most UNIX-like systems, you'll probably need to run these commands as root or using sudo.

Install nose using setuptools: 

easy_install nose

Or, if you don't have setuptools installed, use the download link at right to download the source package, and install in the normal fashion: Ungzip and untar the source package, cd to the new directory, and: 

python setup.py install

If you have an older version of setuptools installed, you may see an error like this:

The required version of setuptools (>=0.6c5) is not available, and can't be installed while this script is running. Please install a more recent version first.
In that case, you'll need to update your setuptools install first, either by running: 
easy_install -U setuptools
or: 
python ez_setup.py

Basic usage

Use the nosetests script (after installation by setuptools):

nosetests [options] [(optional) test files or directories]

In addition to passing command-line options, you may also put configuration options in a .noserc or nose.cfg file in your home directory. These are standard .ini-style config files. Put your nosetests configuration in a [nosetests] section, with the -- prefix removed:

[nosetests]
verbosity=3
with-doctest

There are several other ways to use the nose test runner besides the nosetests script. You may use nose in a test script:

import nose
nose.main()

If you don't want the test script to exit with 0 on success and 1 on failure (like unittest.main), use nose.run() instead:

import nose
result = nose.run()

result will be true if the test run succeeded, or false if any test failed or raised an uncaught exception. Lastly, you can run nose.core directly, which will run nose.main():

python /path/to/nose/core.py

Please see the usage message for the nosetests script for information about how to control which tests nose runs, which plugins are loaded, and the test output.

Features

Writing tests is easier

nose collects tests from unittest.TestCase subclasses, of course. But you can also write simple test functions, and test classes that are not subclasses of unittest.TestCase. nose also supplies a number of helpful functions for writing timed tests, testing for exceptions, and other common use cases. See Writing tests and Testing tools for more.

Running tests is easier

nose collects tests automatically, as long as you follow some simple guidelines for organizing your library and test code. There's no need to manually collect test cases into test suites. Running tests is also more responsive, since nose begins running tests as soon as the first test module is loaded. See Finding and running tests for more.

Setting up your test environment is easier

nose supports fixtures at the package, module, and test case level, so expensive initialization can be done as infrequently as possible. See Fixtures for more.

Doing what you want to do is easier

nose has plugin hooks for loading, running, watching and reporting on tests and test runs. If you don't like the default collection scheme, or it doesn't suit the layout of your project, or you need reports in a format different from the unittest standard, or you need to collect some additional information about tests (like code coverage or profiling data), you can write a plugin to do so. See Writing plugins for more.

Output capture

Unless called with the -s (--nocapture) switch, nose will capture stdout during each test run, and print the captured output only for tests that fail or have errors. The captured output is printed immediately following the error or failure output for the test. (Note that output in teardown methods is captured, but can't be output with failing tests, because teardown has not yet run at the time of the failure.)

Assert introspection

When run with the -d (--detailed-errors) switch, nose will try to output additional information about the assert expression that failed with each failing test. Currently, this means that names in the assert expression will be expanded into any values found for them in the locals or globals in the frame in which the expression executed.

In other words if you have a test like:

def test_integers():
    a = 2
    assert a == 4, "assert 2 is 4"

You will get output like:

File "/path/to/file.py", line XX, in test_integers:
      assert a == 4, "assert 2 is 4"
AssertionError: assert 2 is 4
  >>  assert 2 == 4, "assert 2 is 4"

Please note that dotted names are not expanded, and callables are not called in the expansion.

Setuptools integration

nose may be used with the setuptools test command. Simply specify nose.collector as the test suite in your setup file:

setup (
    # ...
    test_suite = 'nose.collector'
)

Then to find and run tests, you can run:

python setup.py test

When running under setuptools, you can configure nose settings via the environment variables detailed in the nosetests script usage message.

Please note that when run under the setuptools test command, some plugins will not be available, including the builtin coverage, profiler, and missed test plugins.

nose also includes its own setuptools command, nosetests, that provides support for all plugins and command line options, as well as configuration using the setup.cfg file. See nose.commands for more information about the nosetests command.

Writing tests

As with py.test, nose tests need not be subclasses of unittest.TestCase. Any function or class that matches the configured testMatch regular expression ((?:^|[b_.-])[Tt]est) by default) and lives in a module that also matches that expression will be run as a test. For the sake of compatibility with legacy unittest test cases, nose will also load tests from unittest.TestCase subclasses just like unittest does. Like py.test, functional tests will be run in the order in which they appear in the module file. TestCase derived tests and other test classes are run in alphabetical order.

Fixtures

nose supports fixtures (setup and teardown methods) at the package, module, and test level. As with py.test or unittest fixtures, setup always runs before any test (or collection of tests for test packages and modules); teardown runs if setup has completed successfully, whether or not the test or tests pass. For more detail on fixtures at each level, see below.

Test packages

nose allows tests to be grouped into test packages. This allows package-level setup; for instance, if you need to create a test database or other data fixture for your tests, you may create it in package setup and remove it in package teardown once per test run, rather than having to create and tear it down once per test module or test case.

To create package-level setup and teardown methods, define setup and/or teardown functions in the __init__.py of a test package. Setup methods may be named setup, setup_package, setUp, or setUpPackage; teardown may be named teardown, teardown_package, tearDown or tearDownPackage. Execution of tests in a test package begins as soon as the first test module is loaded from the test package.

Test modules

A test module is a python module that matches the testMatch regular expression. Test modules offer module-level setup and teardown; define the method setup, setup_module, setUp or setUpModule for setup, teardown, teardown_module, or tearDownModule for teardown. Execution of tests in a test module begins after all tests are collected.

Test classes

A test class is a class defined in a test module that is either a subclass of unittest.TestCase, or matches testMatch. Test classes that don't descend from unittest.TestCase are run in the same way as those that do: methods in the class that match testMatch are discovered, and a test case constructed to run each with a fresh instance of the test class. Like unittest.TestCase subclasses, other test classes may define setUp and tearDown methods that will be run before and after each test method.

Test functions

Any function in a test module that matches testMatch will be wrapped in a FunctionTestCase and run as a test. The simplest possible failing test is therefore:

def test():
    assert False

And the simplest passing test:

def test():
    pass

Test functions may define setup and/or teardown attributes, which will be run before and after the test function, respectively. A convenient way to do this, especially when several test functions in the same module need the same setup, is to use the provided with_setup decorator:

def setup_func():
    # ...

def teardown_func():
    # ...

@with_setup(setup_func, teardown_func)
def test():
    # ...

For python 2.3, add the attributes by calling the decorator function like so:

def test():
    # ...
test = with_setup(setup_func, teardown_func)(test)

or by direct assignment:

test.setup = setup_func
test.teardown = teardown_func

Please note that with_setup is useful only for test functions, not for test methods in TestCase subclasses or other test classes. For those cases, define setUp and tearDown methods in the class.

Test generators

nose supports test functions and methods that are generators. A simple example from nose's selftest suite is probably the best explanation:

def test_evens():
    for i in range(0, 5):
        yield check_even, i, i*3

def check_even(n, nn):
    assert n % 2 == 0 or nn % 2 == 0

This will result in 4 tests. nose will iterate the generator, creating a function test case wrapper for each tuple it yields. As in the example, test generators must yield tuples, the first element of which must be a callable and the remaining elements the arguments to be passed to the callable.

Setup and teardown functions may be used with test generators. The setup and teardown attributes must be attached to the generator function:

@with_setup(setup_func, teardown_func)
def test_generator():
    ...
    yield func, arg, arg ...

The setup and teardown functions will be executed for each test that the generator returns.

For generator methods, the setUp and tearDown methods of the class (if any) will be run before and after each generated test case.

Please note that method generators are not supported in unittest.TestCase subclasses.

Finding and running tests

nose, by default, follows a few simple rules for test discovery.

Be aware that plugins and command line options can change any of those rules.

Testing tools

The nose.tools module provides a number of testing aids that you may find useful, including decorators for restricting test execution time and testing for exceptions, and all of the same assertX methods found in unittest.TestCase (only spelled in pep08 fashion, so assert_equal rather than assertEqual). See nose.tools for a complete list.

About the name

Contact the author

You can email me at jpellerin+nose at gmail dot com.

To report bugs, ask questions, or request features, please use the issues tab at the Google code site: http://code.google.com/p/python-nose/issues/list. Patches are welcome!

Similar test runners

nose was inspired mainly by py.test, which is a great test runner, but formerly was not all that easy to install, and is not based on unittest.

Test suites written for use with nose should work equally well with py.test, and vice versa, except for the differences in output capture and command line arguments for the respective tools.

License and copyright

nose is copyright Jason Pellerin 2005-2007

This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

nosetests setuptools command

You can run tests using the nosetests setuptools command:

python setup.py nosetests

This command has a few benefits over the standard test command: all nose plugins are supported, and you can configure the test run with both command line arguments and settings in your setup.cfg file.

To configure the nosetests command, add a [nosetests] section to your setup.cfg. The [nosetests] section can contain any command line arguments that nosetests supports. The differences between issuing an option on the command line and adding it to setup.cfg are:

Here's an example [nosetests] setup.cfg section:

[nosetests]
verbosity=1
detailed-errors
with-coverage=1
cover-package=nose
debug=nose.loader
pdb=1
pdb-failures=1

If you commonly run nosetests with a large number of options, using the nosetests setuptools command and configuring with setup.cfg can make running your tests much less tedious.

nosetests usage

usage: nosetests [options] [names]
    
    nose provides an alternate test discovery and running process for
    unittest, one that is intended to mimic the behavior of py.test as much as
    is reasonably possible without resorting to magic.
    
    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 are examined for python source files
    or directories that match testMatch. Package discovery descends all
    the way down the tree, so package.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 file,
    functions and classes whose names match testMatch 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 methods available.

    Tests may raise nose.SkipTest to indicate that they should be
    skipped or nose.DeprecatedTest to indicate that they are
    deprecated. Skipped and deprecated tests do not count as failures,
    but details on them are printed at the end of the test run along
    with any failures and errors.
        
    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:

      nosetests test.module
      nosetests another.test:TestCase.test_method
      nosetests a.test:TestCase
      nosetests /path/to/test/file.py:test_function
      
    Note however that specifying a test name will *not* cause nose to run
    a test that it does not discover. Test names specified are compared
    against tests discovered, and only the requested tests are
    run. Setup and teardown methods are run at all stages. That means
    that if you run:

      nosetests some.tests.test_module:test_function

    And have defined setup or teardown methods in tests and test_module,
    those setup methods will run before the test_function test, and
    teardown after, just as if you were running all tests.

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

      nosetests -w /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 (output capture, assert introspection, and any plugins
    that control or produce output) detailed in the options below.

    Configuration
    -------------

    In addition to passing command-line options, you may also put configuration
    options in a .noserc or nose.cfg file in your home directory. These are
    standard .ini-style config files. Put your nosetests configuration in a
    [nosetests] section, with the -- prefix removed:

      [nosetests]
      verbosity=3
      with-doctest

    All configuration files that are found will be loaded and their options
    combined.
    

options:
  -h, --help            show this help message and exit
  -V, --version         Output nose version and exit
  -v, --verbose         Be more verbose. [NOSE_VERBOSE]
  --verbosity=VERBOSITY
                        Set verbosity; --verbosity=2 is the same as -vv
  -l DEBUG, --debug=DEBUG
                        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=DEBUG_LOG
                        Log debug messages to this file (default: sys.stderr)
  -q, --quiet           
  -w WHERE, --where=WHERE
                        Look for tests in this directory [NOSE_WHERE]
  -e EXCLUDE, --exclude=EXCLUDE
                        Don't run tests that match regular expression
                        [NOSE_EXCLUDE]
  -i INCLUDE, --include=INCLUDE
                        Also run tests that match regular expression
                        [NOSE_INCLUDE]
  -m TEST_MATCH, --match=TEST_MATCH, --testmatch=TEST_MATCH
                        Use this regular expression to find tests
                        [NOSE_TESTMATCH]
  -s, --nocapture       Don't capture stdout (any stdout output will be
                        printed immediately) [NOSE_NOCAPTURE]
  -d, --detailed-errors
                        Add detail to error output by attempting to evaluate
                        failed asserts [NOSE_DETAILED_ERRORS]
  --pdb                 Drop into debugger on errors
  --pdb-failures        Drop into debugger on failures
  -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.)
  -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]
  --with-coverage       Enable plugin Coverage:  If you have Ned Batchelder's
                        coverage module installed, you may activate a coverage
                        report. The coverage report will cover any python
                        source module imported after the start of the test
                        run, excluding modules that match testMatch. If you
                        want to include those modules too, use the --cover-
                        tests switch, or set the NOSE_COVER_TESTS environment
                        variable to a true value. To restrict the coverage
                        report to modules from a particular package or
                        packages, use the --cover-packages switch or the
                        NOSE_COVER_PACKAGES environment variable.
                        [NOSE_WITH_COVERAGE]
  --cover-package=COVER_PACKAGES
                        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-inclusive     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]
  --with-doctest        Enable plugin Doctest:  Activate doctest plugin to
                        find and run doctests in non-test modules.
                        [NOSE_WITH_DOCTEST]
  --doctest-tests       Also look for doctests in test modules
                        [NOSE_DOCTEST_TESTS]
  --doctest-extension=DOCTESTEXTENSION
                        Also look for doctests in files with this extension
                        [NOSE_DOCTEST_EXTENSION]
  --with-isolation      Enable plugin IsolationPlugin:  Activate the isolation
                        plugin to isolate changes to external modules to a
                        single 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 may not be used with the
                        coverage plugin.  [NOSE_WITH_ISOLATION]
  --with-missed-tests   Enable plugin MissedTests:  Enable to get a warning
                        when tests specified on the command line are not found
                        during the test run.  [NOSE_WITH_MISSED-TESTS]
  --with-profile        Enable plugin Profile:  Use this plugin to run tests
                        using the hotshot profiler.   [NOSE_WITH_PROFILE]
  --profile-sort=PROFILE_SORT
                        Set sort order for profiler output
  --profile-stats-file=PROFILE_STATS_FILE
                        Profiler stats file; default is a new temp file on
                        each run
  --profile-restrict=PROFILE_RESTRICT
                        Restrict profiler output. See help for pstats.Stats
                        for details

Bug reports

Please report bugs and make feature requests here.

Hack

Write plugins! It's easy and fun.

Get the code: 

svn checkout http://python-nose.googlecode.com/svn/trunk/ nose

Patches are welcome. I'd suggest grabbing a copy of svk so that you can have local version control and submit full patches against an up-to-date tree easily.

Thanks to Google for providing the Google code hosting service.

Changelog

0.9.3

0.9.2

0.9.1

0.9.0

0.9.0b2

0.9.0b1

0.9.0a2

0.9.0a1

0.8.7

0.8.6

0.8.5

0.8.4

0.8.3

0.8.2

0.8.1

0.8

0.7.5

0.7.2

0.7.1

0.7

0.6

0.5.1