https://github.com/yamadapc/jsdoctest
Run jsdoc examples as doctests.
https://github.com/yamadapc/jsdoctest
compiler doctest documentation javascript jsdoc mocha testing
Last synced: 22 days ago
JSON representation
Run jsdoc examples as doctests.
- Host: GitHub
- URL: https://github.com/yamadapc/jsdoctest
- Owner: yamadapc
- License: mit
- Created: 2014-11-17T12:04:15.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2021-02-10T21:41:49.000Z (over 4 years ago)
- Last Synced: 2025-04-07T07:43:06.038Z (about 2 months ago)
- Topics: compiler, doctest, documentation, javascript, jsdoc, mocha, testing
- Language: JavaScript
- Homepage: https://yamadapc.github.io/jsdoctest
- Size: 2.52 MB
- Stars: 95
- Watchers: 4
- Forks: 9
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/yamadapc/jsdoctest)
[](https://coveralls.io/r/yamadapc/jsdoctest)
[](http://waffle.io/yamadapc/jsdoctest)
[](https://david-dm.org/yamadapc/jsdoctest)
[](https://david-dm.org/yamadapc/jsdoctest#info=devDependencies)
[](https://www.npmjs.org/package/jsdoctest)
[](https://www.npmjs.org/package/jsdoctest)
[](https://gitter.im/yamadapc/jsdoctest?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
- - -
**jsdoctest** parses [`jsdoc`](http://usejsdoc.org/) `@example` tags from
annotated functions and runs them as if they were doctests.
Inspired by the [doctest](https://docs.python.org/2/library/doctest.html) python
library, as well as its [doctestjs](http://doctestjs.org) javascript
implementation.
## 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](/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`](https://github.com/mochajs/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](/LICENSE) file.
## Donations
Would you like to buy me a beer? Send bitcoin to 3JjxJydvoJjTrhLL86LGMc8cNB16pTAF3y