As I said at the very beginning, unittest has an API with lots of interfaces. You can read about the interfaces for test frameworks in part 1, part 2 and part 3 of this series. This post is about the interface for test authors.
If the other posts are fresh in your mind, it’s important to remember
that this post is focused on the standard implementation of
After all, it’s that implementation which creates the interface for test
authors. There are other implementations (e.g.
DocTestCase) which provide completely different interfaces for test
authors, and one could write one’s own implementation that provided
something else entirely.
Almost all of the time that you want to write tests, you subclass
unittest.TestCase. It’s not the only way to write unit tests with
unittest, but it’s rather handy, particularly since the default test
loader looks for subclasses of
This is going to be much easier for all of us if I work from an example.
class SomeTests(TestCase): def setUp(self): print "setUp" def tearDown(self): print "tearDown" def test_a(self): print "a" def test_b(self): print "b"
The test loader will make something that looks like
unittest.TestSuite([SomeTests("test_a"), SomeTests("test_b")]). That
is, it constructs an instance of
SomeTests for each method beginning
The tests will only be run when
TestCase.run(result) is called. The
tests do not get access to the result object, instead the run() method
mediates between the tests and the result.
TestCase.run(result) method will run
setUp(), then the
test method given in the constructor (e.g.
setUp() raises any exception,
tearDown() will not be run. The
result object will have
addError called on it with the test and the
If the test method raises an exception, one of two things can happen. If
the exception is an instance of
result.addFailure(test, exc_info) is called, where test is the
TestCase instance and
exc_info is the
result.addError(test, exc_info) is called. In either case,
tearDown() is then run.
tearDown() raises an exception,
There are lots of built-in assertion methods on
These all raise
self.failureException if their assertion fails. These
are part of the interface for test authors, but they are already very
well documented. Just note that if you write your own, remember to raise
self.failureException, or better yet call
self.fail(), rather than
AssertionError or something crazy like that.
That’s pretty much it.
Of course, you could write your own object that implemented
ITestCase, and use your own test loader, and then you don’t
have to care about anything in this post. But don’t do that. Better to
As always, feedback welcome.