- - -

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

!demo

Set-up

Here's a two line set-up you can use:
``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...`).

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