Doctests
Doctests are explanatory descriptions of programs with executable code examples. Their main purpose is to explicate requirements, assumptions, and relationships between components that are difficult to understand from traditional API documentation. At the same time they provide tests of core functionality.
Doctests are written as HTML5+JavaScript pages with embedded script tags
marked by a "doctest"
css class:
<script class="doctest">
These scripts are evaluated and thereby tested when the page loads. See the
source of this page for examples.
Typically doctests are started by a
<body onload="Doctest.run()">
call. This method loops over all script elements with a "doctest"
css class and replaces these scripts with <pre>
tags that
(unlike<script>
tags) are visible to the user.
Let's look at an example of a simple program that uses a composite design pattern. A node with a query component that can be reused in other classes:
We can now check whether the basic setup of our composite pattern works:
Looking at the source of this doctest you will see that the test is done by the static
Doctest.expect(expr, result)
method. This
method throws an error which can be used standard browser development tools to
locate and trace the cause of the error.