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 finds and evaluates usage examples in code comments and reports any inaccuracies. doctest works with JavaScript and CoffeeScript modules.
Example
// toFahrenheit :: Number -> Number
//
// Convert degrees Celsius to degrees Fahrenheit.
//
// > toFahrenheit(0)
// 32
// > toFahrenheit(100)
// 212
function toFahrenheit(degreesCelsius) {
return degreesCelsius * 9 / 5 + 32;
}
Doctest will execute toFahrenheit(0)
and verify that its output is 32
.
Installation
$ npm install doctest
Running doctests
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.
Supported module systems
Module system | Option | Node.js | Dependencies |
---|---|---|---|
AMD | amd |
✔︎ | ✘ |
CommonJS | commonjs |
✔︎ | ✔︎ |
ECMAScript modules | esm |
✔︎ | ✔︎ |
Specify module system via JavaScript API:
> doctest ({module: 'amd'}) ('path/to/amd/module.js')
Specify module system via command-line interface:
$ doctest --module commonjs path/to/commonjs/module.js
Line wrapping
Input lines may be wrapped by beginning each continuation with FULL STOP (.
):
// > reverse([
// . 'foo',
// . 'bar',
// . 'baz',
// . ])
// ['baz', 'bar', 'foo']
Output lines may be wrapped in the same way:
// > reverse([
// . 'foo',
// . 'bar',
// . 'baz',
// . ])
// [ 'baz',
// . 'bar',
// . 'foo' ]
Exceptions
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
Scoping
Each doctest has access to variables in its scope chain.
Integrations
Running the test suite
$ npm install
$ npm test