Run jsdoc examples as doctests
npm install jsdoctest









- - -
jsdoctest parses jsdoc @example tags from
annotated functions and runs them as if they were doctests.
Inspired by the doctest python
library, as well as its doctestjs javascript
implementation.
!demo
bash
$ npm i -g jsdoctest && jsdoctest --init
Adding jsdoctest script to your package.json...
Installing mocha and jsdoctest with npm:
... npm doing some work...
You can now run doctests with npm run jsdoctest or npm test
`
This will add sensible defaults to your package.json which you can then edit.Test-case Format
Examples need to be valid javascript, followed by a comment with the string
=> prefixing the results:
`javascript
/**
* @example
* returns10()
* // => 10
* returns20()
* // => 20
*/
`It doesn't matter if the comment is on the same line or the next one, so the
following is also valid:
`javascript
/**
* @example
* returns10() // => 10
* returns20()
* // => 20
*/
`Async test cases are supported prefixing the expected results with the
async => string and pretending to have the cb callback function.
`javascript
/**
* @example
* takesCallbackAndYields10('here', cb)
* // async => 10
* takesCallbackAndYields20('here', cb)
* // async => 30
*/
`Promises are also supported, just add the same
// async => prefix and be
sure not to use a variable named cb on your text expression.
`javascript
/**
* @example
* returnsPromiseThatYields10('here')
* // async => 10
*/
`Examples
The examples directory has a couple of examples, which may be
useful. Better documentation will be added if the project raises in complexity.Usage
The recommended way of using jsdoctest is to use
mocha. That is made possible with:
`bash
npm i mocha jsdoctest
mocha --require jsdoctest
`There's also a rudimentary command-line interface, which can be ran with:
`bash
npm i jsdoctest
jsdoctest
`Disabling
To disable running jsdoctests, while still requiring it with mocha (I don't
know why, but you may) you can set the JSDOCTEST_DISABLE environment variable
to anything (JSDOCTEST_DISABLE=true mocha --require...`).