Code archaeology: A Detroubulator retrospective

[MortenWittrock]

The other day, I stumbled on this disc at home:



It is my very last copy of a CD-ROM containing version 1.0 of the Detroubulator open source unit test tool for SAP XI/PI. The discs were handed out at TechEd 2006 in Amsterdam. The tool and its source code was released on October 17th, at the SDN Day community event on the day before TechEd.

I hadn’t looked at the project in years, so I took the opportunity to revisit the code and the project’s documentation. In this blog post, I’ll give you an overview of Detroubulator, and share my thoughts on seeing the code and documentation again after quite a few years.

So what is Detroubulator anyway?

Detroubulator started life as a much smaller tool I wrote for testing XSLT mappings outside of SAP XI. The tool was called XTest, and if you think that’s a pretty tedious name, I couldn’t agree more 😄

tns and I started discussing whether it might be possible to turn XTest into a more general purpose tool. In other words, expand the scope of the tool from just XSLT to all the mapping types supported by SAP XI. We agreed it would indeed be possible, and we started work on the Detroubulator project.



The Detroubulator logo 🙂


Why is automated unit testing worth pursuing? I think we nailed the answer to that question pretty well in the Detroubulator FAQ:

The main benefit is that automated unit testing greatly reduces the effort required to repeatedly test your mapping programs. While it's definitely possible to unit test manually in the Integration Builder, it's is a time-consuming and error-prone task. Furthermore, it's a task that must, in an ideal world at least, be done every time a change is made to the mapping program. Detroubulator lets you write your unit tests once and for all and run them at the press of a button. The minimal effort required to run your unit tests means that testing can become an integrated part of development rather than an effort that only takes place when development is complete. Having a suite of unit tests available also makes it easier and safer to make changes to an existing mapping program; running your test suite at each step of the way builds confidence that the changes made to the mapping program didn't inadvertently introduce errors.

The name Detroubulator was inspired by The Simpsons, by the way. The FAQ defined it like this:

Detroubulate is a Simpsons-inspired neologism meaning to get someone out of trouble.

Detroubulator and the community

Detroubulator was community-centric from day one. Via the SAP Developer Network, we invited interested community members to join the tool’s beta test phase. Quite a few did, and we received some very useful feedback from those early beta testers.

Once version 1.0 was ready, it was released at the SDN Day community event in Amsterdam in 2006, as I mentioned in the introduction. Version 1.1, the next version of Detroubulator, was released in 2007 at the SDN Day community events in Munich and Las Vegas.

Also, Thorsten and I blogged about Detroubulator on SDN throughout the project.

The code

Detroubulator 1.1, the version which is on GitHub now, is written in Java 1.6. The build is handled by Apache Ant, which also packages the release archive for distribution. The project consists of 61 Java source files containing a total of 3920 lines of code (both numbers include unit tests). I used the cloc tool to do the counting, by the way.

The project contains two ABAP function modules in a function group. The ABAP code is distributed in source code form using SAPlink (today, abapGit would have been the obvious choice).

The project was hosted on Google’s open source project hosting service called Google Code. Similar to e.g. GitHub, the service offered version control, an issue tracking system and a wiki to open source projects. It was, however, shut down by Google in 2016.

Returning to the source code after a number of years, I’m generally pretty happy with its quality. It’s readable, the formatting is pretty good, there is a decent amount of comments and the various entities have sensible names. Exceptions are handled and assumptions are tested with assert statements. We also do a reasonable amount of logging.

Unit testing is done using JUnit with EasyMock used for mocking. All tests are executed by Ant (see the runtests target in the Ant buildfile) during the build. The number of unit tests could definitely have been higher, though.

The so-called test file, i.e. the XML document containing the SAP XI/PI mapping program tests, is validated quite thoroughly when a test is run. This means that most configuration errors lead to sensible, human-readable error messages, instead of an incomprehensible stack trace.

I see a bit of duplicated code here and there (hey, I thought DRY meant Do Repeat Yourself!?), which should have been cleaned up, but by no means an alarming amount.

You can see for yourself, if you are interested; the complete project with all source code and other required files is now on GitHub. The repository contains version 1.1 of Detroubulator, which was originally released on December 7th, 2007.

Documentation

Open source projects with great code but lousy documentation (or no documentation at all) have a harder time gaining traction; they simply ask too much of prospective users. For that reason, having quality documentation was one of the project’s goals from the get-go.

We put a lot of effort into writing the documentation, and when I revisit it today, I feel that we achieved our goal. All aspects of using the tool are documented quite well, and the HowToBuild.html file does a reasonable job of introducing developers to building the software from scratch.

If you browse the documentation on GitHub (the files are located in the docs folder), you might notice a bunch of variables like, for example, $version$. When Ant builds Detroubulator and packages up a ZIP file for distribution, those variables are replaced with actual values. This happens in the varsubst Ant target.