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, 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, 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, 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.TestCasesubclasses, other test classes may 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 fixtures may be named setup_class, setupClass, setUpClass, setupAll or setUpAll for set up and teardown_class, teardownClass, tearDownClass, teardownAll or tearDownAll for teardown and 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():
    # ...

def teardown_func():
    # ...

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

For python 2.3 or earlier, 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 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 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.

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

Do not edit above this line. Content above this line is automatically generated and edits above this line will be discarded.

Comments