Python Programming, news on the Voidspace Python Projects and all things techie.

unittest2 0.4.0: Several Major New Features

emoticon:html unittest2 is an enhanced version of unittest including a standard test runner (automatic test discovery), class and module level fixtures (setUpClass / setUpModule etc), many powerful new assert methods, better resource management with addCleanups and a host of other new features. These new features are all going into the Python version of unittest in Python 2.7 and Python 3.2. The point of unittest2 is that it works with Python 2.4 - 2.6; you can use it now.

The latest release is 0.4.0, which roughly equates to the feature set that will be in unittest in Python 2.7 beta 1 which is due out any minute now. The last public release of unittest2 I announced was version 0.2.0 and there have been several new and important features since then.

The most important ones are three new command line options (also available as parameters to unittest2.main()) for running tests

failfast, catch and buffer command line options

The unit2 test runner script now supports three new command line options for both standard test running and test discovery.

  • -f / --failfast

    Stop the test run on the first error or failure.

  • -c / --catch

    Control-c during the test run waits for the current test to end and then reports all the results so far. A second control-c raises the normal KeyboardInterrupt exception.

    There are a set of functions implementing this feature available to test framework writers wishing to support this control-c handling. See Signal Handling in the development documentation [1].

  • -b / --buffer

    The standard out and standard error streams are buffered during the test run. Output during a passing test is discarded. Output is echoed normally on test fail or error and is added to the failure messages.

The command line can also be used for test discovery, for running all of the tests in a project or just a subset.

assert method changes

There have been a few new / changed assert methods since unittest2 0.2.0:

  • assertSameElements has been removed and assertItemsEqual added.

    assertItemsEqual asserts that sequences contain the same elements. It is the equivalent of self.assertEqual(sorted(first), sorted(second)) but works with unhashable and unorderable types. It is more useful than the old implementation of assertSameElements that ignored duplicates.

  • Addition of TestCase.assertNotRegexpMatches.

    This is for symmetry with assertRegexpMatches. On failure it shows you how the regular expression matches the text provided.

  • delta keyword argument for assertAlmostEqual and assertNotAlmostEqual.

    I really like this change because the default implementation of assertAlmostEqual is never (almost) useful to me. By default these methods round to a specified number of decimal places. When you use the delta keyword the assertion is that the difference between the two values you provide is less than (or equal to) the delta value. This permits it to be used with non-numeric values:

    import datetime
    delta = datetime.timedelta(seconds=10)
    second_timestamp =
    self.assertAlmostEqual(first_timestamp, second_timestamp, delta=delta)

There are a whole hosts of other minor changes, you can see the full changelog since version 0.2.0 below. The only other feature especially worth mentioning is that test discovery supports the providing of a dotted package name instead of a path name:

unit2 discover -c package.test


2010/04/08 - 0.4.0

Addition of removeHandler for removing the control-C handler.

delta keyword argument for assertAlmostEqual and assertNotAlmostEqual.

Addition of -b command line option (and TestResult.buffer) for buffering stdout / stderr during test runs.

Addition of TestCase.assertNotRegexpMatches.

Allow test discovery using dotted module names instead of a path.

All imports requiring the signal module are now optional, for compatiblity with IronPython (or other platforms without this module).

Tests fixed to be compatible with nosetest.

2010/03/26 - 0.3.0

assertSameElements removed and assertItemsEqual added; assert that sequences contain the same elements.

Addition of -f/--failfast command line option, stopping test run on first failure or error.

Addition of -c/--catch command line option for better control-C handling during test runs.

Added BaseTestSuite, for use by frameworks that don't want to support shared class and module fixtures.

Skipped test methods no longer have setUp and tearDown called around them.

Faulty load_tests functions no longer halt test discovery.

Using non-strings for failure messages now works.

Potential for UnicodeDecodeError whilst creating failure messages fixed.

Split out monolithic test module into a package.

BUGFIX: Correct usage message now shown for unit2 scripts.

BUGFIX: __unittest in module globals trims frames from that module in reported stacktraces.


These are the tasks left to complete before the Python 2.7 release:

  • Addition of removeHandler to 2.7 (maybe too late)
  • Making removeHandler a context manager?
  • Tests for command line handling of -b
  • Tests for dotted path discovery
  • Docstrings for assertRegexpMatches and assertNotRegexpMatches
  • Issues 8301, 8302 and 8303 on the Python bug tracker
  • Document BaseTestSuite and _ErrorHolder
  • Look at issue 7559.


The signal handling, the -c command line option, should work on all CPython platforms. It doesn't work correctly on Jython or IronPython that have missing or incomplete implementations of the signal module.

There is a feature in unittest2 that isn't in Python 2.7 (yet), the removeHandler function. This can either be used as a standalone function or as a decorator for test methods that use the signal.SIGINT handler and so can't be executed with the unittest2 control-c handling in place:

def test_signal_handling(self):

Like this post? Digg it or it.

Posted by Fuzzyman on 2010-04-08 23:09:04 | |

Categories: , Tags: , ,

Hosted by Webfaction