About " testThisMethodShouldPerformThisFunction"
I think you should read this essay about BDD: http://dannorth.net/introducing-bdd
I am of the opinion that doc tests are much more readable. Consider a simple unit test:
def testOnePlusOneShouldBeTwo(self):
self.assertEquals(1 + 1, 2)
def testTwoPlusTwoShouldBeFour(self):
self.assertEquals(2 + 2, 4)
Compared to a doc test:
One plus one should be two:
>>> 1 + 1
2
Two plus two should be four:
>>> 2 + 2
4
I find doc tests easier to generate as well, as when you are poking at your application from the Python interpreter, you can just copy and paste your session into a .py file in your doc tests suite package, and then simply intersperse with plain-text as you see fit.
As to the where doc tests live compared to unit tests, the answer is, wherever you want them too. That is if you have a separate package for your unit tests, you could just as easily have a separate package of doc tests. In the Zope 3 source code there is a convention of having mymodule.py be associated with doc tests located at mymodule.txt, but this not intrinsic to doc testing. The Grok project for example puts all of the doc tests in a directory called 'tests' for doc test equivalents of regular unit tests, and 'ftests' for doc test equivalents of functional tests:
http://svn.zope.org/grok/trunk/src/grok/tests/
http://svn.zope.org/grok/trunk/src/grok/ftests/
Thanks Kevin for pointing out the grok tests. Note that these are somewhat unusual way to use doctests compared to the way you'd test most APIs, as Grok is unusual in the way it reads in ('groks') modules.
To contrast, I'll point to a few .txt file based doctests that I helped, as these are slightly more common:
Calendaring:
http://svn.nuxeo.org/trac/pub/br...doc/
usecase.txt
Workflow:
http://codespeak.net/svn/z3/hurr...ow/
workflow.txt
As an example of a doctest in Zope 3 (zope.interface functionality; I didn't write), see here:
http://svn.zope.org/Zope3/trunk/...71692&
view=auto
Regards,
Martijn
I guess this is obvious to everybody, but I would like anyhow to stress that you can mix both unit testing and doctests. This is what I do in my unit testing script :
++++++++++++++++
# Import the module to be tested
import pyreport
import unittest, doctest
testsuite = unittest.TestSuite()
testloader = unittest.TestLoader()
load_test = lambda t: testsuite.addTest(
testloader.loadTestsFromTestCase(t))
# Define here plenty of unit tests, and add
# them to testsuite
testsuite.addTest(doctest.DocTestSuite(pyreport))
runner = unittest.TextTestRunner()
if __name__ == '__main__':
runner.run(testsuite)
++++++++++++++++
This is probably not the most elegant way of doing it. Now that I look back at the code I find it awkward, but it does work.
+1 doctests rather than unittests
It's easier and quicker to write doctests, so I end up writing more tests, which is a good thing.
There is too much verbiage in writing unittest tests.
What is the problem with using mocks in doctests? Works fine for me.
+1 to Gael. Both are complementary and I don't get why one should have to choose one over the other.
Tim: doctest can make the code so ugly to read when the test is complicated (like testing for Exceptions). Plus they are rendered in when using the help() function from an interpreter and can make it less readable as well. It's really a matter of taste.
Sylvain: I realise that this is a matter of taste, and was merely contributing my personal opinion. But honestly, after using both, I can't think of many (any?) situations where unittest feels more appropriate. (Though maybe it is useful for pulling large testsuites together.)
For doctests that are too ugly to appear in help you can separate them into a separate file. Doctests don't have to be in the immediate docstring of a function, they just need the function/method name to be accessible from the current namespace.
May be this is a matter of personal preferences?
Personally, I never view 'doctests' as tests; any executable code I put into docstrings is meant to be a part of documentation. Of course, it nice that doctest can make sure these code samples never get out of sync with the code but that's it.
All my 'real' tests are separate python modules, written for nose/unittest.
Something to note about the way we use doctests. We separate documentation tests from testing edge cases.
We tell the main stories of our franeworks using separate documentation files. These are intended to be documentation first, and texts second.
To get necessary coverage, dealing with edge cases and regression tests, we put separate tests in test files. For these, any testing framework can be used, although I dtill prefer using doctests for these, as I find them more readable.
In the last post, I saud "texts second". I meant "tests second". 
One more thing I prefer about unittest over doctest: I can run just one of the tests if I need to, either because I am debugging in it, or the whole suite takes too long for quick iterations.
With doctests, there is no granularity: the entire string must be run.
Commenting by HaloScan
