[Twisted-Python] TDD using Trial

[Tim Allen]

On Sun, Aug 30, 2009 at 01:40:34PM -0500, Nathan Lundquist wrote:
> I was wondering if any tutorials existed for setting up unit tests for 
> use with trial. I've done a fair share of googling and only found 
> tickets suggesting that more documentation be made available for trial.

Setting up unit tests with trial is (deliberately) almost identical to
setting up unit tests with the "unittest" module in Python's standard
library. The key differences are:

    - Trial provides a subclass of unittest.TestCase called
      twisted.trial.unittest.TestCase, which adds the following features
      on top of the standard Python API:
	- t.t.u.TestCase supports testing of Twisted-based code,
	  spinning up the reactor and shutting it down when necessary,
	  etc.
	- t.t.u.TestCase allows the setUp, tearDown and individual test
	  methods to return Deferreds, which causes Trial to wait for
	  those Deferreds to fire before it continues on.
	- t.t.u.TestCase has an expanded set of assertions available,
	  including Twisted-specific ones like failUnlessFailure (to
	  check the Failure object returned by a deferred) but also
	  prettier output for simple ones like failUnlessEqual.
	- t.t.u.TestCase has a 'patch' method which allows you to
	  monkeypatch other code for testing purposes. All patches are
	  reverted at the end of the individual test.
	- t.t.u.TestCase subclasses and even individual test methods can
	  be given a 'skip' property, set to a string describing why
	  that TestCase or test should be skipped. This lets you stop
	  broken tests being reported as failures, but unlike just
	  commenting them out, you don't have to worry that the test
	  will be left out of refactorings or forgotten about and never
	  uncommented. You can even skip tests at runtime, for example
	  if a test is platform specific and the test is being run on
	  the 'wrong' platform.
    - Trial will happily run unittest.TestCase test cases, but they
      can't use Twisted features like the reactor or deferreds. If
      you just want to use Trial as an alternative to nosetests, you
      should be fine.
    - If you want the automatic test-discovery to work, you need to put
      your TestCase classes inside files named "test_whatever.py",
      inside a Python package. Then you can just give Trial the name of
      the Python package and it will run all the tests it can find
      inside it.

Is that helpful?