[Python-3000] doctests vs. unittests (was Re: pimp; restructuring the standard library)

[Barry Warsaw]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Jun 28, 2007, at 4:04 PM, Chris McDonough wrote:

> I've historically not been a huge fan of doctests because (these
> things may have changed since last I used doctest in anger):

I used to think the same thing, but I've gotten the doctest  
religion.  I'm using them almost exclusively in the new Mailman code,  
and we use them at work (though both still have traditional Python  
unit tests).

The thing that convinced me was the realization (assisted by my  
colleagues) that doctests are first and foremost documentation.  They  
are testable documentation sure, but the unit tests are secondary.   
There's no question that for things like system documentation, the  
narrative that weaves the testable bits together in a well written  
doctest are much more valuable than the tests.  Most unittest based  
tests have little or no comments, and nothing approaching the  
narrative in a good doctest, so it's clear that unittests are tests  
first and probably not documentation at all.

I've even experimented with writing a PEP for my enum package (as yet  
unsubmitted) that is nothing more than a doctest.  It seemed almost  
completely natural.

A good test suite can benefit from both doctests and unittests and I  
don't think unittest will ever go away (nor should it), but in my  
latest work I'm opting more and more for doctests.  That Tim Peters  
is a smart guy after all I guess. :)

- -Barry

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (Darwin)

iQCVAwUBRoSAfnEjvBPtnXfVAQLSrQP/criiWjS2RdChwq5CVw1BbYbS5LP8WI7b
4SY6BRLFFWH218IrihVa8kZh8cvrTb1PHxVqiuEQIj3qcHo3SuMO6A1MKYZJhuCN
vOINQkseaP1jGn5/b85/Q3OSUGbVfdWS+E7Yri5qCva/GaTNwCNNHNTT9+K7LBqE
7AA937O2oa8=
=97lr
-----END PGP SIGNATURE-----