StoryTeller is an Eclipse plugin which helps you write high quality code by using your tests as living documentation, or put differently, by telling the story of your code.

Use your unit tests as living documentation

Making code easier to understand is important since code is harder to read than to write. A great way to do that is to see tests as stories about the code. This helps you focus on communication and intent, rather than technical details.

This is where StoryTeller comes in.
It helps you by displaying relevant tests side-by-side with your code, and displaying test names as normal sentences rather than method names. These features help you turn computer-focused tests into human-focused documentation.

Seeing tests as stories is an idea I learned from Kent Beck, JUnit's creator, who argued that many testing related problems disappear when that mindset is used.

After all, the most important audience of code is not computers, but humans.

Download Eclipse plugin

To install StoryTeller use the following Eclipse update site.

http://storyteller.socosomi.com/update

Tip: Paste the link in the Work with box under Help > Install New Software...

For more detailed instructions, please read the Installing new software section of the Eclipse documentation. The plugin is compatible with Ganymede (3.4) or later, and has been successfully tested up to Juno (4.2).

Shows related tests side-by-side with your code

StoryTeller gives you a Related Tests view which always shows tests that are relevant to the code you are viewing. Java aware search is used to find related tests no matter what they are named, and the list is automatically kept updated as you work with the code. Double click on a test to jump right to it.

It doesn't matter if you mark your test methods with the test prefix as in JUnit 3, or using the @Test annotation in JUnit 4 or TestNG. You can use regular CamelCase or separate_words_with_underscore if you like.
StoryTeller handles them all.

Normal sentences rather than method names

WhileCamelCaseIsVeryUseful, plain old text is just easier to read. That is why StoryTeller displays test names as normal sentences rather than method names.

Using normal sentences also helps you think of the tests as a specification or documentation, not just a method. You can even use copy/paste or drag 'n drop to quickly get raw material for a spec or documentation.

As a nice bonus, StoryTeller will preserve acronyms and names of recognized classes when turning test names into sentences, making them easier to read.

Writing better unit tests

Finally, a few tips and tricks for writing unit tests that better tell the story of the code.

• Your test method names can be as long as you like. Use descriptive names!
• Don't just name the test method after the method it is testing. Tell me what to expect. Tell me what is significant about the input and output.
• Use one test class per set of test data (called "fixture"). Name the test class after the fixture. That is how JUnit is designed and intended to be used.
• You can have as many test classes as you want, they are free! Split up test classes that become too large.
• Duplication is often more okay in tests than in production code because readability of tests is so important.
• Avoid abstract super classes for unit test classes as they make the individual test classes harder to read.
• Write tests before production code to get code that is easier to understand, use and maintain.
• Use the Test-Driven Development Duel to turn unit testing into a fun exercise.
• For each bug you fix, write an automated test to prove it.
• The tests needed to drive design in Test-Driven Development are not necessarily the tests needed to show the intent of the code.
• It is okay to delete a test which isn't needed to tell the story about the code.
• Don't get obsessed with 100% test coverage. You get decreasing value in return for each test you add.

Caveat: Of course, there is also a technical or coverage aspect of unit testing, but it is of less importance. The primary audience of code is humans, not computers.

Behind the scenes

StoryTeller is created by Socosomi. While that sounds like a company name, it is really just a label for software quality related stuff created by Henrik Jernevad.

The plugin is created because I wanted it myself, but would be thrilled if someone else found it useful. I would love to hear back from you and will take any and all feedback into consideration. I do however make no guarantees for updates since this is all made on spare time.

StoryTeller is published under the Eclipse Public License. The source code for the plugin is available on request until I feel comfortable to release it more widely.