[Zope-dev] RFC: Proposed new style for documenting and testing ZTK packages

[Marius Gedminas]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: Digital signature
Url : http://mail.zope.org/pipermail/zope-dev/attachments/20100419/246dd348/attachment.bin