doctest

Doctests for JavaScript and CoffeeScript

doctest

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/bower_components/esprima/esprima.js"></script>
    <script src="path/to/bower_components/jquery/dist/jquery.js"></script>
    <script src="path/to/bower_components/underscore/underscore.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 indicates the number of test failures:

$ echo $?
0

doctest partially supports AMD and CommonJS modules:

Module systemNode.jsBrowser
AMD✔︎✔︎
AMD w/ dependencies
CommonJS✔︎
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

It's easy to indicate that an error (of a particular kind) is expected:

// > null.length
// TypeError

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 0.0.0.0 port 8000 ...

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