deltazero-cz / jsdoctest

Run jsdoc examples as doctests.

---

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 --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:

/**
 * @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 jsdoctest
mocha --require jsdoctest <module-name>

There's also a rudimentary command-line interface, which can be ran with:

npm i jsdoctest
jsdoctest <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