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
Set-up
Here's a two line set-up you can use:
$ npm i -g jsdoctest && jsdoctest --initAdding `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:
/** * @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:
/** * @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.
/** * @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.
/** * @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:
npm i mocha jsdoctestmocha --require jsdoctest <module-name>
There's also a rudimentary command-line interface, which can be ran with:
npm i jsdoctestjsdoctest <module-name>
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...
).
License
This code is licensed under the MIT license for Pedro Tacla Yamada. For more information, please refer to the LICENSE file.
Donations
Would you like to buy me a beer? Send bitcoin to 3JjxJydvoJjTrhLL86LGMc8cNB16pTAF3y