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 – that is, has test or Test at a word boundary or following a - or _) 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, nose runs functional tests 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, class, 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, regardless of the status of the test run. 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 matches testMatch or is a subclass of unittest.TestCase. All test classes are run the same way: Methods in the class that match testMatch are discovered, and a test case is constructed to run each method with a fresh instance of the test class. Like unittest.TestCase subclasses, other test classes can define setUp and tearDown methods that will be run before and after each test method. Test classes that do not descend from unittest.TestCase may also include generator methods and class-level fixtures. Class-level setup fixtures may be named setup_class, setupClass, setUpClass, setupAll or setUpAll; teardown fixtures may be named teardown_class, teardownClass, tearDownClass, teardownAll or tearDownAll. Class-level setup and teardown fixtures must be class methods.

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():
    "set up test fixtures"

def teardown_func():
    "tear down test fixtures"

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

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

def test():
    "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 unittest.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 five 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.

By default, the test name output for a generated test in verbose mode will be the name of the generator function or method, followed by the args passed to the yielded callable. If you want to show a different test name, set the description attribute of the yielded callable.

Setup and teardown functions may be used with test generators. However, please note that setup and teardown attributes attached to the generator function will execute only once. To execute fixtures for each yielded test, attach the setup and teardown attributes to the function that is yielded, or yield a callable object instance with setup and teardown attributes.

For example:

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

Here, the setup and teardown functions will be executed once. Compare to:

def test_generator():
    # ...
    yield func, arg, arg # ...

@with_setup(setup_func, teardown_func)
def func(arg):
    assert something_about(arg)

In the latter case the setup and teardown functions will execute once for each yielded test.

For generator methods, the setUp and tearDown methods of the class (if any) will be run before and after each generated test case. The setUp and tearDown methods do not run before the generator method itself, as this would cause setUp to run twice before the first test without an intervening tearDown.

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