Pythoneer

Sometimes when you want to do something right and you are lacking the tools you write them (but very often I don’t ), but in the case of doctests for dojo I saw the need. This time I took the time to write a doctest-class for dojo. It is currently only a ticket in the dojo trac, but some feedback looks pretty promising.

I saw the Ian Bicking had already once written a doctest module, but after skimming over it and thinking about the task, I decided to write it from scratch and a pure dojo fit, since it surely is not much work (as it also turned out, which is a rare case).
I knew the doctests module from the Python, where it obviously also comes from. In the beginning I found doctests ugly, those huge chunks of console-pastes inside my docstring. But after getting to know the value of the doctests by learning django’s newforms completely by a huge doctest I felt what they can do and that they can really help a lot.
Doctests just make you understand the code in the place it is written. If you (as I do) often look into the sources it can be really helpful to see a programming example right there inside the docstring of the class/method/function.

To make it short, I implemented this for JavaScript and it works nicely. I am actually developing a dojo.data-store but in order to do that I needed doctests, that’s where the need came from.
One of dojo’s base functions might look like this now:

dojo.trim = function(/*String*/ str){
	// summary: trims whitespaces from both sides of the string
	// description:
	//	This version of trim() was selected for inclusion into the base
	//	due to its compact size and relatively good performance (see Steven Levithan's blog:
	//	http://blog.stevenlevithan.com/archives/faster-trim-javascript).
	//	The fastest but longest version of this function is going to be placed in dojo.string.
	// examples:
	//	>>> dojo.trim(" trim me ")
	//	"trim me"
	//	>>> dojo.trim("\t\ttrim me ")
	//	"trim me"
	//	>>> dojo.trim(" \t\t trim me \t ")
	//	"trim me"
	//	>>> dojo.trim("trim me")
	//	"trim me"
	//	>>> dojo.trim(" trim me")
	//	"trim me"
	//	>>> dojo.trim("trim me ")
	//	"trim me"
	//	>>> dojo.trim("")
	//	""
	return str.replace(/^\s\s*/, '').replace(/\s\s*$/, '');	// String
}

You can see more examples here and here (search for the doctest starting with “>>>” and you will find some).
Below “examples” you can see the inline doctest. I really just wrote those tests in the FireBug console and copied them later into the code.

Run doctests
The trac ticket in dojo including the files and some info you can find here. You can download the patch right here.
First apply the patch, so that the dojox.testing.DocTest module is available.
This patch containing the doctest class is though to be a part of dojo, so it currently requires that you have a dojo module or a module that you registered with dojo (dojo.registerModulePath()).
To run i.e. the above shown doctest you just need to know in which file (module) it is (dojo._base.lang in this case) and type the following into your FireBug console:

>>> dojo.require("");
>>> var doctest = new dojox.testing.DocTest();
>>> doctest.run("dojo._base.lang");

It will then print out a line for each test in the FireBug console with the result and some info. In the before case it looks like this:

...
Test 44: OK: dojo.trim(" trim me ")
Test 45: OK: dojo.trim("\t\ttrim me ")
Test 46: OK: dojo.trim(" \t\t trim me \t ")
Test 47: OK: dojo.trim("trim me")
Test 48: OK: dojo.trim(" trim me")
Test 49: OK: dojo.trim("trim me ")
Test 50: OK: dojo.trim("")


Embed doctest
You can also embed the doctests into other test modules, i.e. if you are just want to add the doctests to your unittests and get them all as one result. You can simply check the property errors of your doctest instance:

>>> doctest.errors
[]

As you can see if there are no errors it’s length is 0.
You can see an example of how to do that here in the file data/tests/stores/QueryReadStore.js the first function testDocTests() runs the doctests of the module “dojox.data.QueryReadStore” and verifies that there are no errors.

I hope this will be useful to some people. Let me know if you have any kind of feedback, bugs or whatever. In the class itself you can see that I have also already thought of some things that need to be done/added to this class. Have fun doctesting …