Organising design-by-contract test code

Lets say you write component-oriented, loosely coupled, design-by-contract (java) software and you do rigorous unit testing. How do you organise your codebase?

Diagram showing a way to organise interface, test, and implementation code

Here’s one way.

  1. Put all of your (work) interfaces, and everything referenced from those interfaces (like simple data beans and exceptions) in an “API” package. If you use a tool like Maven to split your code up into small libraries, make the API package into a seperate library. The main reason for this is that you (hopefully) make it possible for packages that use your library to compile and link against only the API package, which promotes loose coupling.
  2. Optionally put “support code” which will only ever really need one implementation or will be shared by implementations in an “SPI” package. If your library has a “implementation registation” or brokering interface such as the JDBC driver manager, it is likely a good candidate for this SPI package. (The abbreviation SPI stands for Service Provider Interface). Either package this SPI package with your API package, or provide it seperately.
  3. Write abstract test cases for each of your (work) interfaces. These abstract test cases are specifically geared at testing the contract promoted by the (work) interfaces, and not things like setup, initialization or destruction code. (If you write your code test-first, you’ll write these tests before you start on the work interfaces). Since JUnit (at least for 3.x) pretty much requires that you use subclassing of its TestCase class, it may make sense to introduce a common abstract base test class immediately (I tend to have an abstract base test case for handling the “no test result” result that junit 3.x does not natively support). This kind of abstract test case might look like this:
    public abstract class AbstractFooXXXTestCase
    
        extends AbstractFooTestCase {
    
      protected abstract FooXXX getInstance();  public void testFooNeverReturnsNull() {
    
        assertNotNull( getInstance().foo() );
    
      }
    
    }

    You can keep these TCK tests right next to the concrete tests for your (first) implementation code, or you can make it into a seperate package.

  4. Create concrete subclasses for these abstract test cases, which feed the superclass an instance of an implementation of the (work) interface that is being tested. These concrete classes are responsible for creating mock objects of the dependencies, doing any neccessary initialization, etc.
  5. Create the implementation code that is needed to make the concrete test cases compile and run successfully. If you’ve prepared a seperate “API” package, you might want to consider naming this package the implementation (or “impl” for short) package. If there’s a specific technology used for this implementation (like a specific database backend), you might want to name the package after that, instead of just using “impl”.
  6. The SPI package probably needs some test cases of its own. These are not a part of your TCK. Keep them close to the SPI code.
  7. Rinse and repeat. When doing incremental development, you’ll typically add a test to one of the TCK test classes, possibly modify the API and implementation package to make sure so everything compiles once more, re-run the concrete test suite to make sure the newly added test fails, then modify the implementation code and re-run the tests until all the tests pass again. When doing more of an up-front design, its still a good idea to start codifying design contracts for your (work) interfaces in a TCK suite as soon as possible, as a properly written TCK is probably a bit less ambiguous than most specification documents.

Note that, for bigger projects with multiple implementations, the exposed interfaces of the SPI and TCK packages need to be treated with similar care as those in the API package, since adapting implementation test cases to changes in the TCK might be too much effort otherwise.

I’ve been using this kind of code organisation for quite a while now (first for the jicarilla.org codebase, later also for commercial projects). PicoContainer uses it too, and it might very well be where I borrowed the idea from.

Theatersport: a dutch form improvisation theatre

For about a year and a half now, I’ve been very happy to be a part of Pro Deo, a theatersportvereniging (English: Theatresports). I thought I’d share a little about it.

Mix tournament

Picture from the ‘mixtoernooi’ in 2005. By Rudine Bijlsma.

Yesterday was the twice-yearly “mixtoernooi” (above picture from a previous one), where the teams (if you’re thinking “teams? What teams?” – Go click those links) consist of players with varying levels of experience. These are always lots of fun, since its a good way for the less experienced players to learn to be “on stage” with a bit of a “safety net” provided by the players with a little more experience.

It was a good show. Quite a bit of audience, good atmosphere, and lots of energy.

We had two matches of about 45 minutes each, and I was in one of them, meaning I played a part in three improvised scenes of about 4 minutes each. Our team played a spacejump, a free impro, and a time for a song. It went well and afterwards I was real proud of each of my teammates for putting on a great show. Of course, we lost from the other team by a large margin, which is how it should be.

Improvisation theatre builds character

Theatresports teaches its practicioners how to listen, how to be a team player, how to feel confident about themselves, and much more.

Theatresports is an excellent way to learn how to feel confident on stage (once you dare step up there with a hundred people watching you and no clue yet what it is you’re going to do in about 3 seconds, you dare do allmost anything), which is also a great way to learn how to feel confident when presenting or speaking in front of an audience.

Theatresports excels even more at learning how to be a team player. In order to function well as an improvisation theatre team, there needs to be a whole lot of trust between each of the players, and a high comfort level. And beyond that, nearly everything about the “art form” is there to encourage or even require healthy collaborative behaviour. Golden rules like “you should accept whatever it is that someone invents right there on the spot” (you don’t really want to get into a discussion about it in the middle of your scene) go way, way beyond the “lazy consensus” that open source people may be used to.

Theatresports makes you a better listener. In order to be able to interact with other people on stage (and with the audience) in a witty and dynamic fashion, without any kind of script, you need to pay attention, and lots of attention, to what is going on around you, otherwise you’ll misread your teammates intentions and the whole scene can go down the drain.

Etc etc etc.

Of course, for me, these are really insignificant pluses compared to the joy of doing various silly things with friends. We have a few hours of lessons and practice tonight, and after that we’ll frequently hang out in the bar until dawn.