Exiting TDDoc, entering Bumblebee

History
A couple of years ago I got extremely annoyed when I had to write a word document with basically a copy of the code I had written.

There was to be a lot of copy’n’pasted code, runtime values etc and the knowledge that I would have to go through everything again a couple of weeks later because of smaller changes in the code.

I of course argued that there were a lot of test cases describing the system, but the client wouldn’t accept that for documentation.

Since most of the information that would go in that document was available in the test cases, I felt that there had to be a way to get that data into something more human friendly.

RMock and TDDoc
At the same time my collegue Joakim Ohlrogge and I (mostly Joakim, actually) had made an extension to JMock that allowed us to record expectations EasyMock style. The extension was called RecorderTestCase.

We discussed the idea of extracting specially formatted comments, snippets and even calls to mocks and we both felt that it was a killer, just what we needed! One of the advantages would be that instead of writing feasability documents we would start writing test cases that would generate that documentation. We would also get snippets and names in the documentation that were refactoring resilient.

After having had a look at JMock and the development there we decided to make our own mocking framework, RMock. The “R” simply came from “Recording” in RecordingTestCase, and we named the documentation part RDoc.

Alert: Naming conflict!
These were probably the most stupid names we could have come up with since Ruby was catching on at the time. All along we had the collision with RDoc, and after a short while we had a name collision with Steve Purcells RMock for Ruby, but since we already were up and running he decided to rename his project to Mockr. In hindsight we should have renamed RMock right away to avoid a lot of confusion. We actually did rename RDoc to TDDoc (test-driven documentation), but the package names still remain com.agical.rdoc…

Alert: Complexity overload!
The idea was to have RMock publishing data on a hub and having TDDoc to act as a plugin and listen to those events. We later started configuring the whole shabang on that hub, we introduced two service interfaces to be automatically added to that hub, we had to introduce scoping on the hub to avoid data collision for the different test cases. All for the purpose of TDDoc.

Also, we believed that the execution of a few velocity templates would have a serious perfomance inpact on running the tests, so we serialized the test data to disk first to be able to read that blob later and do the documentation generation in a second step. Since we wanted to generate documentation in our Maven execution, we had to tweak the Maven pom.xml to the extent that I was the only person who could get it up and running.

Experience report
We of course used TDDoc to generate the documentation for RMock, and that worked out pretty good, this is an example of html from Mavens xdoc format, and this is an example of pdf using Docbook.

I also used it on a customer project and it did its job there as well, but when we started to run into some seemingly simple bugs that I couldn’t fix without tearing up half of the code, I knew TDDoc was in trouble. I tried to refactor it, but it wasn’t worth it, it was too entangled.

The project had pretty much choked to death on its own complexity vomits, and both me an Joakim thought that we should try something new.

Rebirth
The idea to create documentation from executable code never left our minds, so I started to sketch on the heir. One day at my balcony a saw a bumblebee flying from flower to flower gathering nectar, and I thought that would be a good working name! Some framwork that flew from code to code gathering information as it went along.

Here comes Bumblebee
After trying some different approaches and experimenting some with JUnit4 and the runners, Bumblebee started to take form.

The core is a some pretty simple JUnit 4 runners that report to equally simple Collectors. The implementations of the Collector can decide what to do with that information.

I have made an AgileDoxCollector that writes the de-camelcased names of suites, test cases and test methods that have been run in a nested list. It is a pure Java implementation.

To use Bumblebee with the AgileDoxCollector you need to configure the main test suite like this:

@RunWith(BumbleBeeSuiteRunner.class)
@SuiteClasses({DemonstratingMethodComments.class,
DummyTestSuite2.class, JUnit3TestCase.class})
@BumblebeeCollectors({AgileDoxCollector.class})
public class AgileDoxTestSuite {}

and the sub suites like this:

@RunWith(BumbleBeeSubSuiteRunner.class)
@SuiteClasses({DemonstratingMethodComments.class})
@BumblebeeCollectors({AgileDoxCollector.class})
public class DummyTestSuite2 {}

Then you’re good to go! This setup will write a html file in “target/agile_dox.html” that looks like this:

  • Agile dox test suite
    • Demonstrating method comments
      • Using code snippets
      • Get code from other method
      • Name that will be overridden
      • Execute ruby code directly in comment
      • Ignored method
    • Dummy test suite2
      • Demonstrating method comments
        • Using code snippets
        • Get code from other method
        • Name that will be overridden
        • Execute ruby code directly in comment
        • Ignored method
    • J unit3 test case
      • Test if j unit3 also works

The idea is to impose as little intrusion as possible, and to require as little configuration as possible. The de-camelcasing is a bit akward at the moment, I just implemented it in the simplest possible way.

Open Sourced
When starting to develop Bumblebee I wanted to try a distributed version control system. I played a bit with Mercurial and Bazaar. Since performance isn’t that critical (this will be a small project) and I like it when folders are first class members that aren’t pruned when empty, I stuck for Bazaar. I tried to find a public hosting service that had Bazaar on the list of supported VCS’s, and I only found Launchpad. Hence this is where Bumblebee is open sourced.

More to come

This was a look-back on the events that led to Bumblebee, and a short introduction on how Bumblebee can be used. I intend to blog more on Bumblebee, and I will this blog as a primary support portal as long as I can.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: