Date

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 TestCase. After all, it’s that implementation which creates the interface for test authors. There are other implementations (e.g. FunctionTestCase and DocTestCase) which provide completely different interfaces for test authors, and one could write one’s own implementation that provided something else entirely.

**Subclassing `TestCase`**
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 `TestCase`. 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 with “test”. 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. The default `TestCase.run(result)` method will run `setUp()`, then the test method given in the constructor (e.g. `test_a`), then `tearDown()`. If `setUp()` raises any exception, `tearDown()` will not be run. The result object will have `addError` called on it with the test and the error. If the test method raises an exception, one of two things can happen. If the exception is an instance of `self.failureException`, then `result.addFailure(test, exc_info)` is called, where test is the `TestCase` instance and `exc_info` is the `sys.exc_info()` tuple. Otherwise, `result.addError(test, exc_info)` is called. In either case, `tearDown()` is then run. If `tearDown()` raises an exception, `result.addError(test, exc_info)` is called. There are lots of built-in assertion methods on `unittest.TestCase`. 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 raising `AssertionError` or something crazy like that. That’s pretty much it. Of course, you could write your own object that implemented **`ITest`** and **`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 subclass `unittest.TestCase`. As always, feedback welcome.