Using Doctests

The project uses the doctest module from the Standard Library for all of its tests. Most of the docstrings in htme.py include simple inline tests which double as examples of how the API works.

Doctests might not suit every project, but they work well for testing a modular code generator.

The Tests

Doctests work like an interactive interpreter session. As HTME rendering is deterministic, we can just evaluate an element and provide its HTML equivalent. The doctest module checks that they match. For example, we can include the following code in a docstring, and doctest will check that the expression after the prompt (>>>) generates the output on the following line:

>>> DIV({"class": "button"})
<div class="button"></div>

Using doctest keeps things simple, with each block of code and its tests in the same place. It also makes it easy for new contributors to update the test suite when they edit something.

The Test File

All of the Engine methods are doctested inline. We also want to check the engine's output against complete documents to make sure everything comes together exactly as we expect. The deterministic rendering process makes this simple (compare two strings for equality), so we can still use doctest to ensure that a generated doc matches a test doc.

To avoid having a bunch of complete HTML documents in the docstrings, we have an external file (test.htme) that is used to test the engine's output against (htme is not an extension, we just use it internally for storing data without clobbering anything). The test file is still being developed, and currently only contains one HTML document, but it will contain a collection of them soon.

The Runner

You import htme as a module to use the library (normally with from htme import *). You run the library as a script to execute its test suite. You can pass arguments to the script as documented in the doctest docs.

The doctest approach allows us to use the same tests for Python 2 and 3, by just running htme.py as a script with each interpreter.