Thoughtworks’ Joe Walnes has posted a link (joe.truemesh.com/blog/archives/agile/000047.html) to an interesting project called TestDox (agiledox.sourceforge.net/). Given a suite of JUnit (www.junit.org) tests, it generates documentation.

Like FIT (fit.c2.com), this is an interesting bridge between executable code and documentation. TestDox converts camelCasedTestMethodNames into separate words, so this code

  public class DogTest extends TestCase
  {
    public void testBarksAtCats() {}
    public void testEatsALot() {}
    public void testSleepsWhenNotBarkingOrEating() {}
  }

…would produce the documentation that looks basically like (untested):

Dog

  • Barks at cats
  • Eats a lot
  • Sleeps when not barking or eating

This has arguably limited usefulness, and it depends trickily on class and method naming conventions. But, it starts the ideas flowing, and TestDox’s parent project (Agiledox) will hopefully expand and explore these much further. It may sound like heresy to the XP world, but I’d be interested in being able to do this sort of thing round-trip (documentation -> test -> documentation -> test -> documentation -> …)

In my own unit testing, I haven’t always been so methodical about using method names that describe a characteristic of the entity being tested. It’s not that I don’t use descriptive names, but I may include tests with names like "testEatBadTastingFood()", which describes a specific scenario but not an ongoing behaviour of dogs. Running my tests through TestDox might generate misleading documentation. It’s not that dogs generally eat food they don’t like. I just wanted to test what a dog would/should do in the eventuality that they did eat bad food. I’m not sure if my current behaviour is bad or good, but it will definitely be something I think about next time I sit down to do some coding.

A fear I have is that, with this tool in place, I may be tempted to think about what the generated documentation will look like as I write my tests. This would create a new and potentially conflicting objective in my test writing. And, since I tend to do test driven design, it would ultimately impact my design and coding decisions.

I’m not ruling out the possibility that this change in thinking would improve my code. I guess I’ll just have to try and find out.