[Zope3-dev] The Zope Software Certification Program and Common Repository Proposal

Stephan Richter srichter at cosmos.phy.tufts.edu
Tue Feb 21 12:16:46 EST 2006

On Tuesday 21 February 2006 11:59, Lennart Regebro wrote:
> > Well, a doctest could explain the migration test and what has changed.
> Nothing "changed". It's two different calendar products. It's
> basically an import/export from the old calendar to the new. There is
> nothing to explain.

If nothing changed, then you need no tests. Of course things changed. The data 
structures changed. And the migration test is a wonderful opportunity to 
document those data structure changes.

> are NOT useful to the reader. In fact, it is my now repeatedly stated
> opinion that several of CPSSharedCalendars tests are not useful to any
> reader. They make sure it actually works, they don't provide any
> insight into how to use CPSSharedCalendar. You use it by clicking
> around on a website, not by writing python code.

Of course, the tests are not useful for the end user, but they are useful for 
other programmers. Let's say tomorrow you decide to leave Nuxeo and another 
programmer has to work on your code. It will be much easier to read doctests 
than unit tests.

> I think you are stuck in library-development mode. ;-)

I don't think so. I am developing SchoolTool and the team there is totally 
committed to doctests. There are no code unite tests whatsoever. Not that I 
think that SchoolTool's tests are always perfect, but they get pretty close.

> But this 
> proposal isn't only made for libraries, right? It seems to me that
> several of the requirements have to do with site integration and such,
> things you get for finished products that you can install and use.
> They need to be documented of course, and part of that documentation
> can very well be in doctest format, but most of the documentation that
> is needed (and currently sadly missing) is for end-users. A doctest
> requirement wouldn't help the documentation in any reasonable way, and
> it would slow down the test-writing.

Doctests can be used to address both type of users. I usually find that 
functional tests are for end users and unit/integration doctests for 

> And why should I pretend that the migration tests are documentation of
> how to write a migration, when it is in fact a test that migration
> works even with non-ascii characters? There is today no documentation
> of how to write migration code from the old calendar to the new,
> because that code is written. I don't need to document how to do it
> again. :-)

You are not documenting how to write migration code, but you document how you 
do a particular migration and what data is being migrated. This is important 
to several audiences.

> > SchoolTool solves this by simply storing an old ZODB database and then
> > run the generation scripts, because this is what happens in the real
> > world anyways.
> Well, I solve it by not using doctests, which I like better, because
> it enables me to easily add and change the tests according to me
> finding something new that needs testing, withouthaving to change a
> binary file which can't be diffed. And how do you fit the ZODB into
> the documentation? :-)

Yeah, but the cost is that you keep an old setup around, which is not 

> Tests are not always documentation. It's nice if they can be both, but
> I don't think it's a good idea to require it to be both, because quite
> often, it isn't.

Tests *should* always be documentation. That's the goal of using doctests. XP 
clearly wants tests and documentation be the same thing and task. Doctests 
have given us the technology to fulfill this requirement.

Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training

More information about the Zope3-dev mailing list