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 PEP 8#function-names 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.

exception nose.tools.TimeExpired

nose.tools.assert_almost_equal(first, second, places=None, msg=None, delta=None)

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 difference 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 significant digit).

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

nose.tools.assert_count_equal(first, second, msg=None)

Asserts that two iterables have the same elements, the same number of times, without regard to order.

self.assertEqual(Counter(list(first)),

Counter(list(second)))

Example:

• [0, 1, 1] and [1, 0, 1] compare equal.

• [0, 0, 1] and [0, 1] compare unequal.

nose.tools.assert_dict_contains_subset(subset, dictionary, msg=None)

Checks whether dictionary is a superset of subset.

nose.tools.assert_equal(first, second, msg=None)

Fail if the two objects are unequal as determined by the ‘==’ operator.

nose.tools.assert_false(expr, msg=None)

Check that the expression is false.

nose.tools.assert_greater(a, b, msg=None)

Just like self.assertTrue(a > b), but with a nicer default message.

nose.tools.assert_greater_equal(a, b, msg=None)

Just like self.assertTrue(a >= b), but with a nicer default message.

nose.tools.assert_in(member, container, msg=None)

Just like self.assertTrue(a in b), but with a nicer default message.

nose.tools.assert_is(expr1, expr2, msg=None)

Just like self.assertTrue(a is b), but with a nicer default message.

nose.tools.assert_is_instance(obj, cls, msg=None)

Same as self.assertTrue(isinstance(obj, cls)), with a nicer default message.

nose.tools.assert_is_none(obj, msg=None)

Same as self.assertTrue(obj is None), with a nicer default message.

nose.tools.assert_is_not(expr1, expr2, msg=None)

Just like self.assertTrue(a is not b), but with a nicer default message.

nose.tools.assert_is_not_none(obj, msg=None)

Included for symmetry with assertIsNone.

nose.tools.assert_less(a, b, msg=None)

Just like self.assertTrue(a < b), but with a nicer default message.

nose.tools.assert_less_equal(a, b, msg=None)

Just like self.assertTrue(a <= b), but with a nicer default message.

nose.tools.assert_list_equal(list1, list2, msg=None)

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_logs(logger=None, level=None)

Fail unless a log message of level level or higher is emitted on logger_name or its children. If omitted, level defaults to INFO and logger defaults to the root logger.

This method must be used as a context manager, and will yield a recording object with two attributes: output and records. At the end of the context manager, the output attribute will be a list of the matching formatted log messages and the records attribute will be a list of the corresponding LogRecord objects.

Example:

with self.assertLogs('foo', level='INFO') as cm:
    logging.getLogger('foo').info('first message')
    logging.getLogger('foo.bar').error('second message')
self.assertEqual(cm.output, ['INFO:foo:first message',
                             'ERROR:foo.bar:second message'])

nose.tools.assert_multi_line_equal(first, second, msg=None)

Assert that two multi-line strings are equal.

nose.tools.assert_no_logs(logger=None, level=None)

Fail unless no log messages of level level or higher are emitted on logger_name or its children.

This method must be used as a context manager.

nose.tools.assert_not_almost_equal(first, second, places=None, msg=None, delta=None)

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 difference 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 significant digit).

Objects that are equal automatically fail.

nose.tools.assert_not_equal(first, second, msg=None)

Fail if the two objects are equal as determined by the ‘!=’ operator.

nose.tools.assert_not_in(member, container, msg=None)

Just like self.assertTrue(a not in b), but with a nicer default message.

nose.tools.assert_not_is_instance(obj, cls, msg=None)

Included for symmetry with assertIsInstance.

nose.tools.assert_not_regex(text, unexpected_regex, msg=None)

Fail the test if the text matches the regular expression.

nose.tools.assert_raises(expected_exception, *args, **kwargs)

Fail unless an exception of class expected_exception is raised by the callable when invoked with specified positional and keyword arguments. If a different type of exception is raised, 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 the callable and arguments omitted, will return a context object used like this:

with self.assertRaises(SomeException):
    do_something()

An optional keyword argument ‘msg’ can be provided when assertRaises is used as a context object.

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_regex(expected_exception, expected_regex, *args, **kwargs)

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

Args:

expected_exception: Exception class expected to be raised. expected_regex: Regex (re.Pattern object or string) expected

to be found in error message.

args: Function to be called and extra positional args. kwargs: Extra kwargs. msg: Optional message used in case of failure. Can only be used

when assertRaisesRegex is used as a context manager.

nose.tools.assert_regex(text, expected_regex, msg=None)

Fail the test unless the text matches the regular expression.

nose.tools.assert_sequence_equal(seq1, seq2, msg=None, seq_type=None)

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(set1, set2, msg=None)

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(expr, msg=None)

Check that the expression is true.

nose.tools.assert_tuple_equal(tuple1, tuple2, msg=None)

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.

nose.tools.assert_warns(expected_warning, *args, **kwargs)

Fail unless a warning of class warnClass is triggered by the callable when invoked with specified positional and keyword arguments. If a different type of warning is triggered, it will not be handled: depending on the other warning filtering rules in effect, it might be silenced, printed out, or raised as an exception.

If called with the callable and arguments omitted, will return a context object used like this:

with self.assertWarns(SomeWarning):
    do_something()

An optional keyword argument ‘msg’ can be provided when assertWarns is used as a context object.

The context manager keeps a reference to the first matching warning as the ‘warning’ attribute; similarly, the ‘filename’ and ‘lineno’ attributes give you information about the line of Python code from which the warning was triggered. This allows you to inspect the warning after the assertion:

with self.assertWarns(SomeWarning) as cm:
    do_something()
the_warning = cm.warning
self.assertEqual(the_warning.some_attribute, 147)

nose.tools.assert_warns_regex(expected_warning, expected_regex, *args, **kwargs)

Asserts that the message in a triggered warning matches a regexp. Basic functioning is similar to assertWarns() with the addition that only warnings whose messages also match the regular expression are considered successful matches.

Args:

expected_warning: Warning class expected to be triggered. expected_regex: Regex (re.Pattern object or string) expected

to be found in error message.

args: Function to be called and extra positional args. kwargs: Extra kwargs. msg: Optional message used in case of failure. Can only be used

when assertWarnsRegex is used as a context manager.

nose.tools.eq_(a, b, msg=None)

Shorthand for ‘assert a == b, “%r != %r” % (a, b)

nose.tools.istest(func)

Decorator to mark a function or method as a test

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.nottest(func)

Decorator to mark a function or method as not a test

nose.tools.ok_(expr, msg=None)

Shorthand for assert. Saves 3 whole characters!

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.