On Mon, Apr 19, 2010 at 12:50:23PM +0200, Adam GROSZER wrote:
Hello Tres,
Saturday, April 17, 2010, 3:41:02 AM, you wrote:
TS> -----BEGIN PGP SIGNED MESSAGE----- TS> Hash: SHA1
<snip>
+lots on more docs +lots on 100% coverage
TS> The trickier testing bits we would re-write as super thorough, no TS> shortcuts-taken unit tests: one testcase class per class (or API TS> function) under test, at least one method per class-under-test method, TS> with more preferred to get all code paths / preconditions covered. The TS> goal here would be to comment out the doctests from the test_suites and TS> get the code to 100% coverage using pure unit tests. Meanwhile, the TS> doctests would be refactored into the Sphinx documentation, losing all TS> the bits which obscure their intent as documentation.
I'm somewhat vary on unittests. I've seen some damn cryptic ones that took a lot of time to decipher. A doctest somehow forces you to dump your mind (well at least that, if we're not that brilliant techdoc writers).
That's true, but if the doctest gets too long, any readability advantages are negated. If you've the discipline to keep the doctests short, I don't see why you shouldn't continue writing them instead of unit tests -- and by "short" I mean 1-7 statements: import unittest import doctest from mypackage.mymodule import MyClass class TestMyClass(unittest.TestCase): def test_foo(): x = MyClass() self.assertEquals(x.foo(), 42) def doctest_MyClass_bar(): """Test MyClass.bar >>> y = MyClass() The bar method peforms a bar calculation that typically returns twenty-three: >>> y.bar() 23 """ def doctest_MyClass_bar_raises_if_incorrect_setup(): """Test MyClass.bar >>> y = MyClass(setup='incorrect') If you haven't supplied the correct setup, you get an exception: >>> y.bar() Traceback (most recent call last): ... IncorrectSetupError: the setup was incorrect """ def test_suite(): return unittest.TestSuite([ unittest.makeSuite(TestMyClass), doctest.DocTestSuite(), ]) The downside of this style is that it's difficult to refactor common bits from the doctests into shared methods, so you end up with a lot of duplicated code.
OTOH I think most unittests maybe have some comments, worst case they don't even use "speaking" variable names. I'm not sure whether we can enforce such rules (super thorough, no shortcuts-taken, well commented) if we can't easier ones.
Marius Gedminas -- http://pov.lt/ -- Zope 3 consulting and development