Previous Entry Share Next Entry

The Python doctest module is really great: it makes it easy to simultaneously write test suites and demonstrate the usage for your modules. Python's interactive interpreter is key to its coolness: it's really easy to load the code you're working on, type some examples at the prompt, and turn the session into documentation and a test case.

I've been dusting off my Square Dance Revolution project, written in Java, and I thought: gee, it would be nice to use doctests here. A bit of inspiration from doctestj and Rhino, and a bit of elbow grease and: voila! JDoctest is born!

JDoctest is a Javadoc plugin which implements doctests by calling out to the Rhino javascript interpreter. Rhino's interactive javascript session makes Java as fun to program in / debug / test as Python is. (Rhino makes it easy to call between Javascript and Java.) Copy and paste those examples into javadoc comments, add a @doc.test tag, and you've got a test / use case example. I've added hooks to google-code-prettify to make the output beautiful, too.

Here's a simple example using JDoctest, and the SDR sources are now filled with more complex examples (for example). (New SDR release soon, I promise.) Enjoy!

  • 1
I agree that tests for each and every routine/module is a must, personally I'm not that keen on DocTesting. I prefer unit tests, available for both Python and Java, unittest and JUnit respectively. I'm not really that sure why, maybe I don't like seeing dozens of lines of comments, or maybe I don't like testing just one routine/module, but Unit tests allow me to test exactly what I want; the routine itself and also its interaction with the rest of the program. It's worth giving it a try, and I'll also have fun again with doctesting, just to see if I missed anything last time :)

Doctesting is a certain type of development methodology, really. It's like writing a program using CWeb: by forcing you to structure your tests as documentation performed at an interactive shell, it also encourages interpreter-focused APIs -- making as easy as possible to use all your APIs from the command-line, good implementation of toString() and valueOf() methods, simple interfaces that don't require complex machinations to use. On the other hand, it more tightly integrates your code and tests: test often end up depending on the exact implementation of your toString() methods, and you need to take special care to ensure that (for example) iteration order isn't erroneously enforced by your tests. In a decoupled multiple-developer corporate environment, I'd probably prefer the sort of black box testing JUnit allows. But for interactive development, doctests rock: you end up spending lots of time noodling around at the interactive shell with your half-completed code, trying the corner cases and making sure the thing you just wrote actually works like you think it does -- and when you're done, copy-and-paste the session, add some text describing what it was you were testing, and voila!

  • 1

Log in

No account? Create an account