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

Tools for testing

nose.tools provides a few convenience functions to make writing tests easier. You don’t have to use them; nothing in the rest of nose depends on any of these methods.

nose.tools.ok_(expr, msg=None)
Shorthand for assert. Saves 3 whole characters!
nose.tools.eq_(a, b, msg=None)
Shorthand for ‘assert a == b, “%r != %r” % (a, b)
nose.tools.make_decorator(func)
Wraps a test decorator so as to properly replicate metadata of the decorated function, including nose’s additional stuff (namely, setup and teardown).
nose.tools.raises(*exceptions)

Test must raise one of expected exceptions to pass.

Example use:

@raises(TypeError, ValueError)
def test_raises_type_error():
    raise TypeError("This test passes")

@raises(Exception)
def test_that_fails_by_passing():
    pass

If you want to test many assertions about exceptions in a single test, you may want to use assert_raises instead.

nose.tools.set_trace()
Call pdb.set_trace in the calling frame, first restoring sys.stdout to the real output stream. Note that sys.stdout is NOT reset to whatever it was before the call once pdb is done!
nose.tools.timed(limit)

Test must finish within specified time limit to pass.

Example use:

@timed(.1)
def test_that_fails():
    time.sleep(.2)
nose.tools.with_setup(setup=None, teardown=None)

Decorator to add setup and/or teardown methods to a test function:

@with_setup(setup, teardown)
def test_something():
    " ... "

Note that with_setup is useful only for test functions, not for test methods or inside of TestCase subclasses.

nose.tools.istest(func)
Decorator to mark a function or method as a test
nose.tools.nottest(func)
Decorator to mark a function or method as not a test
nose.tools.assert_almost_equal

Fail if the two objects are unequal as determined by their difference rounded to the given number of decimal places (default 7) and comparing to zero, or by comparing that the between the two objects is more than the given delta.

Note that decimal places (from zero) are usually not the same as significant digits (measured from the most signficant digit).

If the two objects compare equal then they will automatically compare almost equal.

nose.tools.assert_almost_equals

Fail if the two objects are unequal as determined by their difference rounded to the given number of decimal places (default 7) and comparing to zero, or by comparing that the between the two objects is more than the given delta.

Note that decimal places (from zero) are usually not the same as significant digits (measured from the most signficant digit).

If the two objects compare equal then they will automatically compare almost equal.

nose.tools.assert_dict_contains_subset
Checks whether actual is a superset of expected.
nose.tools.assert_equal
Fail if the two objects are unequal as determined by the ‘==’ operator.
nose.tools.assert_equals
Fail if the two objects are unequal as determined by the ‘==’ operator.
nose.tools.assert_false
Fail the test if the expression is true.
nose.tools.assert_greater
Just like self.assertTrue(a > b), but with a nicer default message.
nose.tools.assert_greater_equal
Just like self.assertTrue(a >= b), but with a nicer default message.
nose.tools.assert_in
Just like self.assertTrue(a in b), but with a nicer default message.
nose.tools.assert_is
Just like self.assertTrue(a is b), but with a nicer default message.
nose.tools.assert_is_instance
Same as self.assertTrue(isinstance(obj, cls)), with a nicer default message.
nose.tools.assert_is_none
Same as self.assertTrue(obj is None), with a nicer default message.
nose.tools.assert_is_not
Just like self.assertTrue(a is not b), but with a nicer default message.
nose.tools.assert_is_not_none
Included for symmetry with assertIsNone.
nose.tools.assert_items_equal

An unordered sequence / set specific comparison. It asserts that expected_seq and actual_seq contain the same elements. It is the equivalent of:

self.assertEqual(sorted(expected_seq), sorted(actual_seq))

Raises with an error message listing which elements of expected_seq are missing from actual_seq and vice versa if any.

Asserts that each element has the same count in both sequences. Example:

  • [0, 1, 1] and [1, 0, 1] compare equal.
  • [0, 0, 1] and [0, 1] compare unequal.
nose.tools.assert_less
Just like self.assertTrue(a < b), but with a nicer default message.
nose.tools.assert_less_equal
Just like self.assertTrue(a <= b), but with a nicer default message.
nose.tools.assert_list_equal

A list-specific equality assertion.

Args:

list1: The first list to compare. list2: The second list to compare. msg: Optional message to use on failure instead of a list of

differences.
nose.tools.assert_multi_line_equal
Assert that two multi-line strings are equal.
nose.tools.assert_not_almost_equal

Fail if the two objects are equal as determined by their difference rounded to the given number of decimal places (default 7) and comparing to zero, or by comparing that the between the two objects is less than the given delta.

Note that decimal places (from zero) are usually not the same as significant digits (measured from the most signficant digit).

Objects that are equal automatically fail.

nose.tools.assert_not_almost_equals

Fail if the two objects are equal as determined by their difference rounded to the given number of decimal places (default 7) and comparing to zero, or by comparing that the between the two objects is less than the given delta.

Note that decimal places (from zero) are usually not the same as significant digits (measured from the most signficant digit).

Objects that are equal automatically fail.

nose.tools.assert_not_equal
Fail if the two objects are equal as determined by the ‘==’ operator.
nose.tools.assert_not_equals
Fail if the two objects are equal as determined by the ‘==’ operator.
nose.tools.assert_not_in
Just like self.assertTrue(a not in b), but with a nicer default message.
nose.tools.assert_not_is_instance
Included for symmetry with assertIsInstance.
nose.tools.assert_not_regexp_matches
Fail the test if the text matches the regular expression.
nose.tools.assert_raises

Fail unless an exception of class excClass is thrown by callableObj when invoked with arguments args and keyword arguments kwargs. If a different type of exception is thrown, it will not be caught, and the test case will be deemed to have suffered an error, exactly as for an unexpected exception.

If called with callableObj omitted or None, will return a context object used like this:

with self.assertRaises(SomeException):
    do_something()

The context manager keeps a reference to the exception as the ‘exception’ attribute. This allows you to inspect the exception after the assertion:

with self.assertRaises(SomeException) as cm:
    do_something()
the_exception = cm.exception
self.assertEqual(the_exception.error_code, 3)
nose.tools.assert_raises_regexp

Asserts that the message in a raised exception matches a regexp.

Args:

expected_exception: Exception class expected to be raised. expected_regexp: Regexp (re pattern object or string) expected

to be found in error message.

callable_obj: Function to be called. args: Extra args. kwargs: Extra kwargs.

nose.tools.assert_regexp_matches
Fail the test unless the text matches the regular expression.
nose.tools.assert_sequence_equal

An equality assertion for ordered sequences (like lists and tuples).

For the purposes of this function, a valid ordered sequence type is one which can be indexed, has a length, and has an equality operator.

Args:

seq1: The first sequence to compare. seq2: The second sequence to compare. seq_type: The expected datatype of the sequences, or None if no

datatype should be enforced.
msg: Optional message to use on failure instead of a list of
differences.
nose.tools.assert_set_equal

A set-specific equality assertion.

Args:

set1: The first set to compare. set2: The second set to compare. msg: Optional message to use on failure instead of a list of

differences.

assertSetEqual uses ducktyping to support different types of sets, and is optimized for sets specifically (parameters must support a difference method).

nose.tools.assert_true
Fail the test unless the expression is true.
nose.tools.assert_tuple_equal

A tuple-specific equality assertion.

Args:

tuple1: The first tuple to compare. tuple2: The second tuple to compare. msg: Optional message to use on failure instead of a list of

differences.

Table Of Contents

Previous topic

Finding and running tests

Next topic

Batteries included: builtin nose plugins

This Page