DocTest 1.0 For Ruby Released
DocTest allows the easy generation of tests based on output from the standard interpreter shell (IRB for Ruby), cut and pasted into docstrings.
Copy/paste your IRB testing output as comment for your function:
# doctest: Add 5 and 5 to get 10Later you'll be able to run the test:
# >> five_and_five
# => 10
5 + 5
$ rubydoctest five.rbThis will run with latest sources from the git repository. An updated gem will soon be available
=== Testing 'five.rb'...
OK | Add 5 and 5 to get 10
1 comparisons, 1 doctests, 0 failures, 0 errors
Such docstring-driven testing has its pros:
- Those who are familiar with IRB live testing will find it useful and natural to use.
- One place to look at for the test.
- Large docstring should be avoided and put into a separate test file.
- Some complex testing assertion are not available.
- It can be tedious to test large outputs.
A screencast demonstrating DocTest usage is available.
InfoQ caught up with Duane Johnson to discuss DocTest and docstring-driven tests.
InfoQ: Firstly, what led you to write DocTest? I read you looked at 2 previous implementations.
The latest code can be found on github? It's a merge with a previous version of DocTest? What did you add?
Aren't you satisfied with all the Ruby test frameworks?
DocTest is outside the BDD cycle?
Is DocTest supposed to be a replacement for the other unit test framework or just an additional tool?
Isn't the way DocTest annotates code polluting the reading?
DocTests in Zope and Python
Doc testing is fun! :)
Doctesting has been a common form of testing in Zope for a long time (around 2001 or so). The merits and good uses of doc testing were recently discussed in this thread. The summary is it's important to seperate the use cases for doc testing:
- * Executable documentation doctesting: Intended as "testable" documentation. Documentation comes first with this form of doc test. Outdated or wrong documentation can be rather annoying, so this is good. The risk is that it's easy to go of on a tangent and start testing corner cases - this spoils the readability of the documentation. Narrative doc tests are also harder to maintain, since you may need to comprehend the whole narrative to expand upon one.
- * Edge-case and bug fix doctesting: In this case the narrative between the
test cases is there primarily to explain what is being tested and why. Some
developers like to bang out doc tests as they work, writing down thoughts and snippets of code as they go.
This second form can produce files that are also semi-usable as documentation, and are often preferable when approaching software over reading source code. Sometimes the software you are developing doesn't justify the cost of proper documentation, so this type of doc testing is "better than nothing". The flipside is that this may inhibit initiatives at writing proper documentation, "Look at all these files with words in them that this package already has, I guess it doesn't need anymore documentation." And in an open source project, people can find a packages test-centric doc tests and end up complain about the poor quality of documentation ...
Packages such as z3c.testsetup can be directed to more sophisticated automated detetion of doctests. Aside from picking doc tests out of source code, it also can run plain .txt files as doc tests - these files and the testing layer they are associated with (unit, functional, integration) are denoted with a line such as:
Re: DocTests in Zope and Python
Thank you for this informative comment!
Craig Motlin Sep 01, 2014