Protest rocks! (generate documentation from tests)
Mar 17th, 2006 by Phil Dawes
I’ve been working a bit with Nat Pryce on his ‘Protest’ project recently. It’s a python unit test framework which generates documentation from the tests. E.g. you write test cases like:
class myFunctionTests:
''' myfunction is a function belonging to me '''
def does_something_cool():
... code which asserts that something cool is done ...
def does_something_else_as_well():
assert(something_else)
and the test framework will generate web documentation along the lines of :
myFunction
myfunction is a function belonging to me
Features of function myFunction:
- does something cool
- does something else as well
It then goes on to show the tests that confirm these statements all nicely marked up and also does some nifty graphviz diagramming stuff - all pretty rinky dinky. I’m hoping to get round to using it to document bicyclerepairman before my motivation runs out.
Anyway, the really interesting thing is seeing how the documentation informs which tests I write. In general I’m testing stuff that I wouldn’t have bothered with before just so that I get some doc for it. It also ensures that documentation doesn’t rot since each piece of documentation is tested against the codebase. Sweet!
There’s no proper ‘release’ as such yet, but if you’re interested in partially working software then Nat’s got the subversion repository in his xspecs sf project - just do a
svn checkout https://svn.sourceforge.net/svnroot/xspecs/protest-python/trunk
(hope that’s ok Nat!)
Very interesting. Can we talk about this next week?
Of course it’s all right.
–Nat.
London 2.0 Meetup…
On Monday, I went along to a London 2.0 meeting. As usual with many of these meetups, the first time go along you’re never quite sure who you are looking for. But this time it was slightly easier. The venue……
[…] Phil Dawes demonstrated both Bicycle Repair Man and the Python testing tool Protest (we need screencasts of both!), and I pointed numerous people towards the impressive DabbleDB screencast. Demo of the night probably had to be Remi Delon showing off Python Hosting. They offer a very slick, one-click install of a variety of different webapp frameworks (everything from TurboGears to Zope to Django) for a very reasonable price. His screencast is out soon – but put it this way, TextDrive’s TextPanel is going to have a lot to live up to, not to mention their forthcoming Rails-dedicated hosting (note: I’m a TextDrive user myself). Despite their name, Python-Hosting do also provide Rails hosting, however it’s not yet integrated with their slick user interface. […]
[…] real motivation was that I’d been seduced by the idea of using tests for documentation ala Nat Pryce’s ‘Protest’. Here’s what I came up with: […]