Doctests for JavaScript and CoffeeScript


Doctests are executable usage examples sometimes found in "docstrings". JavaScript doesn't have docstrings, but inline documentation can be included in code comments. doctest tests the accuracy of usage examples in JavaScript and CoffeeScript modules.

// toFahrenheit :: Number -> Number 
// Convert degrees Celsius to degrees Fahrenheit. 
// > toFahrenheit(0) 
// 32 
// > toFahrenheit(100) 
// 212 
function toFahrenheit(degreesCelsius) {
  return degreesCelsius * 9 / 5 + 32;
$ npm install -g doctest
  1. Install doctest and its dependencies:

    $ bower install doctest
  2. Add script tags:

    <script src="path/to/node_modules/esprima/esprima.js"></script>
    <script src="path/to/bower_components/jquery/dist/jquery.js"></script>
    <script src="path/to/bower_components/qunit/qunit/qunit.js"></script>
    <script src="path/to/bower_components/ramda/dist/ramda.js"></script>
    <script src="path/to/bower_components/doctest/lib/doctest.js"></script>

Test a module via JavaScript API:

> doctest("lib/temperature.js")

Test a module via command-line interface:

$ doctest lib/temperature.js

The exit code is 0 if all tests pass, 1 otherwise.

doctest partially supports AMD and CommonJS modules:

Module systemNode.jsBrowser
AMD w/ dependencies
CommonJS w/ dependencies✔︎

Specify module system via JavaScript API:

> doctest("path/to/amd/module.js", {module: "amd"})

Specify module system via command-line interface:

$ doctest --module commonjs path/to/commonjs/module.js

An output line beginning with EXCLAMATION MARK (!) indicates that the preceding expression is expected to throw. The exclamation mark must be followed by SPACE ( ) and the name of an Error constructor. For example:

// > null.length 
// ! TypeError 

The constructor name may be followed by COLON (:), SPACE ( ), and the expected error message. For example:

// > null.length 
// ! TypeError: Cannot read property 'length' of null 

Each doctest has access to variables in its scope chain.

$ make setup
$ make test

This runs doctest's test suite in Node. To run the suite in a browser, first start an HTTP server with test/public as the root. For example:

$ cd test/public
$ python -m SimpleHTTPServer
Serving HTTP on port 8000 ...

Then point a browser at the correct port on localhost to view the results.